Standardize local Traverse runtime home

README.md

@@ -53,6 +53,7 @@ Code, generated artifacts, and tests must align with the approved governing spec
 - 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)
+- Local runtime home: [docs/local-runtime-home.md](/Users/piovese/Documents/cogolo/docs/local-runtime-home.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/executable-package-template.md

@@ -53,6 +53,10 @@ The colocated build command should:
 
 The checked-in template uses a tiny deterministic WASM fixture so packaging, inspection, and smoke validation can stay runnable even when a full external WASM toolchain is not available.
 
+For the broader local runtime-owned layout around generated helper copies, fixture byproducts, and adapter overlays, see:
+
+- `docs/local-runtime-home.md`
+
 ## How to use the template
 
 1. Copy `examples/templates/executable-capability-package/` into a new package folder.

docs/expedition-example-authoring.md

@@ -8,6 +8,14 @@ workflows/examples/expedition/
 examples/expedition/registry-bundle/
 ```
 
+Local runtime-owned generated helpers, overlays, and copied execution byproducts belong under:
+
+```text
+.traverse/local/
+```
+
+See `docs/local-runtime-home.md` for the default layout and ownership boundary.
+
 ## Artifact Categories
 
 Atomic capability contracts:

docs/local-runtime-home.md

@@ -0,0 +1,87 @@
+# Local Traverse Runtime Home
+
+Traverse uses one predictable local runtime home for generated helper artifacts and adapter overlays:
+
+- default path: `.traverse/local/`
+- optional override: `TRAVERSE_RUNTIME_HOME=/absolute/path`
+
+This is a local runtime workspace, not a source-of-truth location for governed artifacts.
+
+## Directory Layout
+
+The default local runtime home is expected to contain:
+
+```text
+.traverse/local/
+  bin/
+  fixtures/
+  overlays/
+```
+
+### `bin/`
+
+Runtime-owned generated helper binaries and package-local executable copies that are produced for local execution.
+
+Examples:
+
+- adapter helper binaries downloaded or generated for local development
+- copied executable package artifacts that the local runtime needs to invoke deterministically
+
+### `fixtures/`
+
+Runtime-owned generated fixtures and transient execution byproducts that are helpful for local smoke paths or deterministic inspection.
+
+Examples:
+
+- generated fixture outputs derived from checked-in templates
+- copied runtime traces or local execution snapshots that should not become governed source artifacts
+
+### `overlays/`
+
+Runtime-owned adapter configuration overlays for local development.
+
+Examples:
+
+- browser adapter local settings
+- MCP adapter local settings
+- device or sidecar-style local integration overlays
+
+## What Stays Outside The Runtime Home
+
+The local runtime home is intentionally not the place for user-authored governed artifacts.
+
+These stay in checked-in source locations:
+
+- contracts: `contracts/`
+- workflows: `workflows/`
+- registry bundles and runtime requests: `examples/`
+- shared checked-in demo fixtures: `apps/demo-fixtures/`
+
+Executable capability packages may keep deterministic build outputs in package-local `./artifacts/` directories when those artifacts are part of the checked-in package shape. The local runtime home is for runtime-owned copies, caches, and overlays, not for replacing package-local layout.
+
+## Ownership Rule
+
+Treat the local runtime home as runtime-owned.
+
+- the runtime may create, replace, or clean up files under `.traverse/local/`
+- developers may inspect it for debugging
+- developers should not treat files there as governed source artifacts
+
+If a file is source-of-truth and should be reviewed, versioned, or merge-gated, it belongs in the repo’s governed artifact locations, not in the runtime home.
+
+## Why This Exists
+
+This keeps local execution reproducible:
+
+- generated helpers are not scattered across arbitrary directories
+- local adapter overlays have one predictable home
+- smoke paths can reference one known runtime-owned location
+- checked-in governed artifacts remain clearly separate from generated local runtime state
+
+## Validation
+
+Verify the documented runtime-home layout with:
+
+```bash
+bash scripts/ci/runtime_home_smoke.sh
+```

scripts/ci/repository_checks.sh

@@ -19,6 +19,7 @@ required_files=(
   "docs/expedition-example-authoring.md"
   "docs/expedition-example-smoke.md"
   "docs/executable-package-template.md"
+  "docs/local-runtime-home.md"
   "examples/expedition/runtime-requests/plan-expedition.json"
   "docs/exception-process.md"
   "docs/project-management.md"
@@ -74,11 +75,14 @@ grep -q "bash scripts/ci/expedition_golden_path.sh" docs/expedition-example-smok
 grep -q "bash scripts/ci/event_driven_workflow_smoke.sh" docs/expedition-example-smoke.md
 grep -q "TRAVERSE_REPO_ROOT" docs/expedition-example-smoke.md
 grep -q "bash scripts/ci/executable_package_template_smoke.sh" docs/executable-package-template.md
+grep -q "docs/local-runtime-home.md" docs/executable-package-template.md
 grep -q "cargo run -p traverse-cli -- bundle inspect examples/expedition/registry-bundle/manifest.json" docs/expedition-example-authoring.md
 grep -q "cargo run -p traverse-cli -- expedition execute examples/expedition/runtime-requests/plan-expedition.json" docs/expedition-example-authoring.md
 grep -q "cargo run -p traverse-cli -- trace inspect" docs/expedition-example-authoring.md
 grep -q "cargo run -p traverse-cli -- bundle register examples/expedition/registry-bundle/manifest.json" docs/expedition-example-authoring.md
 grep -q "workflows/examples/expedition/plan-expedition/workflow.json" docs/expedition-example-authoring.md
+grep -q ".traverse/local/" docs/expedition-example-authoring.md
+grep -q "bash scripts/ci/runtime_home_smoke.sh" docs/local-runtime-home.md
 grep -q "label: Definition of done" .github/ISSUE_TEMPLATE/task.yml
 grep -q "label: Validation" .github/ISSUE_TEMPLATE/task.yml
 grep -q "Specs Are Versioned, Immutable, and Merge-Gating" .specify/memory/constitution.md

scripts/ci/runtime_home_smoke.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repo_root="${TRAVERSE_REPO_ROOT:-$(pwd)}"
+
+doc="${repo_root}/docs/local-runtime-home.md"
+template_doc="${repo_root}/docs/executable-package-template.md"
+authoring_doc="${repo_root}/docs/expedition-example-authoring.md"
+
+test -f "$doc"
+test -s "$doc"
+
+grep -q 'default path: `.traverse/local/`' "$doc"
+grep -q 'TRAVERSE_RUNTIME_HOME=/absolute/path' "$doc"
+grep -q '.traverse/local/' "$doc"
+grep -q 'bin/' "$doc"
+grep -q 'fixtures/' "$doc"
+grep -q 'overlays/' "$doc"
+grep -q 'apps/demo-fixtures/' "$doc"
+grep -q 'package-local `./artifacts/` directories' "$doc"
+grep -q 'bash scripts/ci/runtime_home_smoke.sh' "$doc"
+
+grep -q 'docs/local-runtime-home.md' "$template_doc"
+grep -q 'docs/local-runtime-home.md' "$authoring_doc"
+
+printf 'Runtime home smoke passed.\n'