@opengsd/gsd-core 1.9.0 → 1.10.0

package/gsd-core/workflows/section-manifest.json

@@ -0,0 +1,219 @@
+{
+  "workflows": {
+    "autonomous": [
+      {
+        "id": "converge-fail-fast",
+        "when": "state:plan-strategy-converge",
+        "read": "gsd-core/workflows/autonomous/steps/converge-fail-fast.md"
+      },
+      {
+        "id": "converge-banner",
+        "when": "state:plan-strategy-converge",
+        "read": "gsd-core/workflows/autonomous/steps/converge-banner.md"
+      },
+      {
+        "id": "converge-dispatch-bg",
+        "when": "state:plan-strategy-converge",
+        "read": "gsd-core/workflows/autonomous/steps/converge-dispatch-bg.md"
+      },
+      {
+        "id": "converge-dispatch-inline",
+        "when": "state:plan-strategy-converge",
+        "read": "gsd-core/workflows/autonomous/steps/converge-dispatch-inline.md"
+      },
+      {
+        "id": "converge-loop",
+        "when": "state:plan-strategy-converge",
+        "read": "gsd-core/workflows/autonomous/steps/converge-loop.md"
+      }
+    ],
+    "code-review": [
+      {
+        "id": "structural-pre-pass",
+        "when": "state:fallow-enabled",
+        "read": "gsd-core/workflows/code-review/steps/structural-pre-pass.md"
+      },
+      {
+        "id": "dispatch-fix",
+        "when": "flag:--fix",
+        "read": "gsd-core/workflows/code-review/steps/dispatch-fix.md"
+      }
+    ],
+    "complete-milestone": [
+      {
+        "id": "git-tag",
+        "when": "state:git-create-tag",
+        "read": "gsd-core/workflows/complete-milestone/steps/git-tag.md"
+      }
+    ],
+    "discuss-phase-assumptions": [
+      {
+        "id": "auto-advance-dispatch",
+        "when": "state:auto-advance-active",
+        "read": "gsd-core/workflows/discuss-phase-assumptions/steps/auto-advance-dispatch.md"
+      }
+    ],
+    "docs-update": [
+      {
+        "id": "dispatch-monorepo-packages",
+        "when": "state:is-monorepo",
+        "read": "gsd-core/workflows/docs-update/steps/dispatch-monorepo-packages.md"
+      }
+    ],
+    "execute-phase": [
+      {
+        "id": "partial-wave",
+        "when": "flag:--wave",
+        "read": "gsd-core/workflows/execute-phase/steps/partial-wave.md"
+      },
+      {
+        "id": "gap-closure-artifacts",
+        "when": "state:gap-closure-phase",
+        "read": "gsd-core/workflows/execute-phase/steps/gap-closure-artifacts.md"
+      },
+      {
+        "id": "regression-gate",
+        "when": "state:has-prior-phases",
+        "read": "gsd-core/workflows/execute-phase/steps/regression-gate.md"
+      }
+    ],
+    "new-milestone": [
+      {
+        "id": "project-md-milestone-write",
+        "when": "state:flat-mode",
+        "read": "gsd-core/workflows/new-milestone/steps/project-md-milestone-write.md"
+      },
+      {
+        "id": "reset-phase-safety",
+        "when": "flag:--reset-phase-numbers",
+        "read": "gsd-core/workflows/new-milestone/steps/reset-phase-safety.md"
+      }
+    ],
+    "new-project": [
+      {
+        "id": "auto-mode-detection",
+        "when": "flag:--auto",
+        "read": "gsd-core/workflows/new-project/steps/auto-mode-detection.md"
+      },
+      {
+        "id": "codebase-map-offer",
+        "when": "state:needs-codebase-map",
+        "read": "gsd-core/workflows/new-project/steps/codebase-map-offer.md"
+      },
+      {
+        "id": "auto-mode-config",
+        "when": "flag:--auto",
+        "read": "gsd-core/workflows/new-project/steps/auto-mode-config.md"
+      }
+    ],
+    "plan-phase": [
+      {
+        "id": "reviews-prerequisite",
+        "when": "flag:--reviews",
+        "read": "gsd-core/workflows/plan-phase/steps/reviews-prerequisite.md"
+      },
+      {
+        "id": "prd-express-gate",
+        "when": "flag:--prd",
+        "read": "gsd-core/workflows/plan-phase/steps/prd-express-gate.md"
+      },
+      {
+        "id": "adr-ingest-express-path",
+        "when": "flag:--ingest",
+        "read": "gsd-core/workflows/plan-phase/steps/adr-ingest-express-path.md"
+      },
+      {
+        "id": "research-only-modifiers",
+        "when": "flag:--research-phase",
+        "read": "gsd-core/workflows/plan-phase/steps/research-only-modifiers.md"
+      },
+      {
+        "id": "research-only-early-exit",
+        "when": "flag:--research-phase",
+        "read": "gsd-core/workflows/plan-phase/steps/research-only-early-exit.md"
+      },
+      {
+        "id": "chunked-planning-mode",
+        "when": "state:chunked-mode",
+        "read": "gsd-core/workflows/plan-phase/steps/chunked-planning-mode.md"
+      }
+    ],
+    "progress": [
+      {
+        "id": "mvp-display",
+        "when": "state:phase-mvp-mode",
+        "read": "gsd-core/workflows/progress/steps/mvp-display.md"
+      },
+      {
+        "id": "forensic-audit",
+        "when": "flag:--forensic",
+        "read": "gsd-core/workflows/progress/steps/forensic-audit.md"
+      }
+    ],
+    "quick": [
+      {
+        "id": "discussion-phase",
+        "when": "flag:--discuss",
+        "read": "gsd-core/workflows/quick/steps/discussion-phase.md"
+      },
+      {
+        "id": "research-phase",
+        "when": "flag:--research",
+        "read": "gsd-core/workflows/quick/steps/research-phase.md"
+      },
+      {
+        "id": "plan-checker-loop",
+        "when": "flag:--validate",
+        "read": "gsd-core/workflows/quick/steps/plan-checker-loop.md"
+      },
+      {
+        "id": "worktree-pre-dispatch-commit",
+        "when": "state:worktrees-enabled",
+        "read": "gsd-core/workflows/quick/steps/worktree-pre-dispatch-commit.md"
+      },
+      {
+        "id": "quick-verification",
+        "when": "flag:--validate",
+        "read": "gsd-core/workflows/quick/steps/quick-verification.md"
+      }
+    ],
+    "review": [
+      {
+        "id": "reviewer-instances-note-1",
+        "when": "state:reviewer-instances-configured",
+        "read": "gsd-core/workflows/review/steps/reviewer-instances-note-1.md"
+      },
+      {
+        "id": "reviewer-instances-note-2",
+        "when": "state:reviewer-instances-configured",
+        "read": "gsd-core/workflows/review/steps/reviewer-instances-note-2.md"
+      }
+    ],
+    "transition": [
+      {
+        "id": "workstream-collision-check",
+        "when": "state:workstream-active",
+        "read": "gsd-core/workflows/transition/steps/workstream-collision-check.md"
+      }
+    ],
+    "update": [
+      {
+        "id": "channel-banner",
+        "when": "state:next-channel",
+        "read": "gsd-core/workflows/update/steps/channel-banner.md"
+      }
+    ],
+    "verify-work": [
+      {
+        "id": "automated-ui-verification",
+        "when": "state:ui-phase-active",
+        "read": "gsd-core/workflows/verify-work/steps/automated-ui-verification.md"
+      },
+      {
+        "id": "mvp-uat-framing",
+        "when": "state:phase-mvp-mode",
+        "read": "gsd-core/workflows/verify-work/steps/mvp-uat-framing.md"
+      }
+    ]
+  }
+}

