Repository navigation
Conversation
Plan for schema-deferred direct-mode enumeration (Spec 102): dedicated direct_tool_response_mode config axis, FR-017 directCatalog snapshot design, describe_tool on the direct surface with listing-parity visibility, pre-dispatch validation reuse, frozen-golden handling, and file-touch list. Phase 0/1 artifacts: research.md, data-model.md, quickstart.md, contract. Related #971
Deploying mcpproxy-docs with
|
| Latest commit: |
4a683c1
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://eee59b2e.mcpproxy-docs.pages.dev |
| Branch Preview URL: | https://102-schema-deferred-plan.mcpproxy-docs.pages.dev |
|
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
…findings
Self-review + cross-model review pass over the stage-2 plan artifacts.
Every item below was verified against this tree before recording.
Corrections to false/incomplete claims:
- R11 (new): the {"type":"object"} placeholder is NOT what mcp.NewTool
produces. mcp-go v0.57.0's schema marshaller always writes properties:{}
and required:[], which re-opens the arg-pruning hazard FR-004 exists to
close. Deferred entries must use mcp.NewToolWithRawSchema with annotations
copied on explicitly; mixing RawInputSchema onto a NewTool result is a hard
marshal error, not a silent override. Verified empirically.
- R2: retracts "no golden pins describe_tool response bytes" — the
describe_plain_corpus gate pins 18 response bodies byte-for-byte. Added as
the FOURTH frozen gate with named describePlainDelta substitutions.
- R5: the surface-neutral prose rewrite covers FOUR retrieve_tools strings,
not one — both parameter descriptions and the two shared remediation
constants. tool_ids prose must also name the server__tool id form (FR-011).
- Test strategy: names TestDescribeTool_RegisteredInRetrieveToolsModeOnly's
"direct routing mode" subtest, which asserts the v1 decision this feature
reverses and will go red; and warns the new direct built-in gate must be
standalone, since DeltaIsEnumerated demands a pre099 baseline per surface.
- toolsListAllowedDelta needs no edit: describe_tool is already enumerated
there from spec 099.
Missed interactions now closed:
- D10: parity must hold on BOTH sides. The direct listing filters still
resolve via ParseDirectToolName's first-__ split, so a server named a__b
is judged as server a by the listing and as the real pair by a
catalog-backed describe — describable-but-unlisted, the exact FR-011
disclosure. Filters now resolve through the catalog. Also gated: the
preflight did_you_mean corpus (server-level filtered only, no permission
tier) and the definition-mode case-correction hint.
- D11: FR-007 instructions ignored the operator-configurable instructions
config key, which today reaches only the default server. Direct-server
instructions are now resolveInstructions(cfg) + the deferral legend.
- D12: upstream.Manager is concrete and lists only connected clients, so the
unit matrix had no seam. buildDirectModeTools splits into pure
buildDirectCatalog + renderDirectTools.
- Pre-dispatch validation placement pinned, including the started+completed
activity pair the 085 path emits (issue #969 blind-spot property).
- FR-014 guard: publish an empty catalog on DiscoverTools failure so a flip
during an upstream outage is not lost.
Related #971
…02 gates need The token gates were specified as "measure via the spec-083 profiler pipeline" with no implementation surface. bench/arms/ is a registry of encoding arms (baseline, compact_sig, toon, tron, tscg) that all render retrieve_tools result sets; none renders a direct tools/list, so the deferred measurement needs a new registered arm plus its testdata render golden. Added bench/arms/ to the file-touch list and the package count. Related #971
… the FR-007 instructions precedence in the summary Related #971
…return path; instructions hot-reload caveat stated buildDirectModeTools returns nil early when DiscoverTools fails (mcp_routing.go:81-85), so "append describe_tool inside tool-set construction" must mean every return path or the built-in vanishes on the first upstream hiccup. Also records that instructions are constructor-time on both server instances, so D11 does not promise hot-reload it cannot deliver. Related #971
…ture actually runnable The merge-base capture as written cannot run: the D12 pure seam does not exist at origin/main and DiscoverTools only returns tools from connected clients, so there is no way to render a deterministic direct listing there from a fixture slice. Replaced with a live stdio-fixture capture (the preflight_e2e_test.go / testdata/preflight_fixture_server.js harness, which runs unchanged at the merge-base) plus a same-tree differential fallback, with the trade-off stated. Related #971
📦 Build ArtifactsWorkflow Run: View Run Available Artifacts
How to DownloadOption 1: GitHub Web UI (easiest)
Option 2: GitHub CLI gh run download 33043150949 --repo smart-mcp-proxy/mcpproxy-go
|
…tually is The contract example showed create_issue(owner*:str, ...) while toolsig.Signature.Sig is the parenthesised parameter list only and carries no tool name (internal/toolsig/signature.go:18). Made the name prefix normative and recorded that Signature.Desc is deliberately unused here, since deferred entries keep the full description rather than the 085 first-sentence prefix. Related #971
…rral legend R4 and the contract carried two different draft legend texts. R4 now points at the contract as the single source so the pinned bytes have one origin. Related #971
Mirrors effectiveToolResponseMode (profile_resolver.go:57) so the renderer, the catalog's recorded serializationMode, and the FR-014 rebuild guard cannot resolve the mode by three different paths. Notes it takes no detail override, since tools/list has no parameters. Related #971
…nition annotations) buildFullToolEntry does not read annotations from the entry passed in: it calls p.lookupToolAnnotations (mcp.go:6344), which reads the StateView snapshot, and derives call_with from that, defaulting to ToolVariantRead on nil. A catalog-backed describe that synthesizes a ToolMetadata would therefore still resolve annotations out-of-band — so the listed pending/changed destructive tool SC-007 targets would describe with no annotations and call_with:"read". That is a wrong safety hint, not just a missing field. The definition-assembly seam now takes a catalog-supplied annotations override on the direct surface only, leaving the retrieve_tools path byte-identical for the frozen goldens. Related #971
…the direct check-mode corpus preflight.Scope is a server-name set, so the evaluator structurally cannot express the per-tool gate the direct listing applies — which is why did_you_mean leaks names the listing hides. The fix is concrete rather than aspirational: preflight.EvalContext.Index is an interface (preflight_glue.go:103 supplies preflightIndexReader), so the direct surface passes a catalog-backed reader and both id resolution and the suggestion corpus share one authority. Suppression demoted to fallback. Added preflight_glue.go to the file-touch list. Related #971
…tution row with D9-D12 D4/D5 rows and the Principle IV assessment still described the pre-hardening scope. Also records that all four direct routes share one p.directServer instance (GetMCPServerForMode), so a single SetTools covers the aliases. Related #971
…ndings Round 2 (opencode / gpt-5.6-sol). Every finding was re-verified against this tree before the fix. BLOCKER — catalog/registry publication skew (new R13, D13). The atomic.Pointer makes the catalog swap atomic but NOT the catalog-plus-mcp-go-registry pair: RefreshDirectModeTools publishes the catalog and then calls SetTools (mcp_routing.go:666-673), and mcp-go owns its own registry read, so no lock of ours can span both. Handler-to-schema atomicity does hold (closure capture); the filters and describe resolver are what skew. Closed by rule rather than denied: catalog published first, filters DENY on catalog miss (built-ins matched by an explicit name set — the previous fall-through wording would have let a stale entry skip the permission-tier gate during the window), describe additionally requires directServer.GetTool(name) != nil, plus a generation counter and an interleaving test. MAJOR — check-mode ids (D14). preflight.Evaluate accepts colon ids only (splitToolID, evaluator.go:500-510) and normalizeDescribeCheckIDs forwards ids verbatim, so every server__tool id under check:true would answer not_found no matter what the id gate does. The adapter now canonicalizes before Evaluate and restores the caller's original id and ordering in both response and activity. MINOR — server-level vs tool-level states. DiscoverTools drops disabled and quarantined SERVERS before projection (upstream/manager.go:1128-1138), so the "non-agent listings retain quarantined/disabled" claim was too broad: only pending / changed / tool-level-disabled reach the listing. MINOR — TestRetrieveToolsFullMode_GoldenByteIdentity pins TWO goldens (retrieve_full_default and retrieve_full_stats, mcp_entry_builder_test.go:116). Both are now listed as must-pass-unregenerated. Related #971
…empty one in the deny-on-miss rule Deny-on-miss would otherwise blank the listing before the first publication and break every hand-constructed test proxy that calls the direct filters directly. A nil pointer keeps today's ParseDirectToolName behavior; an empty published generation is real and denies. Related #971
… widen the research index Related #971
…icity claim R9 buys handler-to-schema atomicity only; a reader stopping there would carry away the over-broad claim R13 corrects. Related #971
…indings BLOCKER — D13 did not cover a same-name update. GetTool(name) != nil is satisfied by the old entry while the resolver uses the new catalog, so a schema edit or a flipped collision winner could be described one generation ahead of the registry. Generation stamping is not available (mcp.Tool's only free-form field marshals to _meta, which FR-015 freezes; mcp-go snapshots its tool map before our filters run), so the plan now promises a stated safety property instead of atomicity: SetTools first then publish, permission tier derived from the registered entry's OWN annotations (generation-correct by construction, closing the read-to-destructive over-permit), and the residual same-name staleness enumerated with tests for all four interleavings. MAJOR — the direct server registers nothing at init (mcp_routing.go:651-653, "built lazily... servers.changed will trigger a refresh"). Composing the built-in into rebuild construction alone leaves FR-009 false until the first refresh, worst with zero upstreams, and leaves the catalog nil so the first unrelated reload churns every client. Added D15/R14: an initial direct rebuild in initRoutingModeServers, and the built-in gate now asserts over p.directServer.ListTools() rather than the builder's return value. MAJOR — D11 imported resolveInstructions' defaultInstructions, whose DISCOVERY line says "Use 'retrieve_tools'" and whose CALLING line names call_tool_*, none of which exist on the direct surface. D16: operator text when set, otherwise a direct-specific default. MAJOR — the check-mode column used definition mode's vocabulary. Check mode answers status:"unavailable" plus a preflight.Reason (tool_pending_approval, tool_changed, tool_blocked_by_user, tool_denied_by_config, ...). The adapter now projects those through untouched, with a byte-compatibility test. Related #971
… chosen ordering The table still marked catalog-first as chosen after the round-3 fix reversed it. Rewritten with the same-name row added and the reasoning for SetTools-first made explicit: removal becomes window-free, addition fails closed. Related #971
…t publish Today buildDirectModeTools calls setDirectToolPermissions mid-build, before RefreshDirectModeTools reaches SetTools — the exact ordering R13 rule 1 reverses. Made the constraint explicit so the split in D12 does not carry the old publication point along with it. Related #971
…ocument Round 4 (opencode). Both findings were my own round-3 fixes not carried through. D13 rule 3 (tier from the registered entry's own annotations) had not reached data-model.md, which still routed the listing filters at the catalog's requiredPermission and still asserted "installed by one SetTools call (atomicity)" — the claim R13 retracted. The catalog now backs the (server,tool) split and the describe resolver only; the invariant is restated as R13's safety property. D16 had not reached plan.md, whose FR-007 summary and D11 row still mandated resolveInstructions — the function D16 exists to avoid. Named the single helper resolveDirectInstructions and dropped upstream_servers from the direct default: management tools are registered by the code-exec and call-tool builders only (mcp_routing.go:398, :507), so naming it would repeat the defect. Also records the init state transition (D15) in the data model. Related #971
…wing in Complexity Tracking R13 replaces the spec's literal "rebuilt atomically, so no window exposes one without the other" with a proven safety property, because the two publications straddle mcp-go's registry and cannot be made one transaction without forking it or taking the direct listing off SetTools. A plan that quietly weakens a spec MUST is exactly what review should catch, so the narrowing is now an explicit Complexity Tracking row flagged for the maintainer's assent at the tasks stage, not a silent reinterpretation buried in research. Related #971
…-5 finding) Round 5 showed D13 still had a hole: name-only GetTool membership cannot detect that the registered entry and the catalog entry describe different ORIGINS. A flipped collision winner could get scope-checked against server A while its handler dispatches to server B, and the describe path still took its tier from the catalog, so a read-scoped token could obtain a destructive tool's definition during the window. Two mechanisms close it, both verified against the tree: - Colliding display names are now WITHHELD outright rather than first-writer-wins. The spec sanctions this (resolve deterministically OR report it), and it is strictly safer than today, which is undefined rather than merely non-deterministic: buildDirectModeTools appends both and SetTools collapses them last-writer-wins over a map seeded by a map iteration of m.clients. - A name can still change origin without ever colliding (A removed and B added in one reconcile). Closed by a description discriminator: filters and the describe resolver compare the catalog entry's rendered description against the registered mcp.Tool.Description and fail closed on a mismatch. One string comparison, no wire change, and it subsumes the same-name schema-change case. The describe path also takes its tier from the GetTool result's annotations now, not the catalog. Residual narrows from served-stale to briefly-withheld — availability, not correctness. Interleaving tests go from four cases to five. Related #971
…or claim (round-6 finding)
The round-5 draft claimed the description discriminator "subsumes" the same-name
schema-change case. It does not: the direct description is
fmt.Sprintf("[%s] %s", ServerName, Description) (mcp_routing.go:95), so a
schema-only edit leaves it byte-identical, and in deferred mode the appended
signature is lossy by design so a nested-property change can render the same ~.
No field on the registered mcp.Tool encodes the schema in BOTH modes either --
deferred advertises the same {"type":"object"} placeholder for every tool -- and
Tool.Meta is wire-visible, so a hash stamp is closed off by FR-015.
The identity and origin hazards stay fully closed. The schema-only case is now
recorded as an explicit residual rather than claimed fixed, with its blast radius
argued rather than asserted: dispatch is never wrong (the handler validates
against the schema it captured), so an agent acting on a stale definition is
rejected by the pre-dispatch validator with the CORRECT schema embedded and
succeeds on one retry -- the US3/SC-003 self-healing path this feature ships. It
gets its own Complexity Tracking row flagged for maintainer assent, and a sixth
interleaving test that asserts the residual behaves as documented.
Also fixes two stale contradictions the same review surfaced: data-model.md still
labelled byDisplayName first-writer-wins, and R12's signature sketch still had
the builder publishing the catalog.
Related #971
…alog entry (round-7 finding) The R13 rule 5 discriminator compared "the catalog entry's rendered description" against the registered mcp.Tool.Description, but the catalog stored only the raw upstream description -- so the comparison implied a re-render. In deferred mode that suffix comes from toolsig.Cache, which mutates independently of any direct rebuild: Warm adds entries at index time and RetainHashes evicts them (internal/toolsig/cache.go:79, :108). A miss at registration followed by a hit at filter time, or the reverse, would flip the recomputed string with no generation change at all, manufacturing a false mismatch that leaves a still-registered tool unlisted and undescribable until the next rebuild. That is a persistent SC-007 violation -- strictly worse than the microsecond window the discriminator exists to police. renderDirectTools now records each entry's exact renderedDescription on the catalog before publication, and the discriminator compares two immutable snapshots. Two no-rebuild interleaving tests added: cache miss->warm and hit->eviction must both leave the tool listed and describable. Related #971
…e count reads straight Six cases had accumulated as five-plus-two-plus-a-sixth. Regrouped into closed-by-design, closed-by-withholding, and the documented residual, with the two no-rebuild cache cases called out separately as what they are: proof the discriminator reads the stored value. Related #971
…on API and the annotation defaults (round-8 findings) Cross-model review round 8 (two scoped opencode passes) returned five MAJORs and four MINORs; all nine verified genuine against the tree, none rejected. D13 rule 3 was wrong twice over. It told the filters and the describe resolver to derive the permission tier from the REGISTERED entry's annotations via contracts.DeriveCallWith "exactly as dispatch does". DeriveCallWith takes *config.ToolAnnotations, while the registered entry carries mcp.ToolAnnotation -- and mcp.NewTool seeds destructive=true on every tool, with each With...HintAnnotation overwriting only its own field. A read-only upstream tool therefore registers readOnlyHint=true AND the untouched destructiveHint=true, and DeriveCallWith gives destructive top priority: the rule would have classified nearly the whole catalog destructive, hiding it from every read- and write-scoped token while dispatch still admitted the call as read. The tier now comes from the catalog entry's upstream-derived requiredPermission -- identical to today's behavior and to dispatch's -- used behind the rule-5 discriminator. That makes an annotations-only change a third stated residual, bounded exactly like the schema-only one: the handler re-derives the tier from its own captured annotations, so no call is ever mis-authorized, only a listing can be stale. R13 rule 1 forbids the builder from publishing, but R12 still specified buildDirectModeTools as returning []ServerTool alone -- leaving the catalog it built unreachable and RefreshDirectModeTools with nothing to publish. It now returns (tools, catalog), non-nil on every path including the DiscoverTools error return. NewToolWithRawSchema leaves every annotation hint nil where NewTool seeds four defaults, so copying only the upstream hints would have made full and deferred modes marshal different annotations for the same tool (FR-004/FR-008). The deferred renderer now seeds mcp-go's defaults first. D15 publishes an empty catalog at init and FR-014 guards the reload, which together retire the nil-catalog unconditional rebuild -- an accidental self-heal for a dropped first servers.changed. SubscribeEvents is hoisted out of the listener goroutine into the constructor, ahead of StartBackgroundInitialization. Also: spec.md FR-017 gains a note pointing at the plan's three narrowings so the two documents stop contradicting each other (requirement text unchanged); rule-count drift fixed (five, not three/four) and two mislabelled rule-4 references corrected; the skew matrix is seven interleavings plus two no-rebuild cache cases, with the annotations-only case added; generation is given its two concrete uses and a data-model row instead of being vestigial; quickstart no longer promises a signature on every entry, which contradicted FR-005. Related #971
…iduals field by field (round-9 findings) Cross-model review round 9 re-reviewed the round-8 fixes and confirmed all nine, then found five more. All verified genuine, none rejected. The residual inventory was incomplete and the narrowing was under-declared. R13 now walks directCatalogEntry field by field and proves exactly three fields can move while leaving the rendered description byte-identical: paramsJSON, outputSchemaJSON and annotations. outputSchemaJSON was the one nobody had named, and it does not fit under the existing schema residual: nothing validates against an output schema, so the invalid_params self-healing retry that bounds the input case does not apply. Stated separately, with what actually bounds it -- output schemas are advisory shape metadata MCP permits to be absent entirely, so a stale one costs an agent one mis-shaped parse and is corrected at the next publish. The spec.md FR-017 note declared only the FR-017 deviation, while the annotations-only residual also relaxes FR-011 and SC-005 (a read-scoped token can briefly list a tool that just became destructive) and the two schema residuals relax SC-007. The note now names all of them, and repeats that call-time authorization is never stale -- the handler re-derives the tier from its own capture, so the call is refused even while the listing is not. Also: the contract still told implementers to copy annotations onto the raw-schema tool "explicitly", which is precisely the instruction round 8 found broken -- it now carries the seed-defaults-then-override rule. The publisher count was ambiguous (D12 said two builder call sites, D15 implied a second independent publisher); pinned to ONE publisher, RefreshDirectModeTools, which the initial rebuild calls rather than duplicating. Quickstart no longer claims the placeholder schema on every entry -- describe_tool keeps its real one. Related #971
…nto source and derived fields (round-10 finding) Round 10 confirmed the four other round-9 fixes and found the fifth over-claimed. R13's field walk concluded "nothing else on the entry can skew silently" after enumerating only the source fields; it skipped requiredPermission, which is a real directCatalogEntry field that moves without moving the rendered description. No new authorization hole -- requiredPermission is derived from annotations, whose residual already covers the behavior -- but the proof as written was invalid, and an invalid proof is worse than none when it is the thing licensing three declared residuals. The walk is now a two-part table. Source fields carry the visibility verdict: identity and description are visible by construction; paramsJSON is not reliably visible (never rendered in full mode, and a semantically-equal edit renders the identical Sig in deferred mode); outputSchemaJSON and annotations are never rendered at all. Derived fields are shown to add no independent axis: hash covers server, tool, description and both schemas but not annotations (hash.ToolHashWithOutputSchema), and requiredPermission is a pure function of annotations. Three independent source classes, which is exactly what the skew tests drive. Round 10 also confirmed the single-publisher pin is safe at construction time (DiscoverTools snapshots the manager under a read lock and skips disconnected clients) and judged the design converged, with no decision worth cutting. Related #971
…n precise (round-11 findings)
Round 11 found two precision defects in the round-10 proof. Both are about the
proof, not the behavior -- the three residuals and their bounds are unchanged --
but a partition that licenses three declared narrowings has to be exactly right.
The walk said renderedDescription is "a function of exactly two things",
description and the signature. It is not: full mode renders
fmt.Sprintf("[%s] %s", serverName, description) and deferred appends toolName
plus the Sig, so serverName, toolName, the serialization mode and the cache-hit
state are all inputs. Spelled out verbatim now, which also makes clear why the
origin flip is description-visible and why a mode flip is.
The walk's scope was also left implicit -- it covered directCatalogEntry while
the review criterion was the whole catalog. The catalog-level fields are now
accounted for explicitly: entries/byDisplayName/byCanonical are membership,
already covered by the add/remove/origin-flip/collision cases and by rules 2 and
4; serializationMode is visible (a flip adds or removes the whole suffix, which is
what FR-014 rebuilds on); generation is never rendered.
Second: the derived-field table said each "moves iff" its source moves. Only one
direction is needed and only one is true. requiredPermission reads solely
destructiveHint and readOnlyHint, so a title or idempotent edit moves annotations
without moving the tier; and the hash canonicalizes schemas, so a representational
schema edit moves neither hash nor cached signature. Restated as "cannot move
unless a source moves", with the converse explicitly disclaimed -- and the second
case turned to use: it is what makes the input-schema-only skew case constructible
in a test, so the test bullet now pins a canonicalization-equal edit.
Related #971
…ipe (round-12 finding) Round 11's tightening introduced a test that cannot exist. It told the input-schema skew case to use a "canonicalization-equal edit so the hash and cached signature genuinely do not move", while the same bullet requires dispatch to reject the stale-schema call and one retry to succeed. Those cannot both hold: hash parses and re-marshals the schema before hashing, so a canonicalization-equal edit is the same schema, the validator has nothing to reject, and the self-healing assertion is vacuous. This one changes what an engineer builds, not just how the paragraph reads. The recipe is now normative and matches the mechanism: the edit must be semantically different but signature-identical -- confined to nested properties the 085 grammar collapses to a ~ marker -- AND the new hash must be warmed into the signature cache before the rebuild renders, or Peek misses, the suffix vanishes, and the change becomes visible after all. The hash row in R13's derived table now says the same thing from the other direction: a representational edit is not a schema change, a semantic one always moves the hash, and that is precisely why the warm step is part of the case. Related #971
Five defects, each verified against the code or a running core rather than read
off the plan.
- **The FR-010 built-ins gate would not measure what it claims.** It asserts over
p.directServer.ListTools(), described as "what the server actually serves".
ListTools() is mcp-go's registration map (server/server.go:1032);
handleListTools serves filteredTools(ctx) (:1767), which applies every
WithToolFilter - and directServer is the one routing-mode server that carries
filters (filterDirectModeToolsForAuth, filterDirectToolsForAgentCallability,
added to directOpts and to no other server, mcp_routing.go:615-618). Left as
written the gate reproduces the D15/R14 mistake one level up: green while an
over-broad filter empties the real listing. Now: assert the registry AND drive
a real tools/list through the direct server, with any divergence a failure.
- **The same gate could not be byte-exact.** ListTools() returns a map and Go
randomizes map iteration, so a golden serialized straight from it is flaky.
Sort by tool name before serializing.
- **The frozen-gate list was missing its tightest member.**
TestDescribeTool_DefinitionTokenBudget (mcp_describe_tool_test.go:382) holds
describe_tool's definition to 250 tokens and it currently measures ~243. FR-009
exists to name both id forms in the description and in tool_ids - precisely the
edit that spends single-digit headroom. Added as gate 5 with its handling.
- **The quickstart's verification command cannot run.** Its bare tools/list POST
to /mcp/all answers "Invalid session ID" (reproduced against a live core):
/mcp/all is Streamable HTTP and needs initialize, the Mcp-Session-Id header and
notifications/initialized first, and its replies are SSE frames that must have
the "data: " prefix stripped before jq. Replaced with the working three-step
form.
- **spec.md overstated what the direct listing retains.** It said a non-agent
session's listing keeps tools that are "pending, changed, quarantined or
disabled". Server-level quarantine and disable never reach the projection at
all - DiscoverTools skips those clients ("Skipping quarantined client for tool
discovery", internal/upstream/manager.go), confirmed live on a quarantined
server. Only tool-level states are retained.
CLAUDE.md's Recent Changes line said "Added Go 1.24 module toolchain"; go.mod
says go 1.25.5.
83 tasks across 8 phases, organized by user story so US1+US2 (both P1) form the shippable increment and US3/US4 land independently after it. Phase 0 is blocking and is not busywork. plan.md's Complexity Tracking records three narrowings of normative spec MUSTs - FR-017's atomicity delivered as a safety property rather than a transaction, a schema-only change describable one generation stale, and an annotations-only change listed one generation stale - each ending "needs the maintainer's assent at the tasks stage". That stage is now, so T001-T003 make the assent an explicit gate and require the outcome to be written back into spec.md rather than left in the plan's appendix. T004 folds the D1/D2/D3 resolutions back into spec.md, which still carries [NEEDS CLARIFICATION] markers for questions the plan treats as decided. Phase 2 (the directCatalog) is the other hard gate: US1 renders from it, US2 resolves through it, US3 validates against it, US4 rebuilds it. D13 rule 1 is encoded structurally - the builder returns the catalog, the publisher swaps it after SetTools, and T017 fails if a swap happens inside the builder. Two plan corrections while writing the tasks: - The describe_tool prose rewrite is FIVE retrieve_tools-specific strings, not four. The plan said "four" while enumerating five (tool description :64, tool_ids :71, filters :82, describeNotFoundRemediation :50, and the inline malformed-id remediation :195). Verified against mcp_describe_tool.go; the count now matches the enumeration in all three places it appears. - research.md is D1-D16 / R1-R14, not D1-D8 / R1-R10, and tasks.md is no longer "NOT created by this plan". Related #971
Cross-model review (opencode/gpt-5.6) of tasks.md against plan.md. Three P1s, all of them ordering defects that would have surfaced as a blocked agent rather than a failing test. **Phase 2 depended on Phase 4 — through its own prerequisite.** T024 asserts a freshly initialized proxy already lists describe_tool, but the registration sat in Phase 4 (T037), so the foundational phase could not go green until the phase built on top of it had landed. The registration is a one-line append with no resolver behind it, so it moves to Phase 2 as T019b; the describe handler work stays in Phase 4. **No task changed makeDirectModeHandler's signature.** T020 updated call sites for a change nothing performed, and Phase 5's validation task consumed a captured catalog entry that nothing had captured. Added T019a. The closure capture is what makes R9's "a dispatch can never validate against a definition other than the one its own registration advertised" true, so it belongs in the foundational phase. **Phase 6 silently needed Phase 5.** T070's input-schema residual asserts the stale-schema case self-heals on one retry and T072 asserts no call succeeds against the wrong schema — both are pre-dispatch-validation behaviour, while the dependency section claimed US4 needed only the Phase 2 rebuild path. Also: - Phase 0 no longer blocks everything. The three approvals concern publication skew, stale schemas and stale annotations; none of them affects the config axis or toolsig.Peek. Only T004 gates Phase 1; T001-T003 gate their named dependents. - T014 bundled "neither is describable" into a Phase 2 collision test, where no resolver exists yet. Split: catalog assertions stay, describe lands as T046a. - T058 wrote a failing output_schema test AFTER T047 implemented it - a test that cannot fail first does not satisfy the constitution's test-first gate. Split to T046b, before its implementation. - T063/T064 split validation from its activity emission. Landing the first alone would reject calls that appear nowhere in the availability funnel - exactly the blind spot issue #969 established this handler must not have. Now one task. - Phase 3 claims a >=70% reduction in its independent test and had no task measuring it; the gate sat in Polish, outside the MVP that depends on it. Added T035a, and the MVP now names it. - [P] means "different file" by this document's own definition, and was on four groups that share one test file each (T028-T030, T042-T058, T059-T062, T067/T069). Removed there; the batching advice stays, since batchable and parallel are not the same thing. 88 tasks, up from 83.
# Conflicts: # ROADMAP.md
…MUST T001/T002/T003, decided by the maintainer. FR-017's third bullet claimed the advertised entry and its handler are "rebuilt atomically, so no window exposes one without the other". That was not deliverable: the entry lives in mcp-go's registry and the catalog in ours, and mcp-go reads its own tool map under its own lock before our filters run, so the two publications cannot be one transaction without forking it. The bullet now states what IS delivered — no request observes a state less restrictive than both generations, and no request gets a definition for a name the registry is not serving — and keeps literal the half that is literal: a handler validates against the definition its own registration captured, because it closes over it. The other two narrowings are accepted in the same amendment: a schema-only change may be described one generation stale (T002), and an annotations-only change may be listed one generation stale (T003). Each is accepted because of a compensating mechanism this feature ships, and the amendment says which: the input-schema case self-heals through the pre-dispatch validator (one retry succeeds); the annotations case cannot mis-authorize, because call-time authorization re-derives the tier from the handler's own captured annotations and never from the catalog; the output-schema case has no self-healing path and is accepted on its merits, since output schemas are advisory metadata MCP permits to be absent. Moved from the plan's appendix into the requirement text. A narrowing recorded only in an implementation note is one a reader discovers after trusting the MUST.
|
Superseded by #1063, which is now merged into This PR's branch ( It is being closed rather than merged for two reasons: it had become conflicting with Nothing is lost. Closing as superseded. |
Pull request was closed
Speckit stage 2 for Spec 102 (schema-deferred direct mode, issue #971 accepted direction): implementation plan + Phase 0/1 artifacts (research.md, data-model.md, quickstart.md, one contract).
Key decisions recorded (D1-D8): dedicated
direct_tool_response_modekey (defaultfull, flag + env parity); outputSchema deferred with additiveoutput_schemain describe_tool definitions; describe_tool batch cap stays 5; FR-007 convention via static direct-server instructions; FR-009 prose goes surface-neutral with a one-time enumerated regen of the two describe_tool-bearing goldens; FR-017directCatalogsnapshot (atomic swap, deterministic collision guard) shared by listing/signatures/describe/validation; catalog-backed direct describe resolver with listing-parity gates incl. the operation-permission tier; opt-in rollout, no default flip.Golden handling is explicit:
tools_list_prefeature,retrieve_full_default,pre099/, andcode_execution_modepass unregenerated; a new gate pins the direct surface's built-ins in both modes.Plan only — no tasks.md, no implementation. Related #971