heyspex 0.1.0 → 0.2.0

package/package.json

@@ -1,124 +1,231 @@
-{
-  "name": "heyspex",
-  "version": "0.1.0",
-  "description": "HeySpex CLI + MCP server — connect Claude Code, Cursor, and any MCP client to your HeySpex spec vault",
-  "keywords": [
-    "heyspex",
-    "mcp",
-    "model-context-protocol",
-    "claude-code",
-    "cursor",
-    "spec-driven-development",
-    "agents"
-  ],
-  "type": "module",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/pwhermanson/workflow-protocol.git"
-  },
-  "engines": {
-    "node": ">=20.0.0 <25.0.0"
-  },
-  "workspaces": [
-    "spex-console",
-    "pm-control-center",
-    "companion/extension"
-  ],
-  "bin": {
-    "hs": "bin/hs.mjs",
-    "heyspex": "bin/hs.mjs",
-    "heyspex-mcp": "vendor/heyspex-mcp/cli.mjs"
-  },
-  "exports": {
-    "./package.json": "./package.json",
-    "./console-url-resolver": "./scripts/lib/console-url-resolver.mjs"
-  },
-  "files": [
-    "bin/hs.mjs",
-    "bin/postinstall.mjs",
-    "vendor/heyspex-mcp/**/*.mjs",
-    "!vendor/heyspex-mcp/**/*.test.mjs",
-    "scripts/check-mcp-freshness.mjs",
-    "scripts/gateway-skills-lib.mjs",
-    "scripts/vault-id-lib.mjs",
-    "scripts/lib/console-url-resolver.mjs",
-    "scripts/lib/hs-link.mjs",
-    "scripts/lib/dev-mode.mjs",
-    "scripts/dev-server-status.mjs",
-    "scripts/lib/hs-source-*.mjs",
-    "!scripts/lib/hs-source-*.test.mjs",
-    "scripts/lib/standalone-doctor.mjs",
-    "dev-factory/lib/fleet-readiness.mjs",
-    "dev-factory/lib/fleet-state.mjs",
-    "dev-factory/lib/sufficiency-score.mjs",
-    "docs/mcp-client-config.md",
-    "dist/cli/*.mjs",
-    "dist/cli-templates/**",
-    "LICENSE"
-  ],
-  "dependencies": {
-    "js-yaml": ">=3.13.0 <5.0.0"
-  },
-  "devDependencies": {
-    "esbuild": "^0.24.2"
-  },
-  "scripts": {
-    "prepack": "node scripts/build-cli-bundle.mjs",
-    "build:cli": "node scripts/build-cli-bundle.mjs",
-    "postinstall": "node bin/postinstall.mjs",
-    "setup": "node scripts/heyspex-doctor.mjs --fix",
-    "doctor": "node scripts/heyspex-doctor.mjs",
-    "heyspex:on": "node scripts/hs-mode.mjs on",
-    "heyspex:off": "node scripts/hs-mode.mjs off",
-    "heyspex:status": "node scripts/hs-mode.mjs status",
-    "commandcode:install": "node scripts/install-commandcode.mjs",
-    "commandcode:check": "node scripts/install-commandcode.mjs --check",
-    "commandcode:uninstall": "node scripts/install-commandcode.mjs --uninstall",
-    "seats:sync": "node scripts/sync-seat-context.mjs",
-    "seats:check": "node scripts/sync-seat-context.mjs --check",
-    "skills:sync": "node scripts/sync-skills.mjs",
-    "skills:check": "node scripts/sync-skills.mjs --check",
-    "pm:dashboard": "node bin/cli.mjs dashboard",
-    "pm:control-center": "node bin/cli.mjs control-center",
-    "pm:parallel-check": "node bin/cli.mjs parallel-check",
-    "validate:vault-ids": "node scripts/validate-vault-ids.mjs",
-    "validate:vault-naming": "node scripts/validate-vault-naming.mjs",
-    "validate:vault-blockers": "node scripts/validate-vault-blockers.mjs",
-    "validate:vault-frontmatter": "node scripts/validate-vault-frontmatter.mjs",
-    "validate:vault-encoding": "node scripts/fix-mojibake.mjs --check",
-    "fix:vault-encoding": "node scripts/fix-mojibake.mjs --apply",
-    "validate:review-backlinks": "node scripts/validate-review-backlinks.mjs",
-    "build:procedure-catalog": "node scripts/build-procedure-catalog.mjs",
-    "validate:procedure-catalog": "node scripts/build-procedure-catalog.mjs --check",
-    "build:guardrails": "node scripts/build-guardrails.mjs",
-    "validate:guardrails": "node scripts/build-guardrails.mjs --check",
-    "compile:agents": "node scripts/compile-agents.mjs",
-    "validate:agents": "node scripts/compile-agents.mjs --check",
-    "build:vault-index": "node scripts/build-vault-index.mjs",
-    "validate:vault-index": "node scripts/build-vault-index.mjs --check",
-    "check:no-cockpit": "node scripts/check-no-cockpit.mjs",
-    "commit": "node scripts/human-commit.mjs",
-    "commit:owner": "node scripts/owner-commit.mjs",
-    "hooks:install": "node scripts/install-git-hooks.mjs",
-    "hooks:install-claude": "node scripts/install-claude-code-hooks.mjs",
-    "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: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",
-    "companion:status": "pwsh -NoProfile -ExecutionPolicy Bypass -File companion/start.ps1 -Action status",
-    "spexcompanion": "pwsh -NoProfile -ExecutionPolicy Bypass -File companion/start.ps1 -Action start",
-    "spexcompanion:stop": "pwsh -NoProfile -ExecutionPolicy Bypass -File companion/start.ps1 -Action stop",
-    "spexcompanion:status": "pwsh -NoProfile -ExecutionPolicy Bypass -File companion/start.ps1 -Action status",
-    "console": "npm run dev -w spex-console",
-    "console:log": "pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/run-console-devlog.ps1",
-    "console:log:lan": "pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/run-console-devlog.ps1 -Lan",
-    "console:stop": "node scripts/dev-server-stop.mjs",
-    "console:status": "node scripts/dev-server-status.mjs",
-    "test:mcp": "node --test vendor/heyspex-mcp/*.test.mjs scripts/lib/*.test.mjs",
-    "verify:package": "node scripts/verify-mcp-package.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 and nothing else. SpexFleet internals (dev-factory/router.mjs, cloud-clients.mjs, cost-tracker.mjs, dream-research/) 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` bundled by `scripts/build-cli-bundle.mjs`, 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]]."
-}
+{
+  "name": "heyspex",
+  "version": "0.2.0",
+  "description": "HeySpex CLI + MCP server — connect Claude Code, Cursor, and any MCP client to your HeySpex spec vault",
+  "keywords": [
+    "heyspex",
+    "mcp",
+    "model-context-protocol",
+    "claude-code",
+    "cursor",
+    "spec-driven-development",
+    "agents"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/pwhermanson/workflow-protocol.git"
+  },
+  "engines": {
+    "node": ">=20.0.0 <25.0.0"
+  },
+  "workspaces": [
+    "spex-console",
+    "pm-control-center",
+    "companion/extension"
+  ],
+  "bin": {
+    "hs": "bin/hs.mjs",
+    "heyspex": "bin/hs.mjs",
+    "heyspex-mcp": "vendor/heyspex-mcp/cli.mjs",
+    "spexcode": "bin/spexcode.mjs"
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    "./console-url-resolver": "./scripts/lib/console-url-resolver.mjs"
+  },
+  "files": [
+    "bin/hs.mjs",
+    "bin/postinstall.mjs",
+    "vendor/heyspex-mcp/**/*.mjs",
+    "!vendor/heyspex-mcp/**/*.test.mjs",
+    "vendor/heyspex-mcp/config-seed.yaml",
+    "scripts/check-mcp-freshness.mjs",
+    "scripts/gateway-skills-lib.mjs",
+    "scripts/vault-id-lib.mjs",
+    "scripts/lib/console-url-resolver.mjs",
+    "scripts/lib/hs-link.mjs",
+    "scripts/lib/dev-mode.mjs",
+    "scripts/lib/hs-command.mjs",
+    "scripts/lib/shared-path-helpers.mjs",
+    "scripts/dev-server-status.mjs",
+    "scripts/lib/hs-source-*.mjs",
+    "scripts/lib/agent-env-markers.mjs",
+    "!scripts/lib/hs-source-*.test.mjs",
+    "scripts/lib/standalone-doctor.mjs",
+    "dev-factory/lib/fleet-readiness.mjs",
+    "dev-factory/lib/fleet-state.mjs",
+    "dev-factory/lib/code-repo-root.mjs",
+    "dev-factory/lib/sufficiency-score.mjs",
+    "dev-factory/lib/model-catalog.mjs",
+    "dev-factory/model-catalog.json",
+    "docs/mcp-client-config.md",
+    "dist/cli/*.mjs",
+    "dist/cli-templates/**",
+    "LICENSE",
+    "scripts/install-claude-code-hooks.mjs",
+    "scripts/install-cursor-hooks.mjs",
+    "scripts/lib/customer-kit.mjs",
+    "scripts/lib/template-pin.mjs",
+    "scripts/cursor-hooks/manifest.mjs",
+    "scripts/dev-server-stop.mjs",
+    "scripts/wip-ledger-health.mjs",
+    "scripts/hs-worktree.mjs",
+    "scripts/lib/hs-worktree-args.mjs",
+    "dev-factory/lib/worktree-allocator.mjs",
+    "dev-factory/engine/worktree.mjs",
+    "scripts/hs-view.mjs",
+    "scripts/hs-capture-cli.mjs",
+    "scripts/lib/heyspex-home.mjs",
+    "scripts/hs-companion.mjs",
+    "scripts/lib/hs-companion-settings.mjs",
+    "scripts/hs-next.mjs",
+    "scripts/hs-mode.mjs",
+    "scripts/heyspex-mode.mjs",
+    "scripts/hs-gateway.mjs",
+    "scripts/hs-settings.mjs",
+    "scripts/hs-classifier.mjs",
+    "scripts/hs-auto.mjs",
+    "scripts/hs-auto-resolve.mjs",
+    "scripts/hs-auto-source.mjs",
+    "dev-factory/lib/spec-io.mjs",
+    "dev-factory/lib/epic-detect.mjs",
+    "plugins/heyspex/bin/launch-mcp.mjs",
+    "plugins/heyspex/bin/run-hook.mjs",
+    "plugins/heyspex/.claude-plugin/plugin.json",
+    "plugins/heyspex/.mcp.json",
+    "plugins/heyspex/.cursor-plugin/plugin.json",
+    "plugins/heyspex/mcp.json",
+    "plugins/heyspex/hooks/*.json",
+    "scripts/claude-hooks/*.mjs",
+    "!scripts/claude-hooks/*.test.mjs",
+    "!scripts/claude-hooks/*.smoke.mjs",
+    "!scripts/claude-hooks/*.fixtures.mjs",
+    "!scripts/claude-hooks/*.measure.mjs",
+    "scripts/stamp-provenance-on-edit.mjs",
+    "scripts/provenance-lib.mjs",
+    "scripts/lib/subagent-git-lock.mjs",
+    "dev-factory/lib/seat-context.mjs",
+    "dev-factory/lib/context-budget.mjs",
+    "dev-factory/lib/fleet-queue.mjs",
+    "dev-factory/lib/fleet-queue-file.mjs",
+    "spexharness/src/adapters/*.mjs",
+    "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/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/git-identity-guard.decide.mjs",
+    "spexharness/src/gates/git-identity-guard.mjs",
+    "spexharness/src/gates/git-reflog-audit.mjs",
+    "spexharness/src/gates/git-stash-gate.decide.mjs",
+    "spexharness/src/gates/git-stash-gate.mjs",
+    "spexharness/src/gates/id-display-format-gate.mjs",
+    "spexharness/src/gates/inject-doctrine-gate.mjs",
+    "spexharness/src/gates/inject-vault-context.mjs",
+    "spexharness/src/gates/naughty-list-gate.mjs",
+    "spexharness/src/gates/plan-review-gate.mjs",
+    "spexharness/src/gates/preflight-reminder-gate.mjs",
+    "spexharness/src/gates/research-protocol-gate.mjs",
+    "spexharness/src/gates/settings-write-gate.decide.mjs",
+    "spexharness/src/gates/settings-write-gate.mjs",
+    "spexharness/src/profile/*.mjs",
+    "spexharness/src/doctrine/*.mjs",
+    "spexharness/doctrine/baseline/SPEXCODE-DOCTRINE.baseline.json",
+    "spexharness/src/chat/tui/ansi.mjs",
+    "spexharness/src/chat/tui/palette.mjs",
+    "spexharness/src/chat/tui/select.mjs",
+    "spexharness/src/config-root.mjs",
+    "spexharness/src/context-budget.mjs",
+    "spexharness/src/dev-server-control.mjs",
+    "spexharness/src/events.mjs",
+    "spexharness/src/git-reflog-audit.mjs",
+    "spexharness/src/intent-classifier.mjs",
+    "spexharness/src/intent-directive.mjs",
+    "spexharness/src/redact.mjs",
+    "spexharness/src/rule-table.mjs",
+    "spexharness/src/seat-context.mjs",
+    "spexharness/src/session-bootstrap.mjs",
+    "spexharness/src/session-record.mjs",
+    "spexharness/src/token-inventory.mjs",
+    "!spexharness/**/*.test.mjs"
+  ],
+  "dependencies": {
+    "js-yaml": ">=3.13.0 <5.0.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.24.2"
+  },
+  "scripts": {
+    "prepack": "node scripts/build-cli-bundle.mjs && node scripts/prepack-closure-gate.mjs",
+    "build:cli": "node scripts/build-cli-bundle.mjs",
+    "postinstall": "node bin/postinstall.mjs",
+    "setup": "node scripts/heyspex-doctor.mjs --fix",
+    "doctor": "node scripts/heyspex-doctor.mjs",
+    "heyspex:on": "node scripts/hs-mode.mjs on",
+    "heyspex:off": "node scripts/hs-mode.mjs off",
+    "heyspex:status": "node scripts/hs-mode.mjs status",
+    "commandcode:install": "node scripts/install-commandcode.mjs",
+    "commandcode:check": "node scripts/install-commandcode.mjs --check",
+    "commandcode:uninstall": "node scripts/install-commandcode.mjs --uninstall",
+    "seats:sync": "node scripts/sync-seat-context.mjs",
+    "seats:check": "node scripts/sync-seat-context.mjs --check",
+    "skills:sync": "node scripts/sync-skills.mjs",
+    "skills:check": "node scripts/sync-skills.mjs --check",
+    "pm:dashboard": "node bin/cli.mjs dashboard",
+    "pm:control-center": "node bin/cli.mjs control-center",
+    "pm:parallel-check": "node bin/cli.mjs parallel-check",
+    "validate:vault-ids": "node scripts/validate-vault-ids.mjs --require-family",
+    "validate:vault-naming": "node scripts/validate-vault-naming.mjs",
+    "validate:vault-blockers": "node scripts/validate-vault-blockers.mjs",
+    "validate:vault-frontmatter": "node scripts/validate-vault-frontmatter.mjs",
+    "validate:vault-encoding": "node scripts/fix-mojibake.mjs --check",
+    "fix:vault-encoding": "node scripts/fix-mojibake.mjs --apply",
+    "validate:review-backlinks": "node scripts/validate-review-backlinks.mjs",
+    "build:procedure-catalog": "node scripts/build-procedure-catalog.mjs",
+    "validate:procedure-catalog": "node scripts/build-procedure-catalog.mjs --check",
+    "build:guardrails": "node scripts/build-guardrails.mjs",
+    "validate:guardrails": "node scripts/build-guardrails.mjs --check",
+    "compile:agents": "node scripts/compile-agents.mjs",
+    "validate:agents": "node scripts/compile-agents.mjs --check",
+    "build:vault-index": "node scripts/build-vault-index.mjs",
+    "validate:vault-index": "node scripts/build-vault-index.mjs --check",
+    "check:retired-names": "node scripts/check-retired-names.mjs",
+    "check:model-ids": "node scripts/check-model-ids.mjs",
+    "check:shared-helpers": "node scripts/check-shared-helpers.mjs",
+    "check:no-process-exit": "node scripts/check-no-process-exit.mjs",
+    "check:epic-milestone-phrasing": "node scripts/check-epic-milestone-phrasing.mjs",
+    "smoke:cli-help": "node scripts/smoke-cli-help.mjs",
+    "commit": "node scripts/human-commit.mjs",
+    "commit:owner": "node scripts/owner-commit.mjs",
+    "hooks:install": "node scripts/install-git-hooks.mjs",
+    "hooks:install-claude": "node scripts/install-claude-code-hooks.mjs",
+    "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: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",
+    "companion:status": "pwsh -NoProfile -ExecutionPolicy Bypass -File companion/start.ps1 -Action status",
+    "spexcompanion": "pwsh -NoProfile -ExecutionPolicy Bypass -File companion/start.ps1 -Action start",
+    "spexcompanion:stop": "pwsh -NoProfile -ExecutionPolicy Bypass -File companion/start.ps1 -Action stop",
+    "spexcompanion:status": "pwsh -NoProfile -ExecutionPolicy Bypass -File companion/start.ps1 -Action status",
+    "console": "npm run dev -w spex-console",
+    "console:log": "pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/run-console-devlog.ps1",
+    "console:log:lan": "pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/run-console-devlog.ps1 -Lan",
+    "console:stop": "node scripts/dev-server-stop.mjs",
+    "console:status": "node scripts/dev-server-status.mjs",
+    "//test": "`npm test` is an ALIAS for `test:all` (scripts/run-all-tests.mjs) - the repo-health sweep over all four suites. It is deliberately NOT wired into CI or any git/Claude hook: .github/workflows/ci.yml runs `npm test --workspace spex-console`, which is a different script and is unaffected.",
+    "test": "npm run test:all",
+    "test:all": "node scripts/run-all-tests.mjs",
+    "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",
+    "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]]."
+}

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

@@ -0,0 +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"]
+}

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

