Structural history schema authority

CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Added
+
+- **Structural history schema authority**: Graft now carries a canonical
+  `schemas/graft-structural-history.graphql` schema with Wesley-generated
+  TypeScript contracts and a deterministic artifact drift check, establishing
+  the schema-first Echo migration boundary without changing Echo or Wesley.
+- **Structural source span invariants**: The canonical structural-history schema
+  now rejects source spans whose end offsets or present end lines precede their
+  starts.
+- **Opened workspace paths**: MCP sessions can now call `workspace_open` to
+  open another git worktree path, activate it by default, and inspect opened
+  paths through `workspace_list_opened` without adding per-tool `cwd` routing.
+
 ### Changed
 
 - **Structural reading boundary**: `graft_review` impact counts and
@@ -20,6 +33,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/).
   report a partial residual posture when committed import-scan fallback
   evidence is unavailable after a zero-count WARP graph reading.
 
+### Security
+
+- **Dependency audit posture**: Patched audited transitive dependencies through
+  pnpm overrides for `brace-expansion` and `qs`, preserving a clean release
+  security gate.
+
 ## [0.8.0] - 2026-05-13
 
 ### Added

GUIDE.md

@@ -18,7 +18,7 @@ Manually enforce policies or inspect structural history from your terminal.
 ### 3. Shared Daemon Mode
 Run the central execution authority for multi-repo work and persistent monitors.
 - **Run**: `npx @flyingrobots/graft daemon`
-- **Read**: [docs/SETUP.md](./docs/SETUP.md) (Daemon bootstrap and `workspace_authorize` / `workspace_bind`)
+- **Read**: [docs/SETUP.md](./docs/SETUP.md) (Daemon bootstrap and `workspace_open`)
 - **Read**: [Architecture](./ARCHITECTURE.md) (Daemon section)
 
 ## Big Picture: System Orchestration
@@ -33,7 +33,7 @@ Graft is a tiered governor. It manages the context burden across three layers:
 
 - [ ] **I am setting up a new project**: Start with `README.md` Quick Start.
 - [ ] **I am configuring Claude Code**: Use `npx graft init --write-claude-hooks`.
-- [ ] **I am using daemon mode in a generic MCP client**: Read [docs/SETUP.md](./docs/SETUP.md) and expect explicit `workspace_authorize` then `workspace_bind`.
+- [ ] **I am using daemon mode in a generic MCP client**: Read [docs/SETUP.md](./docs/SETUP.md) and expect `workspace_open` as the normal agent-facing path.
 - [ ] **I am debugging a structural diff**: Use `npx graft struct diff --json`.
 - [ ] **I am contributing to Graft**: Read `METHOD.md` and `docs/BEARING.md`.
 

README.md

@@ -132,12 +132,16 @@ npx @flyingrobots/graft daemon
 ```
 
 Daemon sessions start `unbound`. If your client connects through the
-daemon instead of repo-local stdio, the first repo-scoped flow is:
+daemon instead of repo-local stdio, the normal agent-facing flow is:
 
-1. `workspace_authorize` for the target repo/worktree
-2. `workspace_bind` for the active daemon session
+1. `workspace_open` with the target repo/worktree `cwd`
+2. optionally `workspace_list_opened` to inspect opened paths and the
+   active workspace
 3. then use repository-scoped tools such as `safe_read`
 
+Use `workspace_authorize` and `workspace_bind` only when you need the
+lower-level daemon control plane directly.
+
 Use [docs/SETUP.md](./docs/SETUP.md) for the exact client bootstrap and
 daemon control-plane posture.
 

docs/MCP.md

@@ -52,14 +52,18 @@ npx @flyingrobots/graft daemon
 ```
 
 Daemon sessions start `unbound`. Once a client is connected to the
-daemon MCP surface, repository-scoped work follows this control-plane
-flow:
+daemon MCP surface, repository-scoped work normally follows this
+agent-facing flow:
 
-1. `workspace_authorize` with the target `cwd`
-2. `workspace_bind` with the target `cwd`
+1. `workspace_open` with the target `cwd`
+2. optionally `workspace_list_opened` to inspect opened paths and the
+   active workspace
 3. then call repository-scoped tools such as `safe_read`, `graft_since`,
    or `code_show`
 
+`workspace_authorize` and `workspace_bind` remain available as lower-level
+daemon control-plane tools.
+
 ## Key Tool Groups
 - **Bounded Reads**: `safe_read`, `file_outline`, `read_range`, `changed_since`
 - **Governed Edits**: `graft_edit`
