From 157afae6fb62f8350cd00cdedb6174aa8fe7fc52 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9D=90=93=F0=9D=90=9E=F0=9D=90=9A=F0=9D=90=A4?= =?UTF-8?q?=F0=9D=90=A8=F0=9D=90=B0=F0=9D=90=9A?= <27560638+Teakowa@users.noreply.github.com> Date: Mon, 14 Sep 2026 14:24:30 +0800 Subject: [PATCH 1/8] docs: define domain intelligence contract --- docs/architecture/domain-intelligence.md | 100 +++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 docs/architecture/domain-intelligence.md diff --git a/docs/architecture/domain-intelligence.md b/docs/architecture/domain-intelligence.md new file mode 100644 index 00000000..f5e3067e --- /dev/null +++ b/docs/architecture/domain-intelligence.md @@ -0,0 +1,100 @@ +# Wright Domain Intelligence Contract + +Wright exposes Workshop domain intelligence as a composed query over existing semantic owners. It does not own a second Workshop catalog or a source-language semantic model. + +Decision history: [ADR-0016](../adr/0016-domain-intelligence-query-contract.md). + +## Purpose + +Agent, CLI, embedding, and transport consumers need bounded context about the semantic construct they are working with: canonical Workshop facts, relevant source-language context, evidence-backed guidance, and effective project policy. They obtain that context through one Wright-owned query contract instead of loading a monolithic prompt or reimplementing owner lookups. + +## Ownership + +| Information class | Authority | +| --- | --- | +| Canonical Workshop identities, signatures, settings, localization, gameplay facts, and other Workshop semantics | `workshop-rs` | +| OverPy syntax/semantic context and mapping from OverPy source constructs | `opy-rs` | +| DEL/OSTW syntax/semantic context and mapping from DEL/OSTW source constructs | `deltin-rs` | +| Domain-intelligence query composition, evidence envelope, first-party guidance policy, project-policy application, and product presentation | Wright | +| Human-authored guidance content | Its declared author/source; Wright curates and serves it but does not promote it to semantic authority | +| Project-specific enablement/preferences | The consuming project/configuration; Wright applies them without changing underlying evidence | + +A guidance document may refer to a canonical Workshop identity, but it must not restate copied catalog data as an independent authority. If a canonical fact is needed, the query resolves it from its owner. + +## Selection + +A domain-intelligence request selects a bounded semantic subject through one of two forms: + +1. **Canonical selection** supplies one or more opaque canonical identities issued by the owning Workshop contract. Localized display names are not identities. +2. **Source selection** supplies a language ID plus source/document identity and position. Wright delegates semantic resolution to the owning implementation or configured provider and composes the returned canonical subject references with any owner-supplied source context. + +Wright must not infer a source selection with textual matching when the owner cannot resolve it. Missing owner capability is an explicit unavailable result. + +The logical request shape is: + +```text +DomainIntelligenceRequest + selector = Canonical([SemanticRef...]) + | Source(language_id, document, position) + include = facts | source_context | guidance | policy +``` + +`include` is a projection over the selected subjects. The service does not return the complete guidance corpus or catalog by default. + +## Response model + +The shared result is structured rather than prompt text: + +```text +DomainIntelligenceResult + subjects[] + facts[] + source_context[] + guidance[] + policy[] + unavailable[] +``` + +Each subject carries its owner, semantic kind, canonical or owner-specific identity, and presentation metadata when available. Wright may join information by stable owner identity, but it does not invent a cross-language semantic identity when no owner mapping exists. + +`facts` contain machine-readable owner-backed data. `source_context` contains source-owner information needed to explain how the selected source construct relates to the subject. Wright standardizes the envelope and provenance, not the source language's internal semantic model. + +`guidance` contains human-authored recommendations, caveats, or usage patterns. Guidance has a stable guidance ID, applicability to semantic subjects, provenance/evidence references, limitations, and human-readable content. Guidance remains independently editable from canonical facts. + +`policy` reports only the effective project/consumer policy relevant to the selected guidance or query. Policy may select, suppress, or rank guidance, but it cannot rewrite canonical facts, provenance, or evidence classification. + +`unavailable` reports missing owner capability or unavailable evidence explicitly. Wright does not guess a replacement fact or silently downgrade to text matching. + +## Evidence and provenance + +Every returned fact or guidance item declares its evidence class and provenance. The durable evidence classes are: + +- `exact`: owner-backed semantic fact or invariant; +- `static_metric`: deterministic measurement of the current program/artifact; +- `runtime_evidence`: observation from an identified Workshop/runtime experiment; +- `heuristic`: bounded inference with documented limitations and false-positive risk; +- `community_guidance`: experience-backed recommendation that is not semantic authority. + +Evidence class and authority are the confidence contract. Wright does not assign a synthetic numeric confidence score. Human-authored metadata cannot self-promote a heuristic or community claim to `exact`. + +Provenance must identify the responsible owner/source and a traceable locator or evidence reference where one exists. Runtime and community claims require enough provenance to distinguish them from canonical semantics. + +## Public service boundary + +The shared product operation is `domainIntelligence` on Wright's existing session-aware tool/query service. CLI, embedding, stdio/JSON-RPC, and future agent adapters reuse that operation rather than creating agent-specific semantics. + +The operation is additive within the existing `wright-embedding/v1` / `wright-result/v1` compatibility rules. Adding it does not require a new major contract version; removing or incompatibly changing its declared fields does. + +Existing `targetMetadata` remains a catalog/discovery summary. It is not the domain-intelligence contract because it exposes broad target metadata rather than a selected, provenance-bearing composition of facts and guidance. + +## Provider boundary + +This contract does not require LPP to grow a source-selection method before evidence demands it. An in-process owner or provider may support source selection through an owner-backed semantic query. If a configured provider cannot resolve a source position to semantic subjects, Wright returns the capability gap explicitly. + +A future LPP source-selection capability is a separate protocol decision and must preserve the same ownership rule: the provider resolves source-language meaning; Wright composes product context. + +## Guidance boundary + +First-party guidance is distributed as human-authored content plus machine-readable identity, applicability, evidence, provenance, and limitation metadata. Its storage syntax and distribution mechanism are not semantic contracts and may evolve without moving canonical Workshop facts into Wright. + +Wright does not require a package manager, executable plugin runtime, remote knowledge database, or prompt template to serve this contract. Those mechanisms require separate evidence and decisions. \ No newline at end of file From d3aa7f4b883379025738b1ad834d647f821d6b09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9D=90=93=F0=9D=90=9E=F0=9D=90=9A=F0=9D=90=A4?= =?UTF-8?q?=F0=9D=90=A8=F0=9D=90=B0=F0=9D=90=9A?= <27560638+Teakowa@users.noreply.github.com> Date: Mon, 14 Sep 2026 14:24:54 +0800 Subject: [PATCH 2/8] docs: record domain intelligence architecture decision --- ...0016-domain-intelligence-query-contract.md | 66 +++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 docs/adr/0016-domain-intelligence-query-contract.md diff --git a/docs/adr/0016-domain-intelligence-query-contract.md b/docs/adr/0016-domain-intelligence-query-contract.md new file mode 100644 index 00000000..0b00162c --- /dev/null +++ b/docs/adr/0016-domain-intelligence-query-contract.md @@ -0,0 +1,66 @@ +# ADR-0016: Domain-intelligence query contract + +- Status: Proposed +- Date: 2026-09-14 +- Related: [Issue #323](https://github.com/wrightkit/wright/issues/323), [ADR-0010](0010-independent-implementations-and-wright-integration.md), [ADR-0015](0015-canonical-facts-and-declarative-lint-policy.md) + +## Context + +Wright already exposes a session-aware tool service for CLI, embedding, and transport consumers. Its `targetMetadata` operation is a broad catalog summary, while ADR-0015 separates owner-backed canonical facts from Wright lint/policy and evidence classification. + +Agent workflows need a narrower capability: given the semantic construct currently being worked on, retrieve only the relevant Workshop facts, source-owner context, evidence-backed guidance, and project policy. Serving that through static prompts or copied metadata would duplicate semantic authority, make provenance ambiguous, and force each consumer to implement its own lookup behavior. + +The design must also support human-authored best practices without allowing community guidance to become an implicit correctness specification. + +## Decision + +Wright adds one product-level domain-intelligence composition contract with these rules: + +1. **The service is a query, not a semantic store.** Canonical Workshop facts and identities are resolved from `workshop-rs`; source-language meaning is resolved by the source owner. Wright owns composition and presentation. +2. **Selection is semantic and bounded.** A request selects canonical owner identities directly, or supplies a source location that an owning implementation/provider resolves to semantic subjects. Wright does not fall back to textual guessing when source resolution is unavailable. +3. **Responses keep information classes separate.** The shared result has subject, fact, source-context, guidance, project-policy, and unavailable sections. Wright standardizes their envelope and provenance but does not normalize source-language internals into a new cross-language semantic model. +4. **Evidence is explicit.** Returned items distinguish `exact`, `static_metric`, `runtime_evidence`, `heuristic`, and `community_guidance`. Evidence class plus authority is the confidence contract; no synthetic numeric confidence score is introduced. +5. **Human guidance stays separate from canonical facts.** Guidance is authored as content plus stable identity, applicability, evidence/provenance, and limitations. Wright may curate and distribute first-party guidance, but guidance cannot self-promote to canonical semantics. +6. **Project policy is an overlay.** It may select, suppress, or rank guidance for a consumer/project, but it cannot rewrite facts, provenance, or evidence classification. +7. **All product consumers reuse the same operation.** `domainIntelligence` belongs on the existing session-aware Wright tool/query service. CLI, embedding, stdio/JSON-RPC, and future agent adapters remain thin consumers of that contract. +8. **The change is additive to the existing v1 embedding/result compatibility rules.** A new major contract version is not required solely to add the operation. +9. **LPP is not extended pre-emptively.** Provider-backed source selection may expose a future protocol gap; until evidence requires a wire capability, unsupported source selection is reported explicitly rather than forcing a speculative LPP extension. + +`targetMetadata` remains a broad target/catalog discovery summary and is not repurposed as the domain-intelligence operation. + +## Alternatives considered + +- **Reuse `targetMetadata` and add more fields:** rejected because a bulk catalog response does not express semantic selection, source-owner resolution, guidance provenance, or project policy, and would trend toward a monolithic agent payload. +- **Copy Workshop facts into Wright guidance assets:** rejected because it creates a shadow semantic authority that can drift from `workshop-rs`. +- **Put best-practice guidance in `workshop-rs`:** rejected because community heuristics and product guidance are not canonical Workshop semantics. +- **Create a general knowledge database, plugin runtime, or package manager first:** rejected because no current consumer evidence requires those mechanisms and they add independent versioning/distribution concerns. +- **Extend LPP first:** deferred because canonical identity queries and in-process owner integrations do not require a new wire method; a provider protocol change should follow an observed provider-backed source-selection need. +- **Embed prompt-ready text in Wright core:** rejected because prompt formatting is consumer presentation, while the durable contract should remain structured and reusable across CLI, embedding, and other agents. + +## Consequences + +- Agents can request small, context-specific payloads instead of loading the entire Workshop knowledge surface. +- Canonical facts remain owned and updated where their semantics live. +- Community guidance can evolve independently while retaining explicit evidence and limitations. +- Source-owner capability gaps remain visible rather than being hidden by Wright text heuristics. +- Implementation must add a public operation/result shape and provide contract tests across the shared tool service and transport adapters. +- A provider-backed source selector may later require a separate LPP decision, but that work is not required by this ADR. + +## Compatibility impact + +The decision adds a new public query operation without changing source-language syntax, Workshop semantics, compiler lowering, diagnostics, or existing query behavior. Under the current embedding/result versioning rules, adding the operation is compatible within major version 1. + +Implementation evidence must show that direct/in-process and transport consumers observe the same structured result, owner facts are not duplicated as Wright authority, and unavailable owner capabilities are surfaced explicitly. + +## Scope boundaries + +This ADR does not decide: + +- the storage path or serialization syntax used to author first-party guidance; +- remote guidance distribution, registries, or executable plugins; +- prompt templates or token-cache optimization; +- a new LPP method for semantic selection; +- automatic source edits based on guidance; +- whether every source-language construct can map to a canonical Workshop identity. + +Those decisions require separate concrete consumer or provider evidence. \ No newline at end of file From 50063a1a2c7922ca251d176002994c0514b02d0d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9D=90=93=F0=9D=90=9E=F0=9D=90=9A=F0=9D=90=A4?= =?UTF-8?q?=F0=9D=90=A8=F0=9D=90=B0=F0=9D=90=9A?= <27560638+Teakowa@users.noreply.github.com> Date: Mon, 14 Sep 2026 14:25:03 +0800 Subject: [PATCH 3/8] docs: route domain intelligence architecture --- docs/architecture/README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/architecture/README.md b/docs/architecture/README.md index ce81d07d..d5acedb8 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -16,6 +16,7 @@ Keep these evidence classes separate: | Product/repository ownership and dependency direction | [`ownership.md`](ownership.md) | | Language/provider integration and failure routing | [`integration.md`](integration.md) | | Wright-owned lint/analyze/inspect/edit/agent/CI/LSP tooling model | [`tooling.md`](tooling.md) | +| On-demand Workshop domain intelligence for agent/embedding consumers | [`domain-intelligence.md`](domain-intelligence.md) | | CLI/driver behavior | [`../cli.md`](../cli.md) | | Embedding/tool API | [`../embedding.md`](../embedding.md) | | Language services/LSP | [`../language-services.md`](../language-services.md) | From 038e36b2645feec3ecb1781730456956260b9b75 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9D=90=93=F0=9D=90=9E=F0=9D=90=9A=F0=9D=90=A4?= =?UTF-8?q?=F0=9D=90=A8=F0=9D=90=B0=F0=9D=90=9A?= <27560638+Teakowa@users.noreply.github.com> Date: Mon, 14 Sep 2026 14:25:13 +0800 Subject: [PATCH 4/8] docs: index domain intelligence ADR --- docs/adr/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/adr/README.md b/docs/adr/README.md index aab921c5..02ec28db 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -35,4 +35,5 @@ audit date. * [ADR-0013: Entry-based source-provider integration seam](0013-entry-based-source-provider-seam.md) * [ADR-0014: Repository-namespaced immutable R2 release artifacts](0014-namespaced-immutable-r2-artifacts.md) * [ADR-0015: Canonical facts, declarative lint rules, and project policy](0015-canonical-facts-and-declarative-lint-policy.md) -* [Post-ADR-0010 decision inventory](post-0010-inventory.md) +* [ADR-0016: Domain-intelligence query contract](0016-domain-intelligence-query-contract.md) +* [Post-ADR-0010 decision inventory](post-0010-inventory.md) \ No newline at end of file From e5b653a10a340fbd8ddcc9e4e38dac63b532f4af Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9D=90=93=F0=9D=90=9E=F0=9D=90=9A=F0=9D=90=A4?= =?UTF-8?q?=F0=9D=90=A8=F0=9D=90=B0=F0=9D=90=9A?= <27560638+Teakowa@users.noreply.github.com> Date: Mon, 14 Sep 2026 14:25:24 +0800 Subject: [PATCH 5/8] docs: integrate domain intelligence tooling boundary --- docs/architecture/tooling.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/docs/architecture/tooling.md b/docs/architecture/tooling.md index 297fa0a2..4caa0b4e 100644 --- a/docs/architecture/tooling.md +++ b/docs/architecture/tooling.md @@ -3,9 +3,11 @@ Wright owns cross-language product tooling over semantic information supplied by the owning implementations and canonical Workshop. Decision history: the distinct command workflows are recorded in -[ADR-0011](../adr/0011-distinct-tooling-workflows.md), and the canonical-facts +[ADR-0011](../adr/0011-distinct-tooling-workflows.md), the canonical-facts and lint-policy split is recorded in -[ADR-0015](../adr/0015-canonical-facts-and-declarative-lint-policy.md). +[ADR-0015](../adr/0015-canonical-facts-and-declarative-lint-policy.md), and +on-demand domain-intelligence composition is recorded in +[ADR-0016](../adr/0016-domain-intelligence-query-contract.md). ## Tooling surfaces @@ -51,6 +53,8 @@ Normal source tooling does not require full-file regeneration. Preserve comments CLI, LSP, agent/MCP-style adapters, embedding, and CI should reuse common Wright-owned semantic/query/edit services rather than each implementing language-specific logic independently. +On-demand domain intelligence follows the same rule: Wright composes owner-backed semantic identities and facts with separately provenance-bearing guidance and project policy through the shared query service. It does not copy canonical Workshop facts into an agent-specific knowledge store. See [`domain-intelligence.md`](domain-intelligence.md). + Machine-readable contracts are versioned and deterministic when declared. Presentation layers must not alter semantic outcomes. ## Lint and analysis evidence @@ -63,4 +67,4 @@ Wright owns the product UX, not the source-language compiler semantics. Source→Workshop combines source-owner semantics/lowering with `workshop-rs` canonical validation/emission. Workshop→OPY/DEL reconstruction belongs to the respective source implementation. Direct OPY↔DEL translation is optional and should not drive architecture for symmetry. -A command may exist before every source construct is supported; capability claims must follow owner + integration evidence. +A command may exist before every source construct is supported; capability claims must follow owner + integration evidence. \ No newline at end of file From fcf419a2ba489c252dd802a7ce0eccef4574038b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9D=90=93=F0=9D=90=9E=F0=9D=90=9A=F0=9D=90=A4?= =?UTF-8?q?=F0=9D=90=A8=F0=9D=90=B0=F0=9D=90=9A?= <27560638+Teakowa@users.noreply.github.com> Date: Mon, 14 Sep 2026 14:53:08 +0800 Subject: [PATCH 6/8] docs: refine domain intelligence contract --- docs/architecture/domain-intelligence.md | 57 +++++++++++++----------- 1 file changed, 30 insertions(+), 27 deletions(-) diff --git a/docs/architecture/domain-intelligence.md b/docs/architecture/domain-intelligence.md index f5e3067e..9e0c5ea8 100644 --- a/docs/architecture/domain-intelligence.md +++ b/docs/architecture/domain-intelligence.md @@ -6,7 +6,7 @@ Decision history: [ADR-0016](../adr/0016-domain-intelligence-query-contract.md). ## Purpose -Agent, CLI, embedding, and transport consumers need bounded context about the semantic construct they are working with: canonical Workshop facts, relevant source-language context, evidence-backed guidance, and effective project policy. They obtain that context through one Wright-owned query contract instead of loading a monolithic prompt or reimplementing owner lookups. +Agent, CLI, embedding, and transport consumers need bounded context about the semantic construct they are working with: canonical Workshop facts, relevant source-language context, and practical guidance. They obtain that context through one Wright-owned query contract instead of loading a monolithic prompt or reimplementing owner lookups. ## Ownership @@ -15,18 +15,19 @@ Agent, CLI, embedding, and transport consumers need bounded context about the se | Canonical Workshop identities, signatures, settings, localization, gameplay facts, and other Workshop semantics | `workshop-rs` | | OverPy syntax/semantic context and mapping from OverPy source constructs | `opy-rs` | | DEL/OSTW syntax/semantic context and mapping from DEL/OSTW source constructs | `deltin-rs` | -| Domain-intelligence query composition, evidence envelope, first-party guidance policy, project-policy application, and product presentation | Wright | -| Human-authored guidance content | Its declared author/source; Wright curates and serves it but does not promote it to semantic authority | -| Project-specific enablement/preferences | The consuming project/configuration; Wright applies them without changing underlying evidence | +| Domain-intelligence query composition, public result contract, built-in guidance curation, and product presentation | Wright | +| Built-in human-authored guidance | Wright-curated first-party corpus; it remains guidance rather than semantic authority | -A guidance document may refer to a canonical Workshop identity, but it must not restate copied catalog data as an independent authority. If a canonical fact is needed, the query resolves it from its owner. +A guidance item may refer to a canonical Workshop identity, but it must not restate copied catalog data as an independent authority. If a canonical fact is needed, the query resolves it from its owner. + +External or project-configured guidance sources are not part of the initial contract. A future source/distribution contract may add them without changing canonical ownership, but Wright does not accept arbitrary guidance sources until trust, provenance, conflict, and update behavior are defined. ## Selection A domain-intelligence request selects a bounded semantic subject through one of two forms: -1. **Canonical selection** supplies one or more opaque canonical identities issued by the owning Workshop contract. Localized display names are not identities. -2. **Source selection** supplies a language ID plus source/document identity and position. Wright delegates semantic resolution to the owning implementation or configured provider and composes the returned canonical subject references with any owner-supplied source context. +1. **Canonical selection** supplies one or more opaque canonical identities issued by the owning Workshop contract. Localized display names are not identities. Canonical selection does not require a loaded source project. +2. **Source selection** supplies a language ID plus source/document identity and position. Wright delegates semantic resolution to the owning implementation or configured provider and composes the returned canonical subject references with any owner-supplied source context. Source selection requires the relevant project/provider context. Wright must not infer a source selection with textual matching when the owner cannot resolve it. Missing owner capability is an explicit unavailable result. @@ -36,7 +37,7 @@ The logical request shape is: DomainIntelligenceRequest selector = Canonical([SemanticRef...]) | Source(language_id, document, position) - include = facts | source_context | guidance | policy + include = items | source_context ``` `include` is a projection over the selected subjects. The service does not return the complete guidance corpus or catalog by default. @@ -48,40 +49,40 @@ The shared result is structured rather than prompt text: ```text DomainIntelligenceResult subjects[] - facts[] + items[] source_context[] - guidance[] - policy[] unavailable[] ``` Each subject carries its owner, semantic kind, canonical or owner-specific identity, and presentation metadata when available. Wright may join information by stable owner identity, but it does not invent a cross-language semantic identity when no owner mapping exists. -`facts` contain machine-readable owner-backed data. `source_context` contains source-owner information needed to explain how the selected source construct relates to the subject. Wright standardizes the envelope and provenance, not the source language's internal semantic model. +Each `item` has one simple public classification: + +- `fact`: owner-backed factual information about the selected semantic subject; +- `warning`: Wright-curated guidance about a meaningful risk, cost, or behavior that commonly deserves attention; +- `info`: Wright-curated recommendation, usage pattern, caveat, or explanatory context. -`guidance` contains human-authored recommendations, caveats, or usage patterns. Guidance has a stable guidance ID, applicability to semantic subjects, provenance/evidence references, limitations, and human-readable content. Guidance remains independently editable from canonical facts. +These classifications are domain-intelligence presentation semantics, not lint/diagnostic severity. A `fact` is not an error, and `warning`/`info` guidance does not become a correctness diagnostic merely because it is returned by the query. -`policy` reports only the effective project/consumer policy relevant to the selected guidance or query. Policy may select, suppress, or rank guidance, but it cannot rewrite canonical facts, provenance, or evidence classification. +Facts remain machine-readable where the owner exposes structured data. Guidance has a stable guidance ID, applicability to semantic subjects, provenance, limitations when needed, and human-readable content. Guidance remains independently editable from canonical facts. -`unavailable` reports missing owner capability or unavailable evidence explicitly. Wright does not guess a replacement fact or silently downgrade to text matching. +`source_context` contains source-owner information needed to explain how the selected source construct relates to the subject. Wright standardizes the envelope and provenance, not the source language's internal semantic model. -## Evidence and provenance +`unavailable` reports missing owner capability or unavailable source context explicitly. Wright does not guess a replacement fact or silently downgrade to text matching. -Every returned fact or guidance item declares its evidence class and provenance. The durable evidence classes are: +## Provenance -- `exact`: owner-backed semantic fact or invariant; -- `static_metric`: deterministic measurement of the current program/artifact; -- `runtime_evidence`: observation from an identified Workshop/runtime experiment; -- `heuristic`: bounded inference with documented limitations and false-positive risk; -- `community_guidance`: experience-backed recommendation that is not semantic authority. +Every returned item identifies its responsible owner or guidance source and carries a traceable locator or evidence reference where one exists. -Evidence class and authority are the confidence contract. Wright does not assign a synthetic numeric confidence score. Human-authored metadata cannot self-promote a heuristic or community claim to `exact`. +The public query contract does not require consumers to understand a detailed evidence taxonomy such as runtime evidence, heuristic, or community guidance, and it does not assign synthetic numeric confidence scores. Richer evidence metadata may exist in the owning fact source or guidance corpus for curation and review, but it does not replace the simple `fact` / `warning` / `info` contract. -Provenance must identify the responsible owner/source and a traceable locator or evidence reference where one exists. Runtime and community claims require enough provenance to distinguish them from canonical semantics. +Human-authored guidance cannot self-promote to a canonical fact. Provenance must remain sufficient to tell owner-backed facts from Wright-curated guidance. ## Public service boundary -The shared product operation is `domainIntelligence` on Wright's existing session-aware tool/query service. CLI, embedding, stdio/JSON-RPC, and future agent adapters reuse that operation rather than creating agent-specific semantics. +The shared product operation is `domainIntelligence` on Wright's common query/tooling surface. CLI, embedding, stdio/JSON-RPC, and future agent adapters reuse that operation rather than creating agent-specific semantics. + +The operation may be exposed through the existing ToolService facade, but canonical selection must not require an eagerly loaded project session. Source selection may use session/provider state because resolving source positions is inherently project- and owner-dependent. The operation is additive within the existing `wright-embedding/v1` / `wright-result/v1` compatibility rules. Adding it does not require a new major contract version; removing or incompatibly changing its declared fields does. @@ -95,6 +96,8 @@ A future LPP source-selection capability is a separate protocol decision and mus ## Guidance boundary -First-party guidance is distributed as human-authored content plus machine-readable identity, applicability, evidence, provenance, and limitation metadata. Its storage syntax and distribution mechanism are not semantic contracts and may evolve without moving canonical Workshop facts into Wright. +The initial built-in guidance corpus is curated by Wright. Guidance is human-authored content plus machine-readable identity, semantic applicability, provenance, and limitations where needed. Its storage syntax and distribution mechanism are not semantic contracts and may evolve without moving canonical Workshop facts into Wright. + +This initial ownership choice does not require all future guidance to be authored by Wright. Additional community or project guidance sources may be added later if a concrete source/distribution contract defines trust, provenance, conflict, and update behavior. -Wright does not require a package manager, executable plugin runtime, remote knowledge database, or prompt template to serve this contract. Those mechanisms require separate evidence and decisions. \ No newline at end of file +Wright does not require a package manager, executable plugin runtime, remote knowledge database, project-policy overlay, or prompt template to serve the initial contract. Those mechanisms require separate evidence and decisions. From ebe6f2e328fa1a966fa75cfafac7d325c953a32f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9D=90=93=F0=9D=90=9E=F0=9D=90=9A=F0=9D=90=A4?= =?UTF-8?q?=F0=9D=90=A8=F0=9D=90=B0=F0=9D=90=9A?= <27560638+Teakowa@users.noreply.github.com> Date: Mon, 14 Sep 2026 14:53:27 +0800 Subject: [PATCH 7/8] docs: align ADR-0016 with product decisions --- ...0016-domain-intelligence-query-contract.md | 43 +++++++++++-------- 1 file changed, 26 insertions(+), 17 deletions(-) diff --git a/docs/adr/0016-domain-intelligence-query-contract.md b/docs/adr/0016-domain-intelligence-query-contract.md index 0b00162c..d025cc69 100644 --- a/docs/adr/0016-domain-intelligence-query-contract.md +++ b/docs/adr/0016-domain-intelligence-query-contract.md @@ -6,11 +6,11 @@ ## Context -Wright already exposes a session-aware tool service for CLI, embedding, and transport consumers. Its `targetMetadata` operation is a broad catalog summary, while ADR-0015 separates owner-backed canonical facts from Wright lint/policy and evidence classification. +Wright already exposes shared query/tooling services for CLI, embedding, and transport consumers. Its `targetMetadata` operation is a broad catalog summary, while ADR-0015 separates owner-backed canonical facts from Wright lint/policy behavior. -Agent workflows need a narrower capability: given the semantic construct currently being worked on, retrieve only the relevant Workshop facts, source-owner context, evidence-backed guidance, and project policy. Serving that through static prompts or copied metadata would duplicate semantic authority, make provenance ambiguous, and force each consumer to implement its own lookup behavior. +Agent workflows need a narrower capability: given the semantic construct currently being worked on, retrieve only the relevant Workshop facts, source-owner context, and practical guidance. Serving that through static prompts or copied metadata would duplicate semantic authority, make provenance ambiguous, and force each consumer to implement its own lookup behavior. -The design must also support human-authored best practices without allowing community guidance to become an implicit correctness specification. +The design must also support human-authored best practices without allowing guidance to become an implicit correctness specification. ## Decision @@ -18,21 +18,26 @@ Wright adds one product-level domain-intelligence composition contract with thes 1. **The service is a query, not a semantic store.** Canonical Workshop facts and identities are resolved from `workshop-rs`; source-language meaning is resolved by the source owner. Wright owns composition and presentation. 2. **Selection is semantic and bounded.** A request selects canonical owner identities directly, or supplies a source location that an owning implementation/provider resolves to semantic subjects. Wright does not fall back to textual guessing when source resolution is unavailable. -3. **Responses keep information classes separate.** The shared result has subject, fact, source-context, guidance, project-policy, and unavailable sections. Wright standardizes their envelope and provenance but does not normalize source-language internals into a new cross-language semantic model. -4. **Evidence is explicit.** Returned items distinguish `exact`, `static_metric`, `runtime_evidence`, `heuristic`, and `community_guidance`. Evidence class plus authority is the confidence contract; no synthetic numeric confidence score is introduced. -5. **Human guidance stays separate from canonical facts.** Guidance is authored as content plus stable identity, applicability, evidence/provenance, and limitations. Wright may curate and distribute first-party guidance, but guidance cannot self-promote to canonical semantics. -6. **Project policy is an overlay.** It may select, suppress, or rank guidance for a consumer/project, but it cannot rewrite facts, provenance, or evidence classification. -7. **All product consumers reuse the same operation.** `domainIntelligence` belongs on the existing session-aware Wright tool/query service. CLI, embedding, stdio/JSON-RPC, and future agent adapters remain thin consumers of that contract. -8. **The change is additive to the existing v1 embedding/result compatibility rules.** A new major contract version is not required solely to add the operation. -9. **LPP is not extended pre-emptively.** Provider-backed source selection may expose a future protocol gap; until evidence requires a wire capability, unsupported source selection is reported explicitly rather than forcing a speculative LPP extension. +3. **Canonical lookup is project-independent.** Direct canonical selection must work without an eagerly loaded source project. Source-position selection may require project/provider state because source resolution is owner-dependent. +4. **The public information model stays simple.** Returned domain-intelligence items use `fact`, `warning`, or `info`. `fact` is owner-backed factual information; `warning` and `info` are Wright-curated guidance at different levels of attention. These are domain-intelligence presentation classes, not lint/diagnostic severity. +5. **Provenance is explicit without imposing a public evidence taxonomy.** Each item identifies its responsible owner or guidance source and carries traceable references where available. Consumers are not required to understand a separate enum for runtime evidence, heuristics, or community guidance, and Wright does not synthesize numeric confidence scores. +6. **Built-in guidance is curated by Wright.** The initial corpus is first-party Wright guidance with stable identity, semantic applicability, provenance, and limitations where needed. Human guidance cannot self-promote to canonical semantics. +7. **External guidance sources are deferred.** Community or project-configured guidance may be added later only after a concrete contract defines trust, provenance, conflict, and update behavior. The initial design does not add a project-policy overlay or arbitrary guidance loading. +8. **All product consumers reuse the same operation.** `domainIntelligence` belongs on Wright's common query/tooling surface. CLI, embedding, stdio/JSON-RPC, and future agent adapters remain thin consumers of that contract. +9. **The change is additive to the existing v1 embedding/result compatibility rules.** A new major contract version is not required solely to add the operation. +10. **LPP is not extended pre-emptively.** Provider-backed source selection may expose a future protocol gap; until evidence requires a wire capability, unsupported source selection is reported explicitly rather than forcing a speculative LPP extension. `targetMetadata` remains a broad target/catalog discovery summary and is not repurposed as the domain-intelligence operation. ## Alternatives considered -- **Reuse `targetMetadata` and add more fields:** rejected because a bulk catalog response does not express semantic selection, source-owner resolution, guidance provenance, or project policy, and would trend toward a monolithic agent payload. +- **Reuse `targetMetadata` and add more fields:** rejected because a bulk catalog response does not express semantic selection, source-owner resolution, or provenance-bearing guidance, and would trend toward a monolithic agent payload. +- **Require a loaded project/session for every query:** rejected because canonical Workshop facts and built-in guidance are useful without source-project context; only source-position resolution inherently needs owner/project state. +- **Expose a detailed public evidence taxonomy:** rejected because consumers primarily need a clear fact-versus-guidance distinction and provenance. Runtime/community/heuristic detail can remain source metadata where useful without becoming the main product model. - **Copy Workshop facts into Wright guidance assets:** rejected because it creates a shadow semantic authority that can drift from `workshop-rs`. -- **Put best-practice guidance in `workshop-rs`:** rejected because community heuristics and product guidance are not canonical Workshop semantics. +- **Put best-practice guidance in `workshop-rs`:** rejected because product guidance is not canonical Workshop semantics. +- **Accept arbitrary community/project guidance in v1:** deferred because the system does not yet define trust, provenance, conflict, or update behavior for external sources. Wright curates the initial built-in corpus while keeping the item contract open to future sources. +- **Add project-policy suppression/ranking in v1:** rejected because there is no current consumer requirement for a domain-intelligence policy overlay; lint policy should not be generalized into this product surface without evidence. - **Create a general knowledge database, plugin runtime, or package manager first:** rejected because no current consumer evidence requires those mechanisms and they add independent versioning/distribution concerns. - **Extend LPP first:** deferred because canonical identity queries and in-process owner integrations do not require a new wire method; a provider protocol change should follow an observed provider-backed source-selection need. - **Embed prompt-ready text in Wright core:** rejected because prompt formatting is consumer presentation, while the durable contract should remain structured and reusable across CLI, embedding, and other agents. @@ -41,26 +46,30 @@ Wright adds one product-level domain-intelligence composition contract with thes - Agents can request small, context-specific payloads instead of loading the entire Workshop knowledge surface. - Canonical facts remain owned and updated where their semantics live. -- Community guidance can evolve independently while retaining explicit evidence and limitations. +- Simple `fact` / `warning` / `info` presentation keeps the agent-facing contract understandable while provenance preserves traceability. +- Canonical lookups can serve reference-style workflows without requiring a source project. +- Wright can evolve a curated guidance corpus without creating a second Workshop semantic authority. - Source-owner capability gaps remain visible rather than being hidden by Wright text heuristics. -- Implementation must add a public operation/result shape and provide contract tests across the shared tool service and transport adapters. +- Implementation must add a public operation/result shape and provide contract tests across the shared query surface and transport adapters. - A provider-backed source selector may later require a separate LPP decision, but that work is not required by this ADR. ## Compatibility impact The decision adds a new public query operation without changing source-language syntax, Workshop semantics, compiler lowering, diagnostics, or existing query behavior. Under the current embedding/result versioning rules, adding the operation is compatible within major version 1. -Implementation evidence must show that direct/in-process and transport consumers observe the same structured result, owner facts are not duplicated as Wright authority, and unavailable owner capabilities are surfaced explicitly. +Implementation evidence must show that direct/in-process and transport consumers observe the same structured result, direct canonical queries do not require unnecessary project loading, owner facts are not duplicated as Wright authority, and unavailable owner capabilities are surfaced explicitly. ## Scope boundaries This ADR does not decide: - the storage path or serialization syntax used to author first-party guidance; -- remote guidance distribution, registries, or executable plugins; +- community/project guidance source loading or remote guidance distribution; +- registries or executable plugins; +- project-specific suppression/ranking policy for guidance; - prompt templates or token-cache optimization; - a new LPP method for semantic selection; - automatic source edits based on guidance; - whether every source-language construct can map to a canonical Workshop identity. -Those decisions require separate concrete consumer or provider evidence. \ No newline at end of file +Those decisions require separate concrete consumer or provider evidence. From e6227fc88191ec9198f32ec66fecb4f5636e0a62 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=F0=9D=90=93=F0=9D=90=9E=F0=9D=90=9A=F0=9D=90=A4?= =?UTF-8?q?=F0=9D=90=A8=F0=9D=90=B0=F0=9D=90=9A?= <27560638+Teakowa@users.noreply.github.com> Date: Mon, 14 Sep 2026 14:53:40 +0800 Subject: [PATCH 8/8] docs: align tooling domain intelligence boundary --- docs/architecture/tooling.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/architecture/tooling.md b/docs/architecture/tooling.md index 4caa0b4e..4c090d6a 100644 --- a/docs/architecture/tooling.md +++ b/docs/architecture/tooling.md @@ -53,7 +53,7 @@ Normal source tooling does not require full-file regeneration. Preserve comments CLI, LSP, agent/MCP-style adapters, embedding, and CI should reuse common Wright-owned semantic/query/edit services rather than each implementing language-specific logic independently. -On-demand domain intelligence follows the same rule: Wright composes owner-backed semantic identities and facts with separately provenance-bearing guidance and project policy through the shared query service. It does not copy canonical Workshop facts into an agent-specific knowledge store. See [`domain-intelligence.md`](domain-intelligence.md). +On-demand domain intelligence follows the same rule: Wright composes owner-backed semantic identities and facts with separately provenance-bearing Wright-curated guidance through the shared query surface. Direct canonical queries do not require source-project state; source-position queries may use project/provider context. Wright does not copy canonical Workshop facts into an agent-specific knowledge store. See [`domain-intelligence.md`](domain-intelligence.md). Machine-readable contracts are versioned and deterministic when declared. Presentation layers must not alter semantic outcomes. @@ -67,4 +67,4 @@ Wright owns the product UX, not the source-language compiler semantics. Source→Workshop combines source-owner semantics/lowering with `workshop-rs` canonical validation/emission. Workshop→OPY/DEL reconstruction belongs to the respective source implementation. Direct OPY↔DEL translation is optional and should not drive architecture for symmetry. -A command may exist before every source construct is supported; capability claims must follow owner + integration evidence. \ No newline at end of file +A command may exist before every source construct is supported; capability claims must follow owner + integration evidence.