@@ -0,0 +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"
+}

package/plugins/heyspex/.mcp.json

@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "heyspex": {
+      "type": "stdio",
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/bin/launch-mcp.mjs"],
+      "env": {
+        "HEYSPEX_VAULT_ROOT": "${CLAUDE_PROJECT_DIR}"
+      }
+    }
+  }
+}

package/plugins/heyspex/bin/launch-mcp.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+// HeySpex plugin MCP launcher (post-repo-split — HS-S1BX; prototype stage: HS-QTBK).
+//
+// The heyspex MCP server (vendor/heyspex-mcp/cli.mjs) reaches a customer machine
+// two ways: bundled inside the `heyspex` npm package (node_modules/heyspex/
+// vendor/heyspex-mcp/cli.mjs, once `npm install heyspex` has run), or via a
+// source checkout of the heyspex-app repo. This shim locates whichever is
+// reachable and hands off in-process, failing with an actionable message
+// instead of a silent MCP connection error.
+//
+// Resolution order:
+//   1. HEYSPEX_MCP_ENTRY — explicit override (absolute path to cli.mjs)
+//   2. node_modules/heyspex/vendor/heyspex-mcp/cli.mjs — found by walking up
+//      from THIS launcher's own location for the containing node_modules/heyspex
+//      install. Package-first is correct for the plugin use case: plugins run
+//      on customer machines, where a plain `npm install heyspex` is the one
+//      artifact that's always there — a source checkout of heyspex-app is not a
+//      safe assumption. When this launcher itself ships inside that install
+//      (node_modules/heyspex/plugins/heyspex/bin/launch-mcp.mjs), the walk finds
+//      the package root in a single hop; if the launcher is running from
+//      somewhere else (a source checkout, a plugin cache outside node_modules),
+//      the walk finds nothing and this candidate is skipped.
+//   3. $CLAUDE_PROJECT_DIR/vendor/heyspex-mcp/cli.mjs           (source checkout)
+//   4. $CURSOR_PROJECT_DIR/vendor/heyspex-mcp/cli.mjs   (Cursor sets both, but
+//      only CLAUDE_PROJECT_DIR as a compatibility alias — do not rely on it)
+//   5. $HEYSPEX_VAULT_ROOT/vendor/heyspex-mcp/cli.mjs           (source checkout)
+//   6. <cwd>/vendor/heyspex-mcp/cli.mjs                         (source checkout)
+
+import { existsSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+/**
+ * Walk up from `fromFile` looking for the `node_modules/heyspex` directory that
+ * contains it, and return the vendor/heyspex-mcp/cli.mjs path under that package
+ * root — or null if this file isn't nested inside such an install.
+ */
+function findPackagedEntry(fromFile) {
+  let dir = dirname(fromFile);
+  for (;;) {
+    const parent = dirname(dir);
+    if (parent === dir) return null; // reached the filesystem root
+    const base = dir.split(sep).pop();
+    const parentBase = parent.split(sep).pop();
+    if (base === "heyspex" && parentBase === "node_modules") {
+      return resolve(dir, "vendor/heyspex-mcp/cli.mjs");
+    }
+    dir = parent;
+  }
+}
+
+const packagedEntry = findPackagedEntry(fileURLToPath(import.meta.url));
+
+const candidates = [
+  process.env.HEYSPEX_MCP_ENTRY,
+  packagedEntry,
+  process.env.CLAUDE_PROJECT_DIR &&
+    resolve(process.env.CLAUDE_PROJECT_DIR, "vendor/heyspex-mcp/cli.mjs"),
+  process.env.CURSOR_PROJECT_DIR &&
+    resolve(process.env.CURSOR_PROJECT_DIR, "vendor/heyspex-mcp/cli.mjs"),
+  process.env.HEYSPEX_VAULT_ROOT &&
+    resolve(process.env.HEYSPEX_VAULT_ROOT, "vendor/heyspex-mcp/cli.mjs"),
+  resolve(process.cwd(), "vendor/heyspex-mcp/cli.mjs"),
+].filter(Boolean);
+
+const entry = candidates.find((p) => existsSync(p));
+
+if (!entry) {
+  console.error(
+    [
+      "[heyspex plugin] Could not locate the HeySpex MCP server (vendor/heyspex-mcp/cli.mjs).",
+      "Searched:",
+      ...candidates.map((p) => `  - ${p}`),
+      "",
+      "Fixes:",
+      "  - Run `npm install heyspex` in this project, then restart — the plugin",
+      "    boots the server from node_modules/heyspex.",
+      "  - Or point this at a source checkout of the heyspex-app repo, e.g. by",
+      "    setting CLAUDE_PROJECT_DIR or HEYSPEX_VAULT_ROOT to its path.",
+      "  - Or set HEYSPEX_MCP_ENTRY to the absolute path of cli.mjs directly.",
+    ].join("\n"),
+  );
+  process.exit(1);
+}
+
+// The guessed "grandparent of vendor/heyspex-mcp" vault root only makes sense
+// for a source checkout, where that directory IS the vault. For the packaged
+// entry it resolves to node_modules/heyspex, which is never the customer's
+// vault — leave HEYSPEX_VAULT_ROOT alone in that case and let the server's own
+// multi-tier vault resolver (vault-resolve.mjs) find the real one.
+if (!process.env.HEYSPEX_VAULT_ROOT && entry !== packagedEntry) {
+  process.env.HEYSPEX_VAULT_ROOT = resolve(entry, "../../..");
+}
+
+await import(pathToFileURL(entry).href);

package/plugins/heyspex/bin/run-hook.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+// HeySpex plugin hook launcher — the hooks.json counterpart of launch-mcp.mjs.
+//
+// Every command in ../hooks/hooks.json is
+//   node "${CLAUDE_PLUGIN_ROOT}/bin/run-hook.mjs" <hook> [args]
+// The hook bodies and their shim (scripts/claude-hooks/_run.mjs) live in the
+// HeySpex PLATFORM checkout, not in the plugin cache and not in the customer
+// repo — so `$CLAUDE_PROJECT_DIR/scripts/...` (the old form) only ever
+// resolved inside heyspex-app and failed with MODULE_NOT_FOUND everywhere else
+// (non-blocking, so every gate was silently off). This launcher finds the
+// platform and hands off in-process, so the shim still owns stdin and the exit
+// code, exactly as if Claude Code had invoked it directly.
+//
+// Resolution order (first that has scripts/claude-hooks/_run.mjs):
+//   1. HEYSPEX_PLATFORM_ROOT                         (explicit override)
+//   2. HEYSPEX_MCP_ENTRY → <root>/vendor/heyspex-mcp/cli.mjs — `hs install`
+//      writes this into the customer repo's .claude/settings.json env
+//   3. this launcher's own checkout (<root>/plugins/heyspex/bin/)
+//   4. node_modules/heyspex containing this launcher (published package)
+//   5. $CLAUDE_PROJECT_DIR, $CURSOR_PROJECT_DIR      (the platform repo itself)
+//
+// Fail-open like the shim: nothing found → one stderr line, exit 0.
+
+import { existsSync } from 'node:fs';
+import { dirname, resolve, sep } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const SHIM_REL = ['scripts', 'claude-hooks', '_run.mjs'];
+const here = dirname(fileURLToPath(import.meta.url));
+
+function packagedRoot(fromDir) {
+  let dir = fromDir;
+  for (;;) {
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    if (dir.split(sep).pop() === 'heyspex' && parent.split(sep).pop() === 'node_modules') return dir;
+    dir = parent;
+  }
+}
+
+const env = process.env;
+const candidates = [
+  env.HEYSPEX_PLATFORM_ROOT?.trim(),
+  env.HEYSPEX_MCP_ENTRY?.trim() && resolve(env.HEYSPEX_MCP_ENTRY.trim(), '..', '..', '..'),
+  resolve(here, '..', '..', '..'),
+  packagedRoot(here),
+  env.CLAUDE_PROJECT_DIR?.trim(),
+  env.CURSOR_PROJECT_DIR?.trim(),
+].filter(Boolean);
+
+const shim = candidates.map((root) => resolve(root, ...SHIM_REL)).find((p) => existsSync(p));
+
+if (!shim) {
+  process.stderr.write(
+    `[heyspex plugin] hook ${process.argv[2] ?? '?'} skipped: no HeySpex platform checkout found ` +
+      `(set HEYSPEX_MCP_ENTRY via \`hs install\`, or HEYSPEX_PLATFORM_ROOT). Searched: ${candidates.join(', ')}\n`,
+  );
+  process.exit(0);
+}
+
+// argv is already [node, <this>, <hook>, ...args] — the shape _run.mjs reads.
+await import(pathToFileURL(shim).href);