Document adapter versus core runtime boundaries

README.md

@@ -51,6 +51,7 @@ Code, generated artifacts, and tests must align with the approved governing spec
 - Brainstorming decisions: [brainstorming.md](/Users/piovese/Documents/cogolo/brainstorming.md)
 - Quality standards: [docs/quality-standards.md](/Users/piovese/Documents/cogolo/docs/quality-standards.md)
 - Compatibility policy: [docs/compatibility-policy.md](/Users/piovese/Documents/cogolo/docs/compatibility-policy.md)
+- Adapter boundaries: [docs/adapter-boundaries.md](/Users/piovese/Documents/cogolo/docs/adapter-boundaries.md)
 - Contract publication policy: [docs/contract-publication-policy.md](/Users/piovese/Documents/cogolo/docs/contract-publication-policy.md)
 - Exception process: [docs/exception-process.md](/Users/piovese/Documents/cogolo/docs/exception-process.md)
 - ADR guidance: [docs/adr/README.md](/Users/piovese/Documents/cogolo/docs/adr/README.md)

docs/adapter-boundaries.md

@@ -0,0 +1,85 @@
+# Adapter Responsibilities Versus Core Runtime Responsibilities
+
+Traverse keeps the core runtime narrow and topology-agnostic.
+
+The core model governs:
+
+- capability, event, and workflow contracts
+- registry behavior and artifact registration
+- runtime request validation and execution state
+- trace and runtime evidence generation
+- browser-subscription and MCP-facing message contracts
+
+Adapters and sidecar-like helpers may exist around that core, but they are optional integration surfaces, not part of the mandatory runtime shape.
+
+## Core Runtime Responsibilities
+
+The core runtime owns the governed semantic model.
+
+That includes:
+
+- validating governed requests, contracts, and workflow traversal
+- selecting approved capabilities and workflows
+- applying placement and execution rules
+- producing runtime state, trace, and terminal artifacts
+- exposing transport-agnostic browser-subscription and MCP-facing payload contracts
+
+These responsibilities must remain stable regardless of whether Traverse is embedded directly in a process, wrapped by a browser adapter, surfaced through MCP, or accompanied by local helper processes.
+
+## Adapter Responsibilities
+
+Adapters exist to connect governed Traverse behavior to a concrete environment.
+
+Adapters may own:
+
+- transport bindings such as HTTP, browser, IPC, or other host-specific delivery paths
+- local configuration overlays and environment-specific defaults
+- sidecar-like helper behavior for integration convenience
+- host-specific bootstrapping, discovery, or packaging glue
+- UI- or tool-facing presentation layers that consume governed runtime artifacts
+
+Adapters must not redefine governed runtime semantics. They may shape transport and host integration, but they should reuse the already-governed runtime, trace, placement, browser-subscription, and MCP surfaces.
+
+## Optional Sidecar Behavior
+
+Traverse is not adopting a mandatory sidecar topology.
+
+Why:
+
+- the core runtime is meant to stay portable across browser, edge, cloud, and device environments
+- a required sidecar would overcommit Traverse to one deployment shape too early
+- mandatory sidecars would blur the boundary between core governed semantics and optional infrastructure glue
+
+Sidecar-style helpers are allowed when useful, but only as optional adapter choices.
+
+Examples:
+
+- a local browser helper that exposes the governed browser-subscription contract over a concrete transport
+- an MCP-serving process that wraps the governed MCP surface
+- a device or desktop helper that manages local configuration overlays or host integration details
+
+## What Must Stay Transport-Agnostic
+
+The following belong to the core governed surface and should not become adapter-specific inventions:
+
+- runtime request meaning
+- state-machine meanings and transition evidence
+- trace artifact structure
+- browser-subscription message ordering and payload shape
+- MCP discovery, get, execute, and observe semantics
+
+An adapter may wrap these with a protocol or deployment model, but it should not rename or redefine them.
+
+## Practical Rule
+
+If a concern changes the meaning of runtime behavior, it belongs to the core runtime.
+
+If a concern only changes how governed behavior is exposed to a host environment, it belongs to an adapter.
+
+## Related Docs
+
+- `docs/oss-pattern-extraction.md`
+- `docs/local-runtime-home.md`
+- `docs/compatibility-policy.md`
+- `specs/013-browser-runtime-subscription/spec.md`
+- `specs/014-mcp-surface/spec.md`

docs/compatibility-policy.md

@@ -60,6 +60,10 @@ Breaking examples:
 - incompatible invocation behavior
 - changed failure semantics without version change
 
+The boundary between governed core runtime responsibilities and optional adapters is documented in:
+
+- `docs/adapter-boundaries.md`
+
 ## Specs
 
 Approved specs are immutable once they govern implementation.

scripts/ci/adapter_boundaries_smoke.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_root="${TRAVERSE_REPO_ROOT:-$(pwd)}"
+
+doc="${repo_root}/docs/adapter-boundaries.md"
+readme="${repo_root}/README.md"
+compat="${repo_root}/docs/compatibility-policy.md"
+
+test -f "$doc"
+test -s "$doc"
+
+grep -q "core runtime narrow and topology-agnostic" "$doc"
+grep -q "capability, event, and workflow contracts" "$doc"
+grep -q "trace and runtime evidence generation" "$doc"
+grep -q "browser-subscription and MCP-facing payload contracts" "$doc"
+grep -q "transport bindings such as HTTP, browser, IPC" "$doc"
+grep -q "not adopting a mandatory sidecar topology" "$doc"
+grep -q "optional adapter choices" "$doc"
+grep -q 'specs/013-browser-runtime-subscription/spec.md' "$doc"
+grep -q 'specs/014-mcp-surface/spec.md' "$doc"
+
+grep -q 'docs/adapter-boundaries.md' "$readme"
+grep -q 'docs/adapter-boundaries.md' "$compat"
+
+printf 'Adapter boundaries smoke passed.\n'

scripts/ci/repository_checks.sh

@@ -14,6 +14,7 @@ required_files=(
   ".specify/memory/constitution.md"
   "docs/quality-standards.md"
   "docs/compatibility-policy.md"
+  "docs/adapter-boundaries.md"
   "docs/contract-publication-policy.md"
   "docs/expedition-example-authoring.md"
   "docs/expedition-example-smoke.md"
@@ -50,6 +51,7 @@ fi
 grep -q "GitHub Project 1" README.md
 grep -q "Apache-2.0" README.md
 grep -q "personal research" README.md
+grep -q "docs/adapter-boundaries.md" README.md
 grep -q "Definition of Done" docs/ticket-standard.md
 grep -q "in-progress" docs/ticket-standard.md
 grep -q "active branch, PR, or an explicitly assigned developer" docs/ticket-standard.md
@@ -87,6 +89,11 @@ grep -q "Non-Negotiable Quality Standards" specs/001-foundation-v0-1/spec.md
 grep -q "AI Review Process" docs/ai-review-process.md
 grep -q '"schema_version": "1.0.0"' specs/governance/approved-specs.json
 grep -q "Spec-alignment gate implementation" docs/quality-standards.md
+grep -q "docs/adapter-boundaries.md" docs/compatibility-policy.md
+grep -q "specs/013-browser-runtime-subscription/spec.md" docs/adapter-boundaries.md
+grep -q "specs/014-mcp-surface/spec.md" docs/adapter-boundaries.md
+grep -q "mandatory sidecar topology" docs/adapter-boundaries.md
+grep -q "optional adapter choices" docs/adapter-boundaries.md
 grep -q "## Governing Spec" .github/pull_request_template.md
 
 echo "Repository checks passed."