heyspex 0.2.6 → 0.2.7

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

@@ -7,67 +7,67 @@ description: Promote whatever doc you hand it to its next stage — a capture (H
 
 **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.
+> **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

@@ -7,32 +7,32 @@ description: Push an epic implementation plan into the HeySpex vault, optionally
 
 **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.
+> **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

@@ -7,24 +7,24 @@ description: Post-plan QC gut-check — stress-test a drafted plan before execut
 
 **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`.)
+> **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

@@ -36,20 +36,32 @@ description: Confidence-ladder research method's entrypoint — SpexCrawl via th
    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) —
+   "<url>" --json`. May run on any self-hosted fleet machine or this machine's own Docker —
    prefer other reachable machines over the one the orchestrating session runs on; check
    `docker info`, start Docker/the stack if needed, poll the real endpoint for readiness before
    use. If this task's changed/claimed files are SpexCrawl-related, skip SpexCrawl entirely and
    go straight to Firecrawl. Hosted `api.firecrawl.dev` credits are unchanged — still
    ask-before-spend every time. Full contract: `.commandcode/skills/hs-res/SKILL.md`.
 
-   **In a repo that uses the `heyspex` npm package** (not a HeySpex platform checkout): the
-   package ships only the SpexCrawl client (`dev-factory/spexcrawl/spexcrawl-cli.mjs` under
-   `node_modules/heyspex/`). It needs the HeySpex Companion, which the npm package does not
-   distribute yet, so it usually exits 3 `SPEXCRAWL_UNAVAILABLE`. The Firecrawl fallback and
-   the DeepSeek synthesis CLI (`firecrawl-cli.mjs`, `synthesize-cli.mjs`) are HeySpex-platform
-   only and are not in the package. When a CLI named in steps 2 or 4 is missing or reports
-   unavailable, stop and tell the user this research method is not available in their install.
+   **In a repo that uses the `heyspex` npm package** (not a HeySpex platform checkout — the
+   CLIs above resolve under `node_modules/heyspex/`; owner ruling 2026-10-17). Prerequisite:
+   Docker Desktop running a self-hosted Firecrawl stack on this machine. No env var and no API
+   key: the Firecrawl CLI finds it by itself (`docker ps`, then localhost:3002). The method is
+   Firecrawl for URLs, SpexCrawl for pages, your own model for the write-up:
+   1. **Find URLs** — `node dev-factory/spexcrawl/firecrawl-cli.mjs search "<query>" --json`
+      per angle.
+   2. **Fetch every URL you will cite** with SpexCrawl:
+      `node dev-factory/spexcrawl/spexcrawl-cli.mjs scrape "<url>" --json`.
+      SpexCrawl needs the HeySpex Companion; when it exits 3
+      `SPEXCRAWL_UNAVAILABLE`, fetch the same URL from the same local Firecrawl:
+      `node dev-factory/spexcrawl/firecrawl-cli.mjs scrape "<url>" --json`.
+   3. **Synthesize yourself** — skip steps 3–4 below (the DeepSeek CLI `synthesize-cli.mjs` is
+      HeySpex-platform only and not in the package). From the fetched pages only, write a
+      cited **Executive Summary** (every claim tagged `[S1]`, `[S2]`, …) and a numbered
+      **Sources** list (title + URL per `[Sn]`).
+   4. **Save** as in step 5, `sources` filled from the fetched URLs.
+   If the Firecrawl CLI exits 3 `FIRECRAWL_UNAVAILABLE`, stop and relay its message to the
+   user (it says to start Docker Desktop and the Firecrawl stack, with the steps).
 
 3. **Assemble a numbered sources block** (`[S1]`, `[S2]`, …) from the gathered
    `{title, url, snippet, markdown}` results, write it plus the question and cite-only

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

@@ -7,20 +7,20 @@ description: Pull the top open item from the HeySpex Resolution lane (conflicts,
 
 **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]].
+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-view.md

@@ -7,26 +7,26 @@ description: Open one console surface in a chromeless app-mode browser window (s
 
 **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 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.
+# 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/cursor/kill-ports.md

@@ -7,29 +7,29 @@ description: Kill every process listening on a TCP port in the range 3000–5999
 
 **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.
+**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.