@@ -68,7 +72,8 @@ flow:
 - **Structural Metrics**: `graft_churn`, `graft_difficulty`
 - **Precision**: `code_show`, `code_find`, `code_refs`
 - **Activity & Footing**: `activity_view`, `causal_status`, `causal_attach`, `doctor`
-- **Daemon Control Plane**: `workspace_authorizations`, `workspace_authorize`, `workspace_bind`, `workspace_status`, `workspace_rebind`, `workspace_revoke`, `daemon_status`, `daemon_repos`, `daemon_sessions`, `daemon_monitors`, `monitor_*`
+- **Workspace Routing**: `workspace_open`, `workspace_list_opened`, `workspace_status`
+- **Daemon Control Plane**: `workspace_authorizations`, `workspace_authorize`, `workspace_bind`, `workspace_rebind`, `workspace_revoke`, `daemon_status`, `daemon_repos`, `daemon_sessions`, `daemon_monitors`, `monitor_*`
 
 ## Current Truth
 - MCP is the primary agent surface.

docs/SETUP.md

@@ -98,6 +98,8 @@ Daemon control-plane inspection now exists through MCP tools:
 - `monitor_stop`
 - `workspace_authorizations`
 - `workspace_authorize`
+- `workspace_open`
+- `workspace_list_opened`
 - `workspace_bind`
 - `workspace_status`
 - `workspace_rebind`
@@ -120,10 +122,14 @@ Practical daemon-backed MCP first-use sequence:
 
 1. configure your MCP client with `graft serve --runtime daemon`
 2. let the bridge auto-start the daemon, or start `npx @flyingrobots/graft daemon`
-3. call `workspace_authorize` with the target `cwd`
-4. call `workspace_bind` with the target `cwd`
+3. call `workspace_open` with the target `cwd`
+4. optionally call `workspace_list_opened` to inspect opened paths and the
+   active workspace
 5. then use repository-scoped tools such as `safe_read` or `graft_map`
 
+Use `workspace_authorize` plus `workspace_bind` when you need direct
+operator control over daemon authorization and binding state.
+
 ### MCP runtime selection
 
 Repo-local stdio is the default and remains the simplest path:
@@ -157,8 +163,7 @@ Use repo-local stdio when you want one MCP server bound directly to the
 current checkout. Use daemon-backed stdio when you want daemon-only
 capabilities such as shared worker pools, persistent monitors, and
 daemon control-plane inspection. Daemon-backed sessions start unbound;
-repository-scoped tools require `workspace_authorize` and
-`workspace_bind`.
+repository-scoped tools normally begin with `workspace_open`.
 
 ### One-step bootstrap
 
@@ -399,8 +404,9 @@ If your client doesn't support `npx`, install globally and use:
 
 This section shows the repo-local stdio path. If you connect through
 `graft daemon` instead, the MCP session starts `unbound` and needs
-`workspace_authorize` plus `workspace_bind` before repository-scoped
-tool calls.
+`workspace_open` before repository-scoped tool calls. The lower-level
+`workspace_authorize` and `workspace_bind` tools remain available for
+operator control-plane workflows.
 
 ## Claude Code Hooks
 

docs/design/CORE_structural-history-schema-and-echo-migration.md

@@ -320,3 +320,19 @@ The implementation phase should add deterministic tests in this order:
 Tests must assert observable behavior. They should not depend on wall-clock
 timing, unseeded randomness, stdout/stderr text, or source-code introspection as
 proof.
+
+## Implementation Status
+
+- `schemas/graft-structural-history.graphql` is the first Graft-owned canonical
+  structural history schema.
+- `src/generated/graft-structural-history.ts` is generated by the existing
+  Wesley CLI TypeScript emitter from that schema.
+- `schemas/graft-structural-history.manifest.json` records the schema source
+  hash, Wesley L1 registry hash, generated artifact hash, required structural
+  types, required read operations, and required evidence labels.
+- `scripts/check-structural-history-schema-artifacts.ts` and
+  `test/unit/contracts/graft-structural-history-schema.test.ts` provide the
+  first deterministic drift check for the schema/generated artifact pair.
+- This slice does not wire Echo runtime reads yet. It establishes schema
+  authority first so later Echo import and parity work has a canonical Graft
+  model to target.