heyspex 0.2.2 → 0.2.4

package/docs/driving-heyspex-from-copilot.md

@@ -1,165 +1,174 @@
-# Driving HeySpex from GitHub Copilot (and other non-MCP assistants)
-
-**Capability table dated: 2026-07-10.** Harness support changes fast; re-verify against the
-sources before relying on a row. Refresh is owned by the harness-integrations pillar.
-
-HeySpex is tool-agnostic by construction. Every everyday action reaches the vault through one of
-three write paths, and at least one of them works in **any** assistant that can either speak MCP or
-run a shell command:
-
-1. **MCP tools** — `heyspex_*` tools over the Model Context Protocol (richest surface).
-2. **The `hs` CLI** — plain shell commands with stable exit codes and `--json` output. No MCP
-   client required; works in any assistant, terminal, or CI runner that can shell out.
-3. **The console web UI** — `localhost:3000`, works in any browser.
-
-This guide is the fallback path: how to drive the everyday agent loop when your assistant has
-**no** MCP tool support, using only the `hs` CLI.
-
-Grounded in [[HS-RDG9-RES-github-copilot-and-vs-code-mcp-support-t]] (the 2026 verification that
-Copilot now has a real MCP client) and [[HS-TACM-RES-tool-agnostic-mcp-compatibility-matrix-2026-05-27]]
-(the broader cross-tool matrix — note its "VS Code + Copilot = shell-only, no MCP" row is stale as
-of the RDG9 refresh and is being amended separately).
-
-## Per-harness capability table (2026-07-10)
-
-**Legend** — **MCP**: native MCP client (tools, and sometimes prompts/resources). **`hs` CLI**:
-can shell out to `hs`. **Prompts**: supports MCP prompts exposed as slash commands. **Everyday
-loop**: can do see-next → claim → report progress → submit for review.
-
-| Harness                                                              |                    MCP                     |         `hs` CLI          |           Prompts            |         Everyday loop         | Honest ceiling                                                                                                                                                                                                    |
-| -------------------------------------------------------------------- | :----------------------------------------: | :-----------------------: | :--------------------------: | :---------------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **VS Code agent mode (Copilot)**                                     | ✓ full (`.vscode/mcp.json`, `servers` key) |             ✓             | ✓ (`/mcp.<server>.<prompt>`) |   via MCP tools **or** `hs`   | Full MCP spec — tools, prompts, resources, sampling, OAuth. Subject to a 128-tool per-request cap; curate the exposed tool subset.                                                                                |
-| **GitHub Copilot CLI**                                               |   ✓ (auto-discovers `.github/mcp.json`)    |             ✓             |          ✓ (`/mcp`)          |   via MCP tools **or** `hs`   | Full MCP client (GA Feb 2026). Honors the org "MCP servers in Copilot" policy gate — admin approval may be required.                                                                                              |
-| **Copilot coding agent (github.com cloud)**                          |              ✓ **tools only**              | ✓ if sandbox allows shell |         ✗ no prompts         | via MCP **tools** **or** `hs` | No MCP prompts, no resources, no OAuth. Servers are configured in repo settings, not a committed file; local/allowlisted servers only. **Do not rely on slash-command prompts here — use tools or the `hs` CLI.** |
-| **Any assistant WITHOUT MCP tool support**                           |                     ✗                      |             ✓             |              ✗               |       via `hs` CLI only       | The `hs` CLI is the complete fallback. Everything in the loop is a plain shell command; nothing is unreachable just because the assistant lacks tool support.                                                     |
-| **Claude Code / Cursor / Cline / Continue.dev / Google Antigravity** |                  ✓ native                  |             ✓             |              ✓               |    via MCP tools (primary)    | First-class MCP today; the `hs` CLI is available as a fallback. See [[HS-TACM-RES-tool-agnostic-mcp-compatibility-matrix-2026-05-27]].                                                                            |
-
-Design consequence: keep the primary UX in **tools**, not MCP prompts, because the cloud coding
-agent doesn't support prompts. Treat slash-command prompts as a VS Code / Copilot-CLI enhancement,
-and the `hs` CLI as the universal floor. HeySpex does **not** promise native slash-command parity on
-a surface that cannot support prompts.
-
-## The everyday loop with the `hs` CLI
-
-Run these from anywhere inside the vault (the CLI walks up to find `specs/`; or set
-`HS_VAULT_ROOT`). All four commands are pure shell — no MCP client involved. Add `--json` for
-machine-readable output.
-
-### 1. See what's next
-
-```bash
-hs next --summary --json
-```
-
-Returns the on-deck brief (spec id, title, summary, and a claim target). Drop `--json` for the
-human-readable prompt; drop `--summary` for the full post-claim execution brief.
-
-### 2. Claim the work
-
-```bash
-hs claim acquire HS-WJ1C-TASK --json
-```
-
-Atomic: two concurrent acquires for one spec yield exactly one success and one `already_claimed`
-conflict (exit 9) that names the existing claimant. Release on hand-off with
-`hs claim release HS-WJ1C-TASK`.
-
-### 3. Report progress
-
-```bash
-hs claim progress HS-WJ1C-TASK --stage Grounding --ac 0
-```
-
-`--stage` takes a work-stage verb (Grounding, Breaking down, Drafting, Validating, Testing,
-Reviewing). `--ac <n>` is the 0-based acceptance-criterion index you are on — it drives the live
-checklist on the What's Next surface. Call it again as you move between stages and complete criteria.
-
-### 4. Submit for review
-
-```bash
-hs mcp call heyspex_submit_for_review --arg spec_id=HS-WJ1C-TASK --json
-```
-
-`hs mcp call` runs a single MCP tool as a **one-shot shell command** — it does not require your
-assistant to be an MCP client. This close-out step validates acceptance-criteria progress against
-your claim, PATCHes the status API (never hand-edit frontmatter `status:`), applies review-grain
-coercion and parent rollup, releases the claim, and returns close-out guidance. A `409` on submit is
-a real reason (e.g. incomplete criteria) — report it, don't work around it.
-
-> Why `hs mcp call` and not a dedicated `hs submit` verb: see-next, claim, and report-progress each
-> have a first-class `hs` verb; submit-for-review is reached through the generic one-shot MCP-call
-> escape hatch, which reuses the exact close-out logic the MCP tool runs. It is still a plain shell
-> command with no MCP-client requirement.
-
-## Configuring MCP where it IS supported
-
-For VS Code agent mode and Copilot CLI you get the richer MCP tool surface. The MCP config
-templates (`.vscode/mcp.json` with the `servers` key, `.github/mcp.json` for Copilot CLI
-auto-discovery) and the Copilot instructions file are owned by the harness-integrations config work
-and documented separately — this guide covers only the universal `hs` CLI fallback.
-
-## Hooks under Copilot
-
-Copilot CLI runs the HeySpex hooks it finds in `.claude/settings.json` (and the plugin's `hooks/hooks.json`), so the
-gates (capture-on-idea obligation, claim-before-build, naming guards) apply to Copilot agents too. What differs:
-
-- **Fail-closed**: Copilot denies a tool call when a `preToolUse` command crashes or exits non-zero. Every registered
-  command is therefore a self-locating bootstrap that does not need `$CLAUDE_PROJECT_DIR` and exits 0 when it cannot find
-  the HeySpex runtime; `_run.mjs` itself never exits non-zero except for a deliberate deny (translated to Copilot's
-  top-level `{"permissionDecision":"deny"}` JSON with exit 0).
-- **Turn it off**: `hs mode off` (all harnesses, per project; `hs mode on|status|toggle`), `HEYSPEX_MODE=off` for one
-  shell, or `HEYSPEX_COPILOT_HOOKS_OFF=1` / `agent_behaviors.harness_hooks.copilot.enabled: false` for Copilot only.
-  The four always-on security gates (`env-vault-guard`, `research-method-guard`, `research-protocol-gate`,
-  `git-identity-guard`) ignore all three.
-- **Stopgap on an older checkout** (before the bootstrap ships): `HEYSPEX_MODE=off` only helps if the hook command can
-  start, and the old command needs `CLAUDE_PROJECT_DIR`; export it (`CLAUDE_PROJECT_DIR=<repo>`) alongside `HEYSPEX_MODE=off`.
-
-### One source of hooks, and the cloud agent
-
-Plugin OR repo hooks, never both: Copilot CLI loads the heyspex plugin AND the repo's `.claude/settings.json` /
-`.github/hooks/*.json`, so a repo with both fires every hook twice. `npm run doctor` (check `hook-double-fire`) warns
-about that and reports `unknown`, not a failure, when it cannot read a plugin registry.
-
-The Copilot **cloud agent** loads no plugins: its only hook source is `.github/hooks/*.json` on the **default branch**.
-`npm run hooks:write-github` generates `.github/hooks/heyspex.json` (bash `command` entries only, camelCase events,
-resolving `node_modules/heyspex/scripts/claude-hooks/_run.mjs` then `./scripts/claude-hooks/_run.mjs`, else exit 0).
-Requirements: the sandbox must contain `node_modules/heyspex` (install it in `copilot-setup-steps`), the firewall must
-allow the console URL (claim heartbeats), and MCP is configured in repository settings (tools only, no OAuth).
-
-### Gates that are weaker or absent on Copilot
-
-Generated from `scripts/lib/hook-dispositions.mjs` (a test fails when this block is stale). The MCP preflight refusals
-(`heyspex_claim_spec`, `heyspex_submit_for_review`, `heyspex_save_research`) are the hook-independent hard floor on every
-surface that connects the MCP server.
-
-<!-- hook-dispositions:copilot:begin (generated by scripts/lib/hook-dispositions.test.mjs; UPDATE_HOOK_DOCS=1 refreshes) -->
-| Gate | Disposition | Compensating control / what is lost |
-| --- | --- | --- |
-| `research-method-guard` | unportable | MCP preflight refusal on heyspex_save_research (hard floor, hook-independent) + .github/copilot-instructions.md research rule; Copilot has no Skill or Workflow tool to hook. |
-| `deep-research-cost-gate` | unportable | MCP preflight refusal on heyspex_save_research + .github/copilot-instructions.md cost-confirmation rule; Copilot has no Skill or Workflow tool to hook. |
-| `plan-review-gate` | unportable | MCP preflight refusals (heyspex_claim_spec / heyspex_submit_for_review / heyspex_save_research) + .github/copilot-instructions.md plan rule (state the plan in chat, claim the spec before editing) + HS-20SW directive-obligation-gate claim-before-build deny |
-| `plan-exit-ingest-gate` | unportable | MCP preflight refusals (heyspex_claim_spec / heyspex_submit_for_review / heyspex_save_research) + .github/copilot-instructions.md plan rule (state the plan in chat, claim the spec before editing) + HS-20SW directive-obligation-gate claim-before-build deny |
-| `preflight-reminder` | advisory-degraded | Copilot drops command-hook output on userPromptSubmitted (no prompt-time context channel); the text moves to sessionStart / .github/copilot-instructions.md. Real enforcement is the MCP preflight refusal. |
-| `intent-classifier-trigger` | advisory-degraded | Copilot drops command-hook output on userPromptSubmitted (no prompt-time context channel); the text moves to sessionStart / .github/copilot-instructions.md. The hook still runs and arms obligation state; the HS-20SW directive-obligation-gate turns that state into a hard deny. |
-| `inject-communication-style` | advisory-degraded | Copilot drops command-hook output on userPromptSubmitted (no prompt-time context channel); the text moves to sessionStart / .github/copilot-instructions.md. |
-| `inject-vault-context` | advisory-degraded | Copilot drops command-hook output on userPromptSubmitted (no prompt-time context channel); the text moves to sessionStart / .github/copilot-instructions.md. Per-prompt vault retrieval has no Copilot channel at all. |
-| `claim-before-code-gate` | advisory-degraded | Armed only by plan-exit-ingest-gate, which has no Copilot trigger (no ExitPlanMode tool), so it stays dormant; covered by the HS-20SW claim-before-build rule. |
-| `diagnose-capture-reminder` | advisory-degraded | Copilot preToolUse has no context channel for an inject, so this advisory is silent (lost). |
-<!-- hook-dispositions:copilot:end -->
-
-Plan mode: Copilot has no `ExitPlanMode` tool, so the plan gates cannot fire. State the plan in chat and claim the spec
-before editing code (`.github/copilot-instructions.md`); the HS-20SW claim-before-build deny backs that up.
-
-**Unverified** (no official page read, or not run live): the VS Code 128-tool per-request cap (the microsoft/vscode issue
-below is the only source); the spelling of MCP tool names inside hook payloads (hooks match by suffix); whether
-`${CLAUDE_PLUGIN_ROOT}` expands in the plugin `.mcp.json` under the Copilot CLI (documented for VS Code only); how the MCP
-server learns the Copilot session id (its preflight marker falls back to a 4 hour TTL); whether the CLI reads a Claude-format
-`hookSpecificOutput` deny.
-
-## Sources
-
-- [[HS-RDG9-RES-github-copilot-and-vs-code-mcp-support-t]] — Copilot MCP support verified mid-2026 (cloud agent = tools only).
-- [[HS-TACM-RES-tool-agnostic-mcp-compatibility-matrix-2026-05-27]] — cross-tool compatibility matrix (Copilot row being amended).
-- [MCP and GitHub Copilot cloud agent — GitHub Docs](https://docs.github.com/en/copilot/concepts/agents/coding-agent/mcp-and-coding-agent) — cloud coding agent supports MCP tools only.
-- [Adding MCP servers for GitHub Copilot CLI — GitHub Docs](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers) — `.github/mcp.json` auto-discovery.
-- [Hard tool limit (128) in VS Code agent mode — microsoft/vscode#290356](https://github.com/microsoft/vscode/issues/290356) — 128-tool per-request cap.
+# Driving HeySpex from GitHub Copilot (and other non-MCP assistants)
+
+**Capability table dated: 2026-07-10.** Harness support changes fast; re-verify against the
+sources before relying on a row. Refresh is owned by the harness-integrations pillar.
+
+HeySpex is tool-agnostic by construction. Every everyday action reaches the vault through one of
+three write paths, and at least one of them works in **any** assistant that can either speak MCP or
+run a shell command:
+
+1. **MCP tools** — `heyspex_*` tools over the Model Context Protocol (richest surface).
+2. **The `hs` CLI** — plain shell commands with stable exit codes and `--json` output. No MCP
+   client required; works in any assistant, terminal, or CI runner that can shell out.
+3. **The console web UI** — `localhost:3000`, works in any browser.
+
+This guide is the fallback path: how to drive the everyday agent loop when your assistant has
+**no** MCP tool support, using only the `hs` CLI.
+
+Grounded in [[HS-RDG9-RES-github-copilot-and-vs-code-mcp-support-t]] (the 2026 verification that
+Copilot now has a real MCP client) and [[HS-TACM-RES-tool-agnostic-mcp-compatibility-matrix-2026-05-27]]
+(the broader cross-tool matrix — note its "VS Code + Copilot = shell-only, no MCP" row is stale as
+of the RDG9 refresh and is being amended separately).
+
+## Per-harness capability table (2026-07-10)
+
+**Legend** — **MCP**: native MCP client (tools, and sometimes prompts/resources). **`hs` CLI**:
+can shell out to `hs`. **Prompts**: supports MCP prompts exposed as slash commands. **Everyday
+loop**: can do see-next → claim → report progress → submit for review.
+
+| Harness                                                              |                    MCP                     |         `hs` CLI          |           Prompts            |         Everyday loop         | Honest ceiling                                                                                                                                                                                                    |
+| -------------------------------------------------------------------- | :----------------------------------------: | :-----------------------: | :--------------------------: | :---------------------------: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **VS Code agent mode (Copilot)**                                     | ✓ full (`.vscode/mcp.json`, `servers` key) |             ✓             | ✓ (`/mcp.<server>.<prompt>`) |   via MCP tools **or** `hs`   | Full MCP spec — tools, prompts, resources, sampling, OAuth. Subject to a 128-tool per-request cap; curate the exposed tool subset.                                                                                |
+| **GitHub Copilot CLI**                                               |   ✓ (auto-discovers `.github/mcp.json`)    |             ✓             |          ✓ (`/mcp`)          |   via MCP tools **or** `hs`   | Full MCP client (GA Feb 2026). Honors the org "MCP servers in Copilot" policy gate — admin approval may be required.                                                                                              |
+| **Copilot coding agent (github.com cloud)**                          |              ✓ **tools only**              | ✓ if sandbox allows shell |         ✗ no prompts         | via MCP **tools** **or** `hs` | No MCP prompts, no resources, no OAuth. Servers are configured in repo settings, not a committed file; local/allowlisted servers only. **Do not rely on slash-command prompts here — use tools or the `hs` CLI.** |
+| **Any assistant WITHOUT MCP tool support**                           |                     ✗                      |             ✓             |              ✗               |       via `hs` CLI only       | The `hs` CLI is the complete fallback. Everything in the loop is a plain shell command; nothing is unreachable just because the assistant lacks tool support.                                                     |
+| **Claude Code / Cursor / Cline / Continue.dev / Google Antigravity** |                  ✓ native                  |             ✓             |              ✓               |    via MCP tools (primary)    | First-class MCP today; the `hs` CLI is available as a fallback. See [[HS-TACM-RES-tool-agnostic-mcp-compatibility-matrix-2026-05-27]].                                                                            |
+
+Design consequence: keep the primary UX in **tools**, not MCP prompts, because the cloud coding
+agent doesn't support prompts. Treat slash-command prompts as a VS Code / Copilot-CLI enhancement,
+and the `hs` CLI as the universal floor. HeySpex does **not** promise native slash-command parity on
+a surface that cannot support prompts.
+
+## The everyday loop with the `hs` CLI
+
+Run these from anywhere inside the vault (the CLI walks up to find `specs/`; or set
+`HS_VAULT_ROOT`). All four commands are pure shell — no MCP client involved. Add `--json` for
+machine-readable output.
+
+### 1. See what's next
+
+```bash
+hs next --summary --json
+```
+
+Returns the on-deck brief (spec id, title, summary, and a claim target). Drop `--json` for the
+human-readable prompt; drop `--summary` for the full post-claim execution brief.
+
+### 2. Claim the work
+
+```bash
+hs claim acquire HS-WJ1C-TASK --json
+```
+
+Atomic: two concurrent acquires for one spec yield exactly one success and one `already_claimed`
+conflict (exit 9) that names the existing claimant. Release on hand-off with
+`hs claim release HS-WJ1C-TASK`.
+
+### 3. Report progress
+
+```bash
+hs claim progress HS-WJ1C-TASK --stage Grounding --ac 0
+```
+
+`--stage` takes a work-stage verb (Grounding, Breaking down, Drafting, Validating, Testing,
+Reviewing). `--ac <n>` is the 0-based acceptance-criterion index you are on — it drives the live
+checklist on the What's Next surface. Call it again as you move between stages and complete criteria.
+
+### 4. Submit for review
+
+```bash
+hs mcp call heyspex_submit_for_review --arg spec_id=HS-WJ1C-TASK --json
+```
+
+`hs mcp call` runs a single MCP tool as a **one-shot shell command** — it does not require your
+assistant to be an MCP client. This close-out step validates acceptance-criteria progress against
+your claim, PATCHes the status API (never hand-edit frontmatter `status:`), applies review-grain
+coercion and parent rollup, releases the claim, and returns close-out guidance. A `409` on submit is
+a real reason (e.g. incomplete criteria) — report it, don't work around it.
+
+> Why `hs mcp call` and not a dedicated `hs submit` verb: see-next, claim, and report-progress each
+> have a first-class `hs` verb; submit-for-review is reached through the generic one-shot MCP-call
+> escape hatch, which reuses the exact close-out logic the MCP tool runs. It is still a plain shell
+> command with no MCP-client requirement.
+
+## Configuring MCP where it IS supported
+
+For VS Code agent mode and Copilot CLI you get the richer MCP tool surface. The MCP config
+templates (`.vscode/mcp.json` with the `servers` key, `.github/mcp.json` for Copilot CLI
+auto-discovery) and the Copilot instructions file are owned by the harness-integrations config work
+and documented separately — this guide covers only the universal `hs` CLI fallback.
+
+## Hooks under Copilot
+
+Copilot CLI runs the HeySpex hooks it finds in `.claude/settings.json` (and the plugin's `hooks/hooks.json`), so the
+gates (capture-on-idea obligation, claim-before-build, naming guards) apply to Copilot agents too. What differs:
+
+- **Fail-closed**: Copilot denies a tool call when a `preToolUse` command crashes or exits non-zero. Every registered
+  command is therefore a self-locating bootstrap that does not need `$CLAUDE_PROJECT_DIR` and exits 0 when it cannot find
+  the HeySpex runtime; `_run.mjs` itself never exits non-zero except for a deliberate deny (translated to Copilot's
+  top-level `{"permissionDecision":"deny"}` JSON with exit 0).
+- **Turn it off**: `hs mode off` (all harnesses, per project; `hs mode on|status|toggle`), `HEYSPEX_MODE=off` for one
+  shell, or `HEYSPEX_COPILOT_HOOKS_OFF=1` / `agent_behaviors.harness_hooks.copilot.enabled: false` for Copilot only.
+  The four always-on security gates (`env-vault-guard`, `research-method-guard`, `research-protocol-gate`,
+  `git-identity-guard`) ignore all three.
+- **Stopgap on an older checkout** (before the bootstrap ships): `HEYSPEX_MODE=off` only helps if the hook command can
+  start, and the old command needs `CLAUDE_PROJECT_DIR`; export it (`CLAUDE_PROJECT_DIR=<repo>`) alongside `HEYSPEX_MODE=off`.
+
+### One source of hooks, and the cloud agent
+
+Plugin OR repo hooks, never both: Copilot CLI loads the heyspex plugin AND the repo's `.claude/settings.json` /
+`.github/hooks/*.json`, so a repo with both fires every hook twice. `npm run doctor` (check `hook-double-fire`) warns
+about that and reports `unknown`, not a failure, when it cannot read a plugin registry.
+
+The rows `hs install` commits into `.claude/settings.json` are the one case that resolves itself: they run through
+the committed launcher `.claude/heyspex/run-hook.mjs` (marker `// yields-to-plugin: v1`), which exits 0 silently
+when a heyspex plugin is enabled on this machine (installed in `~/.claude/plugins/installed_plugins.json`, enabled in
+`enabledPlugins`, or present under `~/.copilot/installed-plugins` / `~/.copilot/plugins`) — so the plugin's copy fires
+and the repo's does not. `enabledPlugins["heyspex@..."] === false` (user or project settings) means the plugin is off for
+that harness and the repo rows run; `HEYSPEX_REPO_HOOKS=1` never yields. The doctor reports `ok` for a repo whose every
+`.claude/settings*.json` row goes through a yielding launcher. `.github/hooks/*.json` rows never use the launcher: for
+those, plugin OR hooks stays a real choice.
+
+The Copilot **cloud agent** loads no plugins: its only hook source is `.github/hooks/*.json` on the **default branch**.
+`npm run hooks:write-github` generates `.github/hooks/heyspex.json` (bash `command` entries only, camelCase events,
+resolving `node_modules/heyspex/scripts/claude-hooks/_run.mjs` then `./scripts/claude-hooks/_run.mjs`, else exit 0).
+Requirements: the sandbox must contain `node_modules/heyspex` (install it in `copilot-setup-steps`), the firewall must
+allow the console URL (claim heartbeats), and MCP is configured in repository settings (tools only, no OAuth).
+
+### Gates that are weaker or absent on Copilot
+
+Generated from `scripts/lib/hook-dispositions.mjs` (a test fails when this block is stale). The MCP preflight refusals
+(`heyspex_claim_spec`, `heyspex_submit_for_review`, `heyspex_save_research`) are the hook-independent hard floor on every
+surface that connects the MCP server.
+
+<!-- hook-dispositions:copilot:begin (generated by scripts/lib/hook-dispositions.test.mjs; UPDATE_HOOK_DOCS=1 refreshes) -->
+| Gate | Disposition | Compensating control / what is lost |
+| --- | --- | --- |
+| `research-method-guard` | unportable | MCP preflight refusal on heyspex_save_research (hard floor, hook-independent) + .github/copilot-instructions.md research rule; Copilot has no Skill or Workflow tool to hook. |
+| `deep-research-cost-gate` | unportable | MCP preflight refusal on heyspex_save_research + .github/copilot-instructions.md cost-confirmation rule; Copilot has no Skill or Workflow tool to hook. |
+| `plan-review-gate` | unportable | MCP preflight refusals (heyspex_claim_spec / heyspex_submit_for_review / heyspex_save_research) + .github/copilot-instructions.md plan rule (state the plan in chat, claim the spec before editing) + HS-20SW directive-obligation-gate claim-before-build deny |
+| `plan-exit-ingest-gate` | unportable | MCP preflight refusals (heyspex_claim_spec / heyspex_submit_for_review / heyspex_save_research) + .github/copilot-instructions.md plan rule (state the plan in chat, claim the spec before editing) + HS-20SW directive-obligation-gate claim-before-build deny |
+| `preflight-reminder` | advisory-degraded | Copilot drops command-hook output on userPromptSubmitted (no prompt-time context channel); the text moves to sessionStart / .github/copilot-instructions.md. Real enforcement is the MCP preflight refusal. |
+| `intent-classifier-trigger` | advisory-degraded | Copilot drops command-hook output on userPromptSubmitted (no prompt-time context channel); the text moves to sessionStart / .github/copilot-instructions.md. The hook still runs and arms obligation state; the HS-20SW directive-obligation-gate turns that state into a hard deny. |
+| `inject-communication-style` | advisory-degraded | Copilot drops command-hook output on userPromptSubmitted (no prompt-time context channel); the text moves to sessionStart / .github/copilot-instructions.md. |
+| `inject-vault-context` | advisory-degraded | Copilot drops command-hook output on userPromptSubmitted (no prompt-time context channel); the text moves to sessionStart / .github/copilot-instructions.md. Per-prompt vault retrieval has no Copilot channel at all. |
+| `claim-before-code-gate` | advisory-degraded | Armed only by plan-exit-ingest-gate, which has no Copilot trigger (no ExitPlanMode tool), so it stays dormant; covered by the HS-20SW claim-before-build rule. |
+| `diagnose-capture-reminder` | advisory-degraded | Copilot preToolUse has no context channel for an inject, so this advisory is silent (lost). |
+<!-- hook-dispositions:copilot:end -->
+
+Plan mode: Copilot has no `ExitPlanMode` tool, so the plan gates cannot fire. State the plan in chat and claim the spec
+before editing code (`.github/copilot-instructions.md`); the HS-20SW claim-before-build deny backs that up.
+
+**Unverified** (no official page read, or not run live): the VS Code 128-tool per-request cap (the microsoft/vscode issue
+below is the only source); the spelling of MCP tool names inside hook payloads (hooks match by suffix); whether
+`${CLAUDE_PLUGIN_ROOT}` expands in the plugin `.mcp.json` under the Copilot CLI (documented for VS Code only); how the MCP
+server learns the Copilot session id (its preflight marker falls back to a 4 hour TTL); whether the CLI reads a Claude-format
+`hookSpecificOutput` deny.
+
+## Sources
+
+- [[HS-RDG9-RES-github-copilot-and-vs-code-mcp-support-t]] — Copilot MCP support verified mid-2026 (cloud agent = tools only).
+- [[HS-TACM-RES-tool-agnostic-mcp-compatibility-matrix-2026-05-27]] — cross-tool compatibility matrix (Copilot row being amended).
+- [MCP and GitHub Copilot cloud agent — GitHub Docs](https://docs.github.com/en/copilot/concepts/agents/coding-agent/mcp-and-coding-agent) — cloud coding agent supports MCP tools only.
+- [Adding MCP servers for GitHub Copilot CLI — GitHub Docs](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers) — `.github/mcp.json` auto-discovery.
+- [Hard tool limit (128) in VS Code agent mode — microsoft/vscode#290356](https://github.com/microsoft/vscode/issues/290356) — 128-tool per-request cap.

package/docs/mcp-client-config.md

@@ -91,10 +91,7 @@ Project scope — `.mcp.json` in the root of the repository you want HeySpex to
     "heyspex": {
       "type": "stdio",
       "command": "heyspex-mcp",
-      "args": [],
-      "env": {
-        "HEYSPEX_VAULT_ROOT": "."
-      }
+      "args": []
     }
   }
 }
@@ -108,15 +105,18 @@ If you did not install globally, use the no-install form instead:
     "heyspex": {
       "type": "stdio",
       "command": "npx",
-      "args": ["--yes", "--package", "heyspex", "heyspex-mcp"],
-      "env": {
-        "HEYSPEX_VAULT_ROOT": "."
-      }
+      "args": ["--yes", "--package", "heyspex", "heyspex-mcp"]
     }
   }
 }
 ```
 
+No `HEYSPEX_VAULT_ROOT` here: the server resolves its vault from the folder the
+client launches it in (the vault checkout itself, or a code repo bound with
+`hs vault bind`; see [Which vault the server reads](#which-vault-the-server-reads)).
+Set `HEYSPEX_VAULT_ROOT` only to point at a vault checkout on purpose; pointing it
+at anything else is refused (`VAULT_NOT_FOUND`).
+
 User scope, from any directory:
 
 ```sh
@@ -133,10 +133,7 @@ same object:
   "mcpServers": {
     "heyspex": {
       "command": "heyspex-mcp",
-      "args": [],
-      "env": {
-        "HEYSPEX_VAULT_ROOT": "."
-      }
+      "args": []
     }
   }
 }
@@ -202,21 +199,92 @@ shipped fix.
 
 ## Which vault the server reads
 
-Resolution order, highest first. The directory the process actually started
-in outranks the machine-wide active pointer: a server started inside one vault
-must never write its bookkeeping into whichever vault another terminal last
-marked active.
+**Contract.** There is no single "active" vault. Every vault is active at
+once: a process writes to the vault that belongs to the folder it was launched
+in (owner ruling 2026-10-14, HS-TYJA). The MCP server, `hs`, `spexcode` and
+dev-factory share one resolver (`vendor/heyspex-mcp/vault-resolve.mjs`); the
+console's TypeScript twin (`spex-console/src/lib/vault-resolve/index.ts`)
+follows the same order, checked by one shared fixture
+(`spex-console/src/lib/vault-resolve/precedence-fixtures.json`). The full
+contract is the header of `vendor/heyspex-mcp/vault-binding.mjs`.
+
+### Resolution order (first match wins)
+
+| # | Source | Rule |
+|---|---|---|
+| 1 | Explicit vault id: `hs --vault <id> <cmd>` | Must name a vault registered on this machine. Otherwise `VAULT_NOT_FOUND`; it never falls through to another vault. |
+| 2 | `HEYSPEX_VAULT_ROOT` (repo root) / `HEYSPEX_VAULT_DIR` (the `specs/` folder) | A deliberate override, above everything on disk. It must name a vault: a checkout on disk (`specs/` or a vault-marker `heyspex.yaml`) or a root registered as a vault in `~/.heyspex/registry.json`. Anything else, such as an unregistered code repo, is `VAULT_NOT_FOUND` and is never silently accepted. |
+| 3 | The launch folder, walking up to the filesystem root | Symlinks and junctions are resolved first, and the nearest folder wins. At each level, in this order: a satellite pin in `.mcp.json` / `.cursor/mcp.json`, then a vault checkout (`specs/`, or a vault-marker `heyspex.yaml`), then a repo binding (`heyspex.yaml` with `kind: repo-binding`). A linked git worktree that matches nothing resolves like its main checkout. |
+| 4 | Nothing | `VAULT_UNBOUND`. The MCP server still boots and lists its tools, but every vault-scoped call is refused locally with the code and the fix. Nothing is sent. |
+
+The launch folder is the client's project dir (`CLAUDE_PROJECT_DIR`) when the
+client sets one, and otherwise the process's working directory. The
+registry's `active_vault_id` (and the per-account pointers) are **never read**
+by local resolution. `hs vault switch` still writes the pointer for the cloud
+console and prints a deprecation note saying so.
+
+### Two files called heyspex.yaml, never confused
+
+| File | Lives in | Written by | Keys | Commit it? |
+|---|---|---|---|---|
+| Vault marker | a vault checkout's root | `hs init` | `schema_version`, `vault_root: specs/`, `vault_id` | yes (it is the vault) |
+| Repo binding | a code repo's root | `hs vault bind` | `kind: repo-binding`, `binding_version`, `vault: {id, name, remote}` | **yes**. It holds no machine path. |
+
+The binding names the vault by identity only:
+
+```yaml
+kind: repo-binding
+binding_version: 1
+vault:
+  id: 800f39cb-9245-412e-b957-e42fb80e2d8b
+  name: heyspex-specs
+  remote: github.com/pwhermanson/heyspex-specs
+```
+
+Where that vault is checked out is per machine. The resolver goes from the
+binding's `id` to the registry row with that id in `~/.heyspex/registry.json`
+(`vaults[].repo_root_abs`), and from there to the folder. If this machine has
+no such row, the result is `VAULT_BINDING_BROKEN`. It never guesses. If the
+row exists but its folder is gone, the id still resolves (with a notice), so
+cloud tools keep working. Disk-tier tools refuse until the vault is cloned
+back. The registry's `linked_repos[]` is a per-machine reverse index
+of the folders bound on this machine; resolution does not need it.
+
+### Commands
+
+```
+hs vault bind --vault <name|id> [--repo <dir>] [--force] [--dry-run] [--json]
+    Run inside the code repo. Writes heyspex.yaml (kind: repo-binding) and the
+    registry linked_repos[] row. Both writes are atomic, and the registry is
+    backed up once to registry.json.bak-pre-linked-repos. Idempotent: an
+    unchanged re-run writes nothing. It refuses to re-point a bound repo
+    without --force, and refuses inside a vault checkout.
+hs vault bindings [--json]
+    Every binding on this machine, health-checked (ok / repo-missing /
+    marker-missing / marker-differs / vault-unknown), plus how this folder
+    resolves.
+hs vault resolve [--json]
+    Which vault an agent launched here writes to, and why. Exit code 0 when
+    resolved, 1 with the typed error. The --json shape is stable:
+      { ok: true,  cwd, source, vault_id, vault_root, bound_repo?, worktree_of? }
+      { ok: false, cwd, source: "unbound", error, code, message, from, fix, details }
+```
+
+### Errors
+
+Every resolution error carries `code`, `message`, `from` (the folder the
+resolver walked from) and `fix` (the exact command). MCP tool refusals carry
+the same `refusal` code plus `fix` and `from`.
 
-| # | Source | Notes |
+| Code | Meaning | `fix` |
 |---|---|---|
-| 1 | An explicit vault id | `hs vault use <id>`, or `hs --vault <id> <cmd>` |
-| 2 | `HEYSPEX_VAULT_ROOT` / `HEYSPEX_VAULT_DIR` | the repository root / the `specs/` directory itself; what the config above sets |
-| 3 | A vault or a satellite attachment at or above the working directory | walks up from the working directory; the nearest match wins, and an attachment beats a `heyspex.yaml` / `specs/` marker found at the same or a higher level |
-| 4 | `active_vault_id` in `~/.heyspex/registry.json` | the offline active-vault pointer — reached only when the working directory sits inside no vault at all |
-| 5 | The working directory | last resort, when nothing above matched |
-
-Tier 3 is what makes [satellite repos](#satellite-repos-code-here-specs-elsewhere)
-work, and why they do not depend on the active pointer.
+| `VAULT_UNBOUND` | The folder is in no vault checkout and no bound repo. | `hs vault bind --vault <name\|id>` |
+| `VAULT_BINDING_BROKEN` | `heyspex.yaml` binds a vault id this machine has no registry row for. | Clone it (or `hs pull` in an existing checkout), run `hs vault register <path>`, then `hs vault bind --vault <id>`. |
+| `VAULT_NOT_FOUND` | `--vault` names no registered vault, `HEYSPEX_VAULT_ROOT` / `HEYSPEX_VAULT_DIR` names neither a checkout nor a registered vault root, or `bind --vault X` names no registered vault. | `hs vault list`, `unset HEYSPEX_VAULT_ROOT`, or `hs vault register <path>` |
+| `VAULT_BINDING_CONFLICT` | `bind` would re-point a repo that is already bound. | `hs vault bind --vault <id> --force` |
+| `VAULT_BIND_TARGET_IS_VAULT` | `bind` ran inside a vault checkout. | `hs vault resolve` (nothing to bind) |
+| `REPO_NOT_FOUND` | The `--repo` folder does not exist. | `hs vault bind --repo <existing folder> --vault <name\|id>` |
+| `REGISTRY_UNREADABLE` | `registry.json` does not parse. `bind` never overwrites it. | `hs doctor --fix` |
 
 ## Satellite repos: code here, specs elsewhere