heyspex 0.2.4 → 0.2.6

package/dist/cli-templates/harness-commands/cursor/hs-res.md

@@ -7,61 +7,69 @@ description: Confidence-ladder research method's entrypoint — SpexCrawl via th
 
 **Usage:** `/hs-res [research question/topic]`
 
-# Research (`/hs-res`)
-
-> Parity: `.commandcode/skills/hs-res/SKILL.md` · `.cursor/skills/hs-res/SKILL.md` · `.agents/skills/hs-res/SKILL.md`
-
-## What to do
-
-1. **Take the question.** `$ARGUMENTS` is the research question/topic. If empty, load the
-   console doc-toolbar Promote pin via `heyspex_active_research`
-   (`.heyspex/research-focus.yaml` → `source_idea_id`, `scope`, `spec_path`) and read the source
-   capture body as the question. Either way, restate the scope and confirm with the user.
-
-2. **Gather via SpexCrawl (the Companion) — the PRIMARY method** (owner ruling 2026-08-14,
-   [[spexcrawl-through-the-companion-is-the]]: "Companion > SpexCrawl is now default method
-   for research"). Decompose into a few independent search angles, then per angle:
-   `node dev-factory/spexcrawl/spexcrawl-cli.mjs search "<query>" --json` — one call
-   searches AND returns the cleaned pages of the top results. Specific extra URLs:
-   `node dev-factory/spexcrawl/spexcrawl-cli.mjs scrape "<url>" --json`.
-   Prerequisites: the Companion running and paired to the console. LAN mode
-   (`npm run console:log:lan`) is needed ONLY when the Companion runs on a DIFFERENT
-   machine than the console — since HS-V9WH the Companion polls loopback consoles too
-   ([[a-queue-is-dead-if-its-only-consumer]]: the LAN line was a bug workaround
-   misdocumented as a requirement). When missing, the CLI exits 3 with
-   `SPEXCRAWL_UNAVAILABLE` naming the fix; a silent hang means the Companion is not
-   running or not polling this console.
-
-   **Fallback — self-hosted Firecrawl, AUTOMATIC, no permission needed (owner ruling
-   2026-08-22).** When the SpexCrawl path malfunctions, times out, hits a gate, or is otherwise
-   unavailable, fall back immediately: `node dev-factory/spexcrawl/firecrawl-cli.mjs
-   search "<query>" --json` and `node dev-factory/spexcrawl/firecrawl-cli.mjs scrape
-   "<url>" --json`. May run on any fleet machine (coffee-geek, basement-geek, spec-ops) —
-   prefer other reachable machines over the one the orchestrating session runs on; check
-   `docker info`, start Docker/the stack if needed, poll the real endpoint for readiness before
-   use. If this task's changed/claimed files are SpexCrawl-related, skip SpexCrawl entirely and
-   go straight to Firecrawl. Hosted `api.firecrawl.dev` credits are unchanged — still
-   ask-before-spend every time. Full contract: `.commandcode/skills/hs-res/SKILL.md`.
-
-3. **Assemble a numbered sources block** (`[S1]`, `[S2]`, …) from the gathered
-   `{title, url, snippet, markdown}` results, write it plus the question and cite-only
-   instructions to a temp prompt file.
-
-4. **Synthesize via DeepSeek** —
-   `node dev-factory/spexcrawl/synthesize-cli.mjs --prompt-file <path> --json`
-   (defaults `--max-tokens` to 32000 and auto-escalates ×3 up to a 96000 ceiling if DeepSeek's
-   default-on "thinking" mode burns the whole budget on reasoning — never pass a lower
-   `--max-tokens` yourself; the CLI self-heals this failure mode. Exhausted escalation exits 3
-   with `SYNTHESIZE_UNAVAILABLE`).
-
-5. **Save** via `heyspex_save_research` (or `heyspex_complete_research` under the console pin
-   pipeline), with `sources` populated from the gathered URLs.
-
-**Never fall back** to `deep-research`/`deep-research-quick|medium|thorough`, the
-`Workflow({ scriptPath: '.claude/workflows/deep-research-*.js' })` launch, or native
-`WebSearch`/`WebFetch` for this method. Self-hosted Firecrawl fallback is automatic (no
-permission needed, 2026-08-22 ruling); hosted `api.firecrawl.dev` credits still need the
-user's explicit per-run permission, every time. If a CLI reports unavailable
-(`SPEXCRAWL_UNAVAILABLE` / `FIRECRAWL_UNAVAILABLE` / `SYNTHESIZE_UNAVAILABLE`, exit 3),
-**stop** and tell the user — never silently substitute another backend. Full method,
-escalation rule, and hard prohibitions: `.commandcode/skills/hs-res/SKILL.md`.
+# Research (`/hs-res`)
+
+> Parity: `.commandcode/skills/hs-res/SKILL.md` · `.cursor/skills/hs-res/SKILL.md` · `.agents/skills/hs-res/SKILL.md`
+
+## What to do
+
+1. **Take the question.** `$ARGUMENTS` is the research question/topic. If empty, load the
+   console doc-toolbar Promote pin via `heyspex_active_research`
+   (`.heyspex/research-focus.yaml` → `source_idea_id`, `scope`, `spec_path`) and read the source
+   capture body as the question. Either way, restate the scope and confirm with the user.
+
+2. **Gather via SpexCrawl (the Companion) — the PRIMARY method** (owner ruling 2026-08-14,
+   [[spexcrawl-through-the-companion-is-the]]: "Companion > SpexCrawl is now default method
+   for research"). Decompose into a few independent search angles, then per angle:
+   `node dev-factory/spexcrawl/spexcrawl-cli.mjs search "<query>" --json` — one call
+   searches AND returns the cleaned pages of the top results. Specific extra URLs:
+   `node dev-factory/spexcrawl/spexcrawl-cli.mjs scrape "<url>" --json`.
+   Prerequisites: the Companion running and paired to the console. LAN mode
+   (`npm run console:log:lan`) is needed ONLY when the Companion runs on a DIFFERENT
+   machine than the console — since HS-V9WH the Companion polls loopback consoles too
+   ([[a-queue-is-dead-if-its-only-consumer]]: the LAN line was a bug workaround
+   misdocumented as a requirement). When missing, the CLI exits 3 with
+   `SPEXCRAWL_UNAVAILABLE` naming the fix; a silent hang means the Companion is not
+   running or not polling this console.
+
+   **Fallback — self-hosted Firecrawl, AUTOMATIC, no permission needed (owner ruling
+   2026-08-22).** When the SpexCrawl path malfunctions, times out, hits a gate, or is otherwise
+   unavailable, fall back immediately: `node dev-factory/spexcrawl/firecrawl-cli.mjs
+   search "<query>" --json` and `node dev-factory/spexcrawl/firecrawl-cli.mjs scrape
+   "<url>" --json`. May run on any fleet machine (coffee-geek, basement-geek, spec-ops) —
+   prefer other reachable machines over the one the orchestrating session runs on; check
+   `docker info`, start Docker/the stack if needed, poll the real endpoint for readiness before
+   use. If this task's changed/claimed files are SpexCrawl-related, skip SpexCrawl entirely and
+   go straight to Firecrawl. Hosted `api.firecrawl.dev` credits are unchanged — still
+   ask-before-spend every time. Full contract: `.commandcode/skills/hs-res/SKILL.md`.
+
+   **In a repo that uses the `heyspex` npm package** (not a HeySpex platform checkout): the
+   package ships only the SpexCrawl client (`dev-factory/spexcrawl/spexcrawl-cli.mjs` under
+   `node_modules/heyspex/`). It needs the HeySpex Companion, which the npm package does not
+   distribute yet, so it usually exits 3 `SPEXCRAWL_UNAVAILABLE`. The Firecrawl fallback and
+   the DeepSeek synthesis CLI (`firecrawl-cli.mjs`, `synthesize-cli.mjs`) are HeySpex-platform
+   only and are not in the package. When a CLI named in steps 2 or 4 is missing or reports
+   unavailable, stop and tell the user this research method is not available in their install.
+
+3. **Assemble a numbered sources block** (`[S1]`, `[S2]`, …) from the gathered
+   `{title, url, snippet, markdown}` results, write it plus the question and cite-only
+   instructions to a temp prompt file.
+
+4. **Synthesize via DeepSeek** —
+   `node dev-factory/spexcrawl/synthesize-cli.mjs --prompt-file <path> --json`
+   (defaults `--max-tokens` to 32000 and auto-escalates ×3 up to a 96000 ceiling if DeepSeek's
+   default-on "thinking" mode burns the whole budget on reasoning — never pass a lower
+   `--max-tokens` yourself; the CLI self-heals this failure mode. Exhausted escalation exits 3
+   with `SYNTHESIZE_UNAVAILABLE`).
+
+5. **Save** via `heyspex_save_research` (or `heyspex_complete_research` under the console pin
+   pipeline), with `sources` populated from the gathered URLs.
+
+**Never fall back** to `deep-research`/`deep-research-quick|medium|thorough`, the
+`Workflow({ scriptPath: '.claude/workflows/deep-research-*.js' })` launch, or native
+`WebSearch`/`WebFetch` for this method. Self-hosted Firecrawl fallback is automatic (no
+permission needed, 2026-08-22 ruling); hosted `api.firecrawl.dev` credits still need the
+user's explicit per-run permission, every time. If a CLI reports unavailable
+(`SPEXCRAWL_UNAVAILABLE` / `FIRECRAWL_UNAVAILABLE` / `SYNTHESIZE_UNAVAILABLE`, exit 3),
+**stop** and tell the user — never silently substitute another backend. Full method,
+escalation rule, and hard prohibitions: `.commandcode/skills/hs-res/SKILL.md`.

package/dist/cli-templates/harness-commands/cursor/hs-review.md

@@ -1,26 +1,26 @@
 ---
 name: hs-review
-description: Pull the next review-ready spec from the HeySpex review queue (review-focus.yaml → manifest traversal of `status: in_review` with HS-REV companion → folder scan).
+description: 'Pull the next review-ready spec from the HeySpex review queue (review-focus.yaml → manifest traversal of `status: in_review` with HS-REV companion → folder scan).'
 ---
 
 <!-- Generated by scripts/sync-skills.mjs from .claude/commands/hs-review.md — do not edit by hand. Run `npm run skills:sync`. -->
 
 **Usage:** `/hs-review [HS-XXXX-TASK | HS-XXXX-EPIC] [--ignore-focus]`
 
-Invoke the `heyspex_next_review` MCP tool to fetch the next review-ready spec from the HeySpex vault, then paste the returned `prompt_markdown` verbatim so the user (reviewer) can walk acceptance against the parent spec + HS-REV companion.
-
-Argument parsing for `$ARGUMENTS` (all optional; if `$ARGUMENTS` is empty, call the tool with no parameters):
-
-- A bare token matching `HS-TASK-*` / `HS-EPIC-*` / `HS-*-*` → pass as `spec_id`.
-- A bare token matching `HS-ROADMAP-*` → pass as `roadmap_id`.
-- `--ignore-focus` → set `ignore_focus: true`.
-
-Resolution precedence (built into the tool, do not re-implement here): `args.spec_id` → `.heyspex/review-focus.yaml` pin → manifest traversal for `status: in_review` specs with an `HS-REV-<suffix>-*.md` companion → folder scan as fallback. Sorted by `updated:` ascending (oldest first).
-
-After the tool returns, output the `prompt_markdown` field as-is, then on a final line state the source: `_Source: {source_kind} · {spec_id} · phase {phase_id} · age {age_in_review_days}d_`. Do not summarize, paraphrase, or start executing the returned prompt.
-
-This skill does NOT claim the spec. Reviewing is a human-in-loop activity by design (CLAUDE.md §Session Completion); the reviewer walks the four sections of the HS-REV companion (`## Acceptance verification`, `## Reviewer notes`, `## Memory candidates`, `## Decision: close or reopen`) and decides pass/reopen. Memory candidates are scored against the four-axis rubric (non-derivability / reusability / surprise-cost / concreteness, 0–3 each, threshold ≥ 7/12) — the prompt body includes the rubric and the conflict-check instruction.
-
-If the tool errors with `NO_REVIEW_READY`, tell the user the review queue is empty (no specs at `status: in_review` with an HS-REV companion) and suggest checking `specs/reviews/` for stale companions or filing the missing review doc. If `SPEC_NOT_IN_REVIEW`, surface the spec's actual status so the user can pick the right `/hs-review HS-XXXX` target. If `NO_REVIEW_DOC`, the parent spec is `in_review` but has no `HS-REV-<suffix>-*.md` companion — point the user at CLAUDE.md §Session Completion §3 for the four-section template.
-
-Cross-reference: [[HS-XRO1-RVDC-TASK-heyspex-review-on-deck-mcp-and-hs-review]] (spec), [[HS-UKD6-CLR4-RES-close-out-review-screen-jtbd-architecture]] §J17 (downstream Review surface that will call this tool from the "Copy `/hs-review`" affordance).
+Invoke the `heyspex_next_review` MCP tool to fetch the next review-ready spec from the HeySpex vault, then paste the returned `prompt_markdown` verbatim so the user (reviewer) can walk acceptance against the parent spec + HS-REV companion.
+
+Argument parsing for `$ARGUMENTS` (all optional; if `$ARGUMENTS` is empty, call the tool with no parameters):
+
+- A bare token matching `HS-TASK-*` / `HS-EPIC-*` / `HS-*-*` → pass as `spec_id`.
+- A bare token matching `HS-ROADMAP-*` → pass as `roadmap_id`.
+- `--ignore-focus` → set `ignore_focus: true`.
+
+Resolution precedence (built into the tool, do not re-implement here): `args.spec_id` → `.heyspex/review-focus.yaml` pin → manifest traversal for `status: in_review` specs with an `HS-REV-<suffix>-*.md` companion → folder scan as fallback. Sorted by `updated:` ascending (oldest first).
+
+After the tool returns, output the `prompt_markdown` field as-is, then on a final line state the source: `_Source: {source_kind} · {spec_id} · phase {phase_id} · age {age_in_review_days}d_`. Do not summarize, paraphrase, or start executing the returned prompt.
+
+This skill does NOT claim the spec. Reviewing is a human-in-loop activity by design (CLAUDE.md §Session Completion); the reviewer walks the four sections of the HS-REV companion (`## Acceptance verification`, `## Reviewer notes`, `## Memory candidates`, `## Decision: close or reopen`) and decides pass/reopen. Memory candidates are scored against the four-axis rubric (non-derivability / reusability / surprise-cost / concreteness, 0–3 each, threshold ≥ 7/12) — the prompt body includes the rubric and the conflict-check instruction.
+
+If the tool errors with `NO_REVIEW_READY`, tell the user the review queue is empty (no specs at `status: in_review` with an HS-REV companion) and suggest checking `specs/reviews/` for stale companions or filing the missing review doc. If `SPEC_NOT_IN_REVIEW`, surface the spec's actual status so the user can pick the right `/hs-review HS-XXXX` target. If `NO_REVIEW_DOC`, the parent spec is `in_review` but has no `HS-REV-<suffix>-*.md` companion — point the user at CLAUDE.md §Session Completion §3 for the four-section template.
+
+Cross-reference: [[HS-XRO1-RVDC-TASK-heyspex-review-on-deck-mcp-and-hs-review]] (spec), [[HS-UKD6-CLR4-RES-close-out-review-screen-jtbd-architecture]] §J17 (downstream Review surface that will call this tool from the "Copy `/hs-review`" affordance).

package/docs/copilot-plugin-install.md

@@ -32,7 +32,7 @@ The heyspex-app repository is not required and is not available to customers. Ev
 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`).
+- Node.js 20–24 on PATH (`node --version`; the package requires `>=20 <25`).
 - 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`.
@@ -43,7 +43,7 @@ carries the plugin, the marketplace manifest, the hooks and the MCP server.
 ```bash
 npm install heyspex
 # or, from a tarball you were given:
-npm install ./heyspex-0.2.0.tgz
+npm install ./heyspex-<version>.tgz
 ```
 
 - Sign the machine in to the HeySpex console so hooks and MCP tools can reach the vault:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "heyspex",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "HeySpex CLI + MCP server — connect Claude Code, Cursor, and any MCP client to your HeySpex spec vault",
   "keywords": [
     "heyspex",
@@ -37,7 +37,6 @@
   },
   "files": [
     "bin/hs.mjs",
-    "bin/postinstall.mjs",
     "bin/hs-vault-binding.mjs",
     "vendor/heyspex-mcp/**/*.mjs",
     "!vendor/heyspex-mcp/**/*.test.mjs",
@@ -66,6 +65,7 @@
     "dev-factory/lib/sufficiency-score.mjs",
     "dev-factory/lib/model-catalog.mjs",
     "dev-factory/model-catalog.json",
+    "dev-factory/spexcrawl/spexcrawl-cli.mjs",
     "docs/mcp-client-config.md",
     "docs/copilot-plugin-install.md",
     "docs/driving-heyspex-from-copilot.md",
@@ -88,8 +88,12 @@
     "scripts/lib/hs-worktree-args.mjs",
     "dev-factory/lib/worktree-allocator.mjs",
     "dev-factory/engine/worktree.mjs",
+    "dev-factory/lib/runner-path.mjs",
+    "dev-factory/lib/dispatch-guard.mjs",
     "scripts/hs-view.mjs",
     "scripts/hs-capture-cli.mjs",
+    "scripts/record-grounding.mjs",
+    "scripts/lib/capture-execution-guard.mjs",
     "scripts/lib/heyspex-home.mjs",
     "scripts/hs-companion.mjs",
     "scripts/lib/hs-companion-settings.mjs",
@@ -183,9 +187,9 @@
     "esbuild": "^0.24.2"
   },
   "scripts": {
-    "prepack": "node scripts/build-cli-bundle.mjs && node scripts/prepack-closure-gate.mjs",
+    "prepack": "node scripts/sync-skills.mjs && node scripts/build-cli-bundle.mjs && node scripts/prepack-closure-gate.mjs && node scripts/pack-manifest.mjs strip",
+    "postpack": "node scripts/pack-manifest.mjs restore",
     "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",
@@ -253,5 +257,5 @@
     "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-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]]."
+  "//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`, `hs-handoff`, `hs-pin`, `hs-events`, `hs-export-events`, `hs-prereq`, `hs-trash`, `hs-trust`, `hs-next-launch`, `hs-revalidate`, `hs-test`, `hs-spawn` 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

@@ -2,7 +2,7 @@
   "name": "heyspex",
   "displayName": "HeySpex",
   "icon": "./assets/heyspex-glyph-256.png",
-  "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.",
+  "description": "SpexCode plugin (for Claude Code), also loaded by GitHub Copilot CLI (Claude-format plugin, installed from the same marketplace): HeySpex vault integration — 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"

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

@@ -3,7 +3,7 @@
   "displayName": "HeySpex",
   "version": "0.1.0",
   "logo": "assets/heyspex-glyph.svg",
-  "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.",
+  "description": "Cursor build of the SpexCode plugin (for Claude Code): 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"

package/scripts/claude-hooks/wip-checkpoint.mjs

@@ -49,6 +49,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { getActiveConfig, isResolvedVault } from '../../vendor/heyspex-mcp/vault-resolve.mjs';
+import { parseSpecId } from '../../vendor/heyspex-mcp/spec-id-lib.mjs';
 import { hookVaultHeaders } from '../lib/hook-vault-header.mjs';
 import { resolveConsoleUrl as resolveConsoleUrlShared } from '../lib/console-url-resolver.mjs';
 import { readCredentialsMcpToken, resolveDevMode } from '../lib/dev-mode.mjs';
@@ -105,9 +106,23 @@ function ledgerRoots() {
 // HS-EPIC-BUD-PROTECT under vault id `vault-test`). Real ids are server-minted
 // file keys; a SessionStart preview must never present one of these as the
 // prior session's hand-off.
-const FIXTURE_ID_RE = /^HS-EPIC-(?:FILLER-\d+|OLD\d+|BUD-[A-Z0-9-]+|CLAIMED-BUD|TRIGGER(?:-[A-Z0-9-]+)?)$/;
+// Parsed through the sanctioned id parser (spec-id-lib parseSpecId), never a
+// hand-rolled type-first regex ([[HS-MIL-KY1F]]): only legacy type-first EPIC
+// ids whose family token is one of the known fixture families qualify.
+const FIXTURE_EPIC_FAMILIES = {
+  FILLER: (slug) => /^\d+$/.test(slug), // HS-EPIC-FILLER-07
+  BUD: (slug) => slug !== '', // HS-EPIC-BUD-PROTECT
+  CLAIMED: (slug) => slug === 'BUD', // HS-EPIC-CLAIMED-BUD
+  TRIGGER: () => true, // HS-EPIC-TRIGGER, HS-EPIC-TRIGGER-X
+};
 function isFixtureLedgerEntry(epicId) {
-  return typeof epicId === 'string' && FIXTURE_ID_RE.test(epicId);
+  if (typeof epicId !== 'string') return false;
+  const parsed = parseSpecId(epicId);
+  if (!parsed || parsed.ordering !== 'type-first' || parsed.typeLabel !== 'EPIC') return false;
+  const { familyKey, titleSlug } = parsed;
+  if (/^OLD\d+$/.test(familyKey)) return titleSlug === ''; // HS-EPIC-OLD34
+  const rule = FIXTURE_EPIC_FAMILIES[familyKey];
+  return rule ? rule(titleSlug) : false;
 }
 
 async function readStdinJson() {