From b65d04c044d7f262e01aa1435fb503694e1250ba Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Tue, 11 Aug 2026 17:20:56 -0400 Subject: [PATCH] docs(#3353): record #3346 and #3353 triage decisions as out-of-scope (#3362) * docs(#3346): record new-host-as-in-tree-runtime as out-of-scope New host runtimes go out-of-tree as EoS host-plugins listed in the EoS Registry (ADR-1239), not as first-party in-tree registry entries. Sibling to omp-runtime-in-core.md; on-point precedent #2170 (Devin CLI). * docs(#3353): record commit_gates config as out-of-scope A parallel commit_gates config would duplicate the existing capability gate system (command-exit-zero, #2008/ADR-2008). The route is a commit:pre loop-point reusing the existing gate. Companion defect #3352 stays open. --------- Co-authored-by: sim --- ...commit-gate-reuse-capability-loop-point.md | 88 ++++++++++++++++++ .../eos-registry-not-in-tree-runtime.md | 89 +++++++++++++++++++ 2 files changed, 177 insertions(+) create mode 100644 .out-of-scope/commit-gate-reuse-capability-loop-point.md create mode 100644 .out-of-scope/eos-registry-not-in-tree-runtime.md diff --git a/.out-of-scope/commit-gate-reuse-capability-loop-point.md b/.out-of-scope/commit-gate-reuse-capability-loop-point.md new file mode 100644 index 000000000..4e328053b --- /dev/null +++ b/.out-of-scope/commit-gate-reuse-capability-loop-point.md @@ -0,0 +1,88 @@ +# A parallel `commit_gates` config for artifact preconditions in `cmdCommit` + +**Source:** [#3353](https://github.com/open-gsd/gsd-core/issues/3353) +**Decision:** wontfix — closed as filed; the mechanism already exists in the capability gate system +**Date:** 2026-08-11 + +## Proposal summary + +#3353 asked for a declarative pre-commit gate evaluated inside `cmdCommit` +(`src/commands.cts`): a `commit_gates` array in `.planning/config.json` that matches files in the +commit's scope, runs a shell command against each match, blocks the commit on non-zero (before +staging, so a refusal leaves the index untouched), and is overridable via a CLI flag. The +motivation was concrete and real — a workflow can assert "do not commit while X holds" about an +artifact (e.g. an ungrounded `REVIEWS.md`), be entirely right, and watch the artifact get +committed anyway because the check lives only in the prompt and a model can report a stale or +skipped verdict as fresh. + +This entry denies **the `commit_gates` config as filed.** It does not deny the underlying need. + +## Why GSD does not own this (as filed) + +- **The exact mechanism already exists in the capability system.** Since + [#2008](https://github.com/open-gsd/gsd-core/issues/2008) / ADR-2008, a capability can declare a + `gates` entry with `check.predicate.kind: "command-exit-zero"` — "run your command, block the + loop on non-zero" — at a chosen loop point, with `blocking` and `onError` semantics and a `when` + config-key gate. See + [`docs/how-to/command-exit-zero-gate.md`](../docs/how-to/command-exit-zero-gate.md) and + [`docs/reference/gate-predicates.md`](../docs/reference/gate-predicates.md). The proposed + `commit_gates` shape (`command` + `block_on: "nonzero"` + match + override) is the same + mechanism in a different config. +- **A second config would fragment the architecture.** `commit_gates` in `.planning/config.json`, + fired from `cmdCommit`, would coexist with capability `gates` in `capability.json`, fired from + the loop-resolver — two config locations, two override paths, two evaluators, and ambiguity + about which fires when. GSD deliberately owns one gate system; the capability gate is it. +- **The right route is an extension of the existing system, not a parallel one.** There is **no + `commit:pre` loop point today.** The 12 canonical loop points + (`src/loop-resolver.cts` `CANONICAL_POINTS`: the `:pre`/`:post` pairs for `discuss`, `plan`, + `verify`, and `ship`, plus the four `execute` points — `execute:pre`, `execute:wave:pre`, + `execute:wave:post`, `execute:post`) do not include commit. The loop-point vocabulary is **closed but + additive-only** + ([`docs/reference/capability-manifest.md`](../docs/reference/capability-manifest.md)), so adding + a `commit:pre` point — and wiring `cmdCommit` to invoke the loop-resolver there — lets any + capability declare the existing `command-exit-zero` gate at commit time. That extends the system + you have rather than building a second one beside it. +- **EoS (ADR-1239) is unaffected either way.** `cmdCommit` is engine-internal; a pre-commit gate + touches none of the six host-integration interface points (command/dispatch/model/hooks/state/ + artifact are about host↔engine, not git internals). This is recorded only to head off the + misread that this decision is an EoS constraint — it is a capability-architecture constraint. + +## What this does NOT cover + +This entry denies **a `commit_gates` config separate from the capability gate system.** It does +not deny, and must never be cited against: + +- **Adding a `commit:pre` (and/or `commit:post`) loop extension point** so capabilities can + declare `command-exit-zero` gates at commit time. This is the route the filing should take, and + it is welcome as a capability-system proposal (new loop point + ADR-level schema note). +- **The companion defect.** [#3352](https://github.com/open-gsd/gsd-core/issues/3352) — reviewer + evidence is never verified, raw per-lane output is `rm -rf`'d, and an ungrounded `REVIEWS.md` + feeds `/gsd-plan-phase --reviews` — is confirmed-bug on its own merits and stays open. That a + full fix will likely *use* a commit-point gate does not make the `commit_gates` config the right + home for the gate mechanism. +- **New `check.predicate` kinds** added to the existing capability gate evaluator — a separate, + valid extension path. +- **Hardening `cmdCommit`'s existing git-level checks** (gitignore, branching strategy, staging + failures) — those are unrelated to declarative artifact preconditions. + +## Re-open criteria + +- A need is shown for a commit-time gate that the capability loop-point model genuinely cannot + express — e.g. a precondition that must fire when *no* capability is installed and that cannot + itself be a loop point. This is narrow: the `commit:pre` point + `command-exit-zero` predicate + covers the stated case (run a checker on a matched artifact, block on non-zero), so re-opening + requires the loop-point route to have been tried and found structurally insufficient. + +## Related + +- [#3352](https://github.com/open-gsd/gsd-core/issues/3352) — companion defect (confirmed-bug): + ungrounded `REVIEWS.md` is never verified then deleted +- [#2008](https://github.com/open-gsd/gsd-core/issues/2008) / ADR-2008 — the `command-exit-zero` + capability gate this decision points to +- [`docs/how-to/command-exit-zero-gate.md`](../docs/how-to/command-exit-zero-gate.md) — authoring + recipe +- [`docs/reference/gate-predicates.md`](../docs/reference/gate-predicates.md) — gate predicate + reference +- [`docs/reference/capability-manifest.md`](../docs/reference/capability-manifest.md) — the 12 + closed/additive-only loop points +- [ADR-1239](../docs/adr/1239-gsd-embeddable-orchestration-engine.md) — EoS (unaffected) diff --git a/.out-of-scope/eos-registry-not-in-tree-runtime.md b/.out-of-scope/eos-registry-not-in-tree-runtime.md new file mode 100644 index 000000000..642c53b55 --- /dev/null +++ b/.out-of-scope/eos-registry-not-in-tree-runtime.md @@ -0,0 +1,89 @@ +# New host runtimes as first-class in-tree registry entries + +**Source:** [#3346](https://github.com/open-gsd/gsd-core/issues/3346) +**Decision:** wontfix — closed as filed; redirected to the EoS Registry / out-of-tree host-plugin path +**Date:** 2026-08-11 + +## Proposal summary + +#3346 asked to add a `reasonix` runtime as a **first-party, in-tree** integration: a +`capabilities/reasonix/capability.json` descriptor merged into the generated runtime +`bin/lib/capability-registry.cjs`, so `gsd-tools` dispatch/isolation/effort queries resolve +when GSD runs inside "Reasonix." The stated motivation was that launcher skills picked up by +Reasonix reference tools/paths of another host, and dispatch resolves to the wrong integration. + +This is the same shape of ask as the OMP request: a previously-unsupported host proposed as a +new entry in the in-tree runtime registry GSD maintains itself. + +## Why GSD does not own this + +- **GSD is not expanding its in-tree supported-runtime set.** Each first-class runtime is a + permanent maintenance obligation across the registry, installer, artifact conversion, agent + discovery, model routing, dispatch isolation, golden install-parity fixtures, and localized + capability matrices — carried indefinitely for a host GSD does not control. This is the same + ground recorded for OMP (see [`omp-runtime-in-core.md`](./omp-runtime-in-core.md)). +- **The supported direction is the Embeddable Orchestration System (EoS), and it is already + available.** [ADR-1239](../docs/adr/1239-gsd-embeddable-orchestration-engine.md) exists + precisely so a host embeds GSD through a stable negotiated interface and a thin **host-plugin** + authored against the published Host-Integration SDK + ([`docs/how-to/author-a-host-plugin.md`](../docs/how-to/author-a-host-plugin.md)) — **without + modifying gsd-core source.** New hosts are listed in the + [EoS Registry](../docs/registries/eos-registry.md) (`docs/registries/eos.json`, `type: "eos"`), + the non-endorsing discoverability catalog, via a docs PR (`npm run gen:registry`). Existing + entries (`gsd-cursor`, `gsd-omp`) already follow this path. +- **The directly-analogous precedent is one month old and on point.** The Devin CLI request + ([#2170](https://github.com/open-gsd/gsd-core/issues/2170), closed not planned 2026-07-11) — a + genuinely new terminal coding agent proposed as a new runtime integration — was declined with + an explicit policy statement: *"The point of the EoS is to let people deploy and curate their + own integrations, not to have the maintainers continually monitor all the platforms and make + sure they work… If you want to use Devin, then you can build the extension for it."* Reasonix is + the same category of request. +- **The filed draft's load-bearing claim did not match the host's own documentation.** The + feature's entire justification — that Reasonix reads the `.agents/skills` and `.claude/skills` + convention roots — is contradicted by Reasonix's own SPEC.md/site, which describe + `~/.reasonix/skills/` and `.reasonix/commands/`. A registry entry must source every axis from + the host's authoritative docs per `docs/how-to/add-or-update-a-host-integration.md`'s "never + infer, guess, or assume" rule; the draft asserted values that the primary source contradicts. + This is recorded as a correction so a resubmission does not repeat it — not as an additional + ground for the decision, which holds on the EoS-direction ground alone. + +## What this does NOT cover + +This entry denies **first-party, in-tree runtime registration for new hosts.** It does not deny, +and must never be cited against: + +- **Shipping an out-of-tree host-plugin for Reasonix, or for any other host.** This is welcome + and supported, and is the intended route. A Reasonix plugin that embeds GSD via the + Host-Integration SDK and is listed in `docs/registries/eos.json` is exactly the path this + decision points to. +- **Feature capabilities** (`role: "feature"`) published out-of-tree under ADR-1244 — a different + axis (what loop behavior you add, not which runtime you are). +- **Fixing defects that surface through a non-registered runtime**, or improving the documented + override/SDK contracts a host plugin depends on. +- **Migrations of *already-supported* runtimes** onto the EoS architecture (the #2086/#2095/#2096/ + #2097/#2099 family). Those are lower-risk upgrades of hosts GSD already owns, not new-host + onboardings, and are unaffected by this decision. +- **Any existing runtime's support tier.** + +## Re-open criteria + +- GSD reopens first-class in-tree runtime registration — e.g. funded development changes the + maintenance calculus, or third-party `role: "runtime"` descriptors become loadable from outside + the repo (ADR-857 D8's deferred purely-additive external loader). Until one of these holds, the + answer for any new host is the EoS Registry, not the in-tree registry. +- A host demonstrates an integration need the EoS Host-Integration Interface genuinely cannot + express (none shown to date; Reasonix's real artifact needs map onto existing `skills`/`commands` + artifact kinds). + +## Related + +- [`omp-runtime-in-core.md`](./omp-runtime-in-core.md) — sibling decision; same ground (new host + as in-tree runtime), same redirect to EoS +- [ADR-1239](../docs/adr/1239-gsd-embeddable-orchestration-engine.md) — GSD as an Embeddable + Orchestration Engine (EoS) +- [`docs/how-to/author-a-host-plugin.md`](../docs/how-to/author-a-host-plugin.md) — the supported + out-of-tree authoring path +- [`docs/registries/README.md`](../docs/registries/README.md) — EoS Registry entry schema + + submission process +- [#2170](https://github.com/open-gsd/gsd-core/issues/2170) — Devin CLI runtime, the one-month-old + on-point precedent