Define the Wright domain-intelligence contract for agent workflows

[Teakowa]

Goal

Define the durable Wright-owned contract for exposing Workshop domain intelligence to coding agents and embedding consumers before implementation work expands the agent surface.

Context

Wright already owns agent/embedding workflows and semantic query surfaces, while canonical Workshop facts remain owned by workshop-rs and source-language semantics remain in their owning implementations.

A useful next product capability is context-sensitive domain intelligence: when an agent is working with a Workshop action, value, event, setting, or related semantic construct, Wright can expose the relevant canonical facts and bounded best-practice guidance on demand instead of requiring large static prompts or duplicated language knowledge.

The design needs a clear ownership split before implementation so factual semantics, Wright-curated guidance, source-language behavior, and agent presentation do not collapse into one unversioned knowledge layer.

Scope

• Define the product contract for querying domain intelligence through Wright agent/embedding surfaces.
• Define ownership and provenance for canonical Workshop facts and identities, source-language-specific semantic context, and human-authored best-practice guidance.
• Define a simple public distinction between owner-backed facts and guidance that deserves warning- or info-level attention without reusing lint diagnostics as semantic authority.
• Define how an agent selects or supplies semantic context so Wright can return only relevant information rather than a large static knowledge payload.
• Allow direct canonical queries without requiring a loaded source project; require project/provider context only where source-position resolution needs it.
• Define the boundary between durable machine-readable facts and human-authored guidance that may evolve independently.
• Start with a Wright-curated built-in guidance corpus while leaving external/community guidance sources for a separate source/distribution contract.
• Reuse existing Wright semantic/query/agent services and owner repositories rather than creating a second Workshop or source-language semantic store.
• Identify whether the accepted design changes a public/embedding contract enough to require a new ADR before implementation.

Non-goals

• Implementing the domain-intelligence service in this design issue.
• Embedding a specific LLM prompt or coding-agent product into Wright core.
• Copying canonical Workshop facts from workshop-rs into a Wright-owned shadow catalog.
• Moving OPY or DEL/OSTW semantics into Wright.
• Treating human guidance as correctness diagnostics or canonical semantic authority.
• Defining a detailed public evidence taxonomy or synthetic confidence score.
• Adding a domain-intelligence project-policy overlay.
• Loading arbitrary community/project guidance sources before trust, provenance, conflict, and update behavior are defined.
• Building a package manager, arbitrary plugin system, remote execution framework, or general-purpose knowledge database.
• Freezing token-cache or transport optimization before a real consumer contract exists.

Acceptance criteria

• A reviewed current contract defines what domain-intelligence queries return, what context selects them, and which repository owns each class of information.
• Canonical facts remain traceable to their owning semantic source rather than duplicated as Wright authority.
• Owner-backed facts remain clearly distinguishable from Wright-curated warning/info guidance, with provenance sufficient to identify their source.
• Direct canonical lookup does not require unnecessary project loading; source-position lookup may use owner/project context.
• The design supports incremental/on-demand agent context instead of requiring one monolithic static prompt payload.
• Agent, CLI, and embedding consumers can share the same Wright-owned query contract without each reimplementing Workshop knowledge lookup.
• Any new public/versioned contract or material architecture decision is identified for ADR recording before implementation proceeds.

Ownership

Wright owns product orchestration, semantic query composition, agent/embedding presentation, and the initial built-in guidance corpus. workshop-rs owns canonical Workshop facts and identities; opy-rs and deltin-rs own source-language semantics. Human-authored guidance must retain explicit provenance and must not become an implicit semantic authority.