@opengsd/gsd-core 1.8.0 → 1.9.0

package/gsd-core/bin/shared/config-defaults.manifest.json

@@ -33,6 +33,7 @@
     "_auto_chain_active": false,
     "node_repair": true,
     "node_repair_budget": 2,
+    "smart_zone_tokens": 100000,
     "ui_phase": true,
     "ui_safety_gate": true,
     "text_mode": false,

package/gsd-core/bin/shared/config-schema.manifest.json

@@ -19,6 +19,7 @@
     "workflow.auto_advance",
     "workflow.node_repair",
     "workflow.node_repair_budget",
+    "workflow.smart_zone_tokens",
     "workflow.human_verify_mode",
     "workflow.text_mode",
     "workflow.research_before_questions",
@@ -48,9 +49,6 @@
     "planning.commit_docs",
     "planning.search_gitignored",
     "planning.sub_repos",
-    "review.ollama_host",
-    "review.lm_studio_host",
-    "review.llama_cpp_host",
     "review.default_reviewers",
     "review.max_prompt_tokens",
     "review.max_prompt_tokens_per_reviewer",
@@ -117,11 +115,6 @@
       "source": "^agent_skills\\.[a-zA-Z0-9_-]+$",
       "description": "agent_skills.<agent-type>"
     },
-    {
-      "topLevel": "review",
-      "source": "^review\\.models\\.[a-zA-Z0-9_-]+$",
-      "description": "review.models.<cli-name>"
-    },
     {
       "topLevel": "features",
       "source": "^features\\.[a-zA-Z0-9_]+$",
@@ -177,11 +170,6 @@
       "source": "^fast_mode\\.agent_overrides\\.[a-zA-Z0-9_-]+$",
       "description": "fast_mode.agent_overrides.<agent-id>"
     },
-    {
-      "topLevel": "review",
-      "source": "^review\\.max_prompt_tokens_per_reviewer\\.[a-zA-Z0-9_-]+$",
-      "description": "review.max_prompt_tokens_per_reviewer.<reviewer-slug>"
-    },
     {
       "topLevel": "review",
       "source": "^review\\.reviewer_instances\\.[a-zA-Z0-9_-]+\\.(cli|model|agent)$",

package/gsd-core/bin/shared/model-catalog.json

@@ -52,6 +52,11 @@
       "sonnet": null,
       "haiku": null
     },
