heyspex 0.2.0 → 0.2.2

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

@@ -0,0 +1,165 @@
+# 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "heyspex",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "HeySpex CLI + MCP server — connect Claude Code, Cursor, and any MCP client to your HeySpex spec vault",
   "keywords": [
     "heyspex",
@@ -45,8 +45,11 @@
     "scripts/gateway-skills-lib.mjs",
     "scripts/vault-id-lib.mjs",
     "scripts/lib/console-url-resolver.mjs",
+    "scripts/lib/window-placement.mjs",
     "scripts/lib/hs-link.mjs",
+    "scripts/lib/hook-vault-header.mjs",
     "scripts/lib/dev-mode.mjs",
+    "scripts/lib/directive-obligations.mjs",
     "scripts/lib/hs-command.mjs",
     "scripts/lib/shared-path-helpers.mjs",
     "scripts/dev-server-status.mjs",
@@ -61,12 +64,17 @@
     "dev-factory/lib/model-catalog.mjs",
     "dev-factory/model-catalog.json",
     "docs/mcp-client-config.md",
+    "docs/copilot-plugin-install.md",
+    "docs/driving-heyspex-from-copilot.md",
+    "plugins/heyspex/README.md",
     "dist/cli/*.mjs",
     "dist/cli-templates/**",
     "LICENSE",
     "scripts/install-claude-code-hooks.mjs",
     "scripts/install-cursor-hooks.mjs",
+    "scripts/install-copilot-hooks.mjs",
     "scripts/lib/customer-kit.mjs",
+    "scripts/lib/hook-dispositions.mjs",
     "scripts/lib/template-pin.mjs",
     "scripts/cursor-hooks/manifest.mjs",
     "scripts/dev-server-stop.mjs",
@@ -94,6 +102,7 @@
     "plugins/heyspex/bin/launch-mcp.mjs",
     "plugins/heyspex/bin/run-hook.mjs",
     "plugins/heyspex/.claude-plugin/plugin.json",
+    ".claude-plugin/marketplace.json",
     "plugins/heyspex/.mcp.json",
     "plugins/heyspex/.cursor-plugin/plugin.json",
     "plugins/heyspex/mcp.json",
@@ -114,12 +123,19 @@
     "spexharness/src/gates/capture-workflow-gate.mjs",
     "spexharness/src/gates/claim-before-code-gate.decide.mjs",
     "spexharness/src/gates/claim-before-code-gate.mjs",
+    "spexharness/src/gates/directive-obligation-gate.decide.mjs",
+    "spexharness/src/gates/directive-obligation-gate.mjs",
     "spexharness/src/gates/deep-research-cost-gate.mjs",
     "spexharness/src/gates/enforce-session-sequence.mjs",
     "spexharness/src/gates/enforce-vault-naming.mjs",
     "spexharness/src/gates/epic-milestone-phrasing-gate.mjs",
+    "spexharness/src/gates/diagnose-capture-reminder.mjs",
     "spexharness/src/gates/git-identity-guard.decide.mjs",
     "spexharness/src/gates/git-identity-guard.mjs",
+    "spexharness/src/gates/_shell-write-targets.mjs",
+    "spexharness/src/gates/vault-write-tier-guard.decide.mjs",
+    "spexharness/src/gates/vault-write-tier-guard.mjs",
+    "spexharness/src/gates/vault-mirror-catchup.mjs",
     "spexharness/src/gates/git-reflog-audit.mjs",
     "spexharness/src/gates/git-stash-gate.decide.mjs",
     "spexharness/src/gates/git-stash-gate.mjs",
@@ -206,6 +222,8 @@
     "hooks:check-claude": "node scripts/install-claude-code-hooks.mjs --check",
     "hooks:install-cursor": "node scripts/install-cursor-hooks.mjs",
     "hooks:check-cursor": "node scripts/install-cursor-hooks.mjs --check",
+    "hooks:write-github": "node scripts/lib/customer-kit.mjs --write-github-hooks",
+    "hooks:check-github": "node scripts/lib/customer-kit.mjs --check-github-hooks",
     "hooks:smoke-cursor": "node scripts/cursor-hooks/_run.smoke.mjs",
     "companion": "pwsh -NoProfile -ExecutionPolicy Bypass -File companion/start.ps1 -Action start",
     "companion:stop": "pwsh -NoProfile -ExecutionPolicy Bypass -File companion/start.ps1 -Action stop",
@@ -224,8 +242,9 @@
     "test:mcp": "node --test vendor/heyspex-mcp/*.test.mjs scripts/lib/*.test.mjs dev-factory/lib/*.test.mjs",
     "test:harness": "node --test spexharness/**/*.test.mjs",
     "verify:package": "node scripts/verify-mcp-package.mjs",
+    "smoke:packed-install": "node scripts/packed-install.smoke.mjs",
     "verify:onboarding": "node scripts/verify-onboarding-scenario.mjs --fake",
     "sweep": "node scripts/sweep.mjs"
   },