package/gsd-core/workflows/sketch.md

@@ -134,7 +134,7 @@ If spikes exist for this project, read them to ground the sketches in reality. M
 
 **a.** Glob for `./.claude/skills/spike-findings-*/SKILL.md` and read any that exist, plus their `references/*.md`. These contain validated patterns and requirements.
 
-**b.** Read `.planning/spikes/MANIFEST.md` if it exists — check the Requirements section for non-negotiable design constraints (e.g., "must support streaming", "must render markdown"). These requirements should be visible in the mockup even though the mockup doesn't implement them for real.
+**b.** Read `.planning/spikes/MANIFEST.md` if it exists — it may hold separate `### {idea-key}` sections for several unrelated ideas. Check the Requirements list of the idea key relevant to this sketch's design direction (or all of them if none clearly matches) for non-negotiable design constraints (e.g., "must support streaming", "must render markdown"). These requirements should be visible in the mockup even though the mockup doesn't implement them for real.
 
 **c.** Read `.planning/spikes/CONVENTIONS.md` if it exists — the established stack informs what's buildable and what interaction patterns are idiomatic.
 

package/gsd-core/workflows/spec-phase.md

@@ -126,7 +126,7 @@ Acceptance Criteria:[score 0.0–1.0]
 Ambiguity: [score] ([calculate])
 ```
 
-**If `--auto` and initial ambiguity already ≤ 0.20 with all minimums met:** Skip interview — derive SPEC.md directly from roadmap + requirements. Log: `[auto] Phase requirements are already sufficiently clear — generating SPEC.md from existing context.` Jump to Step 6.
+**If `--auto` and initial ambiguity already ≤ 0.20 with all minimums met:** Skip interview — derive SPEC.md directly from roadmap + requirements. Log: `[auto] Phase requirements are already sufficiently clear — generating SPEC.md from existing context.` Jump to Step 5.5.
 
 **Otherwise:** Continue to Step 4.
 
@@ -159,15 +159,15 @@ After round [N]:
 
 If gate passes (ambiguity ≤ 0.20 AND all minimums met):
 
-**If `--auto`:** Jump to Step 6.
+**If `--auto`:** Jump to Step 5.5.
 
 **Otherwise:** AskUserQuestion:
 - header: "Spec Gate Passed"
 - question: "Ambiguity is [score] — requirements are clear enough to write SPEC.md. Proceed?"
 - options:
-  - "Yes — write SPEC.md" → Jump to Step 6
+  - "Yes — write SPEC.md" → Jump to Step 5.5
   - "One more round" → Continue interview
-  - "Done talking — write it" → Jump to Step 6
+  - "Done talking — write it" → Jump to Step 5.5
 
 **If max rounds reached (6) and gate not passed:**
 
@@ -251,7 +251,8 @@ if ! node -e 'const a=require(process.argv[1]);if(!Array.isArray(a)||a.length===
   exit 1
 fi
 # Invoke the compiled engine and CAPTURE its report — it computes which categories apply per
-# requirement. The covered/backstop/dismissed/unresolved rows in $COVERAGE drive the
+# requirement. The resolved/dismissed/unresolved rows in $COVERAGE (resolved items carry
+# verification: explicit|backstop) drive the
 # resolution loop below (canonical taxonomy compute, NOT LLM re-derivation from prose).
 # The engine FAILS CLOSED (exit 2) on an invalid authored shape or bad input — so the capture
 # MUST be exit-checked. A bare `COVERAGE=$(node …)` swallows that exit code, leaves $COVERAGE
@@ -288,21 +289,22 @@ an empty `## Edge Coverage` section after explicit confirmation.
 For each Requirement gathered so far:
 1. Classify its shape and raise only applicable edge categories (relevance filter — see
    the taxonomy in the reference). Reuse any edges the Round-4 Failure Analyst already
