From d2e727d3b3fb2ead172e11febbb2f30d534e5061 Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Wed, 5 Aug 2026 09:10:55 -0400 Subject: [PATCH] docs(#3074): correct adr-1671 mcp citation and stale runtime counts (#3080) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ADR-1671 attributed its MCP deferral to "ADR-857 §7 / #956" at five sites. Neither source supports it: docs/adr/857-capability-system.md contains zero MCP references (its Decision 7 is third-party code-loading, Decision 8 is Runtime-as-Capability), and #956 is the closed first-party MemPalace plugin pre-proposal that ADR-1239 explicitly disclaims in its own header. The deferral itself is sound on ADR-1671's own runtime-partial reasoning and never needed the borrowed citation. Ground it there, cross-reference ADR-1239 as the ADR that owns GSD's MCP surface, and record that a companion MCP server shipped 2026-06-28 with three tools - so "MCP is deferred" is not misread as "GSD has no MCP server". The deferral narrows to the served resources and prompts catalog (#3072). Also record that "deferred-tools", named alongside resources and prompts, is not a deferred surface but an unbuildable one: MCP defines three server primitives and the tools surface is tools/list plus tools/call, so schema deferral is host behavior, not a server capability (#3075). Correct two stale counts: 15 runtimes -> 19 (of 44 capability descriptors). The ADR-857 reference in Open questions is a genuine Phase-6 completion property and is deliberately left untouched. Closes #3074 Co-authored-by: sim --- ...671-dynamic-context-management-platform.md | 21 ++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/docs/adr/1671-dynamic-context-management-platform.md b/docs/adr/1671-dynamic-context-management-platform.md index c5a773264..e890f7872 100644 --- a/docs/adr/1671-dynamic-context-management-platform.md +++ b/docs/adr/1671-dynamic-context-management-platform.md @@ -3,7 +3,7 @@ - **Status:** Proposed - **Date:** 2026-06-24 - **Extends:** ADR-0002 (Command Contract Validation Module), ADR-457 (build-at-publish generation model for `bin/lib/*.cjs`) -- **Relates:** ADR-857 §7 (Connected-Capability / MCP contract — kept deferred by this ADR) +- **Relates:** [ADR-1239](1239-gsd-embeddable-orchestration-engine.md) (owns GSD's MCP surface — the companion `gsd-mcp-server`; this ADR defers only the served *content* catalog), ADR-857 (capability system — its Phase-6 completion property bounds workflow size, see Open questions) ## Context @@ -11,7 +11,7 @@ GSD ships command and workflow content as large, hand-edited Markdown files. Two 1. **Authoring is monolithic.** A single workflow body carries every branch inline. `gsd-core/workflows/plan-phase.md` is 93,973 bytes / 1,770 lines; `execute-phase.md` is 93,426 bytes. Mutually-exclusive paths (`--prd`, `--ingest`, `--mvp`, `--reviews`) all live in the same file, so a runtime loads guidance for branches a given invocation will never take. -2. **One payload ships to every runtime.** Install copies the whole `gsd-core/` tree (3.4 MB, 89 workflows, 1.7 MB) **byte-identical to all 15 runtimes** via `copyWithPathReplacement` (`bin/install.js`). The only per-runtime work is string rewrites and description truncation. There is **no per-runtime trimming or splitting**. +2. **One payload ships to every runtime.** Install copies the whole `gsd-core/` tree (3.4 MB, 89 workflows, 1.7 MB) **byte-identical to all 19 runtimes** (the capability descriptors carrying `role: runtime`, of 44 descriptors total) via `copyWithPathReplacement` (`bin/install.js`). The only per-runtime work is string rewrites and description truncation. There is **no per-runtime trimming or splitting**. The result is constant pressure against size caps, enforced today only against *source* files (not emitted output) by a two-part guard (issue #1074): a per-file baseline ratchet plus per-tier hard caps (workflows XL 96 KiB / LARGE 60 KiB / DEFAULT 40 KiB; agents XL 56 KiB / LARGE 48 KiB / DEFAULT 24 KiB). Several files have almost no headroom — `agents/gsd-verifier.md` has **293 bytes**. The one true emission-time cap, Windsurf's 12,000-byte limit (`src/runtime-artifact-conversion.cts`), is a hard `throw` with no graceful fallback. Adding one rule to a tight file forces an extract-to-`references/` refactor (`DEFECT.AGENT-FILE-SIZE-CAP-BREACH`), turning a one-line edit into a multi-file change that ripples across stub frontmatter, the workflow body, reference fragments, and `docs/` — each guarded by a different lint. @@ -30,7 +30,7 @@ Research into the codebase found that most JIT primitives are already present an ### External practice -The closest external analogs are Anthropic Agent Skills' three-tier progressive disclosure (metadata → `SKILL.md` → bundled references), MCP resources/prompts/deferred-tools (list-then-fetch JIT), and priority/token-budget prompt renderers (Priompt, VS Code `@vscode/prompt-tsx`) that include the highest-priority fragments that fit a budget via a binary-search cutoff, with `flexReserve` floors for load-bearing content and `` for a stable cacheable prefix. The portability catch is real and load-bearing: only the Skills *format* (directory + `SKILL.md` + frontmatter) is an open standard; native lazy loading is Claude-specific, and GSD's 15 runtimes do not all support skills or MCP (cf. surface-mismatch bugs #1614 antigravity, #1615 windsurf). +The closest external analogs are Anthropic Agent Skills' three-tier progressive disclosure (metadata → `SKILL.md` → bundled references), MCP resources/prompts/deferred-tools (list-then-fetch JIT), and priority/token-budget prompt renderers (Priompt, VS Code `@vscode/prompt-tsx`) that include the highest-priority fragments that fit a budget via a binary-search cutoff, with `flexReserve` floors for load-bearing content and `` for a stable cacheable prefix. The portability catch is real and load-bearing: only the Skills *format* (directory + `SKILL.md` + frontmatter) is an open standard; native lazy loading is Claude-specific, and GSD's 19 runtimes do not all support skills or MCP (cf. surface-mismatch bugs #1614 antigravity, #1615 windsurf). ## Decision @@ -46,7 +46,13 @@ Adopt a **dynamic context management platform** built on a hybrid of build-time 5. **Formalize the `CONTEXT.md` predicate fact-store → JIT selector.** Give the predicate grammar a parser (on `markdown-sectionizer`), an ID-uniqueness validator, a `--check`/`--write` drift-guard, and a `task → relevant predicate set` selector. This converts hand-assembled briefs into JIT-generated context and attacks the maintainer-side "edit a 200 KB file by hand" pain directly. **This is sequenced first** (see Prototype) because it is the smallest, lowest-risk piece that proves the whole pattern. -6. **Defer MCP (Connected-Capability).** Per ADR-857 §7 / #956, a served MCP catalog (resources/prompts/deferred-tools) remains an additive future enhancement for MCP-capable runtimes — never a replacement for the file-copy floor. Not in scope here. +6. **Defer the MCP served catalog.** A served MCP catalog remains an additive future enhancement for MCP-capable runtimes — never a replacement for the file-copy floor. Not in scope here. + + *The grounds are this ADR's own, not a borrowed citation.* MCP is runtime-partial (see **External practice** above, option D below, and the paragraph closing this section), so only build-time emission relieves caps on every runtime. Earlier revisions of this ADR attributed the deferral to "ADR-857 §7 / #956"; neither source supports it, and the deferral never needed either. `docs/adr/857-capability-system.md` contains no MCP content at all — its Decision 7 is third-party **code-loading** and its Decision 8 is Runtime/CLI-as-Capability — and #956 is the (closed) *first-party MemPalace plugin capability* pre-proposal, which [ADR-1239](1239-gsd-embeddable-orchestration-engine.md) explicitly disclaims in its own header ("Distinct from: #956"). Corrected by #3074. + + *This defers a content catalog, not MCP itself.* A companion MCP server shipped 2026-06-28 under [ADR-1239](1239-gsd-embeddable-orchestration-engine.md) (#1681 / PR #1809) — `package.json` bin `gsd-mcp-server` → `bin/gsd-mcp-server.js`, module `src/mcp-server.cts` — exposing three **tools**: `gsd_invoke_command`, `gsd_read_state`, `gsd_write_state`. ADR-1239 owns that surface; this ADR defers a different one over the same protocol. What is genuinely unbuilt is the served **resources** and **prompts** catalog, tracked in #3072. + + *"deferred-tools" is not deferred; it is unbuildable.* The **External practice** section above names "resources/prompts/deferred-tools" as the external list-then-fetch analog, and that phrase propagated into this decision. MCP defines exactly three server primitives — resources, prompts, and tools — and the tools surface is `tools/list` (cursor-paginated) plus `tools/call`. There is no server-side deferred-tools primitive; deferring tool *schemas* is host behavior, not a server capability. The list-then-fetch property this ADR wants is delivered by resources and prompts. Recorded in #3075 rather than carried here as a deliverable. ### Options considered @@ -55,7 +61,7 @@ Adopt a **dynamic context management platform** built on a hybrid of build-time | A. Progressive-disclosure authoring | Metadata-first files + one-level references; lean on host lazy-load | Partial; needs host lazy-load | Authoring universal; native JIT Claude-first | Adopt as a layer | | B. Build-time composer + per-runtime budget emission | Composer trims fragments to each runtime cap, emits right-sized files | Yes — measured before write | Universal floor | **Adopt as core** | | C. Run-time selection via init seam | Init bundle names which slices this invocation needs | Reduces per-invocation context | Broad (the `gsd_run` shim is universal) | Adopt after B | -| D. MCP served catalog | Serve content as resources/prompts/deferred-tools | For MCP hosts only | Partial; needs 2nd channel | Defer (ADR-857 §7) | +| D. MCP served catalog | Serve content as resources/prompts | For MCP hosts only | Partial; needs 2nd channel | Defer — runtime-partial (see Decision 6) | | E. Predicate fact-store → JIT selector | Parse/validate/select `CONTEXT.md` predicates | Maintainer-side big-file pain | N/A (build + orchestrator) | **Adopt first** | Pure Agent Skills (A alone) and pure MCP (D alone) were rejected as the foundation because both are runtime-partial; only build-time emission (B) relieves caps on every runtime. @@ -273,7 +279,7 @@ Sequenced to de-risk — prove the pattern on the smallest surface first, scale roughly nineteen, which is how a gate becomes something contributors route around. 6. **Wire the init bundle (C)** to emit a per-invocation sections manifest; workflows consume it. 7. **Roll out across LARGE/XL tiers**; update INVENTORY families + parity tests. -8. **(Deferred)** MCP served catalog (ADR-857 §7 / #956). +8. **(Deferred)** MCP served catalog — resources + prompts, served through the same composition seam as the file floor so the two channels cannot drift (#3072). Additive for MCP-capable hosts only; the file-copy floor stays the default (Decision 6). **Ordering landmine:** any generator consuming compiled output must run *after* `build:lib` (tsc), like `gen-plugin-skills` / `gen-capability-registry`; regenerating before `build:lib` silently drops unbuilt modules (`gsd-inventory-manifest-regen-needs-build`). @@ -352,4 +358,5 @@ Prototype scope notes: the parser is intentionally self-contained for the exampl - ADR-0002 — Command Contract Validation Module (the stub `` @-ref contract this platform's emission must keep satisfying). - ADR-457 — build-at-publish generation model (the codegen + drift-guard precedent the composer extends). -- ADR-857 §7 — Connected-Capability / MCP contract (the deferred served-catalog channel). +- [ADR-1239](1239-gsd-embeddable-orchestration-engine.md) — the ADR that owns GSD's MCP surface. It shipped the companion `gsd-mcp-server` (three tools) on 2026-06-28; the catalog this ADR defers (resources + prompts) is a different surface over the same protocol. +- ADR-857 — capability system. It carries **no** MCP content; earlier revisions of this ADR wrongly cited its §7 as the authority for the MCP deferral (corrected by #3074). Its genuine bearing here is the Phase-6 completion property that bounds workflow size, which constrained Phase 3's pilot (see Open questions).