-  "//files": "PUBLISHED SURFACE - every entry is verified by `node scripts/verify-mcp-package.mjs`. It must cover the STATIC import closure of vendor/heyspex-mcp/cli.mjs, plus (since [[HS-LGG2-WW9R-TASK-ship-the-hook-runtime-in-the-npm]]) the customer hook kit: scripts/claude-hooks/_run.mjs, every HOOK_SCOPES customer hook (scripts/lib/customer-kit.mjs) and their static closure under spexharness/src, dev-factory/lib and scripts/ - the hookTargets check names any file that falls out - plus the run-time data files in customer-kit.mjs CUSTOMER_HOOK_DATA (only the baseline edition of SpexCode Doctrine, never the learned spexharness/doctrine/SPEXCODE-DOCTRINE.json; [[HS-A2PO-WW9R-TASK-owner-ruling-does-inject-doctrine-ship]]) - and nothing else. SpexFleet internals (dev-factory/router.mjs, cloud-clients.mjs, cost-tracker.mjs, spexcrawl/) are deliberately absent - research-tools.mjs reaches them through the lazy dev-factory-bridge.mjs. Do not add a path here without re-running the verifier; npm publish is a one-way door ([[HS-ZJSP-0JNK-TASK-ship-the-heyspex-mcp-server-as-an]] / [[HS-8DET-0JNK-TASK-confirm-the-open-core-boundary-and]]). `dist/cli/*.mjs` + `dist/cli-templates/**` are a SEPARATE published surface (`hs-init`, `hs-install`, `hs-claim`, `hs-check`, `hs-env`, `hs-connect`, `hs-join`, `hs-vault`, `hs-workspace`, `hs-defer`, `hs-vault-pull`, `hs-dev`, `hs-index-rebuild`, `hs-index-reconcile` bundled by `scripts/build-cli-bundle.mjs`'s `ENTRIES` array, regenerated fresh every `prepack` - `dist/` itself stays git-ignored) - see that script's doc comment for the entry scope decision and [[HS-JOQX-0JNK-TASK-published-package-runs-hs-init-and-hs]]."
+  "//files": "PUBLISHED SURFACE - every entry is verified by `node scripts/verify-mcp-package.mjs`. It must cover the STATIC import closure of vendor/heyspex-mcp/cli.mjs, plus (since [[HS-LGG2-WW9R-TASK-ship-the-hook-runtime-in-the-npm]]) the customer hook kit: scripts/claude-hooks/_run.mjs, every HOOK_SCOPES customer hook (scripts/lib/customer-kit.mjs) and their static closure under spexharness/src, dev-factory/lib and scripts/ - the hookTargets check names any file that falls out - plus the run-time data files in customer-kit.mjs CUSTOMER_HOOK_DATA (only the baseline edition of SpexCode Doctrine, never the learned spexharness/doctrine/SPEXCODE-DOCTRINE.json; [[HS-A2PO-WW9R-TASK-owner-ruling-does-inject-doctrine-ship]]) - and nothing else. SpexFleet internals (dev-factory/router.mjs, cloud-clients.mjs, cost-tracker.mjs, spexcrawl/) are deliberately absent - research-tools.mjs reaches them through the lazy dev-factory-bridge.mjs. Do not add a path here without re-running the verifier; npm publish is a one-way door ([[HS-ZJSP-0JNK-TASK-ship-the-heyspex-mcp-server-as-an]] / [[HS-8DET-0JNK-TASK-confirm-the-open-core-boundary-and]]). `dist/cli/*.mjs` + `dist/cli-templates/**` are a SEPARATE published surface (`hs-init`, `hs-install`, `hs-claim`, `hs-check`, `hs-env`, `hs-connect`, `hs-join`, `hs-vault`, `hs-workspace`, `hs-defer`, `hs-vault-pull`, `hs-vault-push`, `hs-dev`, `hs-index-rebuild`, `hs-index-reconcile` bundled by `scripts/build-cli-bundle.mjs`'s `ENTRIES` array, regenerated fresh every `prepack` - `dist/` itself stays git-ignored) - see that script's doc comment for the entry scope decision and [[HS-JOQX-0JNK-TASK-published-package-runs-hs-init-and-hs]]."
 }

