heyspex 0.2.1 → 0.2.3

package/docs/copilot-plugin-install.md

@@ -1,162 +1,189 @@
-# Installing the HeySpex (SpexCode) plugin in GitHub Copilot CLI
-
-Instructions written to be handed verbatim to a GitHub Copilot CLI agent. Follow the steps in
-order and stop at any step that fails, reporting the exact output.
-
-This guide is for a team that installs only the `heyspex` npm package. The heyspex-app repository
-is not needed and is not available to customers.
-
-Source of truth for the Copilot commands and file layout:
-<https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference>.
-Hook behaviour under Copilot: <https://docs.github.com/en/copilot/reference/hooks-configuration>.
-Both pages were read on 2026-10-16. The plugin itself is documented in `node_modules/heyspex/plugins/heyspex/README.md`.
-
-## 1. Prerequisites
-
-The heyspex-app repository is not required and is not available to customers. Everything below
-works from the published npm package `heyspex` (or a tarball your HeySpex contact hands you), which
-carries the plugin, the marketplace manifest, the hooks and the MCP server.
-
-- Node.js 20 or newer on PATH (`node --version`).
-- GitHub Copilot CLI installed and signed in (`copilot --version`).
-- A git repo of your own (the one you want governed). From its root, install the package:
-
-```bash
-npm install heyspex
-# or, from a tarball you were given:
-npm install ./heyspex-0.2.0.tgz
-```
-
-- Sign the machine in to the HeySpex console so hooks and MCP tools can reach the vault:
-
-```bash
-npx hs login
-```
-
-## 2. Pick ONE: the plugin or the repo hooks (never both)
-
-Copilot reads hooks from an installed plugin and from `.github/hooks/` in the repo. With both,
-every hook runs twice. Choose one.
-
-**Option A: the plugin (recommended).** One command registers the marketplace shipped inside the
-package and installs the plugin:
-
-```bash
-npx hs install --target . --copilot-plugin-apply
-```
-
-Without `npx hs`, the equivalent Copilot commands are:
-
-```bash
-copilot plugin marketplace add ./node_modules/heyspex
-copilot plugin install heyspex@heyspex-marketplace
-copilot plugin list
-```
-
-`./node_modules/heyspex/.claude-plugin/marketplace.json` is a Claude-format marketplace named
-`heyspex-marketplace`; its plugin `source` (`./plugins/heyspex`) resolves inside the package.
-`npx hs install --target . --copilot-plugin` (no `-apply`) only prints these commands.
-
-**Option B: repo hooks, for teammates and the Copilot cloud agent.** Writes
-`.github/hooks/heyspex.json` into your repo; commit it. Each command runs
-`node_modules/heyspex/scripts/claude-hooks/_run.mjs` and exits 0 if the package is not installed,
-so a checkout without `npm install` is never blocked.
-
-```bash
-npx hs install --target . --copilot-hooks
-```
-
-If you pass `--copilot-hooks` together with `--copilot-plugin[-apply]`, the installer warns and
-skips the hooks file.
-
-Then restart the Copilot session (`/restart`) so hooks load, and verify:
-
-```bash
-copilot plugin list      # Option A: heyspex is enabled
-npx hs doctor            # MCP, hooks and account surfaces healthy
-```
-
-## 3. What the plugin loads
-
-| Component | Source | Behaviour under Copilot |
-| --- | --- | --- |
-| Hooks | `node_modules/heyspex/plugins/heyspex/hooks/hooks.json` | PreToolUse, PostToolUse, Stop, UserPromptSubmit and SessionStart gates. Every command locates the runtime itself and exits 0 if it cannot, so a missing variable never denies a tool call. A real deny arrives as a top-level `permissionDecision` with a reason. |
-| MCP server | `node_modules/heyspex/plugins/heyspex/.mcp.json` | The `heyspex_*` vault tools and `hs-*` prompts. |
-| Slash commands | not loaded | Claude Code commands are not a Copilot component. Use MCP prompts or the `hs` CLI. |
-
-## 4. Verify the install
-
-1. In a Copilot session inside any repo, run a harmless tool call, for example read a file. It
-   must succeed. A message containing "Denied by preToolUse hook" means a hook failed; go to
-   section 7.
-2. Confirm the MCP server is up by listing MCP servers in Copilot (`/mcp`) and calling
-   `heyspex_recall_memories` with `{ "limit": 3 }`. If the server is missing, go to section 7.
-3. Confirm the gates work: send a prompt that contains a new product idea of more than 60
-   characters, then try to edit a source file without capturing. The edit should be refused with a
-   reason that names `directive-obligation-gate`. Call `heyspex_update_capture` with the prompt
-   text, then retry the edit. It should pass.
-
-## 5. Turning HeySpex off and on
-
-Run from the repo you are working in:
-
-```bash
-hs mode status     # on | off, and why
-hs mode off        # every hook exits 0 immediately, no restart needed
-hs mode on
-hs mode toggle
-```
-
-Use `npx hs mode off` when `hs` is not on PATH. The switch writes
-`.heyspex/mode.json` in the project and is git-ignored.
-
-Per-shell variants that touch no files:
-
-| Variable | Effect |
-| --- | --- |
-| `HEYSPEX_MODE=off` | Silences hooks for every harness in that shell |
-| `HEYSPEX_COPILOT_HOOKS_OFF=1` | Silences hooks only when the caller is Copilot; Claude Code and Cursor keep theirs |
-
-The config twin of the Copilot switch is `agent_behaviors.harness_hooks.copilot.enabled: false` in
-the vault's `.heyspex/config.yaml`.
-
-Four security gates ignore all of these by design: `env-vault-guard`, `research-method-guard`,
-`research-protocol-gate` and `git-identity-guard`. They only act on secret writes, built-in
-deep-research skills, unprotocolled web research and git identity changes.
-
-## 6. Everyday loop
-
-With MCP available: `heyspex_next_on_deck`, `heyspex_claim_spec`, `heyspex_report_progress`,
-`heyspex_submit_for_review`. Without MCP, the `hs` CLI (`npx hs`) covers the same loop; see
-`docs/driving-heyspex-from-copilot.md`.
-
-## 7. Troubleshooting
-
-- **Every tool call is denied.** Run `hs mode off` to unblock immediately, then capture the exact
-  deny text and the hook command it names. If the command still starts with
-  `node "$CLAUDE_PROJECT_DIR/...`, the package is old; run `npm install heyspex@latest` and reinstall the plugin.
-- **MCP server does not start.** Copilot documents `${PLUGIN_ROOT}` for its own plugin format, and
-  whether it expands `${CLAUDE_PLUGIN_ROOT}` in a Claude-format plugin is unverified. Register the
-  server explicitly:
-
-```bash
-copilot mcp add heyspex -- node ./node_modules/heyspex/plugins/heyspex/bin/launch-mcp.mjs
-```
-
-- **A hook denies with no reason shown.** That is a hook exiting 2 the old way. Report the hook
-  name; it should be answering in Copilot's JSON format.
-- **Hooks run twice.** The repo you are in also carries HeySpex rows in its own
-  `.claude/settings.json` from `hs install`. Use either the plugin or the install kit (or `.github/hooks`) in one repo,
-  not both.
-
-## 8. Report back
-
-State the Copilot CLI version, the output of `copilot plugin list`, the result of the three checks
-in section 4, and the exact text of any deny or MCP error.
-
-## Status of this document
-
-The install commands come from GitHub's plugin reference, and the hook behaviour was verified by
-replaying Copilot-shaped payloads through the registered commands, not by a live Copilot session.
-The first agent that completes section 4 is the real test. Fix history: diagnose HS-20SW and
-capture HS-HNO1 (2026-10-16).
+# Installing the HeySpex (SpexCode) plugin in GitHub Copilot CLI
+
+Instructions written to be handed verbatim to a GitHub Copilot CLI agent. Follow the steps in
+order and stop at any step that fails, reporting the exact output.
+
+This guide is for a team that installs only the `heyspex` npm package. The heyspex-app repository
+is not needed and is not available to customers.
+
+Source of truth for the Copilot commands and file layout:
+<https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference>.
+Hook behaviour under Copilot: <https://docs.github.com/en/copilot/reference/hooks-configuration>.
+Both pages were read on 2026-10-16. The plugin itself is documented in `node_modules/heyspex/plugins/heyspex/README.md`.
+
+## 0. The short version
+
+From the root of your repo, after `npm install heyspex`:
+
+```bash
+npx heyspex setup copilot            # plugin route (Copilot CLI): registers the marketplace and installs the plugin
+npx heyspex setup copilot --hooks    # hooks route (Copilot cloud agent / no plugin): writes .github/hooks/heyspex.json
+npx heyspex setup copilot --check    # which route is active; warns if both are
+npx heyspex setup copilot --uninstall
+```
+
+To have an agent do it, paste it the output of `npx heyspex setup copilot --print` (this document,
+preceded by the exact next command). If no Copilot CLI can be found (PATH, then the Copilot app's bundled copy), the plugin route
+installs nothing, prints the prerequisite and the two commands, and exits 1. Pick ONE route, never both. The manual commands below remain the fallback.
+
+## 1. Prerequisites
+
+The heyspex-app repository is not required and is not available to customers. Everything below
+works from the published npm package `heyspex` (or a tarball your HeySpex contact hands you), which
+carries the plugin, the marketplace manifest, the hooks and the MCP server.
+
+- Node.js 20 or newer on PATH (`node --version`).
+- GitHub Copilot CLI installed and signed in. Any one of: the GitHub Copilot app (its bundled
+  `%LOCALAPPDATA%\github-copilot-sdk\cli\<version>\copilot.exe` is auto-detected, newest version
+  wins, no PATH entry needed), `npm install -g @github/copilot`, or `winget install GitHub.Copilot`.
+  `npx heyspex setup copilot` looks on PATH first, then for the app copy; if neither exists it
+  installs nothing and exits non-zero. `COPILOT_HOME` (Copilot's settings-dir override) is honoured.
+- A git repo of your own (the one you want governed). From its root, install the package:
+
+```bash
+npm install heyspex
+# or, from a tarball you were given:
+npm install ./heyspex-0.2.0.tgz
+```
+
+- Sign the machine in to the HeySpex console so hooks and MCP tools can reach the vault:
+
+```bash
+npx hs login
+```
+
+## 2. Pick ONE: the plugin or the repo hooks (never both)
+
+Copilot reads hooks from an installed plugin and from `.github/hooks/` in the repo. With both,
+every hook runs twice. Choose one.
+
+The `.claude/settings.json` rows `hs install` commits are the exception that needs no choice: they
+route 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 the machine running it, so the plugin's
+copy of the hook is the only one that fires. The launcher reads the same plugin evidence `hs doctor`'s
+`hook-double-fire` check does; `enabledPlugins["heyspex@..."] === false` keeps the repo rows running,
+and `HEYSPEX_REPO_HOOKS=1` forces them. `.github/hooks/*.json` rows do not use the launcher, so for
+those the plugin-or-hooks choice below stands.
+
+**Option A: the plugin (recommended).** One command registers the marketplace shipped inside the
+package and installs the plugin:
+
+```bash
+npx heyspex setup copilot
+```
+
+(`npx hs install --target . --copilot-plugin-apply` does the same.) By hand, the equivalent Copilot commands are:
+
+```bash
+copilot plugin marketplace add ./node_modules/heyspex
+copilot plugin install heyspex@heyspex-marketplace
+copilot plugin list
+```
+
+`./node_modules/heyspex/.claude-plugin/marketplace.json` is a Claude-format marketplace named
+`heyspex-marketplace`; its plugin `source` (`./plugins/heyspex`) resolves inside the package.
+`npx hs install --target . --copilot-plugin` (no `-apply`) only prints these commands.
+
+**Option B: repo hooks, for teammates and the Copilot cloud agent.** Writes
+`.github/hooks/heyspex.json` into your repo; commit it. Each command runs
+`node_modules/heyspex/scripts/claude-hooks/_run.mjs` and exits 0 if the package is not installed,
+so a checkout without `npm install` is never blocked.
+
+```bash
+npx heyspex setup copilot --hooks
+```
+
+(`npx hs install --target . --copilot-hooks` does the same.) `setup copilot --hooks` refuses when the plugin is already installed. If you pass `--copilot-hooks` together with `--copilot-plugin[-apply]`, the installer warns and
+skips the hooks file.
+
+Then restart the Copilot session (`/restart`) so hooks load, and verify:
+
+```bash
+copilot plugin list      # Option A: heyspex is enabled
+npx hs doctor            # MCP, hooks and account surfaces healthy
+```
+
+## 3. What the plugin loads
+
+| Component | Source | Behaviour under Copilot |
+| --- | --- | --- |
+| Hooks | `node_modules/heyspex/plugins/heyspex/hooks/hooks.json` | PreToolUse, PostToolUse, Stop, UserPromptSubmit and SessionStart gates. Every command locates the runtime itself and exits 0 if it cannot, so a missing variable never denies a tool call. A real deny arrives as a top-level `permissionDecision` with a reason. |
+| MCP server | `node_modules/heyspex/plugins/heyspex/.mcp.json` | The `heyspex_*` vault tools and `hs-*` prompts. |
+| Slash commands | not loaded | Claude Code commands are not a Copilot component. Use MCP prompts or the `hs` CLI. |
+
+## 4. Verify the install
+
+1. In a Copilot session inside any repo, run a harmless tool call, for example read a file. It
+   must succeed. A message containing "Denied by preToolUse hook" means a hook failed; go to
+   section 7.
+2. Confirm the MCP server is up by listing MCP servers in Copilot (`/mcp`) and calling
+   `heyspex_recall_memories` with `{ "limit": 3 }`. If the server is missing, go to section 7.
+3. Confirm the gates work: send a prompt that contains a new product idea of more than 60
+   characters, then try to edit a source file without capturing. The edit should be refused with a
+   reason that names `directive-obligation-gate`. Call `heyspex_update_capture` with the prompt
+   text, then retry the edit. It should pass.
+
+## 5. Turning HeySpex off and on
+
+Run from the repo you are working in:
+
+```bash
+hs mode status     # on | off, and why
+hs mode off        # every hook exits 0 immediately, no restart needed
+hs mode on
+hs mode toggle
+```
+
+Use `npx hs mode off` when `hs` is not on PATH. The switch writes
+`.heyspex/mode.json` in the project and is git-ignored.
+
+Per-shell variants that touch no files:
+
+| Variable | Effect |
+| --- | --- |
+| `HEYSPEX_MODE=off` | Silences hooks for every harness in that shell |
+| `HEYSPEX_COPILOT_HOOKS_OFF=1` | Silences hooks only when the caller is Copilot; Claude Code and Cursor keep theirs |
+
+The config twin of the Copilot switch is `agent_behaviors.harness_hooks.copilot.enabled: false` in
+the vault's `.heyspex/config.yaml`.
+
+Four security gates ignore all of these by design: `env-vault-guard`, `research-method-guard`,
+`research-protocol-gate` and `git-identity-guard`. They only act on secret writes, built-in
+deep-research skills, unprotocolled web research and git identity changes.
+
+## 6. Everyday loop
+
+With MCP available: `heyspex_next_on_deck`, `heyspex_claim_spec`, `heyspex_report_progress`,
+`heyspex_submit_for_review`. Without MCP, the `hs` CLI (`npx hs`) covers the same loop; see
+`docs/driving-heyspex-from-copilot.md`.
+
+## 7. Troubleshooting
+
+- **Every tool call is denied.** Run `hs mode off` to unblock immediately, then capture the exact
+  deny text and the hook command it names. If the command still starts with
+  `node "$CLAUDE_PROJECT_DIR/...`, the package is old; run `npm install heyspex@latest` and reinstall the plugin.
+- **MCP server does not start.** Copilot documents `${PLUGIN_ROOT}` for its own plugin format, and
+  whether it expands `${CLAUDE_PLUGIN_ROOT}` in a Claude-format plugin is unverified. Register the
+  server explicitly:
+
+```bash
+copilot mcp add heyspex -- node ./node_modules/heyspex/plugins/heyspex/bin/launch-mcp.mjs
+```
+
+- **A hook denies with no reason shown.** That is a hook exiting 2 the old way. Report the hook
+  name; it should be answering in Copilot's JSON format.
+- **Hooks run twice.** The repo you are in also carries HeySpex rows in its own
+  `.claude/settings.json` from `hs install`. Use either the plugin or the install kit (or `.github/hooks`) in one repo,
+  not both.
+
+## 8. Report back
+
+State the Copilot CLI version, the output of `copilot plugin list`, the result of the three checks
+in section 4, and the exact text of any deny or MCP error.
+
+## Status of this document
+
+The install commands come from GitHub's plugin reference, and the hook behaviour was verified by
+replaying Copilot-shaped payloads through the registered commands, not by a live Copilot session.
+The first agent that completes section 4 is the real test. Fix history: diagnose HS-20SW and
+capture HS-HNO1 (2026-10-16).