heyspex 0.2.0 → 0.2.1

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

@@ -1,35 +1,35 @@
----
-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.
-argument-hint: "[<epic name>] [--next] [--reason <focus reason>]"
-allowed-tools: mcp__heyspex__heyspex_push_plan
----
-
-> **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 `/mcp__heyspex__hs-push` / `/mcp__heyspex__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.
+---
+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.
+argument-hint: "[<epic name>] [--next] [--reason <focus reason>]"
+allowed-tools: mcp__heyspex__heyspex_push_plan
+---
+
+> **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 `/mcp__heyspex__hs-push` / `/mcp__heyspex__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/claude/hs-qc.md

@@ -1,27 +1,27 @@
----
-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.
-argument-hint: "[--plan <path>]  (defaults to the most recent plan)"
-allowed-tools: Task, AskQuestion, mcp__heyspex__heyspex_plan_qc, mcp__heyspex__heyspex_ground_plan, mcp__heyspex__heyspex_plan_review, mcp__heyspex__heyspex_recall_memories, Read, Grep, Glob, WebSearch, WebFetch
----
-
-> **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`.)
+---
+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.
+argument-hint: "[--plan <path>]  (defaults to the most recent plan)"
+allowed-tools: Task, AskQuestion, mcp__heyspex__heyspex_plan_qc, mcp__heyspex__heyspex_ground_plan, mcp__heyspex__heyspex_plan_review, mcp__heyspex__heyspex_recall_memories, Read, Grep, Glob, WebSearch, WebFetch
+---
+
+> **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/claude/hs-resolve.md

@@ -1,23 +1,23 @@
----
-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.
-argument-hint: "[HS-XXXX-EPIC | <item-key> | --ignore-focus]"
-allowed-tools: mcp__heyspex__heyspex_next_resolution
----
-
-Invoke the `mcp__heyspex__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]].
+---
+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.
+argument-hint: "[HS-XXXX-EPIC | <item-key> | --ignore-focus]"
+allowed-tools: mcp__heyspex__heyspex_next_resolution
+---
+
+Invoke the `mcp__heyspex__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/claude/hs-review.md

@@ -1,23 +1,23 @@
----
-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).
-argument-hint: "[HS-XXXX-TASK | HS-XXXX-EPIC] [--ignore-focus]"
-allowed-tools: mcp__heyspex__heyspex_next_review
----
-
-Invoke the `mcp__heyspex__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).
+---
+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).
+argument-hint: "[HS-XXXX-TASK | HS-XXXX-EPIC] [--ignore-focus]"
+allowed-tools: mcp__heyspex__heyspex_next_review
+---
+
+Invoke the `mcp__heyspex__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/claude/hs-view.md

@@ -1,26 +1,28 @@
----
-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`.
-argument-hint: "[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.
+---
+description: Open one console surface in a chromeless app-mode browser window (solo console gauge) — the inspector's Pipeline tab first; follows the focus pin when no doc id is given. Thin wrapper over `hs view`.
+argument-hint: "[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 is not a surface slug → it is the doc id, in any form (`hlfj`, `hs-hlfj`, `HS-HLFJ`, a full basename); opens the inspector on its Pipeline tab. Pass it through as typed — the CLI normalises it.
+   - First token is a surface slug (`inspector`, `docs`, `whats-next`, `captures`, `session-log`, `settings`) → second token, if present, is the doc id (anchors `inspector` and `docs` only).
+   - `pipeline` is accepted but is not its own window: it is the inspector on its Pipeline tab.
+   - `docs` opens two panes: the doc beside the inspector on its Pipeline tab.
+   - No arguments → the inspector on its Pipeline tab, 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/claude/kill-ports.md

@@ -1,32 +1,32 @@
----
-description: Kill every process listening on a TCP port in the range 3000–5999 (clears stuck dev servers).
-argument-hint: "(no arguments)"
-allowed-tools: PowerShell
----
-
-**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.
+---
+description: Kill every process listening on a TCP port in the range 3000–5999 (clears stuck dev servers).
+argument-hint: "(no arguments)"
+allowed-tools: PowerShell
+---
+
+**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/claude/prototype.md

@@ -1,91 +1,91 @@
----
-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.
-argument-hint: "<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`
+---
+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.
+argument-hint: "<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`

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

@@ -7,25 +7,25 @@ description: Retroactively backfill completed work into the vault (creates epic
 
 **Usage:** `/hs-backfill <epic name> [<one-line summary>]`
 
-> **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 prompt `/hs-backfill` can carry at most a single token — never a title plus a summary. This **native project command** is the only IDE surface that receives full `$ARGUMENTS`.
-
-## What to do
-
-**1. Parse `$ARGUMENTS`:** leading text up to the first sentence break / newline → `epic_name` (required — ask if missing). Remainder of the string → a `summary` hint; the tool still requires a full plain-language `summary` per spec-summary-authoring, so expand/refine a terse arg using the conversation.
-
-**2. Gather from the conversation and/or `git log`/`git diff`:**
-- `plan_markdown` — what was actually done + which acceptance criteria were met.
-- `children` — each completed task as `{ name, summary }` (summary required per child).
-- `files_changed` — paths touched.
-- `kind` / `effort` / `tags` / `related` — optional classification.
-
-**3. Call** `heyspex_backfill_epic({ epic_name, summary, plan_markdown, children, files_changed, kind?, effort?, tags?, related? })`. All resulting specs land at `status: in_review` with an auto-generated review doc. This is for work done **outside** the normal `/hs-next` flow — never a substitute for it going forward.
-
-**4. Roadmap registration** defaults to `HS-ROADMAP-PRODUCT` phase `P0` (Review column) unless the call passes `skip_roadmap_registration: true`.
-
-**5. Report** the created epic id + task ids, and remind the user this does not commit or push — they still need to do that themselves.
-
-## Hard prohibitions
-
-- **Never** use this for work that hasn't actually happened — it documents DONE work retroactively; `/hs-push` is for planning work not yet started.
-- **Never** commit or push git.
+> **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 prompt `/hs-backfill` can carry at most a single token — never a title plus a summary. This **native project command** is the only IDE surface that receives full `$ARGUMENTS`.
+
+## What to do
+
+**1. Parse `$ARGUMENTS`:** leading text up to the first sentence break / newline → `epic_name` (required — ask if missing). Remainder of the string → a `summary` hint; the tool still requires a full plain-language `summary` per spec-summary-authoring, so expand/refine a terse arg using the conversation.
+
+**2. Gather from the conversation and/or `git log`/`git diff`:**
+- `plan_markdown` — what was actually done + which acceptance criteria were met.
+- `children` — each completed task as `{ name, summary }` (summary required per child).
+- `files_changed` — paths touched.
+- `kind` / `effort` / `tags` / `related` — optional classification.
+
+**3. Call** `heyspex_backfill_epic({ epic_name, summary, plan_markdown, children, files_changed, kind?, effort?, tags?, related? })`. All resulting specs land at `status: in_review` with an auto-generated review doc. This is for work done **outside** the normal `/hs-next` flow — never a substitute for it going forward.
+
+**4. Roadmap registration** defaults to `HS-ROADMAP-PRODUCT` phase `P0` (Review column) unless the call passes `skip_roadmap_registration: true`.
+
+**5. Report** the created epic id + task ids, and remind the user this does not commit or push — they still need to do that themselves.
+
+## Hard prohibitions
+
+- **Never** use this for work that hasn't actually happened — it documents DONE work retroactively; `/hs-push` is for planning work not yet started.
+- **Never** commit or push git.