package/plugins/heyspex/.claude-plugin/plugin.json

@@ -1,12 +1,12 @@
-{
-  "name": "heyspex",
-  "displayName": "SpexCode plugin (for Claude Code)",
-  "description": "HeySpex vault integration for Claude Code: MCP server (spec vault tools + hs-* prompts) and lifecycle hooks. Prototype packaging per HS-QTBK — additive; the project-level .mcp.json/settings.json wiring remains the live source of truth until cutover.",
-  "author": {
-    "name": "pwher",
-    "email": "paul@monstergrowth.com"
-  },
-  "repository": "https://github.com/pwher/workflow-protocol",
-  "license": "UNLICENSED",
-  "keywords": ["heyspex", "spec-vault", "mcp", "hooks"]
-}
+{
+  "name": "heyspex",
+  "displayName": "SpexCode plugin (for Claude Code and GitHub Copilot CLI)",
+  "description": "HeySpex vault integration for Claude Code and GitHub Copilot CLI (Claude-format plugin, installed from the same marketplace): MCP server (spec vault tools + hs-* prompts) and lifecycle hooks. Prototype packaging per HS-QTBK — additive; the project-level .mcp.json/settings.json wiring remains the live source of truth until cutover.",
+  "author": {
+    "name": "pwher",
+    "email": "paul@monstergrowth.com"
+  },
+  "homepage": "https://www.npmjs.com/package/heyspex",
+  "license": "UNLICENSED",
+  "keywords": ["heyspex", "spec-vault", "mcp", "hooks"]
+}

package/plugins/heyspex/.cursor-plugin/plugin.json

@@ -1,15 +1,15 @@
-{
-  "name": "heyspex",
-  "displayName": "SpexCode plugin (for Claude Code)",
-  "version": "0.1.0",
-  "description": "HeySpex vault integration for Cursor: MCP server (spec vault tools + hs-* workflows) and the full lifecycle hook set. Prototype packaging — additive; the project-level .cursor/mcp.json and .cursor/hooks.json wiring remains the live source of truth until cutover.",
-  "author": {
-    "name": "pwher",
-    "email": "paul@monstergrowth.com"
-  },
-  "repository": "https://github.com/pwher/workflow-protocol",
-  "license": "UNLICENSED",
-  "keywords": ["heyspex", "spec-vault", "mcp", "hooks"],
-  "mcp": "mcp.json",
-  "hooks": "hooks/cursor-hooks.json"
-}
+{
+  "name": "heyspex",
+  "displayName": "SpexCode plugin (for Claude Code)",
+  "version": "0.1.0",
+  "description": "HeySpex vault integration for Cursor: MCP server (spec vault tools + hs-* workflows) and the full lifecycle hook set. Prototype packaging — additive; the project-level .cursor/mcp.json and .cursor/hooks.json wiring remains the live source of truth until cutover.",
+  "author": {
+    "name": "pwher",
+    "email": "paul@monstergrowth.com"
+  },
+  "homepage": "https://www.npmjs.com/package/heyspex",
+  "license": "UNLICENSED",
+  "keywords": ["heyspex", "spec-vault", "mcp", "hooks"],
+  "mcp": "mcp.json",
+  "hooks": "hooks/cursor-hooks.json"
+}

package/plugins/heyspex/README.md

@@ -0,0 +1,312 @@
+# 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.
+
+`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.