heyspex 0.2.1 → 0.2.3

package/plugins/heyspex/README.md

@@ -1,309 +1,323 @@
-# SpexCode plugin (for Claude Code and GitHub Copilot CLI) — Claude Code + Copilot CLI + Cursor (prototype)
-
-Prototype packaging of HeySpex's agent integration as a self-hosted plugin for **both** hosts,
-implementing migration-path steps 1–2 of [[HS-QTBK-5EK5-RES-claude-code-plugin-packaging-for]].
-**Additive:** the project-level wiring stays live and remains the source of truth
-(`.mcp.json` + `.claude/settings.json` for Claude Code; `.cursor/mcp.json` +
-`.cursor/hooks.json` for Cursor). Nothing here activates until the plugin is explicitly installed.
-
-One plugin directory, two manifests — the hosts read different files and never see each other's.
-
-## Layout
-
-| Path | Host | What it is |
-| --- | --- | --- |
-| `.claude-plugin/plugin.json` | Claude Code | Plugin manifest (`name: heyspex`). |
-| `.cursor-plugin/plugin.json` | Cursor | Plugin manifest. Names `mcp.json` and `hooks/cursor-hooks.json` EXPLICITLY, because a Cursor manifest path replaces auto-discovery — without it Cursor would find `hooks/hooks.json` and try to read Claude-shaped config. |
-| `.mcp.json` | Claude Code | MCP server declaration — launches `bin/launch-mcp.mjs` via `${CLAUDE_PLUGIN_ROOT}`. |
-| `mcp.json` | Cursor | MCP server declaration. Runs `${CURSOR_PLUGIN_ROOT}/bin/launch-mcp.mjs` (Cursor expands that variable to the plugin install path), the same launcher `.mcp.json` uses, so it boots from a plain `npm install heyspex`; `HEYSPEX_VAULT_ROOT` is `${workspaceFolder}`. |
-| `bin/launch-mcp.mjs` | Claude Code | Resolver shim: locates `vendor/heyspex-mcp/cli.mjs` in the host vault repo (`HEYSPEX_MCP_ENTRY` override → `$CLAUDE_PROJECT_DIR` → `$CURSOR_PROJECT_DIR` → `$HEYSPEX_VAULT_ROOT` → cwd) and hands off in-process. Needed because the server's deps come from the repo's `node_modules`, so it can't yet run from the plugin's versioned cache copy. |
-| `hooks/hooks.json` | Claude Code, Copilot CLI | **Generated** from the customer-scoped rows of `scripts/lib/customer-kit.mjs` (`node scripts/lib/customer-kit.mjs --write-plugin-hooks`; a test fails on drift). Every command is a self-locating inline bootstrap (plugin-root env `CLAUDE_PLUGIN_ROOT`/`COPILOT_PLUGIN_ROOT`/`PLUGIN_ROOT` → `bin/run-hook.mjs`, else a walk up from the cwd to `scripts/claude-hooks/_run.mjs`, else exit 0) that reaches `bin/run-hook.mjs`, which finds the platform checkout (`HEYSPEX_PLATFORM_ROOT` → `HEYSPEX_MCP_ENTRY` → its own checkout → `node_modules/heyspex` → `$CLAUDE_PROJECT_DIR`) — never `$CLAUDE_PROJECT_DIR/scripts`, which only exists in heyspex-app. MCP-tool matchers carry both `mcp__heyspex__*` and `mcp__plugin_heyspex_heyspex__*` names. |
-| `.github/hooks/heyspex.json` (repo root) | Copilot cloud agent | **Generated** by `npm run hooks:write-github`; bash-only, default branch only. See "Copilot cloud agent" below. |
-| `bin/run-hook.mjs` | Claude Code | Hook launcher: resolves the platform shim `scripts/claude-hooks/_run.mjs` and hands off in-process (fail-open, like the shim). |
-| `hooks/cursor-hooks.json` | Cursor | **Generated** from `scripts/cursor-hooks/manifest.mjs` by `npm run hooks:install-cursor`; drift is a `hs doctor` failure. Commands resolve through `$CURSOR_PROJECT_DIR`. |
-
-Each host has its own marketplace catalog at the repo root, both pointing at this directory:
-`.claude-plugin/marketplace.json` and `.cursor-plugin/marketplace.json` — the documented
-self-hosted single-repo pattern; no hosted registry involved.
-
-## Installing
-
-### From the npm package (customers; no heyspex-app checkout)
-
-A team that only installs the published `heyspex` package does not have, and does not need, the
-heyspex-app repository. The package carries the marketplace (`node_modules/heyspex/.claude-plugin/marketplace.json`,
-plugin source `./plugins/heyspex`), the hooks and the MCP server. From the root of your own repo:
-
-```bash
-npm install heyspex                      # or: npm install ./heyspex-<version>.tgz
-npx hs login
-npx hs install --target . --plugin-apply            # Claude Code
-npx hs install --target . --copilot-plugin-apply    # GitHub Copilot CLI (plugin) ...
-npx hs install --target . --copilot-hooks           # ... OR repo hooks in .github/hooks, never both
-```
-
-By hand: `claude plugin marketplace add ./node_modules/heyspex` /
-`copilot plugin marketplace add ./node_modules/heyspex`, then `... plugin install heyspex@heyspex-marketplace`.
-Restart the session (`/restart` in Copilot), then check `copilot plugin list` and `npx hs doctor`.
-Full walkthrough: `node_modules/heyspex/docs/copilot-plugin-install.md`. The sections below describe the same plugin from the
-platform checkout and are for HeySpex developers.
-
-### Claude Code
-
-One command, from the platform checkout (wraps the manual flow below):
-
-```bash
-node bin/hs.mjs install --target <consumer-repo> --plugin-apply
-```
-
-`--plugin` prints the commands instead of running them. The equivalent manual flow, inside a
-Claude Code session in the consumer repo — or via the `claude plugin` CLI:
-
-```
-/plugin marketplace add <path-or-git-url-of-this-repo>
-/plugin install heyspex@heyspex-marketplace
-```
-
-### GitHub Copilot CLI
-
-Copilot CLI installs Claude-format plugins (`.claude-plugin/plugin.json`) from a marketplace
-(`.claude-plugin/marketplace.json` is on its search path). Source of truth for the commands and the
-file layout: <https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference>
-(fetched 2026-10-16). Hook behaviour: <https://docs.github.com/en/copilot/reference/hooks-configuration>.
-
-```bash
-copilot plugin marketplace add <owner>/<repo>          # or a git URL or a local path to this repo
-copilot plugin install heyspex@heyspex-marketplace      # SPECIFICATION is plugin@marketplace
-copilot plugin list                                    # confirm it is enabled
-```
-
-For local development: `copilot plugin marketplace add /path/to/heyspex-app`; a path-sourced plugin in a local
-marketplace loads live (`/restart` picks up edits).
-
-What gets loaded:
-
-| Component | Loaded from | Notes |
-| --- | --- | --- |
-| Hooks | `hooks/hooks.json` | Same file Claude Code reads. PascalCase events (`PreToolUse`, `PostToolUse`, `Stop`...) use Claude matcher semantics and snake_case payloads. Every command is a self-locating inline bootstrap: it needs no `$CLAUDE_PROJECT_DIR` and exits 0 when it cannot find the runtime (Copilot turns any non-zero exit into a deny). |
-| MCP | `.mcp.json` | Legacy-plugin MCP file. Its `${CLAUDE_PLUGIN_ROOT}` expansion under Copilot is **not documented** (Copilot documents `${PLUGIN_ROOT}` for Agent Plugins `mcp.json` only) and could not be verified without a Copilot CLI on the build machine. If the server does not start, add it explicitly: `copilot mcp add heyspex -- node <install-path>/plugins/heyspex/bin/launch-mcp.mjs`. |
-| Skills / prompts | MCP prompts (`hs-*`) | Delivered by the MCP server. **The Copilot cloud coding agent has no prompts**; there use the `hs` CLI loop in `docs/driving-heyspex-from-copilot.md`. |
-| Commands | not loaded | Claude Code slash commands are not a Copilot component. |
-
-### One source of hooks: plugin OR repo hooks, never both
-
-Copilot CLI (and Claude Code) load hooks from the plugin AND from the repository's own registrations
-(`.claude/settings.json`, `.claude/settings.local.json`, `.github/hooks/*.json`). A repo that has both runs every HeySpex
-hook twice. Pick one per repo:
-
-- **Plugin** (this directory): `copilot plugin install heyspex@heyspex-marketplace` / `/plugin install ...`. Do not run
-  `hs install` hook registration in the same repo, or strip it afterwards.
-- **Repo hooks** (`hs install`, which writes `.claude/settings.json` + the committed launcher): do not also install the plugin.
-
-`npm run doctor` has a `hook-double-fire` check: it warns when HeySpex rows in the repo's `.claude/settings*.json` or
-`.github/hooks/*.json` coexist with an installed heyspex plugin, and reports `unknown` (never a failure) when no plugin
-registry can be read. What it looks at: `~/.claude/plugins/installed_plugins.json` (a `heyspex@...` key),
-`enabledPlugins` in `~/.claude/settings.json` and the project's Claude settings, and, best effort, a heyspex directory
-under `~/.copilot/installed-plugins` or `~/.copilot/plugins` (the Copilot plugin list file is not documented; `copilot
-plugin list` is the authority). As a runtime backstop, `_run.mjs` also de-duplicates a repeated Copilot invocation
-(`HEYSPEX_COPILOT_DEDUPE_OFF=1` disables that).
-
-### Copilot cloud agent: `.github/hooks/heyspex.json`
-
-The Copilot **cloud agent** loads no plugins and no user-level hook files; its only hook source is `.github/hooks/*.json`
-**on the default branch**. `.github/hooks/heyspex.json` is therefore generated from the same customer rows as
-`hooks/hooks.json`, restricted to the hooks whose Copilot disposition is `mapped` (plus `intent-classifier-trigger`, which
-only arms the capture obligation state and whose dropped output does not matter):
-
-```bash
-npm run hooks:write-github     # node scripts/lib/customer-kit.mjs --write-github-hooks  (a test fails on drift)
-npm run hooks:check-github     # exit 1 when stale
-```
-
-- Linux bash only: every entry is `type: "command"` with a `bash` command that resolves
-  `node_modules/heyspex/scripts/claude-hooks/_run.mjs`, then `./scripts/claude-hooks/_run.mjs`, else `exit 0` (fail open).
-  Events are the camelCase names (`sessionStart`, `preToolUse`, `postToolUse`, `userPromptSubmitted`, `agentStop`,
-  `sessionEnd`, `preCompact`); matchers use Copilot tool names (`create|edit|bash|powershell|task`, MCP tools as a
-  `.*<tool>` suffix).
-- The cloud sandbox must contain `node_modules/heyspex` (run `npm install` in the `copilot-setup-steps` workflow), or the
-  hooks silently no-op.
-- The firewall must allow the console URL (`emit-claim-status` and claim heartbeats call it), or those hooks time out (timeouts fail open).
-- The file only takes effect once it is on the repository's **default branch**.
-- If the repo also carries `.claude/settings.json` HeySpex rows, Copilot CLI reads both files: that is the double-fire case
-  above. Use the manifest for the cloud agent only, or rely on the shim de-duplication.
-- MCP is configured in the repository's Copilot settings (tools only, no OAuth), not by a committed file.
-
-### Gates that are weaker or absent on Copilot (published list)
-
-Parity is not identity. Where Copilot has a trigger the gate is a hard deny or re-drive; the rows below are the exceptions.
-The list is generated from `scripts/lib/hook-dispositions.mjs` (the single three-host table, which also covers Claude Code
-and Cursor) and a test fails when this block is stale. The hard floor under all of it is the MCP server itself:
-`heyspex_claim_spec`, `heyspex_submit_for_review` and `heyspex_save_research` refuse without a preflight marker on every
-surface that connects the MCP server, with no hook involved.
-
-<!-- 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 -->
-
-Unverified on Copilot (no official page read, or not run live): the VS Code 128-tool-per-request cap; the spelling of MCP
-tool names inside hook payloads (matched by suffix); `${CLAUDE_PLUGIN_ROOT}` expansion for the plugin `.mcp.json` under
-the Copilot CLI (documented for VS Code only); and how the MCP server learns the Copilot session id (its preflight marker
-falls back to a 4 hour TTL when the runtime exposes none). Also unverified: that a Claude-format `hookSpecificOutput` deny is
-read by the CLI (only the top-level `permissionDecision` form and exit 2 are documented), and where a `matcher` is read
-in the camelCase `.github/hooks` entry shape.
-
-### Turning HeySpex on and off (any harness)
-
-One switch, `hs mode` (alias `heyspex mode`; from a checkout without `hs` on PATH: `node bin/hs.mjs mode ...`):
-
-```bash
-hs mode status      # on | off, and why
-hs mode off         # writes <project>/.heyspex/mode.json; every hook exits 0 at once (no restart)
-hs mode on
-hs mode toggle
-```
-
-- `HEYSPEX_MODE=off` silences hooks for one shell/session without touching a file (wins over the file).
-- `HEYSPEX_COPILOT_HOOKS_OFF=1` (or `agent_behaviors.harness_hooks.copilot.enabled: false` in the vault `.heyspex/config.yaml`)
-  silences every hook **only when the caller is GitHub Copilot**; Claude Code and Cursor keep theirs.
-- The switch is read from the PROJECT being worked on (`CLAUDE_PROJECT_DIR`, then the hook payload `cwd`, then upward
-  from the working directory), so `hs mode off` in a customer repo works even though the hooks run from `node_modules/heyspex`.
-- Four security gates ignore the switch by design (`env-vault-guard`, `research-method-guard`, `research-protocol-gate`,
-  `git-identity-guard`): an agent must not be able to disarm them by writing one JSON file. Their own env-var
-  break-glass (set by a human) still applies. The Copilot opt-out does not cover them either unless the owner extends it.
-
-### Cursor
-
-For local development, symlink or copy this directory into Cursor's local plugin root and
-reload the window (**Developer: Reload Window**):
-
-```
-~/.cursor/plugins/local/heyspex
-```
-
-Otherwise add the repo as a marketplace source from Cursor's plugin surface; the root
-`.cursor-plugin/marketplace.json` catalogs it.
-
-**In the platform repo itself you do not need the plugin at all** — `.cursor/hooks.json`,
-`.cursor/mcp.json`, `.cursor/rules/`, `.cursor/skills/` and `.cursor/commands/` are already
-installed and are the live path. The plugin exists for CONSUMER repos.
-
-## Running Claude Code against Ollama or DeepSeek
-
-Claude Code can be pointed at a local Ollama instance or DeepSeek's cloud API through
-`ANTHROPIC_BASE_URL`: both expose an Anthropic Messages API-compatible endpoint, so Claude
-Code talks to them directly with no proxy. The recipes below are verified against each
-vendor's own docs ([[HS-REF-pointing-claude-code-at-non-anthropic]]).
-
-### Ollama (local)
-
-Requires Ollama 0.14+, which added a native Anthropic-compatible endpoint. The auth token is
-required but ignored.
-
-```bash
-# one-shot
-ollama launch claude --model qwen3-coder
-
-# manual
-export ANTHROPIC_AUTH_TOKEN=ollama
-export ANTHROPIC_API_KEY=""
-export ANTHROPIC_BASE_URL=http://localhost:11434
-claude --model qwen3-coder
-```
-
-### DeepSeek (cloud)
-
-```bash
-export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
-export ANTHROPIC_API_KEY=your-deepseek-api-key
-claude
-```
-
-The `/anthropic` path is required — the bare host `https://api.deepseek.com` (without
-`/anthropic`) is not the Anthropic-compatible endpoint. DeepSeek's own docs specify
-`ANTHROPIC_API_KEY`, not `ANTHROPIC_AUTH_TOKEN`.
-
-### Model name mapping (DeepSeek)
-
-There is no `ANTHROPIC_MODEL` var to set manually — model choice is automatic name-mapping:
-Claude Opus names map to `deepseek-v4-pro` (billed at V4 Pro price), while every other Claude
-name (Haiku/Sonnet) and any unmapped name maps to `deepseek-flash`.
-
-### Known DeepSeek limitations
-
-- `top_p` fixed at 1.0 outside thinking mode (min 0.95 inside it).
-- Unsupported Anthropic content types: documents, search results, redacted thinking, code
-  execution results, MCP tool integrations, container uploads.
-- `budget_tokens` in thinking-mode config is ignored.
-
-### Enforcement is independent of the backend
-
-HeySpex hooks fire regardless of backend: Claude Code hooks fire at session, turn, and
-tool-call points of Claude Code's own loop, so every HeySpex hook in `.claude/settings.json`
-and `plugins/heyspex/hooks/` runs unchanged regardless of backend — see the
-[Claude Code hooks reference](https://code.claude.com/docs/en/hooks).
-
-### Launcher
-
-`hs next <id> --launch --backend ollama|deepseek` sets the right env vars and execs `claude`.
-This is the supported path, shipping with epic
-[[HS-30JD-94Q5-EPIC-claude-code-launches-against-ollama-or]]; until then, use the manual
-recipe above.
-
-## Validating (migration-path step 3)
-
-Run the install above in a **fresh clone / separate consumer repo** (avoids the double-hook
-caveat below), after `npm install` in the platform checkout.
-
-Then restart the session and confirm:
-
-1. The MCP server connects and tools appear as `mcp__plugin_heyspex_heyspex__heyspex_*`.
-2. Hooks fire (SessionStart seat injection, PreToolUse gates) — and only once.
-3. The re-prefix blast radius: anything load-bearing that hardcodes `mcp__heyspex__*`
-   (CLAUDE.md, `.claude/settings.json` permission allow/deny lists, procedures, hook scripts)
-   still behaves. This is the migration cost the research flags as largest.
-
-## Known caveats (by design, this stage)
-
-- **Double-fire:** enabling this plugin in a repo that still registers the same hooks project-level
-  runs every hook twice. Single-source rule: plugin OR repo hooks, never both (see above; `npm run doctor` warns).
-  Validate in a fresh clone, or strip the project hooks first (`node scripts/install-cursor-hooks.mjs --uninstall` for Cursor).
-- **Not standalone:** the plugin requires a HeySpex vault checkout with `npm install` run —
-  the MCP server and hook scripts resolve from the host project, not the plugin cache.
-  Bundling the server into the plugin is a full-cutover-stage task.
-- **`hs-*` skills stay MCP prompts** (research step 4, unresolved): they travel with the MCP
-  server, not as plugin `SKILL.md` files. Commands, rules and agents are deliberately not
-  duplicated here to avoid drift and double registration — which matters more for Cursor, whose
-  plugin format CAN carry `rules/`, `commands/` and `skills/`. Bundling them is a cutover decision,
-  not a packaging one.
-- **Permissions/statusLine are not mirrored** — those remain project-level concerns.
-- **Manual updates are two steps and scope-sensitive:** `claude plugin marketplace update
-  heyspex-marketplace` refreshes the catalog only; the installed copy moves on
-  `claude plugin update heyspex@heyspex-marketplace --scope project` (the CLI defaults to
-  `--scope user` and errors "not installed at scope user" on a project-scoped install).
-  Background auto-update does both, and the new version applies at restart or `/reload-plugins`.
-  Version/auto-update findings: `specs/memory/decisions/claude-code-plugin-auto-update-third.md`.
-- **Two hooks have no Cursor trigger** (`plan-review-gate`, `plan-exit-ingest-gate`): Cursor
-  exposes no `ExitPlanMode` tool call to hooks, so the plan-review gate is enforced by
-  `.cursor/rules/plan-review-required.mdc` instead. Tracked in
-  `scripts/cursor-hooks/manifest.mjs` → `UNPORTABLE`; hooks that run weaker are in `DEGRADED` there.
-  Four hooks have no Copilot trigger (see the published list above).
-- **Backend choice is separate from enforcement:** running the Claude Code host against a local
-  or cloud non-Anthropic model disables no hook — see
-  [Running Claude Code against Ollama or DeepSeek](#running-claude-code-against-ollama-or-deepseek)
-  for the recipes.
-
-## Cutover criteria (research steps 4–5)
-
-Only after the validation above passes end-to-end and the skills-vs-prompts question is settled
-does removing the project-level wiring (or extending this to customer vaults) become a decision.
+# SpexCode plugin (for Claude Code and GitHub Copilot CLI) — Claude Code + Copilot CLI + Cursor (prototype)
+
+Prototype packaging of HeySpex's agent integration as a self-hosted plugin for **both** hosts,
+implementing migration-path steps 1–2 of [[HS-QTBK-5EK5-RES-claude-code-plugin-packaging-for]].
+**Additive:** the project-level wiring stays live and remains the source of truth
+(`.mcp.json` + `.claude/settings.json` for Claude Code; `.cursor/mcp.json` +
+`.cursor/hooks.json` for Cursor). Nothing here activates until the plugin is explicitly installed.
+
+One plugin directory, two manifests — the hosts read different files and never see each other's.
+
+## Layout
+
+| Path | Host | What it is |
+| --- | --- | --- |
+| `.claude-plugin/plugin.json` | Claude Code | Plugin manifest (`name: heyspex`). |
+| `.cursor-plugin/plugin.json` | Cursor | Plugin manifest. Names `mcp.json` and `hooks/cursor-hooks.json` EXPLICITLY, because a Cursor manifest path replaces auto-discovery — without it Cursor would find `hooks/hooks.json` and try to read Claude-shaped config. |
+| `.mcp.json` | Claude Code | MCP server declaration — launches `bin/launch-mcp.mjs` via `${CLAUDE_PLUGIN_ROOT}`. |
+| `mcp.json` | Cursor | MCP server declaration. Runs `${CURSOR_PLUGIN_ROOT}/bin/launch-mcp.mjs` (Cursor expands that variable to the plugin install path), the same launcher `.mcp.json` uses, so it boots from a plain `npm install heyspex`; `HEYSPEX_VAULT_ROOT` is `${workspaceFolder}`. |
+| `bin/launch-mcp.mjs` | Claude Code | Resolver shim: locates `vendor/heyspex-mcp/cli.mjs` in the host vault repo (`HEYSPEX_MCP_ENTRY` override → `$CLAUDE_PROJECT_DIR` → `$CURSOR_PROJECT_DIR` → `$HEYSPEX_VAULT_ROOT` → cwd) and hands off in-process. Needed because the server's deps come from the repo's `node_modules`, so it can't yet run from the plugin's versioned cache copy. |
+| `hooks/hooks.json` | Claude Code, Copilot CLI | **Generated** from the customer-scoped rows of `scripts/lib/customer-kit.mjs` (`node scripts/lib/customer-kit.mjs --write-plugin-hooks`; a test fails on drift). Every command is a self-locating inline bootstrap (plugin-root env `CLAUDE_PLUGIN_ROOT`/`COPILOT_PLUGIN_ROOT`/`PLUGIN_ROOT` → `bin/run-hook.mjs`, else a walk up from the cwd to `scripts/claude-hooks/_run.mjs`, else exit 0) that reaches `bin/run-hook.mjs`, which finds the platform checkout (`HEYSPEX_PLATFORM_ROOT` → `HEYSPEX_MCP_ENTRY` → its own checkout → `node_modules/heyspex` → `$CLAUDE_PROJECT_DIR`) — never `$CLAUDE_PROJECT_DIR/scripts`, which only exists in heyspex-app. MCP-tool matchers carry both `mcp__heyspex__*` and `mcp__plugin_heyspex_heyspex__*` names. |
+| `.github/hooks/heyspex.json` (repo root) | Copilot cloud agent | **Generated** by `npm run hooks:write-github`; bash-only, default branch only. See "Copilot cloud agent" below. |
+| `bin/run-hook.mjs` | Claude Code | Hook launcher: resolves the platform shim `scripts/claude-hooks/_run.mjs` and hands off in-process (fail-open, like the shim). |
+| `hooks/cursor-hooks.json` | Cursor | **Generated** from `scripts/cursor-hooks/manifest.mjs` by `npm run hooks:install-cursor`; drift is a `hs doctor` failure. Commands resolve through `$CURSOR_PROJECT_DIR`. |
+
+Each host has its own marketplace catalog at the repo root, both pointing at this directory:
+`.claude-plugin/marketplace.json` and `.cursor-plugin/marketplace.json` — the documented
+self-hosted single-repo pattern; no hosted registry involved.
+
+## Installing
+
+### From the npm package (customers; no heyspex-app checkout)
+
+A team that only installs the published `heyspex` package does not have, and does not need, the
+heyspex-app repository. The package carries the marketplace (`node_modules/heyspex/.claude-plugin/marketplace.json`,
+plugin source `./plugins/heyspex`), the hooks and the MCP server. From the root of your own repo:
+
+```bash
+npm install heyspex                      # or: npm install ./heyspex-<version>.tgz
+npx hs login
+npx heyspex setup copilot                # GitHub Copilot CLI: plugin route ...
+npx heyspex setup copilot --hooks        # ... OR cloud agent: .github/hooks/heyspex.json, never both
+npx heyspex setup copilot --print        # paste this to your agent: next command + the full guide
+npx hs install --target . --plugin-apply # Claude Code
+```
+
+`setup copilot --check` shows which route is active; `--uninstall` removes the hooks file and prints `copilot plugin uninstall heyspex`.
+
+Fallback, by hand: `claude plugin marketplace add ./node_modules/heyspex` /
+`copilot plugin marketplace add ./node_modules/heyspex`, then `... plugin install heyspex@heyspex-marketplace`.
+Restart the session (`/restart` in Copilot), then check `copilot plugin list` and `npx hs doctor`.
+Full walkthrough: `node_modules/heyspex/docs/copilot-plugin-install.md`. The sections below describe the same plugin from the
+platform checkout and are for HeySpex developers.
+
+### Claude Code
+
+One command, from the platform checkout (wraps the manual flow below):
+
+```bash
+node bin/hs.mjs install --target <consumer-repo> --plugin-apply
+```
+
+`--plugin` prints the commands instead of running them. The equivalent manual flow, inside a
+Claude Code session in the consumer repo — or via the `claude plugin` CLI:
+
+```
+/plugin marketplace add <path-or-git-url-of-this-repo>
+/plugin install heyspex@heyspex-marketplace
+```
+
+### GitHub Copilot CLI
+
+Copilot CLI installs Claude-format plugins (`.claude-plugin/plugin.json`) from a marketplace
+(`.claude-plugin/marketplace.json` is on its search path). Source of truth for the commands and the
+file layout: <https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference>
+(fetched 2026-10-16). Hook behaviour: <https://docs.github.com/en/copilot/reference/hooks-configuration>.
+
+```bash
+copilot plugin marketplace add <owner>/<repo>          # or a git URL or a local path to this repo
+copilot plugin install heyspex@heyspex-marketplace      # SPECIFICATION is plugin@marketplace
+copilot plugin list                                    # confirm it is enabled
+```
+
+For local development: `copilot plugin marketplace add /path/to/heyspex-app`; a path-sourced plugin in a local
+marketplace loads live (`/restart` picks up edits).
+
+What gets loaded:
+
+| Component | Loaded from | Notes |
+| --- | --- | --- |
+| Hooks | `hooks/hooks.json` | Same file Claude Code reads. PascalCase events (`PreToolUse`, `PostToolUse`, `Stop`...) use Claude matcher semantics and snake_case payloads. Every command is a self-locating inline bootstrap: it needs no `$CLAUDE_PROJECT_DIR` and exits 0 when it cannot find the runtime (Copilot turns any non-zero exit into a deny). |
+| MCP | `.mcp.json` | Legacy-plugin MCP file. Its `${CLAUDE_PLUGIN_ROOT}` expansion under Copilot is **not documented** (Copilot documents `${PLUGIN_ROOT}` for Agent Plugins `mcp.json` only) and could not be verified without a Copilot CLI on the build machine. If the server does not start, add it explicitly: `copilot mcp add heyspex -- node <install-path>/plugins/heyspex/bin/launch-mcp.mjs`. |
+| Skills / prompts | MCP prompts (`hs-*`) | Delivered by the MCP server. **The Copilot cloud coding agent has no prompts**; there use the `hs` CLI loop in `docs/driving-heyspex-from-copilot.md`. |
+| Commands | not loaded | Claude Code slash commands are not a Copilot component. |
+
+### One source of hooks: plugin OR repo hooks, never both
+
+Copilot CLI (and Claude Code) load hooks from the plugin AND from the repository's own registrations
+(`.claude/settings.json`, `.claude/settings.local.json`, `.github/hooks/*.json`). A repo that has both runs every HeySpex
+hook twice. Pick one per repo:
+
+- **Plugin** (this directory): `copilot plugin install heyspex@heyspex-marketplace` / `/plugin install ...`. Do not run
+  `hs install` hook registration in the same repo, or strip it afterwards.
+- **Repo hooks** (`hs install`, which writes `.claude/settings.json` + the committed launcher): do not also install the plugin.
+
+**The committed Claude launcher yields to the plugin.** `hs install` commits `.claude/settings.json` rows for every
+teammate, but the plugin is a per-machine choice, so the committed file cannot pick one source per machine — the
+launcher it routes through (`.claude/heyspex/run-hook.mjs`, marker `// yields-to-plugin: v1`) decides at run time
+instead: when a heyspex plugin is enabled on this machine (a `heyspex@...` key in
+`~/.claude/plugins/installed_plugins.json`, `enabledPlugins` naming heyspex with a non-false value, or a heyspex
+directory under `~/.copilot/installed-plugins` / `~/.copilot/plugins`) it exits 0 silently before resolving the
+package, so every hook fires once — from the plugin. `enabledPlugins["heyspex@..."] === false` (in `~/.claude/settings.json`
+or the repo's `.claude/settings[.local].json`) means the plugin is off for that harness and the repo rows run;
+`HEYSPEX_REPO_HOOKS=1` never yields. The plugin's own `bin/run-hook.mjs` never calls the committed launcher, so there is
+no recursion. `.github/hooks/*.json` rows do not go through the launcher: for those, "never both" still applies as written.
+
+`npm run doctor` has a `hook-double-fire` check (reports `ok` when every repo row routes through a yielding launcher): it warns when HeySpex rows in the repo's `.claude/settings*.json` or
+`.github/hooks/*.json` coexist with an installed heyspex plugin, and reports `unknown` (never a failure) when no plugin
+registry can be read. What it looks at: `~/.claude/plugins/installed_plugins.json` (a `heyspex@...` key),
+`enabledPlugins` in `~/.claude/settings.json` and the project's Claude settings, and, best effort, a heyspex directory
+under `~/.copilot/installed-plugins` or `~/.copilot/plugins` (the Copilot plugin list file is not documented; `copilot
+plugin list` is the authority). As a runtime backstop, `_run.mjs` also de-duplicates a repeated Copilot invocation
+(`HEYSPEX_COPILOT_DEDUPE_OFF=1` disables that).
+
+### Copilot cloud agent: `.github/hooks/heyspex.json`
+
+The Copilot **cloud agent** loads no plugins and no user-level hook files; its only hook source is `.github/hooks/*.json`
+**on the default branch**. `.github/hooks/heyspex.json` is therefore generated from the same customer rows as
+`hooks/hooks.json`, restricted to the hooks whose Copilot disposition is `mapped` (plus `intent-classifier-trigger`, which
+only arms the capture obligation state and whose dropped output does not matter):
+
+```bash
+npm run hooks:write-github     # node scripts/lib/customer-kit.mjs --write-github-hooks  (a test fails on drift)
+npm run hooks:check-github     # exit 1 when stale
+```
+
+- Linux bash only: every entry is `type: "command"` with a `bash` command that resolves
+  `node_modules/heyspex/scripts/claude-hooks/_run.mjs`, then `./scripts/claude-hooks/_run.mjs`, else `exit 0` (fail open).
+  Events are the camelCase names (`sessionStart`, `preToolUse`, `postToolUse`, `userPromptSubmitted`, `agentStop`,
+  `sessionEnd`, `preCompact`); matchers use Copilot tool names (`create|edit|bash|powershell|task`, MCP tools as a
+  `.*<tool>` suffix).
+- The cloud sandbox must contain `node_modules/heyspex` (run `npm install` in the `copilot-setup-steps` workflow), or the
+  hooks silently no-op.
+- The firewall must allow the console URL (`emit-claim-status` and claim heartbeats call it), or those hooks time out (timeouts fail open).
+- The file only takes effect once it is on the repository's **default branch**.
+- If the repo also carries `.claude/settings.json` HeySpex rows, Copilot CLI reads both files: that is the double-fire case
+  above. Use the manifest for the cloud agent only, or rely on the shim de-duplication.
+- MCP is configured in the repository's Copilot settings (tools only, no OAuth), not by a committed file.
+
+### Gates that are weaker or absent on Copilot (published list)
+
+Parity is not identity. Where Copilot has a trigger the gate is a hard deny or re-drive; the rows below are the exceptions.
+The list is generated from `scripts/lib/hook-dispositions.mjs` (the single three-host table, which also covers Claude Code
+and Cursor) and a test fails when this block is stale. The hard floor under all of it is the MCP server itself:
+`heyspex_claim_spec`, `heyspex_submit_for_review` and `heyspex_save_research` refuse without a preflight marker on every
+surface that connects the MCP server, with no hook involved.
+
+<!-- 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 -->
+
+Unverified on Copilot (no official page read, or not run live): the VS Code 128-tool-per-request cap; the spelling of MCP
+tool names inside hook payloads (matched by suffix); `${CLAUDE_PLUGIN_ROOT}` expansion for the plugin `.mcp.json` under
+the Copilot CLI (documented for VS Code only); and how the MCP server learns the Copilot session id (its preflight marker
+falls back to a 4 hour TTL when the runtime exposes none). Also unverified: that a Claude-format `hookSpecificOutput` deny is
+read by the CLI (only the top-level `permissionDecision` form and exit 2 are documented), and where a `matcher` is read
+in the camelCase `.github/hooks` entry shape.
+
+### Turning HeySpex on and off (any harness)
+
+One switch, `hs mode` (alias `heyspex mode`; from a checkout without `hs` on PATH: `node bin/hs.mjs mode ...`):
+
+```bash
+hs mode status      # on | off, and why
+hs mode off         # writes <project>/.heyspex/mode.json; every hook exits 0 at once (no restart)
+hs mode on
+hs mode toggle
+```
+
+- `HEYSPEX_MODE=off` silences hooks for one shell/session without touching a file (wins over the file).
+- `HEYSPEX_COPILOT_HOOKS_OFF=1` (or `agent_behaviors.harness_hooks.copilot.enabled: false` in the vault `.heyspex/config.yaml`)
+  silences every hook **only when the caller is GitHub Copilot**; Claude Code and Cursor keep theirs.
+- The switch is read from the PROJECT being worked on (`CLAUDE_PROJECT_DIR`, then the hook payload `cwd`, then upward
+  from the working directory), so `hs mode off` in a customer repo works even though the hooks run from `node_modules/heyspex`.
+- Four security gates ignore the switch by design (`env-vault-guard`, `research-method-guard`, `research-protocol-gate`,
+  `git-identity-guard`): an agent must not be able to disarm them by writing one JSON file. Their own env-var
+  break-glass (set by a human) still applies. The Copilot opt-out does not cover them either unless the owner extends it.
+
+### Cursor
+
+For local development, symlink or copy this directory into Cursor's local plugin root and
+reload the window (**Developer: Reload Window**):
+
+```
+~/.cursor/plugins/local/heyspex
+```
+
+Otherwise add the repo as a marketplace source from Cursor's plugin surface; the root
+`.cursor-plugin/marketplace.json` catalogs it.
+
+**In the platform repo itself you do not need the plugin at all** — `.cursor/hooks.json`,
+`.cursor/mcp.json`, `.cursor/rules/`, `.cursor/skills/` and `.cursor/commands/` are already
+installed and are the live path. The plugin exists for CONSUMER repos.
+
+## Running Claude Code against Ollama or DeepSeek
+
+Claude Code can be pointed at a local Ollama instance or DeepSeek's cloud API through
+`ANTHROPIC_BASE_URL`: both expose an Anthropic Messages API-compatible endpoint, so Claude
+Code talks to them directly with no proxy. The recipes below are verified against each
+vendor's own docs ([[HS-REF-pointing-claude-code-at-non-anthropic]]).
+
+### Ollama (local)
+
+Requires Ollama 0.14+, which added a native Anthropic-compatible endpoint. The auth token is
+required but ignored.
+
+```bash
+# one-shot
+ollama launch claude --model qwen3-coder
+
+# manual
+export ANTHROPIC_AUTH_TOKEN=ollama
+export ANTHROPIC_API_KEY=""
+export ANTHROPIC_BASE_URL=http://localhost:11434
+claude --model qwen3-coder
+```
+
+### DeepSeek (cloud)
+
+```bash
+export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
+export ANTHROPIC_API_KEY=your-deepseek-api-key
+claude
+```
+
+The `/anthropic` path is required — the bare host `https://api.deepseek.com` (without
+`/anthropic`) is not the Anthropic-compatible endpoint. DeepSeek's own docs specify
+`ANTHROPIC_API_KEY`, not `ANTHROPIC_AUTH_TOKEN`.
+
+### Model name mapping (DeepSeek)
+
+There is no `ANTHROPIC_MODEL` var to set manually — model choice is automatic name-mapping:
+Claude Opus names map to `deepseek-v4-pro` (billed at V4 Pro price), while every other Claude
+name (Haiku/Sonnet) and any unmapped name maps to `deepseek-flash`.
+
+### Known DeepSeek limitations
+
+- `top_p` fixed at 1.0 outside thinking mode (min 0.95 inside it).
+- Unsupported Anthropic content types: documents, search results, redacted thinking, code
+  execution results, MCP tool integrations, container uploads.
+- `budget_tokens` in thinking-mode config is ignored.
+
+### Enforcement is independent of the backend
+
+HeySpex hooks fire regardless of backend: Claude Code hooks fire at session, turn, and
+tool-call points of Claude Code's own loop, so every HeySpex hook in `.claude/settings.json`
+and `plugins/heyspex/hooks/` runs unchanged regardless of backend — see the
+[Claude Code hooks reference](https://code.claude.com/docs/en/hooks).
+
+### Launcher
+
+`hs next <id> --launch --backend ollama|deepseek` sets the right env vars and execs `claude`.
+This is the supported path, shipping with epic
+[[HS-30JD-94Q5-EPIC-claude-code-launches-against-ollama-or]]; until then, use the manual
+recipe above.
+
+## Validating (migration-path step 3)
+
+Run the install above in a **fresh clone / separate consumer repo** (avoids the double-hook
+caveat below), after `npm install` in the platform checkout.
+
+Then restart the session and confirm:
+
+1. The MCP server connects and tools appear as `mcp__plugin_heyspex_heyspex__heyspex_*`.
+2. Hooks fire (SessionStart seat injection, PreToolUse gates) — and only once.
+3. The re-prefix blast radius: anything load-bearing that hardcodes `mcp__heyspex__*`
+   (CLAUDE.md, `.claude/settings.json` permission allow/deny lists, procedures, hook scripts)
+   still behaves. This is the migration cost the research flags as largest.
+
+## Known caveats (by design, this stage)
+
+- **Double-fire:** enabling this plugin in a repo that still registers the same hooks project-level
+  runs every hook twice. Single-source rule: plugin OR repo hooks, never both (see above; `npm run doctor` warns).
+  Validate in a fresh clone, or strip the project hooks first (`node scripts/install-cursor-hooks.mjs --uninstall` for Cursor).
+- **Not standalone:** the plugin requires a HeySpex vault checkout with `npm install` run —
+  the MCP server and hook scripts resolve from the host project, not the plugin cache.
+  Bundling the server into the plugin is a full-cutover-stage task.
+- **`hs-*` skills stay MCP prompts** (research step 4, unresolved): they travel with the MCP
+  server, not as plugin `SKILL.md` files. Commands, rules and agents are deliberately not
+  duplicated here to avoid drift and double registration — which matters more for Cursor, whose
+  plugin format CAN carry `rules/`, `commands/` and `skills/`. Bundling them is a cutover decision,
+  not a packaging one.
+- **Permissions/statusLine are not mirrored** — those remain project-level concerns.
+- **Manual updates are two steps and scope-sensitive:** `claude plugin marketplace update
+  heyspex-marketplace` refreshes the catalog only; the installed copy moves on
+  `claude plugin update heyspex@heyspex-marketplace --scope project` (the CLI defaults to
+  `--scope user` and errors "not installed at scope user" on a project-scoped install).
+  Background auto-update does both, and the new version applies at restart or `/reload-plugins`.
+  Version/auto-update findings: `specs/memory/decisions/claude-code-plugin-auto-update-third.md`.
+- **Two hooks have no Cursor trigger** (`plan-review-gate`, `plan-exit-ingest-gate`): Cursor
+  exposes no `ExitPlanMode` tool call to hooks, so the plan-review gate is enforced by
+  `.cursor/rules/plan-review-required.mdc` instead. Tracked in
+  `scripts/cursor-hooks/manifest.mjs` → `UNPORTABLE`; hooks that run weaker are in `DEGRADED` there.
+  Four hooks have no Copilot trigger (see the published list above).
+- **Backend choice is separate from enforcement:** running the Claude Code host against a local
+  or cloud non-Anthropic model disables no hook — see
+  [Running Claude Code against Ollama or DeepSeek](#running-claude-code-against-ollama-or-deepseek)
+  for the recipes.
+
+## Cutover criteria (research steps 4–5)
+
+Only after the validation above passes end-to-end and the skills-vs-prompts question is settled
+does removing the project-level wiring (or extending this to customer vaults) become a decision.