step 6

2026-06-20 14:23:29 -05:00
parent f54cacd6cb
commit 3885774e5b
1 changed files with 158 additions and 0 deletions
@@ -0,0 +1,158 @@
 **Step 6 Results: Resource-First Discovery and Tool Fallback Contract**
 This section finalizes Step 6 by defining discovery behavior for clients that can attach MCP resources and the fallback behavior for clients or chat surfaces that must rely on MCP tools.
 ### Step Deliverable
 - Update the current `docs/` directory with the finalized Step 6 discovery and fallback contract content from this document.
 ### Primary Source Baseline (Repository Docs)
 Step 6 is based on the current project contracts in:
 1. `docs/architecture.md` (resource-first architecture and catalog role)
 2. `docs/usage.md` (operating flows, bounded loading, and fallback sequence)
 3. `docs/copilot.md` (client capability lanes and practical fallback behavior)
 4. `docs/mcp_layout.md` (shared content source and thin-tool fallback position)
 5. `docs/securing.md` (read-only/public-docs security invariant)
 Normative conclusions from those sources:
 1. Discovery stays resource-first.
 2. Tool fallback is allowed, thin, and read-only.
 3. Resources and tools must resolve to the same canonical authored markdown.
 4. Fallback behavior should keep context bounded and deterministic.
 ### Discovery Priority Contract (Normative)
 Preferred sequence for skill discovery and loading:
 1. `resource://catalog/skills_index`
 2. `resource://catalog/skills/{skill_id}`
 3. `resource://skills/{skill_id}/document`
 4. `resource://skills/{skill_id}/references/{ref_id}` only when needed
 Rules:
 1. Start from catalog discovery before loading any skill document.
 2. Do not skip straight to broad document loading when catalog metadata can narrow choices first.
 3. Use `resource://docs/{path*}` only for direct authored-doc access outside skill-specific flows.
 ### Fallback Activation Rule
 Fallback is used only when the active client path cannot reliably attach MCP resources (for example, tool-only chat surfaces).
 Rules:
 1. Keep the same discovery order semantics as the resource path.
 2. If resource attachment is available, prefer resources over tools.
 3. Tool fallback must never become a second authoritative content source.
 ### Tool Fallback Surface (Normative)
 The minimal read-only fallback tool set is:
 1. `search_patterns`
 2. `get_pattern_by_id`
 3. `get_skill_document_by_id`
 Fallback order:
 1. call `search_patterns` to find likely skills
 2. call `get_pattern_by_id` for one selected id when detail is needed
 3. call `get_skill_document_by_id` only for selected skill(s)
 Tool behavior requirements:
 1. read-only and idempotent semantics
 2. deterministic ordering and bounded pagination
 3. explicit not-found responses (`found: false` style) where applicable
 4. payloads remain schema-aligned with catalog resources
 ### Resources-As-Tools Compatibility Layer
 Step 6 may include a resources-as-tools compatibility layer for clients that can call tools but not attach resources.
 Rules:
 1. If enabled, it wraps canonical resource reads rather than re-implementing content transforms.
 2. It preserves canonical URIs and metadata semantics.
 3. It does not replace the minimal catalog tools listed above.
 4. It remains optional and interoperability-driven.
 ### Resource/Tool Parity Contract
 Resources and fallback tools must agree on identity and routing metadata.
 Parity requirements:
 1. `skill_id` and `ref_id` are identical across both paths.
 2. canonical URIs in payloads match Step 3 URI rules.
 3. skill metadata (`id`, `name`, `description`, `tags`, `capabilities`, `version`) remains consistent.
 4. document payload returned by `get_skill_document_by_id` resolves to the same canonical `SKILL.md` content as `resource://skills/{skill_id}/document`.
 ### Relevance and Ranking Contract
 Baseline matching behavior is metadata-first and deterministic.
 Rules:
 1. Search primarily over normalized skill metadata (id, name, description, tags).
 2. Keep deterministic ordering and deterministic pagination behavior.
 3. Keep ranking logic transparent and bounded for predictable client behavior.
 Optional extension policy:
 1. BM25/regex augmentation is allowed only when catalog/tool volume meaningfully harms token efficiency or precision.
 2. Any augmentation must preserve canonical ids, URIs, and deterministic tie-breaking.
 3. Any augmentation remains discovery-only and does not create alternate content payloads.
 ### Context-Bounding and Clarification Policy
 To prevent context bloat and improve answer quality:
 1. load only the most relevant skill document by default
 2. load at most two skill documents in one pass unless the user explicitly asks for more
 3. if confidence is low after catalog discovery, ask one clarifying question before loading additional skill documents
 4. fetch references lazily and only when required
 ### Security and Safety Constraints
 Fallback tools must preserve the project security invariant.
 Rules:
 1. tool surfaces stay documentation-only and read-only
 2. no mutation, shell execution, secret access, or private filesystem exposure
 3. all returned content remains safe to publish publicly
 ### Integration Boundaries
 Step 6 integrates with prior steps as follows:
 1. Step 4 provides the validated in-memory registry.
 2. Step 5 provides canonical resource registration.
 3. Step 6 adds fallback discovery/read behavior that reuses the same registry and canonical markdown sources.
 Separation-of-concerns rule:
 1. Catalog/resource contracts remain canonical.
 2. Fallback tools are interoperability adapters, not a parallel architecture.
 ### Acceptance Criteria for Step 6 Completion
 Step 6 is complete when all are true:
 1. Resource-first discovery remains the documented and implemented default path.
 2. The fallback tool set is minimal, read-only, and schema-aligned.
 3. Fallback tool outputs map to canonical skill identities and URIs.
 4. Context loading is bounded and clarifying-question behavior is documented for low-confidence cases.
 5. No second content source is introduced; resources and tools resolve the same authored markdown.
 ### Non-goals for Step 6
 1. No write or side-effecting tools.
 2. No alternate authored markdown stores or duplicated skill content pipelines.
 3. No guarantee that every client session exposes MCP resource attachment UI.
 4. No packaging/build contract changes (handled in Step 7).
 5. No CI gate expansion details (handled in later validation/governance steps).