heyspex 0.1.0 → 0.2.0

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

@@ -0,0 +1,32 @@
+---
+name: hs-next
+description: Pull the next on-deck execution prompt from the HeySpex roadmap (focus.yaml → in_progress → open).
+---
+
+<!-- Generated by scripts/sync-skills.mjs from .claude/commands/hs-next.md — do not edit by hand. Run `npm run skills:sync`. -->
+
+**Usage:** `/hs-next [handheld|assist|auto] [HS-XXXX-EPIC | HS-XXXX] [--include-horizon] [--ignore-focus] [--claim]`
+
+> **SaaS-safety note:** this file is a thin shim — the workflow orchestration (claim question wording, reply→action mapping, failure-mode handling) lives in `vendor/heyspex-mcp/cli.mjs` (`composeAgentOrchestration`) and is delivered to you as the structured `agent_dispatch` object. **Do not add orchestration prose here.** If a workflow detail needs to change, change it in the MCP server so customer workspaces can't corrupt it. See [[HS-CCKM-J6CD-RES-migrate-slash-command-orchestration-from]] and [[workflow-orchestration-belongs-in-mcp-not-claude-commands]].
+
+## What to do
+
+1. **Parse `$ARGUMENTS`** (all optional, order-flexible):
+   - **Run front** (default `handheld`): `handheld` · `assist` | `assisted` · `auto` | `autonomous` → canonical `front` for MCP (`handheld` | `assisted` | `autonomous`; omit when handheld/default)
+   - bare token `HS-EPIC-*` or `HS-*` → `spec_id`
+   - bare token `HS-ROADMAP-*` → `roadmap_id`
+   - `--include-horizon` → `include_horizon: true`
+   - `--ignore-focus` → `ignore_focus: true`
+   - `--claim` | `--auto-claim` → `auto_claim: true`. Skips the yes/proceed/confirm handshake and claims immediately — same mechanism `autonomous` front already triggers automatically (`shouldAutoClaimOnDeck` in `run-front.mjs`), just usable standalone at any front. `/hs-next HS-IUQO --claim` claims and starts handheld work with no ask; `/hs-next HS-IUQO assisted --claim` does the same at assisted supervision. (Redundant, never conflicting, with `autonomous` front, which already implies it.)
+
+2. **Call** `heyspex_next_on_deck` with `summary: true` plus the parsed args (including `front` when not handheld/default, and `auto_claim: true` when `--claim`/`--auto-claim` was passed).
+
+3. **Output the `user_prompt_markdown` field verbatim** to the user. Do not summarize, paraphrase, or trim. **Do NOT echo the `agent_dispatch` field** — it is a structured routing object you decode, not prose you print. (The @deprecated `prompt_markdown` field mirrors `user_prompt_markdown`; either is safe to print, but prefer `user_prompt_markdown`.) Schema: `specs/schemas/agent-dispatch.schema.json`.
+
+4. **On the user's reply**, decode `agent_dispatch`:
+   - Match the reply against each entry's `tokens` array under `on_user_reply` (or `drift_resolution_menu`, when present).
+   - If the matching entry has `actions`, invoke each `{ tool, args }` in order. If `execute_after: true`, begin executing the work in the same turn — no second permission ask. All listed tools (`heyspex_claim_spec`, `heyspex_record_alignment`, `heyspex_next_on_deck`, `heyspex_release_spec`) are pre-allowlisted.
+   - If the matching entry has `reply`, respond with that string verbatim.
+   - If the `default` entry is `"respond_to_user_question"`, treat the reply as a redirect: answer the user's actual question instead of claiming.
+   - For any tool error, look up its code in `agent_dispatch.failure_modes` and apply the named `handling` only when that error code was **returned by the tool call** — failure_modes are conditional, not a statement that the console is down. Trust `console_status.reachable` on the brief. Never hand-write vault files when `heyspex_file_spec` fails.
+   - On session hand-off, run the `on_handoff` actions (typically `heyspex_release_spec`).

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