-   surfaced as pre-`covered`.
+   surfaced as pre-resolved.
 2. For each raised category, propose a CONCRETE candidate edge (not "consider
    boundaries" — e.g. "R2 merges intervals; what about `[[1,2],[2,3]]` that only touch?").
 3. Resolve each with the user (AskUserQuestion; text mode → numbered list):
    - **Specify it** → write a new pass/fail line into Acceptance Criteria AND mark the
-     edge `covered`.
+     edge `resolved` with `verification: explicit`.
    - **Dismiss (reason)** → mark `dismissed` with a required non-empty reason.
-   - **Backstop with a test** → mark `backstop`; note "held-out edge test" for plan-phase.
+   - **Backstop with a test** → mark `resolved` with `verification: backstop`; note
+     "held-out edge test" for plan-phase.
    - **Defer** → leave `unresolved`.
    - An `unclassified` row (probe `unclassified — review manually`) means the requirement's
      prose matched no shape cue (#1110) — treat it like any other candidate (**Specify**,
      **Dismiss (reason)**, or **Defer**). A manual-review nudge, not a hard block.
 
 **Soft gate (after resolving):**
-- All applicable edges resolved → proceed to Step 6.
+- All applicable edges resolved → proceed to Step 5.6.
 - Any `unresolved` → AskUserQuestion:
   - header: "Edge Coverage"
   - question: "[N] edge(s) are unresolved: [list]. What do you want to do?"
@@ -311,13 +313,14 @@ For each Requirement gathered so far:
   - On "anyway": write SPEC.md with those rows marked `⚠ Edge unresolved — planner must
     treat as assumption`.
 
-**`--auto` mode:** auto-`covered` where a defensible acceptance criterion can be written;
-otherwise auto-`backstop` (never auto-dismiss — a wrong dismissal is the exact silent
-failure being eliminated). Log: `[auto] edge coverage: C covered, B backstop, U unresolved`.
+**`--auto` mode:** auto-`resolved` (verification: explicit) where a defensible acceptance
+criterion can be written; otherwise auto-`resolved` (verification: backstop) (never
+auto-dismiss — a wrong dismissal is the exact silent failure being eliminated). Log:
+`[auto] edge coverage: E explicit, B backstop, U unresolved`.
 
 **`unclassified` exception (#1110):** `--auto` leaves an `unclassified` candidate
 **`unresolved`** (the soft gate surfaces it as a flagged planner assumption) — it never
-auto-`backstop`s it. A missing shape is not evidence an edge exists, so minting a held-out
+auto-resolves it with `verification: backstop`. A missing shape is not evidence an edge exists, so minting a held-out
 edge obligation on a requirement that may be genuinely edge-free would be a false claim and
 risks a vacuous edge test. Leaving it `unresolved` keeps the zero-cue requirement visible
 (never a silent drop) without fabricating an edge — which is exactly #1110's purpose: surface
@@ -425,7 +428,7 @@ downstream rather than blocking authoring.
 
 Use the SPEC.md template from @~/.claude/gsd-core/templates/spec.md.
 
-- Populate the **Edge Coverage** section from Step 5.5 (covered/dismissed/backstop/unresolved rows).
+- Populate the **Edge Coverage** section from Step 5.5 (resolved/dismissed/unresolved rows; resolved items carry `verification: explicit|backstop`).
 - Populate the **Prohibitions** section from Step 5.6 (resolved/dismissed/unresolved rows with the test|judgment tier).
 
 **Requirements for every requirement entry:**

package/gsd-core/workflows/spike-wrap-up.md

@@ -22,8 +22,12 @@ Read all files referenced by the invoking prompt's execution_context before star
 <step name="gather">
 ## Gather Spike Inventory
 
-1. Read `.planning/spikes/MANIFEST.md` for the overall idea context and requirements
-2. Glob `.planning/spikes/*/README.md` and parse YAML frontmatter from each
+1. Read `.planning/spikes/MANIFEST.md` for the `## Ideas` sections (each idea's paragraph and
+   its own scoped Requirements list) and the `## Spikes` table (its Idea column tells you which
+   idea key each spike row belongs to).
+2. Glob `.planning/spikes/*/README.md` and parse YAML frontmatter from each — each spike's
+   `idea:` field is the idea key that owns it. If a README predates #1700 and has no `idea:`
+   field, resolve its idea key from the matching `## Spikes` table row's Idea column instead.
 3. Check if `./.claude/skills/spike-findings-*/SKILL.md` exists for this project
    - If yes: read its `processed_spikes` list from the metadata section and filter those out
    - If no: all spikes are candidates
@@ -101,7 +105,12 @@ For each feature-area group, write a reference file at `references/[feature-area
 
 ## Requirements
 
-[Non-negotiable design decisions from MANIFEST.md Requirements section that apply to this feature area. These MUST be honored in the real build. E.g., "Must use streaming JSON output", "Must support reconnection".]
+[Non-negotiable design decisions pulled ONLY from the Requirements list of the idea key(s) that
+own the spikes in this feature-area group — match each spike's `idea:` frontmatter (or Idea
+column) to its `### {idea-key}` Requirements list in MANIFEST.md. These MUST be honored in the
+real build. E.g., "Must use streaming JSON output", "Must support reconnection".
+
+Never include a requirement from an idea key that has no spike in this group.]
 
 ## How to Build It
 
@@ -136,7 +145,8 @@ description: Implementation blueprint from spike experiments. Requirements, prov
 <context>
 ## Project: [project-dir-name]
 
-[One paragraph from MANIFEST.md describing the overall idea]
+[One paragraph per idea key represented among the wrapped spikes, taken from that idea's
+`### {idea-key}` section in MANIFEST.md — not the whole MANIFEST.md if it holds unrelated ideas.]
 
 Spike sessions wrapped: [date(s)]
 </context>
@@ -144,7 +154,11 @@ Spike sessions wrapped: [date(s)]
 <requirements>
 ## Requirements
 
-[Copied directly from MANIFEST.md Requirements section. These are non-negotiable design decisions that emerged from the user's choices during spiking. Every feature area reference must honor these.]
+[Union of the Requirements lists for every idea key represented among the spikes being wrapped
+in this session — never the whole MANIFEST.md. These are non-negotiable design decisions that
+emerged from the user's choices while spiking those specific idea(s). Every feature area
+reference must honor these. If this wrap-up spans more than one idea key, group the list by
+idea key so a future reader can tell which requirement belongs to which idea.]
 
 - [requirement 1]
 - [requirement 2]
@@ -299,6 +313,7 @@ After the summary, present next-step options:
 - [ ] Spikes grouped by feature area
 - [ ] Spike-findings skill exists at `./.claude/skills/` with SKILL.md (including requirements), references/, sources/
 - [ ] Reference files are implementation blueprints with Requirements, How to Build It, What to Avoid, Constraints
+- [ ] Requirements in each reference file and in SKILL.md are scoped to the idea key(s) actually represented among the wrapped spikes — never blended with an unrelated idea's requirements
 - [ ] `.planning/spikes/CONVENTIONS.md` created or updated with recurring stack/structure/pattern choices
 - [ ] `.planning/spikes/WRAP-UP-SUMMARY.md` written for project history
 - [ ] Project CLAUDE.md has auto-load routing line

package/gsd-core/workflows/spike.md

@@ -53,7 +53,8 @@ If no `.planning/spikes/` directory exists, tell the user there's nothing to ana
 
 Otherwise, load in this order:
 
-**a. MANIFEST.md** — the overall idea, requirements, and spike table with verdicts.
+**a. MANIFEST.md** — every idea section under `## Ideas` (each idea's paragraph and its own
+scoped Requirements) and the `## Spikes` table with verdicts (each row tagged by idea).
 
 **b. Findings skills** — glob `./.claude/skills/spike-findings-*/SKILL.md` and read any that exist, plus their `references/*.md`. These contain curated knowledge from prior wrap-ups.
 
@@ -74,7 +75,8 @@ If integration risks exist, present them as concrete proposed spikes with names
 
 ### Analyze for Frontier Spikes
 
-Think laterally about the overall idea from MANIFEST.md and what's been proven so far. Consider:
+Think laterally about every idea section from MANIFEST.md and what's been proven so far for
+each. Consider:
 
 - **Gaps in the vision:** Capabilities assumed but unproven.
 - **Discovered dependencies:** Findings that reveal new questions.
@@ -86,7 +88,7 @@ Present frontier spikes as concrete proposals numbered from the highest existing
 
 ### Get Alignment and Execute
 
-Present all integration and frontier candidates, then ask which to run. When the user picks spikes, write definitions into `.planning/spikes/MANIFEST.md` (appending to existing table) and proceed directly to building them starting at `research`.
+Present all integration and frontier candidates, then ask which to run. When the user picks spikes, write definitions into `.planning/spikes/MANIFEST.md` (appending to the existing table, with each row's Idea column set to the idea key(s) it extends or validates) and proceed directly to building them starting at `research`.
 </step>
 
 <step name="setup_directory">
@@ -212,33 +214,63 @@ If 2+ credible approaches exist, plan to build quick variants within the spike a
 </step>
 
 <step name="create_manifest">
-Create or update `.planning/spikes/MANIFEST.md`:
+Create or update `.planning/spikes/MANIFEST.md`.
+
+**Assign an idea key.** Derive a short, stable, kebab-case slug (2-4 words) summarizing the
+idea being spiked right now, e.g. `realtime-llm-streaming`. Reuse the exact same idea key for
+every spike in this session and any later session that continues the same idea. Only mint a
+new idea key when the current idea is not a continuation of one already indexed in
+MANIFEST.md — never reuse an existing idea key for an unrelated idea, and never merge two
+different ideas under one key.
+
+If `.planning/spikes/MANIFEST.md` doesn't exist, create it:
 
 ```markdown
 # Spike Manifest
 
-## Idea
-[One paragraph describing the overall idea being explored]
+## Ideas
+
+### {idea-key}
+[One paragraph describing this idea]
 
-## Requirements
-[Design decisions that emerged from the user's choices during spiking. Non-negotiable for the real build. Updated as spikes progress.]
+**Requirements:**
+[Design decisions that emerged from the user's choices while spiking THIS idea. Non-negotiable
+for the real build of this idea. Updated as spikes progress. Never copy or merge requirements
+from a different idea key into this list.]
 
 - [e.g., "Must use streaming JSON output, not single-response"]
 - [e.g., "Must support reconnection on network failure"]
 
 ## Spikes
 
-| # | Name | Type | Validates | Verdict | Tags |
-|---|------|------|-----------|---------|------|
+| # | Idea | Name | Type | Validates | Verdict | Tags |
+|---|------|------|------|-----------|---------|------|
 ```
 
-**Track requirements as they emerge.** When the user expresses a preference during spiking, add it to the Requirements section immediately.
+If `.planning/spikes/MANIFEST.md` already exists:
+
+- **Same idea key already has a `### {idea-key}` section under `## Ideas`:** append to that
+  section's Requirements list as new requirements emerge. Never overwrite or rewrite its
+  `## Idea` paragraph.
+- **New idea key, not yet present:** append a new `### {idea-key}` subsection under `## Ideas`,
+  after any existing idea sections. Never touch, merge into, or delete another idea's section.
+- **A pre-#1700 MANIFEST.md with the old flat shape** (a single top-level `## Idea` / `##
+  Requirements` pair, no `## Ideas` heading): treat its existing content as one implicit idea.
+  Derive an idea key from its `## Idea` paragraph, migrate it in place to `## Ideas` >
+  `### {idea-key}` — preserving the paragraph and every existing Requirements bullet and
+  Spikes row verbatim — then continue as above. Do this migration once; do not repeat it once
+  `## Ideas` exists.
+
+Every row appended to `## Spikes` carries an **Idea** column set to the idea key it belongs to.
+
+**Track requirements as they emerge.** When the user expresses a preference during spiking, add
+it to the current idea's Requirements list immediately — never to a different idea's list.
 </step>
 
 <step name="reground">
 ## Re-Ground Before Each Spike
 
-Before starting each spike (not just the first), re-read `.planning/spikes/MANIFEST.md` and `.planning/spikes/CONVENTIONS.md` to prevent drift within long sessions. Check the Requirements section — make sure the spike doesn't contradict any established requirements.
+Before starting each spike (not just the first), re-read `.planning/spikes/MANIFEST.md` and `.planning/spikes/CONVENTIONS.md` to prevent drift within long sessions. Check the current idea's `### {idea-key}` Requirements list — make sure the spike doesn't contradict any established requirement for this idea. Do not apply another idea's requirements.
 </step>
 
 <step name="build_spikes">
@@ -287,6 +319,7 @@ Multiple files per spike are expected for complex questions (e.g., `test-basic.j
 ```markdown
 ---
 spike: NNN
+idea: {idea-key}
 name: descriptive-name
 type: standard
 validates: "Given [precondition], when [action], then [expected outcome]"
@@ -337,7 +370,8 @@ tags: [tag1, tag2]
 → Does this match what you expected? Describe what you see.
 ──────────────────────────────────────────────────────────────
 
-**h.** Update `.planning/spikes/MANIFEST.md` with the spike's row.
+**h.** Update `.planning/spikes/MANIFEST.md` with the spike's row, setting the Idea column to
+this spike's idea key.
 
 **i.** Commit (if `COMMIT_DOCS` is true):
 ```bash
@@ -450,10 +484,10 @@ gsd_run query commit "docs(spikes): update conventions" --files .planning/spikes
 - [ ] Depth over speed — edge cases tested, surprising findings followed, investigation trail documented
 - [ ] Comparison spikes built back-to-back with head-to-head verdict
 - [ ] Spikes needing human interaction have forensic log layer
-- [ ] Requirements tracked in MANIFEST.md as they emerge from user choices
+- [ ] Requirements tracked in MANIFEST.md, scoped to the idea key that produced them, as they emerge from user choices
 - [ ] CONVENTIONS.md created or updated with patterns that emerged
-- [ ] Each spike README has complete frontmatter, Investigation Trail, and Results
-- [ ] MANIFEST.md is current (with Type column and Requirements section)
+- [ ] Each spike README has complete frontmatter (including its idea key), Investigation Trail, and Results
+- [ ] MANIFEST.md is current (with Idea and Type columns, and each idea's own scoped Requirements section)
 - [ ] Commits use `docs(spike-NNN): [VERDICT]` format
 - [ ] Consolidated report presented with next-step routing
 </success_criteria>

package/gsd-core/workflows/sync-skills.md

@@ -17,7 +17,7 @@ Sync managed `gsd-*` skill directories from one canonical runtime's skills root
 
 If neither `--dry-run` nor `--apply` is specified, dry-run is the default.
 
-**Supported runtime names:** `claude`, `codex`, `grok`, `copilot`, `cursor`, `windsurf`, `opencode`, `gemini`, `kilo`, `augment`, `trae`, `qwen`, `codebuddy`, `cline`, `antigravity` (grok uses the `~/.agents` layout)
+**Supported runtime names:** `antigravity`, `augment`, `claude`, `cline`, `codebuddy`, `codex`, `copilot`, `cursor`, `grok`, `hermes`, `kilo`, `kimi`, `kimi-code`, `opencode`, `pi`, `qwen`, `trae`, `windsurf`, `zcode` — the full capability registry runtime set (`gsd-core/bin/lib/capability-registry.cjs`'s `runtimes`) plus `grok` (a live, dedicated `~/.agents`-layout resolution branch in `getGlobalConfigDir` predating the capability registry — overridable via `GROK_AGENTS_HOME`), excluding `vscode`: it is `installSurface: 'none'` (#2103) and `getGlobalSkillsBase('vscode')` returns `null`, so a skills-root sync to/from it always aborts at Step 2's resolution guard — there is nowhere on disk to sync to.
 
 ---
 
@@ -35,7 +35,7 @@ fi
 
 # Parse --to
 if [[ "$@" == *"--to all"* ]]; then
-  TO_RUNTIMES=(claude codex grok copilot cursor windsurf opencode gemini kilo augment trae qwen codebuddy cline antigravity)
+  TO_RUNTIMES=(antigravity augment claude cline codebuddy codex copilot cursor grok hermes kilo kimi kimi-code opencode pi qwen trae windsurf zcode)
 elif [[ "$@" == *"--to"* ]]; then
   TO_RUNTIMES=( $(echo "$@" | grep -oP '(?<=--to )\S+') )
 fi
@@ -55,29 +55,43 @@ fi
 
 ## Step 2: Resolve Skills Roots
 
-Use `install.js --skills-root` to resolve paths — this reuses the single authoritative path table rather than duplicating it:
+Resolve paths via `gsd_run query skills-root` — this reuses the single authoritative path table via the shipped `gsd-tools` binary (#3024: the installer entry point is not shipped in installed trees, but `gsd-tools` is):
 
 ```bash
-INSTALL_JS="$(dirname "$0")/../gsd-core/bin/install.js"
-# If running from a global install, resolve relative to the GSD package
-INSTALL_JS_GLOBAL="$HOME/.claude/gsd-core/bin/install.js"
-[[ ! -f "$INSTALL_JS" ]] && INSTALL_JS="$INSTALL_JS_GLOBAL"
-
-SRC_SKILLS_ROOT=$(node "$INSTALL_JS" --skills-root "$FROM_RUNTIME")
+_GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-parse --show-toplevel 2>/dev/null || pwd)}"; GSD_TOOLS="${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}"; if [ -f "$GSD_TOOLS" ]; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif command -v gsd-tools >/dev/null 2>&1; then GSD_TOOLS="$(command -v gsd-tools)"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif [ -f "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; elif [ -f "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}" ]; then GSD_TOOLS="${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd-tools is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; if [ -n "${CLAUDE_ENV_FILE:-}" ] && [ -n "${GSD_TOOLS:-}" ]; then printf "export PATH='%s':\"\$PATH\"\n" "${GSD_TOOLS%/*}" >> "$CLAUDE_ENV_FILE" 2>/dev/null || true; fi
+SRC_SKILLS_ROOT=$(gsd_run query skills-root "$FROM_RUNTIME" --raw)
+if [ $? -ne 0 ] || [ -z "$SRC_SKILLS_ROOT" ]; then
+  echo "error: failed to resolve skills root for runtime '$FROM_RUNTIME' (gsd_run query skills-root $FROM_RUNTIME --raw)" >&2
+  exit 1
+fi
 
 for DEST_RUNTIME in "${TO_RUNTIMES[@]}"; do
-  DEST_SKILLS_ROOTS["$DEST_RUNTIME"]=$(node "$INSTALL_JS" --skills-root "$DEST_RUNTIME")
+  RESOLVED_DEST_ROOT=$(gsd_run query skills-root "$DEST_RUNTIME" --raw)
+  if [ $? -ne 0 ] || [ -z "$RESOLVED_DEST_ROOT" ]; then
+    echo "error: failed to resolve skills root for runtime '$DEST_RUNTIME' (gsd_run query skills-root $DEST_RUNTIME --raw)" >&2
+    exit 1
+  fi
 done
 ```
 
+This loop validates every destination in `TO_RUNTIMES` up front — a bad runtime id anywhere in a multi-destination `--to` aborts here, before Step 3 or Step 5 touch anything. The resolved value itself is not retained: each of Steps 3 and 5 re-resolves `DEST_ROOT` for the specific `$DEST_RUNTIME` it is currently processing (see those steps), so `$DEST_ROOT` is always unambiguously scoped to one destination and never threaded through a shared array.
+
 **Guard:** If the source skills root does not exist, print:
 ```
 error: source skills root not found: <path>
        Is GSD installed globally for the '<runtime>' runtime?
-       Run: node ~/.claude/gsd-core/bin/install.js --global --<runtime>
+       Run: npx -y @opengsd/gsd-core@latest --global --<runtime>
 ```
 Then exit.
 
+**Guard:** If resolving the skills root for the source OR any destination runtime fails (`gsd_run query skills-root <runtime> --raw` exits non-zero or prints nothing — see Step 2's bash), print:
+```
+error: failed to resolve skills root for runtime '<runtime>'
+       command: gsd_run query skills-root <runtime> --raw
+       Is '<runtime>' a registered runtime id? See supported runtime names above.
+```
+Then exit. Never proceed to Step 3 or Step 5 with an empty or unresolved root — an empty `$DEST_ROOT` turns `rm -rf "$DEST_ROOT/$SKILL"` into `rm -rf "/$SKILL"`.
+
 **Guard:** If `--to` contains the same runtime as `--from`, skip that destination silently.
 
 ---
@@ -87,6 +101,16 @@ Then exit.
 For each destination runtime:
 
 ```bash
+# Bind the destination root for this iteration's destination runtime. Already
+# validated to resolve successfully in Step 2's eager-validation loop;
+# re-resolving here (rather than reading back a shared array) keeps this
+# value unambiguously scoped to the destination currently being processed.
+DEST_ROOT=$(gsd_run query skills-root "$DEST_RUNTIME" --raw)
+if [ $? -ne 0 ] || [ -z "$DEST_ROOT" ]; then
+  echo "error: failed to resolve skills root for runtime '$DEST_RUNTIME' (gsd_run query skills-root $DEST_RUNTIME --raw)" >&2
+  exit 1
+fi
+
 # List gsd-* subdirectories in source
 SRC_SKILLS=$(ls -1 "$SRC_SKILLS_ROOT" 2>/dev/null | grep '^gsd-')
 
@@ -142,8 +166,22 @@ If `--dry-run` (or no flag): skip this step entirely and exit after printing the
 For each destination with changes:
 
 ```bash
+# Bind DEST_ROOT for this iteration's destination (see Step 3's identical
+# re-resolution note — Step 2 already validated this resolves successfully).
+DEST_ROOT=$(gsd_run query skills-root "$DEST_RUNTIME" --raw)
+
+[[ "$SRC_SKILLS_ROOT" == /* ]] || { echo "error: SRC_SKILLS_ROOT is empty or not absolute: '$SRC_SKILLS_ROOT'" >&2; exit 1; }
+[[ "$DEST_ROOT" == /* ]] || { echo "error: DEST_ROOT is empty or not absolute: '$DEST_ROOT'" >&2; exit 1; }
+
 mkdir -p "$DEST_ROOT"
 
+# #3025: verbatim cp -r copies the SOURCE runtime's converted skill form, which
+# corrupts skills for destinations that need a different conversion (e.g. Claude
+# SKILL.md → Codex TOML agent). Until the installer exposes a per-skill conversion
+# CLI, sync is limited to runtime pairs that share the same skill format.
+# Run `gsd install --<dest-runtime> --local` to get correctly converted skills
+# for a destination that uses a different format.
+
 for SKILL in $CREATE_LIST $UPDATE_LIST; do
   rm -rf "$DEST_ROOT/$SKILL"
   cp -r "$SRC_SKILLS_ROOT/$SKILL" "$DEST_ROOT/$SKILL"