+    "kimi-code": {
+      "opus": null,
+      "sonnet": null,
+      "haiku": null
+    },
     "cursor": {
       "opus": null,
       "sonnet": null,

package/gsd-core/bin/shared/runtime-aliases.manifest.json

@@ -63,6 +63,11 @@
   "kimi": [
     "kimi"
   ],
+  "kimi-code": [
+    "kimi-code",
+    "kimicode",
+    "kimi_code"
+  ],
   "codebuddy": [
     "codebuddy",
     "codebuddy-cli"

package/gsd-core/references/context-budget.md

@@ -83,3 +83,43 @@ Either list works — `enabledMcpjsonServers` is an explicit allow-list, `disabl
 ### Composition with model_profile
 
 Trimming MCPs and tuning `model_profile` are independent levers that **compound**. Disabling a 25k-token MCP saves 25k per turn whether you're running `quality` (opus everywhere) or `budget` (sonnet/haiku); the savings are additive, not in lieu of model tuning. Don't pick one — do both, and audit MCPs first because the per-turn savings show up immediately and stack across every subagent the orchestrator spawns.
+
+---
+
+# Phase Sizing (gsd-planner)
+
+## Estimate Emission (#2631, ADR-2629)
+
+Every plan carries an `estimate` block. It is the quantitative reason a phase must be sliced — tracer-first says *slice thin*, the estimate says *how thin, for this codebase*.
+
+**Compute it:**
+1. Sum `estimateTokens`-scale cost across the plan: implementation + the files each task reads + verification output. Roughly chars/4 over what the executor will actually touch.
+2. Run `estimate-calibration` and **multiply your raw figure by its `factor`.** It is the measured estimate-vs-actual ratio for THIS project — a factor of 1 means there is not yet enough history to correct.
+3. `confidence` is **derived, not judged**: it is the `confidence` value from the same calibration query, keyed to the sample count (`low` <3, `med` 3–5, `high` ≥6). **Do not rate your own certainty.** Self-rated confidence was measured in this project and found weak (`references/honest-verifier.md:25-29`); every signal here routes on measured history instead.
+
+**Over budget?** The plan-checker flags a plan whose estimate exceeds `workflow.smart_zone_tokens`. This is advisory — it never blocks. When flagged, re-slice: a tracer plus expansion slices, each inside the budget. Prefer more, smaller plans over one that spends the agent's best early-context tokens and finishes degraded.
+
+## Context Budget Rules
+
+Plans should complete within ~50% context (not 80%). No context anxiety, quality maintained start to finish, room for unexpected complexity.
+
+**Each plan: 2-3 tasks maximum.**
+
+| Context Weight | Tasks/Plan | Context/Task | Total |
+|----------------|------------|--------------|-------|
+| Light (CRUD, config) | 3 | ~10-15% | ~30-45% |
+| Medium (auth, payments) | 2 | ~20-30% | ~40-50% |
+| Heavy (migrations, multi-subsystem) | 1-2 | ~30-40% | ~30-50% |
+
+## Split Signals
+
+**ALWAYS split if:**
+- More than 3 tasks
+- Multiple subsystems (DB + API + UI = separate plans)
+- Any task with >5 file modifications
+- Checkpoint + implementation in same plan
+- Discovery + implementation in same plan
+
+**CONSIDER splitting:** >5 files total, natural semantic boundaries, context cost estimate exceeds 40% for a single plan. See `<planner_authority_limits>` for prohibited split reasons.
+
+See @~/.claude/gsd-core/references/planner-guidance.md for Granularity Calibration table (Coarse/Standard/Fine plans-per-phase).

package/gsd-core/references/gate-prompts.md

@@ -90,11 +90,14 @@ Up to 4 suggested next actions with selection (status, resume workflows).
 3-option handler for existing CONTEXT.md in discuss workflow.
 - question: "Phase {N} already has a CONTEXT.md. How should we handle it?"
 - header: "Context"
-- options: Overwrite | Append | Cancel
+- options: Update it | View it | Skip
 
 ## Pattern: gray-area-option
 Dynamic template for presenting gray area choices in discuss workflow.
 - question: "{Gray area title}"
 - header: "Decision"
-- options: {Option 1} | {Option 2} | Let Claude decide
-- Note: Options generated at runtime. Always include "Let Claude decide" as last option.
+- options: {Option 1} | {Option 2}
+- Note: Options generated at runtime. Present real choices only — do NOT include a
+  "skip" or "you decide" option (the user ran discuss-phase to decide). An "Other"
+  free-text escape hatch may be offered per modes/default.md, but never a
+  "Let Claude decide" cop-out.

package/gsd-core/references/model-profile-resolution.md

@@ -1,38 +1,89 @@
 # Model Profile Resolution
 
-Resolve model profile once at the start of orchestration, then use it for all Task spawns.
+Resolve each agent's model through `gsd-tools`, then pass it to the `Agent()` spawn — or
+omit the parameter entirely when nothing resolved.
 
 ## Resolution Pattern
 
+Prefer the field your workflow's own `init.*` payload already emits (every orchestrator
+init that spawns subagents carries one — `mapper_model`, `planner_model`,
+`executor_model`, `doc_writer_model`, …). Declare it in the workflow's parse line so the
+binding is stated, not implied:
+
+```
+Parse JSON for: `mapper_model`, …
+```
+
+When the agent type is only known at runtime — a capability hook naming its own agent, for
+example — resolve it directly instead:
+
 ```bash
-MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+AGENT_MODEL=$(gsd_run query resolve-model "<agent-type>" --raw)
 ```
 
-Default: `balanced` if not set or config missing.
+Both surfaces return the same thing: a model string for the active runtime, or the **empty
+string** when nothing resolved.
 
 ## Lookup Table
 
 @~/.claude/gsd-core/references/model-profiles.md
 
-Look up the agent in the table for the resolved profile. Pass the model parameter to Task calls:
+## Passing the model to a spawn
 
 ```
-Task(
+Agent(
   prompt="...",
   subagent_type="gsd-planner",
-  model="{resolved_model}"  # "inherit", "sonnet", or "haiku"
+  model="{planner_model}"
+)
+```
+
+Substitute the field **this workflow bound** — never a generic placeholder name.
+
+**#2517 — omit, do not emit an empty model.** When the resolved value is `"inherit"` or
+empty, **omit the `model=` parameter entirely**:
+
+```
+Agent(
+  prompt="...",
+  subagent_type="gsd-planner"
 )
 ```
 
-**Note:** Opus-tier agents resolve to `"inherit"` (not `"opus"`). This causes the agent to use the parent session's model, avoiding conflicts with organization policies that may block specific opus versions.
+No model parameter is passed at all — `planner_model` resolved to `"inherit"` or empty, and
+omitting it inherits the orchestrator's model. Passing either value through as an argument
+instead 404s on non-Claude runtimes.
+
+This is not cosmetic, and both values really occur. `model_profile: "inherit"` — and any
+opus-tier agent — resolves to the literal string `"inherit"`. `resolve_model_ids: "omit"`
+resolves to the **empty string** whenever the project sets it explicitly or the active
+runtime has no native tier aliases; an agent type absent from the profile table takes that
+same empty-string path, because it has no tier for the earlier steps to resolve. Emitting
+either value verbatim fails the spawn on every runtime without native tier aliases.
+
+**#2684 — substitute a field your workflow actually bound.** `model="{…}"` must name a key
+your own `init.*` payload emits, a shell variable you assigned, or a field on your declared
+parse line. A placeholder that resolves to nothing does not fail loudly — the orchestrator
+silently invents a value, which is the invisible partial application ADR-1411 prohibits.
+`tests/model-omit-when-inherit-guard.test.cjs` enforces both rules.
+
+## Profile semantics
+
+**Note:** Opus-tier agents resolve to `"inherit"` (not `"opus"`). This causes the agent to
+use the parent session's model, avoiding conflicts with organization policies that may
+block specific opus versions — and, per the rule above, means the `model=` parameter is
+omitted rather than set.
 
-If `model_profile` is `"adaptive"`, agents resolve to role-based assignments (opus/sonnet/haiku based on agent type).
+If `model_profile` is `"adaptive"`, agents resolve to role-based assignments (opus/sonnet/
+haiku based on agent type).
 
-If `model_profile` is `"inherit"`, all agents resolve to `"inherit"` (useful for OpenCode `/model`).
+If `model_profile` is `"inherit"`, all agents resolve to `"inherit"` (useful for OpenCode
+`/model`).
 
 ## Usage
 
-1. Resolve once at orchestration start
-2. Store the profile value
-3. Look up each agent's model from the table when spawning
-4. Pass model parameter to each Task call (values: `"inherit"`, `"sonnet"`, `"haiku"`)
+1. Bind the model once — from the `init.*` payload field, or `query resolve-model` when the
+   agent type is runtime-determined
+2. Declare the bound field on the workflow's parse line
+3. Pass `model="{bound_field}"` on each `Agent()` spawn
+4. Omit `model=` entirely whenever the bound value is `"inherit"` or empty

package/gsd-core/references/offer-next.md

@@ -0,0 +1,88 @@
+<!--
+  offer-next.md — extracted from execute-phase.md step "offer_next" (#2537).
+  Eagerly @-referenced from execute-phase.md so runtime behavior is unchanged; the
+  extraction restores byte-budget headroom the frozen ceiling exists to provide.
+-->
+
+
+**Exception:** If `gaps_found`, the `verify_phase_goal` step already presents the gap-closure path (`/gsd:plan-phase {X} --gaps`). No additional routing needed — skip auto-advance.
+
+**No-transition check (spawned by auto-advance chain):**
+
+Parse `--no-transition` flag from $ARGUMENTS.
+
+**If `--no-transition` flag present:**
+
+Execute-phase was spawned by plan-phase's auto-advance. Do NOT run transition.md.
+After verification passes and roadmap is updated, return completion status to parent:
+
+```
+## PHASE COMPLETE
+
+Phase: ${PHASE_NUMBER} - ${PHASE_NAME}
+Plans: ${completed_count}/${total_count}
+Verification: {Passed | Gaps Found}
+
+[Include aggregate_results output]
+```
+
+STOP. Do not proceed to auto-advance or transition.
+
+**If `--no-transition` flag is NOT present:**
+
+**Auto-advance detection:**
+
+1. Parse `--auto` flag from $ARGUMENTS
+2. Read consolidated auto-mode (`active` = chain flag OR user preference; chain flag already synced in init step):
+   ```bash
+   AUTO_MODE=$(gsd_run query check auto-mode --pick active 2>/dev/null || echo "false")
+   ```
+
+**If `--auto` flag present OR `AUTO_MODE` is true (AND verification passed with no gaps):**
+
+```
+╔══════════════════════════════════════════╗
+║  AUTO-ADVANCING → TRANSITION             ║
+║  Phase {X} verified, continuing chain    ║
+╚══════════════════════════════════════════╝
+```
+
+Execute the transition workflow inline (do NOT use Agent — orchestrator context is ~10-15%, transition needs phase completion data already in context):
+
+Read and follow `~/.claude/gsd-core/workflows/transition.md`, passing through the `--auto` flag so it propagates to the next phase invocation.
+
+**If neither `--auto` nor `AUTO_MODE` is true:**
+
+**STOP. Do not auto-advance. Do not execute transition. Do not plan next phase. Present options to the user and wait.**
+
+**IMPORTANT: There is NO `/gsd-transition` command. Never suggest it. The transition workflow is internal only.**
+
+Check whether CONTEXT.md already exists for the next phase:
+
+```bash
+ls .planning/phases/*{next}*/{next}-CONTEXT.md 2>/dev/null || echo "no-context"
+```
+
+If CONTEXT.md does **not** exist for the next phase, present:
+
+```
+## ✓ Phase {X}: {Name} Complete
+
+/gsd:progress ${GSD_WS} — see updated roadmap
+/gsd:discuss-phase {next} ${GSD_WS} — start here: discuss next phase before planning  ← recommended
+/gsd:plan-phase {next} ${GSD_WS} — plan next phase (skip discuss)
+/gsd:execute-phase {next} ${GSD_WS} — execute next phase (skip discuss and plan)
+```
+
+If CONTEXT.md **exists** for the next phase, present:
+
+```
+## ✓ Phase {X}: {Name} Complete
+
+/gsd:progress ${GSD_WS} — see updated roadmap
+/gsd:plan-phase {next} ${GSD_WS} — start here: plan next phase (CONTEXT.md already present)  ← recommended
+/gsd:discuss-phase {next} ${GSD_WS} — re-discuss next phase
+/gsd:execute-phase {next} ${GSD_WS} — execute next phase (skip planning)
+```
+
+Only suggest the commands listed above. Do not invent or hallucinate command names.

package/gsd-core/references/planning-config.md

@@ -255,6 +255,7 @@ Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research":
 | `workflow.auto_advance` | boolean | `false` | `true`, `false` | Auto-advance to next phase after completion |
 | `workflow.node_repair` | boolean | `true` | `true`, `false` | Attempt automatic repair of failed plan nodes |
 | `workflow.node_repair_budget` | number | `2` | Any positive integer | Max repair retries per failed node |
+| `workflow.smart_zone_tokens` | number | `100000` | Any positive integer | Smart-zone token budget for phase-effort estimation (#2630, ADR-2629). A phase whose estimate exceeds this is flagged with a split recommendation — advisory only, never a block. A *policy default*, not a benchmark constant: degradation begins before the advertised context window is full, but the effective ceiling is model- and task-dependent, so the calibration loop corrects it per project. _Alias:_ `smart_zone_tokens` is the flat-key form used in `CONFIG_DEFAULTS`; `workflow.smart_zone_tokens` is the canonical namespaced form. |
 | `workflow.ai_integration_phase` | boolean | `true` | `true`, `false` | Run /gsd:ai-integration-phase before planning AI system phases |
 | `workflow.api_coverage_gate` | boolean | `true` | `true`, `false` | Require an explicit API-coverage decision (full-by-default, opt-out-not-opt-in) before a phase that integrates an external API/SDK/service can seal. At plan:pre prompts a COVERAGE.md matrix; at verify:pre a blocking gate fails the seal unless the matrix exists with every non-integrated capability an explicit, reasoned opt-out (#1562) |
 | `workflow.ui_phase` | boolean | `true` | `true`, `false` | Generate UI-SPEC.md for frontend phases |
@@ -395,7 +396,7 @@ Several config fields affect each other or trigger special behavior:
 
 8. **`sub_repos` auto-sync** -- On every config load, GSD scans for child directories with `.git` and updates the `sub_repos` array if the filesystem has changed. Legacy `multiRepo: true` is automatically migrated to a detected `sub_repos` array.
 
-9. **`workflow.use_worktrees` and branch divergence** -- When `use_worktrees` is `true` (default), executor worktrees are forked from `origin/HEAD` by the Claude Code harness. If your current branch has commits that `origin/HEAD` does not (for example an unmerged milestone or feature branch), GSD automatically degrades to sequential execution for that run and prints a one-line `⚠ Worktree base mismatch` warning. To restore parallel execution permanently, set `worktree.baseRef:"head"` in `.claude/settings.local.json` (run `node gsd-tools.cjs worktree set-baseref`). This makes the harness fork worktrees from the live HEAD instead of `origin/HEAD`. Both fresh installs and upgrades of GSD Core set this automatically (no-clobber) when `use_worktrees` is enabled; you can also run the command manually at any time. Setting `workflow.use_worktrees: false` is the alternative if worktrees are not needed at all.
+9. **`workflow.use_worktrees` and branch divergence** -- When `use_worktrees` is `true` (default), executor worktrees are forked from `origin/HEAD` -- by the host's own harness on `dispatch.isolation: harness-worktree` runtimes (Claude Code, Cursor), or by GSD itself on `orchestrator-worktree` runtimes (Codex, OpenCode, Kimi, Kimi Code). The divergence behavior below is identical either way, because the fork base is a property of the repository rather than of whoever creates the worktree. If your current branch has commits that `origin/HEAD` does not (for example an unmerged milestone or feature branch), GSD automatically degrades to sequential execution for that run and prints a one-line `⚠ Worktree base mismatch` warning. To restore parallel execution permanently, set `worktree.baseRef:"head"` in `.claude/settings.local.json` (run `node gsd-tools.cjs worktree set-baseref`). This makes the harness fork worktrees from the live HEAD instead of `origin/HEAD`. Both fresh installs and upgrades of GSD Core set this automatically (no-clobber) when `use_worktrees` is enabled; you can also run the command manually at any time. Setting `workflow.use_worktrees: false` is the alternative if worktrees are not needed at all.
 
 ---
 

package/gsd-core/references/reviewer-instances.md

@@ -58,32 +58,39 @@ cannot diverge (`DEFECT.GENERATIVE-FIX`; parity-locked in
 
 ## Invocation
 
-For each selected INSTANCE, invoke its base `cli` using the instance's own `model`/`agent` —
-NOT the global `review.models.<cli>`. Each instance writes to its OWN per-instance output file
-under the run-scoped `{run_dir}` (`RUN_DIR` from `gather_context`, #2358 — never a bare
-`{phase}`-keyed `/tmp` path) and runs as a distinct reviewer identity.
+An instance resolves **through** a lane; it is not a lane itself (ADR-2782 D8). It takes no part in
+the roster, the flag set, or lane uniqueness — which is why an instance heading
+(`## OpenCode Review (opencode-deepseek)`) must never be read as a lane section.
 
-For an OpenCode-backed instance (the motivating adapter):
+Since Phase 5b (#2799) `invoke_reviewers` iterates declared lanes rather than hand-authored per-CLI
+blocks, so an instance is invoked through the same single seam as its base lane, with two
+substitutions:
 
 ```bash
-# $INSTANCE_MODEL / $INSTANCE_AGENT come from the instance spec; $INSTANCE_NAME is the
-# reviewer identity (e.g. opencode-deepseek). --agent is OpenCode's native subagent flag;
-# omit it when the instance has no agent. {run_dir} is the run-scoped mktemp directory
-# created once in gather_context (#2358) — same directory every other reviewer block uses.
-if [ -n "$INSTANCE_AGENT" ] && [ "$INSTANCE_AGENT" != "null" ]; then
-  cat {run_dir}/gsd-review-prompt.md | opencode run --model "$INSTANCE_MODEL" --agent "$INSTANCE_AGENT" - 2>/dev/null > {run_dir}/gsd-review-${INSTANCE_NAME}.md
-else
-  cat {run_dir}/gsd-review-prompt.md | opencode run --model "$INSTANCE_MODEL" - 2>/dev/null > {run_dir}/gsd-review-${INSTANCE_NAME}.md
-fi
-if [ ! -s {run_dir}/gsd-review-${INSTANCE_NAME}.md ]; then
-  echo "OpenCode review ($INSTANCE_NAME) failed or returned empty output." > {run_dir}/gsd-review-${INSTANCE_NAME}.md
-fi
+# $INSTANCE_NAME is the reviewer identity (e.g. opencode-deepseek); $INSTANCE_MODEL / $INSTANCE_AGENT
+# come from the instance spec. --run-dir is the run-scoped mktemp directory created once in
+# gather_context (#2358) — the same directory every lane uses.
+#
+# The instance's OWN model replaces the lane's configured model, and the output lands under the
+# INSTANCE name so two instances of one adapter never overwrite each other.
+gsd_run query review-lane invoke \
+  --slug "$INSTANCE_CLI" \
+  --run-dir "$RUN_DIR" --repo-root "$REPO_ROOT" \
+  --model "$INSTANCE_MODEL" ${INSTANCE_AGENT:+--agent "$INSTANCE_AGENT"} \
+  --as "$INSTANCE_NAME"
 ```
 
-For an instance backed by a DIFFERENT cli, reuse that cli's invocation block with two
-substitutions: use the instance's `model` in place of the global `review.models.<cli>` value,
-and write to `{run_dir}/gsd-review-${INSTANCE_NAME}.md`. Only `opencode` honours an
-`agent` field in v1; ignore `agent` for other adapters.
+`--as` is what makes the run write `{run_dir}/gsd-review-${INSTANCE_NAME}.md` instead of the lane's
+own `{run_dir}/gsd-review-<slug>.md`.
+
+Everything the lane declares — probe, prompt channel, output channel, timeout floor, empty-output
+policy, handler — applies unchanged to an instance. That is the point of routing instances through
+the lane rather than duplicating its invocation: a cross-cutting fix reaches instances for free,
+where the previous per-adapter block had to be copied and kept in sync by hand.
+
+Only `opencode` honours an `agent` field in v1; it is ignored by other adapters. `model` and `agent`
+are opaque pass-through strings and are NEVER interpolated into a shell string — the runner spawns
+with an argv array and `shell: false`.
 
 ---
 

package/gsd-core/references/runtime-aware-dispatch.md

@@ -0,0 +1,42 @@
+# Runtime-Aware Subagent Dispatch (epic #2505 Phase 4 / #2508)
+
+GSD workflows dispatch specialized subagents by role (planner, executor,
+verifier, …). On **named-dispatch runtimes** (Claude Code, OpenCode, Cursor,
+Cline, … — every runtime whose descriptor declares `hostIntegration.dispatch.namedDispatch: true`), the role name dispatches the named subagent directly.
+
+On **built-in-only runtimes** (kimi-code — three built-in subagents only:
+`coder`, `explore`, `plan`; no custom registration per
+`moonshotai.github.io/kimi-code/en/customization/agents`), a GSD role name is
+unknown and the dispatch must use the closest built-in.
+
+## Resolution
+
+Before dispatching a subagent by role, resolve the type for the current runtime
+via the `resolve-dispatch-type` query. Pass the requested role name; the query
+returns the name unchanged on named-dispatch runtimes and maps to the closest
+built-in (`coder`/`explore`/`plan`) on kimi-code. The `|| echo` fallback
+preserves named-dispatch behavior on older GSD installs that lack the query.
+
+The persona rides `${AGENT_SKILLS_<ROLE>}` (Phase 3 / #2510) regardless of the
+resolved type — on non-Claude runtimes with no `agent_skills` config,
+`gsd-tools query agent-skills <role>` returns the installed agent prompt as
+the block. So a coder dispatch with the planner persona injected gives kimi-code
+the planner's behavior in the coder built-in's process.
+
+## Suffix → built-in map
+
+| Agent role suffix | Built-in | Rationale |
+|---|---|---|
+| `-planner`, `-roadmapper`, `-selector`, `-spec` | `plan` | Plans/designs; no file writes |
+| `-researcher`, `-mapper`, `-checker`, `-verifier`, `-auditor`, `-analyzer`, `-synthesizer`, `-profiler`, `-curator`, `-classifier`, `-reviewer` | `explore` | Read-only investigation |
+| everything else (`-executor`, `-fixer`, `-writer`, `-debugger`, …) | `coder` | General-purpose with full tool set |
+| `general-purpose`, `general`, `default`, `sonnet`, `opus`, `haiku` | `coder` | Already-generic names |
+
+## Why not a hook?
+
+Kimi Code's documented PreToolUse hook API
+(`moonshotai.github.io/kimi-code/en/customization/hooks`) supports only
+`permissionDecision: allow|deny` on blockable events — it cannot rewrite the
+dispatch payload's role field in flight. A PreToolUse-remap hook (the epic's
+original "Option B") is therefore infeasible; this per-dispatch resolution
+(Option A) is the documented-API-correct path.

package/gsd-core/references/ui-consideration-probe.md

@@ -30,8 +30,8 @@ bloating this closed core.
 | id | name | applies to element kinds | consideration question |
 |----|------|--------------------------|------------------------|
 | empty | Empty / no data | form, list-collection, media | What is shown when there is no data — zero items, an unfilled form, or absent media? |
-| loading | Loading / in-flight | form, list-collection, media, nav | What is shown while data or content is still loading (skeleton, spinner, progressive reveal)? |
-| error | Error / failure | form, list-collection, media, nav | What is shown when the load or submit fails (message, retry affordance, partial fallback)? |
+| loading | Loading / in-flight | form, list-collection, media, nav, interactive-control | What is shown while data or content is still loading (skeleton, spinner, progressive reveal)? |
+| error | Error / failure | form, list-collection, media, nav, interactive-control | What is shown when the load or submit fails (message, retry affordance, partial fallback)? |
 | populated | Populated / happy path | list-collection, media | What does the normal populated (happy-path) state look like at a typical volume of content? |
 | partial | Partial / incomplete | form, list-collection | What is shown for partial or incomplete data — some fields or rows present, others missing? |
 | overflow | Overflow / truncation | list-collection, nav, static-content | What happens when content exceeds its container — scroll, clip, wrap, or truncate? |

package/gsd-core/references/worktree-branch-check.md

@@ -17,7 +17,7 @@ did not create (#48).
 <worktree_branch_check>
 FIRST ACTION: HEAD assertion MUST run before anything else, and this block is
 VERIFY-ONLY. Worktrees spawned by Claude Code's `isolation="worktree"` use the
-`worktree-agent-<id>` namespace. The orchestrator owns this worktree's lifecycle;
+`agent-<id>` namespace (previously `worktree-agent-<id>`; both are accepted). The orchestrator owns this worktree's lifecycle;
 a sub-agent MUST NOT hold state-correction primitives (hard-reset, update-ref,
 force-move, index-discard) on a worktree it did not create (#48, #2924). If ANY
 assertion below fails, HALT immediately — print the FATAL line, `exit 42`, and let
@@ -27,11 +27,11 @@ commit.
 HEAD_REF=$(git symbolic-ref --quiet HEAD || echo "DETACHED")
 ACTUAL_BRANCH=$(git rev-parse --abbrev-ref HEAD)
 if [ "$HEAD_REF" = "DETACHED" ] || echo "$ACTUAL_BRANCH" | grep -Eq '^(main|master|develop|trunk|release/.*)$'; then
-  echo "FATAL: worktree HEAD on '$ACTUAL_BRANCH' (expected worktree-agent-*); refusing to commit or self-recover via 'git update-ref' (#2924)." >&2
+  echo "FATAL: worktree HEAD on '$ACTUAL_BRANCH' (expected agent-* or worktree-agent-*); refusing to commit or self-recover via 'git update-ref' (#2924)." >&2
   exit 42
 fi
-if ! echo "$ACTUAL_BRANCH" | grep -Eq '^worktree-agent-[A-Za-z0-9._/-]+$'; then
-  echo "FATAL: worktree HEAD '$ACTUAL_BRANCH' is not in the worktree-agent-* namespace; refusing to commit (#2924)." >&2
+if ! echo "$ACTUAL_BRANCH" | grep -Eq '^(worktree-)?agent-[A-Za-z0-9._/-]+$'; then
+  echo "FATAL: worktree HEAD '$ACTUAL_BRANCH' is not in the agent-* / worktree-agent-* namespace; refusing to commit (#2924)." >&2
   exit 42
 fi
 ACTUAL_BASE=$(git rev-parse HEAD)

package/gsd-core/templates/summary-minimal.md

@@ -6,6 +6,10 @@ tags: [searchable tech]
 provides:
   - [bullet list of what was built/delivered]
 affects: [list of phase names or keywords]
+actuals:
+  tokens: [chars/4 over files actually changed]
+  tasks: [tasks completed]
+  commits: [commits made]
 tech-stack:
   added: [libraries/tools]
   patterns: [architectural/code patterns]

package/gsd-core/templates/summary-standard.md

@@ -6,6 +6,10 @@ tags: [searchable tech]
 provides:
   - [bullet list of what was built/delivered]
 affects: [list of phase names or keywords]
+actuals:
+  tokens: [chars/4 over files actually changed]
+  tasks: [tasks completed]
+  commits: [commits made]
 tech-stack:
   added: [libraries/tools]
   patterns: [architectural/code patterns]

package/gsd-core/templates/summary.md

@@ -21,6 +21,13 @@ provides:
   - [bullet list of what this phase built/delivered]
 affects: [list of phase names or keywords that will need this context]
 
+# Actuals (#2632) — pairs with the plan's `estimate` to calibrate future estimates.
+# Same estimateTokens scale (chars/4 over the realized diff), never a harness token count.
+actuals:
+  tokens: [chars/4 over files actually changed]
+  tasks: [tasks completed]
+  commits: [commits made]
+
 # Tech tracking
 tech-stack:
   added: [libraries/tools added in this phase]

package/gsd-core/workflows/ai-integration-phase.md

@@ -33,10 +33,10 @@ Parse JSON for: `phase_dir`, `phase_number`, `phase_name`, `phase_slug`, `padded
 
 Resolve agent models:
 ```bash
-SELECTOR_MODEL=$(gsd_run query resolve-model gsd-framework-selector 2>/dev/null | jq -r '.model' 2>/dev/null || true)
-RESEARCHER_MODEL=$(gsd_run query resolve-model gsd-ai-researcher 2>/dev/null | jq -r '.model' 2>/dev/null || true)
-DOMAIN_MODEL=$(gsd_run query resolve-model gsd-domain-researcher 2>/dev/null | jq -r '.model' 2>/dev/null || true)
-PLANNER_MODEL=$(gsd_run query resolve-model gsd-eval-planner 2>/dev/null | jq -r '.model' 2>/dev/null || true)
+SELECTOR_MODEL=$(gsd_run query resolve-model gsd-framework-selector --pick model 2>/dev/null || true)
+RESEARCHER_MODEL=$(gsd_run query resolve-model gsd-ai-researcher --pick model 2>/dev/null || true)
+DOMAIN_MODEL=$(gsd_run query resolve-model gsd-domain-researcher --pick model 2>/dev/null || true)
+PLANNER_MODEL=$(gsd_run query resolve-model gsd-eval-planner --pick model 2>/dev/null || true)
 ```
 
 Check config:

package/gsd-core/workflows/audit-fix.md

@@ -94,6 +94,10 @@ final output — do not proceed to fixing.
 <step name="fix-loop">
 For each **auto-fixable** finding (up to `--max`, ordered by severity desc):
 
+<!-- #2508 runtime-aware-dispatch -->
+
+> **Runtime-aware dispatch (#2508 Phase 4).** GSD workflows dispatch specialized subagents by role. Before dispatching on a built-in-only runtime (kimi-code — three built-ins only), resolve the role to a built-in via `gsd_run query resolve-dispatch-type --requested <role> --raw`. On named-dispatch runtimes (Claude/OpenCode/…) the role is returned unchanged; on kimi-code it maps to `coder`/`explore`/`plan` by role-suffix. The persona rides `${AGENT_SKILLS_<ROLE>}` (Phase 3) regardless. See @gsd-core/references/runtime-aware-dispatch.md.
+
 **a. Spawn executor agent** (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)**:**
 ```
 Agent(

package/gsd-core/workflows/audit-milestone.md

@@ -69,6 +69,10 @@ Extract `MILESTONE_REQ_IDS` from REQUIREMENTS.md traceability table — all REQ-
 
 Print: "Spawning integration checker (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)"
 
+<!-- #2517 model-omit-on-inherit -->
+
+> **Model omission (#2517).** Omit the `model` parameter entirely when the value it would carry (`integration_checker_model`) is `"inherit"` or empty. An empty value 404s on runtimes without native tier aliases — the default on non-Claude runtimes. Omitting it inherits the orchestrator's model. See @gsd-core/references/model-profile-resolution.md.
+
 ```
 Agent(
   prompt="Check cross-phase integration and E2E flows.
@@ -82,6 +86,10 @@ Milestone Requirements:
 
 MUST map each integration finding to affected requirement IDs where applicable.
 
+<!-- #2508 runtime-aware-dispatch -->
+
+> **Runtime-aware dispatch (#2508 Phase 4).** GSD workflows dispatch specialized subagents by role. Before dispatching on a built-in-only runtime (kimi-code — three built-ins only), resolve the role to a built-in via `gsd_run query resolve-dispatch-type --requested <role> --raw`. On named-dispatch runtimes (Claude/OpenCode/…) the role is returned unchanged; on kimi-code it maps to `coder`/`explore`/`plan` by role-suffix. The persona rides `${AGENT_SKILLS_<ROLE>}` (Phase 3) regardless. See @gsd-core/references/runtime-aware-dispatch.md.
+
 Verify cross-phase wiring and E2E user flows.
 ${AGENT_SKILLS_CHECKER}",
   subagent_type="gsd-integration-checker",