@@ -0,0 +1,73 @@
+---
+name: hs-promote
+description: Promote whatever doc you hand it to its next stage — a capture (HS-CAP-*) to research, or a research doc (HS-RES-*) to a milestone with AI-assisted epic stubs. One verb, inferred by id prefix. Native command (carries full $ARGUMENTS; the MCP prompt only gets the first token).
+---
+
+<!-- Generated by scripts/sync-skills.mjs from .claude/commands/hs-promote.md — do not edit by hand. Run `npm run skills:sync`. -->
+
+**Usage:** `/hs-promote <HS-CAP-XXXX[,HS-CAP-YYYY...] | HS-RES-XXXX> [rest of args depend on which — see below]`
+
+> **Platform asymmetry — read this, it is load-bearing.** Claude Code delivers only the **first whitespace token** of an MCP prompt's argument (GitHub [#14210](https://github.com/anthropics/claude-code/issues/14210), closed *not planned*), so the namespaced MCP prompts (`/hs-promote-capture`, `/hs-promote-research`) can each carry at most a single token. This **native project command** is the only IDE surface that receives full `$ARGUMENTS`.
+>
+> **Why one command instead of two.** `/hs-promote-capture` and `/hs-promote-research` used to be separate commands — which meant typing the word "promote" twice (`/hs-promote-capture HS-CAP-XXXX promote`) when the command name already said what it does. There's exactly one verb here — *promote whatever doc you hand it to its next stage* — so there's one command. The **id prefix alone** tells you which flow applies (`HS-CAP-*` vs `HS-RES-*` are mutually exclusive and mechanical to detect); the two flows underneath are otherwise unrelated (different tools, different payload shapes, different two-phase mechanics) and stay fully separate below — only the entrypoint is shared.
+
+## Step 0 — identify the doc
+
+Read the **leading token** of `$ARGUMENTS` (case-insensitive; captures may be a comma/whitespace-separated list):
+- Contains `-CAP` as its type label (legacy `HS-CAP-XXXX` or era-3 `HS-<fileKey>-<familyKey>-CAP-<slug>`) → go to **§A. Capture → research**.
+- Contains `-RES` the same way → go to **§A2. Research → milestone**.
+- **Era-3 short/display forms carry NO type label** — `HS-XV4W` (short id) and `HS-XV4W-HV6H` (file key + family key, the form humans see rendered) name a spec without saying its kind. Resolve the kind by fetching it: `heyspex_active_capture({ spec_id })` succeeding → it's a capture, §A. Otherwise treat it as research and try §A2. The tools accept any of these forms and collapse them to the stored short id themselves — never tell the user their id is wrong just because it carries (or lacks) the family key.
+- None of the above → ask the user which doc they mean (don't guess).
+
+If the capture tools are not already available in this session, call `heyspex_load_tools` first so `heyspex_active_capture` / `heyspex_promote_capture` / `heyspex_promote_capture_to_diagnose` are callable.
+
+---
+
+## §A. Capture → research (`HS-CAP-*`)
+
+**1. Parse the rest of `$ARGUMENTS`:**
+- Leading token(s) matching `HS-CAP-[A-Z0-9-]{3,}` (comma- and/or whitespace-separated) → `capture_ids` (1 or more).
+- Next token: `HS-RES-[A-Z0-9-]{3,}` → `target_research` = that id. Or the literal word `new`/`NEW` (also the default when this token is omitted entirely) → `target_research = "NEW"`; any remaining words up to an `enhances:` token → `new_research_name`.
+- A token shaped `enhances:HS-MIL-XXXX` anywhere in the string → `enhances`.
+
+**2. Route by kind:**
+- For each `capture_id`, read its `kind:` via `heyspex_active_capture({ spec_id: capture_id })`.
+- Exactly one capture_id AND its `kind: bug-fix` → `heyspex_promote_capture_to_diagnose({ capture_id })` (creates `HS-DIAG-*`). Never mix a bug-fix capture into a multi-capture research promote.
+- Otherwise → `heyspex_promote_capture({ capture_ids, target_research, new_research_name?, enhances? })`:
+  - `target_research === "NEW"` is **two-phase**: first call **omits** `accepted_outline` — it returns a proposed `{ name, outline, tags, enhances_suggestion }`. **Show it to the user and confirm** before calling again with the same args plus `accepted_outline` (Phase 2 performs the writes). Never skip straight to Phase 2.
+  - An existing `target_research` id is single-phase (direct, idempotent append) — no outline confirm needed.
+  - A `CAPTURE_INSUFFICIENT` error names the missing elements (core-idea, example, done-criteria, kind, user-stories) — the correct response is to elicit that detail from the user and improve the capture, not to pass `force_promote: true` unless the human explicitly says to promote anyway.
+  - **Check the outline against the capture's own Notes before presenting it.** Before showing `proposed_outline` (AI-proposed or agent-authored) to the user, walk every verbatim quote in the capture's `## Notes` and state plainly whether the outline addresses it. If a quote asks for something the outline doesn't cover, add a section for it or say so before asking for confirm — a missed verbatim quote is exactly what got two real items dropped from a milestone in this vault's own history ([[HS-GDT5-F16L-DIAG-promote-flow-drafts-research-and-stubs]]).
+  - **Outline confirm ≠ research done.** Phase 2 only writes the research **stub** — every section body is the literal placeholder `_TBD — fill in this section._`. Confirming the outline approves its *shape* (section headings), not its findings. As the very next step after Phase 2 creates the file, fill in every section with real content **by running the `/hs-res` method** (SpexCrawl gather via the Companion + DeepSeek synthesis — see `.claude/commands/hs-res.md`); **never author the research yourself in the main session** — main-session self-research skips the routed research seats and burns the expensive model on work the fleet owns. Do not report the research as complete, and do not move on to `/hs-promote-research`, until the TBD placeholders are gone. (`heyspex_promote_research` mechanically refuses with `RESEARCH_STILL_STUB` while any remain, but don't rely on that gate — write the research because it's the point of the flow, not because a check will otherwise fail.)
+
+**3. Report the result** — the research id (created or extended) or diagnose id created, and confirm the capture(s)' `promoted_to` now points at it.
+
+---
+
+## §A2. Research → milestone (`HS-RES-*`)
+
+**1. Parse the rest of `$ARGUMENTS`:**
+- `research_id` is the leading `HS-RES-*` token (already identified in Step 0).
+- Next word matching `spawn|augment|both` → `intent`. Default `spawn` when omitted.
+- Next token: `HS-MIL-[A-Z0-9-]{3,}` → `target_milestone` = that id. Or the literal word `new`/`NEW` (also the default when this token is omitted entirely) → `target_milestone = "NEW"`; remaining words → `new_milestone_name`.
+- If `intent` includes `augment`, any remaining `HS-EPIC-[A-Z0-9-]{3,}` tokens → `augment_epic_ids` (required in that case — ask for them if `augment` was requested but none were given).
+
+**2. Default policy:** `target_milestone: "NEW"` unless the user names an **existing `status: open`** milestone that clearly extends the same thesis. Spawning into an `in_progress` milestone is blocked unless the owner explicitly passes `attach_to_in_progress_milestone: true` + `attach_override_reason` (≥40 chars audit trail) — never default to this path or infer the override on the agent's own judgment.
+
+**3. Phase 1 — proposal.** Call `heyspex_promote_research({ research_id, target_milestone, new_milestone_name?, intent, spawn_epic_count?, augment_epic_ids? })` **without** `accepted_stubs`. Show the user the returned `proposed_stubs[]` and let them edit/remove/approve.
+   - **If `ai_proposal.ok === false` (e.g. `reason: "no_api_key"`), `proposed_stubs` comes back empty — the agent must author the stubs itself.** This is NOT a shortcut to skip the confirm step; it makes the confirm step *more* necessary, not less, because nothing upstream has vetted these stubs yet. Author them from the research doc's actual content, present them to the user exactly as you would an AI proposal (name/kind/effort/rationale per stub), and wait for a real approval turn before calling Phase 2. **Do not call Phase 2 in the same turn you authored the stubs in** — that is precisely the failure this line exists to prevent (observed 2026-08-12: an agent self-authored 3 epic stubs and executed `accepted_stubs` in the same tool-call batch with no human turn in between).
+   - **Check the stubs against the SOURCE CAPTURE's own Notes before presenting them.** Before showing `proposed_stubs` (AI-proposed or agent-authored) to the user, walk every verbatim quote in the source capture's `## Notes` — the capture(s) named in the research doc's `sources_captures`, not just the research doc's own prose, since a two-hop drift can lose fidelity the research doc's text won't show — and confirm each is addressed by a stub or explicitly named as out of scope. This check caught two real gaps missed by an agent-authored stub list in this vault's own history ([[HS-GDT5-F16L-DIAG-promote-flow-drafts-research-and-stubs]]).
+
+**4. Phase 2 — execute (after human confirms).** Call again with the same args plus `accepted_stubs: [...]` (the confirmed, possibly-edited subset) to perform the transactional write.
+
+**5. Report the result** — the milestone id (new or existing) plus spawned epic ids, or the augmented epic ids. Note that research stays `status: open` (research is evergreen) — only its `enhances:`/`spawned_epics:` links change.
+
+---
+
+## Hard prohibitions
+
+- **Never** execute a Phase-2 write (`accepted_outline` or `accepted_stubs`) without the human having seen and confirmed the Phase-1 proposal. For `accepted_stubs` the tool now refuses this mechanically: the proposal turn leaves a marker keyed on the research id, and an execute turn without one returns `STUB_REVIEW_REQUIRED`. If the human replaced every proposed stub, pass `stub_edit_note` (≥40 chars) saying what they changed — otherwise a fully-drifted execute returns `STUB_REVIEW_DRIFT`. As with `RESEARCH_STILL_STUB`, treat the mechanical refusal as the backstop, not the first line of defense.
+- **Never** call `heyspex_promote_research` against a research doc that still carries `_TBD — fill in this section._` placeholders — fill it in via the `/hs-res` method first (§A step 2 above), never by authoring the research yourself in the main session. The tool refuses this mechanically (`RESEARCH_STILL_STUB`) but the agent should never rely on that as the first line of defense.
+- **Never** route a bug-fix capture through `heyspex_promote_capture` — it goes to `heyspex_promote_capture_to_diagnose` instead.
+- **Never** attach a research promote to an `in_progress` milestone without an explicit owner override (`attach_to_in_progress_milestone` + `attach_override_reason`).
+- **Never** commit or push.

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

@@ -0,0 +1,38 @@
+---
+name: hs-push
+description: Push an epic implementation plan into the HeySpex vault, optionally pinning it on deck in the same call. Native command (carries full $ARGUMENTS; the MCP prompt only gets the first token). Consolidates the former hs-push / hs-push-next split into one command + flag.
+---
+
+<!-- Generated by scripts/sync-skills.mjs from .claude/commands/hs-push.md — do not edit by hand. Run `npm run skills:sync`. -->
+
+**Usage:** `/hs-push [<epic name>] [--next] [--reason <focus reason>]`
+
+> **Platform asymmetry — read this, it is load-bearing.** Claude Code delivers only the **first whitespace token** of an MCP prompt's argument (GitHub [#14210](https://github.com/anthropics/claude-code/issues/14210), closed *not planned*), so the namespaced MCP prompts `/hs-push` / `/hs-push-next` can each carry at most a single token — never an epic name plus a `--next` flag plus a focus reason together. This **native project command** is the only IDE surface that receives full `$ARGUMENTS`. It also **consolidates** the old two-prompt split (`hs-push` vs `hs-push-next`) into one command: both ultimately call the same `heyspex_push_plan` tool with only `on_deck` differing, so there is no behavior lost by merging them here — just one flag instead of two command names.
+
+## What to do
+
+**1. Parse `$ARGUMENTS`:**
+- `--next` (anywhere, case-insensitive) → `on_deck = true`. Absent → `on_deck = false` (file the epic without pinning focus).
+- `--reason <text>` → `focus_reason` (only meaningful when `on_deck` is true; rest of that flag's value up to the next `--` flag or end of string).
+- Remaining leading, non-flag text → an `epic_name` hint. Optional — if omitted, derive the title from the plan under discussion in chat.
+
+**2. Gather the rest of the payload from the conversation** (a Cursor/proprietary `.plan.md` the user pasted or referenced, or a plan already discussed in chat):
+- `summary` — required plain-language frontmatter summary (spec-summary-authoring contract).
+- `plan_markdown` — epic body markdown (goal, phases, acceptance criteria).
+- `milestone` — **required**: the parent `HS-MIL-*` wikilink. Ask the user if it isn't obvious from context; the tool call fails without it.
+- `source_plan_paths` — any `.plan.md` file paths referenced (auto-detected from `plan_markdown` too).
+- `kind` / `effort` / `tags` / `related` — optional scheduler/classification fields.
+
+**3. Call** `heyspex_push_plan({ epic_name, summary, plan_markdown, milestone, on_deck, focus_reason?, source_plan_paths?, kind?, effort?, tags?, related? })`. This writes the epic **only** — `children: []`; tasks are never filed here, only later via `/hs-next` breakdown.
+
+**4. After the call:**
+- `on_deck: true` → the epic is set `in_progress`, `.heyspex/focus.yaml` is written, and a NEXT STEP block is added. Tell the user to run `/hs-next` next.
+- `on_deck: false` → tell the user to re-run `/hs-push --next` (or `/hs-next <the new epic id>`) when ready to start work.
+
+**5. Conflict handling:** if the tool returns a behavioral-conflict block against `related` specs and `on_deck` was requested, the write is blocked by default (no files written, no focus pinned). Surface the conflicts to the user — only pass `skip_conflict_check: true` on their explicit say-so, and note a `conflict_override` should be recorded afterward.
+
+## Hard prohibitions
+
+- **Never** file tasks here — epics only (`children: []`); tasks are just-in-time via `/hs-next` breakdown.
+- **Never** silently bypass a conflict block — surface it and let the human decide.
+- **Never** commit or push git.

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

@@ -0,0 +1,30 @@
+---
+name: hs-qc
+description: Post-plan QC gut-check — stress-test a drafted plan before executing it (the plan→execute gate). Reason through the gut-check questions, launch explorers to fill gaps, fold findings into the plan, then record Proof-of-Use.
+---
+
+<!-- Generated by scripts/sync-skills.mjs from .claude/commands/hs-qc.md — do not edit by hand. Run `npm run skills:sync`. -->
+
+**Usage:** `/hs-qc [--plan <path>]  (defaults to the most recent plan)`
+
+> **Where this sits.** `/hs-ground` (pre-plan) → draft → `heyspex_plan_review` → **`/hs-qc`** → `ExitPlanMode`. Both plan-review + QC markers required ([[HS-R4OY]]).
+
+## What to do
+
+**0. Mandatory drift passes** — Axis A (as-built code) + Axis B (design supersession per [[drift-is-two-axes-as-built-and-design-supersession]]). Re-run `heyspex_plan_review`; read `axis_b_drift`. Do not trust parent epic AC over newer memory decisions.
+
+**0b. When `axis_b_drift` is non-empty — ask the user before recording QC:**
+
+Present each conflict. **Default (Recommended):** re-scope the plan (remove dead work). **Override:** user explicitly confirms proceed anyway → `heyspex_plan_qc({ axis_b_user_confirmed: true, axis_b_confirmation_note: "…" })`. Tool returns `QC_AXIS_B_DRIFT` until resolved or user-confirmed. **The override is currently broken** per [[HS-EP8E-C1L2-DIAG-heyspex-plan-qc-override-path-ignores-ax]] (reproduced twice) — until fixed, `HEYSPEX_PLAN_QC_GATE_OFF=1` is the only working escape, and its use should be reported to the owner.
+
+**1. Run the gut-check (verbatim — the owner's standard).**
+
+Wonderful work! Can you please do a quality check and a gut-check? … *(full questions unchanged)*
+
+**2. Act on what you find.** Fold findings into the plan; re-run `heyspex_plan_review` if material.
+
+**3. Record Proof-of-Use.** `heyspex_plan_qc` with substantive `findings_summary` including **`Axis B:`** line.
+
+**4. Then `ExitPlanMode`.**
+
+(Break-glass: `HEYSPEX_PLAN_QC_GATE_OFF=1`.)

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

@@ -0,0 +1,67 @@
+---
+name: hs-res
+description: Confidence-ladder research method's entrypoint — SpexCrawl via the Companion (search/gather) is PRIMARY + DeepSeek (synthesis); self-hosted Firecrawl is an AUTOMATIC fallback (no permission needed, owner ruling 2026-08-22), zero Claude/Anthropic involvement.
+---
+
+<!-- Generated by scripts/sync-skills.mjs from .claude/commands/hs-res.md — do not edit by hand. Run `npm run skills:sync`. -->
+
+**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`.

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

@@ -0,0 +1,26 @@
+---
+name: hs-resolve
+description: Pull the top open item from the HeySpex Resolution lane (conflicts, dangling refs, cycles, prerequisites, validation/stale-index) with a fix brief. Replaces the old conflict-only prompt.
+---
+
+<!-- Generated by scripts/sync-skills.mjs from .claude/commands/hs-resolve.md — do not edit by hand. Run `npm run skills:sync`. -->
+
+**Usage:** `/hs-resolve [HS-XXXX-EPIC | <item-key> | --ignore-focus]`
+
+Invoke the `heyspex_next_resolution` MCP tool to fetch the top open resolution item from the HeySpex vault, then paste the returned `prompt_markdown` verbatim so the user can act on the fix brief.
+
+Argument parsing for `$ARGUMENTS` (all optional; if empty, call the tool with no parameters):
+
+- A token containing `:` (e.g. `dangling_ref:hs-epic-x:hs-task-y`) → pass as `item_key` (fetch that specific item's brief; bypasses the focus pin).
+- A bare spec id matching `HS-EPIC-*` / `HS-TASK-*` / `HS-MIL-*` / `HS-*-*` → pass as `scope` (deck-aware: restrict detection to that spec so its gating prerequisite/conflicts surface). This is what the On-Deck `resolve_command: /hs-resolve <epic-id>` passes.
+- `--ignore-focus` → set `ignore_focus: true` (skip the Neon resolution focus pin; lead with the top-ranked open item).
+
+Resolution precedence (built into the tool — do not re-implement): `item_key` → `scope`/`ignore_focus` (top-ranked of the open list) → the Neon focus pin (server-applied) → top-ranked open item. Items are ordered with **gating** and **errors first** (`orderResolutionItems`).
+
+After the tool returns, output the `prompt_markdown` field as-is, then on a final line state the source: `_Source: {source} · {item.kind} · {item.key}_`. Do not summarize, paraphrase, or start executing actions from the brief without the user's go-ahead.
+
+This is the surviving `/hs-resolve` (the legacy conflict-only prompt that errored **"Not an Epic"** on a milestone has been retired — the resolver is item-centric and never type-checks the target). Authority from the brief's resolution menu: **Re-scan / clear** is agent-autonomous; **Switch to this**, **Defer**, **edge removal**, and **override** require explicit user confirmation. `stale_index` items expose **only** re-scan/clear — never an edge-mutating action.
+
+Detection is HTTP-only (the tool reads the console aggregator — the one detection path — it does not re-detect). If the tool errors with `CONSOLE_UNREACHABLE`, tell the user to **start the console dev server (port 3000, or run `hs server status` to see which port it actually bound)** — this only happens on a dev machine; SaaS console is always up. On `CONSOLE_TIMEOUT`, suggest retrying shortly (the server may be cold-compiling). On `ITEM_NOT_FOUND`, the `item_key` is not in the open set — list items with `/hs-resolve` (no args).
+
+This skill does NOT claim or build anything; it presents the fix brief. Sibling skills: `/hs-next` (build pipeline), `/hs-review` (review pipeline), `/hs-resolve` (this — resolution lane). See [[HS-0EJ6-RMCP-EPIC-hs-resolve-mcp-tool-and-skill]] and [[HS-I8FM-RSRF-EPIC-resolution-surface-api-and-pin]].

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

@@ -0,0 +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).
+---
+
+<!-- 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).

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

@@ -0,0 +1,30 @@
+---
+name: hs-view
+description: Open one console surface in a chromeless app-mode browser window (solo console gauge) — pipeline funnel first; follows the focus pin when no doc id is given. Thin wrapper over `hs view`.
+---
+
+<!-- Generated by scripts/sync-skills.mjs from .claude/commands/hs-view.md — do not edit by hand. Run `npm run skills:sync`. -->
+
+**Usage:** `/hs-view [surface] [doc id] [--width N] [--height N] [--browser edge|chrome]`
+
+# HeySpex solo-surface viewer (`/hs-view`)
+
+> Parity: `.commandcode/skills/hs-view/SKILL.md` · `.cursor/skills/hs-view/SKILL.md` · `.agents/skills/hs-view/SKILL.md`
+
+Optional macro over the one core ([[capability-three-faces-no-per-capability-slash]]): shell to `hs view`, never reimplement it. Design: [[HS-RU2R-I87U-RES-solo-surface-cli-launcher-single]].
+
+## What to do
+
+1. **Resolve `$ARGUMENTS` by smart first-token detection** — grammar is positional, token-identical with the CLI:
+   - First token looks like a spec id (`HS-…`) → doc id; surface defaults to `pipeline`.
+   - First token is a surface slug (`pipeline`, `docs`, `whats-next`, `captures`, `session-log`, `settings`) → second token, if present, is the doc id (anchors `pipeline` and `docs` only).
+   - No arguments → `pipeline`, anchored on the focus pin (live-follow).
+   - Pass `--width` / `--height` / `--browser edge|chrome` through unchanged.
+2. **Run it yourself** from the repo root:
+   ```bash
+   node bin/hs.mjs view <surface> [<doc-id>] [flags]
+   ```
+3. The verb probes ground-truth dev-server status first — if the console is down, relay its message and offer `npm run dev` (don't start the server unprompted).
+4. Relay the one-line result (URL + window size); closing the window closes it, re-running reopens it.
+
+Never hand-build `msedge --app=…` invocations — the CLI verb owns server probing, URL resolution, and browser mechanics.

package/dist/cli-templates/harness-commands/cursor/kill-ports.md

@@ -0,0 +1,35 @@
+---
+name: kill-ports
+description: Kill every process listening on a TCP port in the range 3000–5999 (clears stuck dev servers).
+---
+
+<!-- Generated by scripts/sync-skills.mjs from .claude/commands/kill-ports.md — do not edit by hand. Run `npm run skills:sync`. -->
+
+**Usage:** `/kill-ports (no arguments)`
+
+**Always use the PowerShell tool for this command — never the Bash tool.** Bash routes to a POSIX shell in this environment and the PowerShell syntax below will fail there.
+
+Kill all processes that are **listening** on TCP ports in the range **3000–5999** inclusive. This clears orphaned dev servers (Next.js, console, companion bridges, etc.) that are holding ports.
+
+Run this single command via the **PowerShell** tool. It discovers the listening connections in range, reports each `port → pid (process name)` it is about to kill, then force-kills the unique owning PIDs and confirms:
+
+```powershell
+$conns = Get-NetTCPConnection -State Listen -ErrorAction SilentlyContinue |
+  Where-Object { $_.LocalPort -ge 3000 -and $_.LocalPort -le 5999 }
+if (-not $conns) { Write-Output 'No listeners on ports 3000-5999. Nothing to kill.'; return }
+$pids = $conns | Select-Object -ExpandProperty OwningProcess -Unique
+foreach ($c in $conns) {
+  $p = Get-Process -Id $c.OwningProcess -ErrorAction SilentlyContinue
+  $name = if ($p) { $p.ProcessName } else { '?' }
+  Write-Output ("port {0,-5} -> pid {1} ({2})" -f $c.LocalPort, $c.OwningProcess, $name)
+}
+foreach ($procId in $pids) {
+  try { Stop-Process -Id $procId -Force -ErrorAction Stop; Write-Output ("killed pid {0}" -f $procId) }
+  catch { Write-Output ("could not kill pid {0}: {1}" -f $procId, $_.Exception.Message) }
+}
+```
+
+Notes:
+- Only TCP **listeners** are targeted, so client/outbound connections in that range are left alone.
+- If `Stop-Process` fails on a PID (e.g. a Windows system process like `svchost`, which needs admin and shouldn't be killed anyway, or a process that already exited), report the `Access is denied` / error and continue with the rest — do not abort the whole run.
+- After running, briefly summarize how many ports were freed.

package/dist/cli-templates/harness-commands/cursor/prototype.md

@@ -0,0 +1,95 @@
+---
+name: prototype
+description: Build an HTML/frontend prototype for the HeySpex Console. Files MUST land in spex-console/public/design-previews/<slug>-v<N>[-<variant>].html with a sibling .meta.json that validates against specs/schemas/prototype-meta.schema.json. Use this any time the user asks to "build a prototype", "mock up a UI", or invokes /frontend-design in this repo.
+---
+
+<!-- Generated by scripts/sync-skills.mjs from .claude/commands/prototype.md — do not edit by hand. Run `npm run skills:sync`. -->
+
+**Usage:** `/prototype <slug> [--from-spec HS-XXXX] [--bump] [--variant <name>]`
+
+This skill is the **implementation** of `specs/protocols/prototype-lifecycle-protocol.md`. The protocol is the SSOT — when they conflict, the protocol wins and this skill is the bug. Fetch it with `heyspex_get_procedure({ name: "prototype-lifecycle-protocol" })` when you need the full rules.
+
+It applies to:
+
+- explicit `/prototype` invocation
+- any natural-language "build me an HTML prototype / mock / preview / canvas" ask
+- `/frontend-design` invocations in this repo (the plugin builds the artifact; this skill governs placement)
+
+## The contract — no exceptions
+
+**Required output paths** (both files, same commit):
+
+1. `spex-console/public/design-previews/<slug>-v<N>[-<variant>].html` — the self-contained prototype.
+2. `spex-console/public/design-previews/<slug>-v<N>[-<variant>].meta.json` — the sidecar.
+
+Anything outside this folder — including a stray top-level `prototypes/` directory — is **invisible** to the console. The route at `spex-console/src/app/api/ui-design/prototypes/route.ts` reads this folder flat (no recursion, no nested folders). A prototype that doesn't show up in the Prototypes surface does not exist for the user.
+
+## Naming
+
+- **`<slug>`** (lineage slug) — kebab-case, describes the surface (`capture-canvas`, `shipped-surface`, `review-inbox`). May contain hyphens. **Match an existing lineage if you're iterating on a known surface** — grep `spex-console/public/design-previews/` before inventing a new slug.
+- **`-v<N>`** — version, starts at `-v1`. **Bump rather than overwrite.** The console groups versions into a lineage with full history. If `--bump`, increment from the highest existing `-v<N>` for that slug.
+- **`-<variant>`** (optional) — sibling variant within a version (e.g. `-v2-alt`, `-v2-minimal`, `-v2-terminal`). May contain hyphens. The console nests variants under their parent version and shows a `+N variants at vK` chip on the lineage card. Variants are for "A/B explorations of the same version", not new lineages.
+- **No `index.html`, no nested folders, no dated filenames.** Just `<slug>-v<N>[-<variant>].html`.
+
+## meta.json schema
+
+Validate against `specs/schemas/prototype-meta.schema.json`. Required: `title` + `status`. Always set `surface_area` and 1–4 `tags` on new sidecars (the console's filter rail depends on them — leaving them empty makes the prototype harder to find).
+
+```json
+{
+  "title": "Human-readable name (e.g. 'Capture canvas v2')",
+  "description": "One-paragraph summary: what it demonstrates, key interactions, aesthetic direction, technical notes. The console hides this on the card and shows it in the drawer Notes tab — write for that context.",
+  "status": "draft",
+  "surface_area": "capture | on-deck | preloader | shell | review | roadmap | other",
+  "tags": ["kebab-case", "1-to-4"],
+  "updated_at": "2026-06-03T18:17:00.000Z",
+  "design_doc": "specs/ui/<slug>-design.md  (optional but required for promotion to accepted)",
+  "linked_specs": [
+    "HS-XXXX-CAP-...",
+    "HS-XXXX-EPIC-..."
+  ],
+  "parent": "<slug>-v<N-1>.html  (optional, when this iterates on a prior version)",
+  "embeds": ["other-prototype-slug  (optional)"]
+}
+```
+
+- **`status` MUST be `"draft"` at create time.** Promotion to `"accepted"` runs through the console's `/api/ui-design/prototypes/<slug>/promote` route and requires both a linked `design_doc` AND a review entry under `specs/reviews/`. The skill does not write `accepted` — refuse if the user asks. (`"archived"` is for superseded versions; usually set later, not at create time.)
+- **Compute `updated_at` as `new Date().toISOString()`** at write time.
+- **`linked_specs`** accepts vault basenames (no `.md` extension) and `HS-*` IDs. Always include the capture/epic/task the prototype embodies. Pull from `--from-spec` if provided. Never invent IDs.
+- Reference siblings in this folder for examples — `shipped-surface-v1.meta.json` (thorough) or `on-deck-v2.meta.json` (minimal).
+
+## Workflow
+
+When this skill is invoked or matched:
+
+1. **Resolve lineage slug.** Match an existing slug if iterating on a known surface; otherwise pick a new kebab-case slug.
+2. **Resolve version.** Default `-v1`. If a file with the same slug already exists, default to bumping to the next integer; honour explicit `--bump`. **Never silently overwrite** — if the target file exists and `--bump` was not passed, surface the conflict and ask.
+3. **Resolve variant.** `--variant <name>` produces `<slug>-v<N>-<name>.html`. Without it, you produce the base variant.
+4. **Pull source spec context.** If `--from-spec HS-XXXX` is passed or the user references a spec, Read it first so the prototype reflects real content, not invented filler.
+5. **Aesthetic.** Defer to the user's brief (e.g. "Claude-in-PowerShell terminal aesthetic" overrides defaults). Otherwise honour console design-system tokens — fetch via `heyspex_design_*` MCP tools, do not grep `spex-console/DESIGN.md`. Recall UI memories first: `heyspex_recall_memories({ tags: ["ui", "console", "design-system"] })`.
+6. **Decide `surface_area` and `tags`.** Pick `surface_area` from the enum based on what the prototype shows. Pick 1–4 lowercase kebab-case `tags` covering the dominant patterns (e.g. `empty-state`, `dark-mode`, `keyboard-nav`).
+7. **Write both files in the same commit.** HTML at `spex-console/public/design-previews/<slug>-v<N>[-<variant>].html`, sidecar at the matching `.meta.json` path. Single self-contained HTML file (inline CSS/JS).
+8. **Validate the sidecar shape** against the schema before saving. Required: `title` + `status`. `status` MUST be `"draft"`. `tags` MUST match `^[a-z0-9-]+$`. `surface_area` MUST be in the enum. `linked_specs[]` items MUST match `^HS-[A-Z0-9]+-` (family keys contain digits, e.g. `HS-9HVY-CAP`). Fix and re-write if any fail.
+9. **Confirm.** After writing, report the gallery URL (`/design-previews/<slug>-v<N>[-<variant>].html`). The console's UI-Design → Prototypes surface picks it up via `/api/ui-design/prototypes` and groups it into the matching lineage automatically.
+
+## Anti-patterns — do not do these
+
+- Do **not** create a new `prototypes/` folder at the repo root.
+- Do **not** nest as `<slug>/index.html`.
+- Do **not** overwrite an existing `<slug>-v<N>[-<variant>].html` — bump or use a new variant.
+- Do **not** ship without a sibling sidecar.
+- Do **not** write `status: "accepted"` from this skill — promotion runs through the console's `/promote` route only.
+- Do **not** invent linked specs. Only reference `HS-*` IDs that exist in the vault.
+- Do **not** leave `surface_area` and `tags` empty on new sidecars — the console's filter rail depends on them.
+- Do **not** Read `spex-console/DESIGN.md` for token lookups; use `heyspex_design_get_token` / `heyspex_design_get_pattern` MCP tools.
+
+## Reference
+
+- **Protocol (SSOT):** `specs/protocols/prototype-lifecycle-protocol.md` — fetch with `heyspex_get_procedure({ name: "prototype-lifecycle-protocol" })`
+- **Schema (SSOT):** `specs/schemas/prototype-meta.schema.json`
+- **Discovery route:** `spex-console/src/app/api/ui-design/prototypes/route.ts`
+- **Surface component:** `spex-console/src/components/surfaces/ui-design-surface.tsx`
+- **Lineage parser:** `spex-console/src/lib/prototype-lineage.ts`
+- **Folder:** `spex-console/public/design-previews/`
+- **Thorough sidecar example:** `shipped-surface-v1.meta.json`
+- **Minimal sidecar example:** `on-deck-v2.meta.json`