@opengsd/gsd-core 1.9.1 → 1.11.0

package/gsd-core/references/doc-conflict-engine.md

@@ -56,7 +56,7 @@ Exit WITHOUT writing any destination files. The gate must hold regardless of WAR
 
 **If only WARNINGS and/or INFO (no blockers):**
 
-Render the full report, then prompt for approval via the `approve-revise-abort` or `yes-no` pattern from `references/gate-prompts.md`. Respect text mode (see the workflow's own text-mode handling). If the user aborts, exit cleanly with a cancellation message.
+Render the full report, then prompt for approval via the `approve-revise-abort` or `yes-no` pattern from `gsd-core/references/gate-prompts.md`. Respect text mode (see the workflow's own text-mode handling). If the user aborts, exit cleanly with a cancellation message.
 
 **If the report is empty (no entries in any bucket):**
 

package/gsd-core/references/execute-mvp-tdd.md

@@ -4,7 +4,7 @@
 
 ## When this gate fires
 
-- `MVP_MODE` is `true` (resolved from CLI flag → ROADMAP `**Mode:**` field → config; see `references/planner-mvp-mode.md`).
+- `MVP_MODE` is `true` (resolved from CLI flag → ROADMAP `**Mode:**` field → config; see `gsd-core/references/planner-mvp-mode.md`).
 - `TDD_MODE` is `true` (resolved from `--tdd` flag → `workflow.tdd_mode` config).
 - The current task being executed has `tdd="true"` in its `<task>` frontmatter (set by the planner per Phase 1).
 - The task's `<behavior>` block lists at least one expected behavior.
@@ -71,11 +71,11 @@ The `--force-mvp-gate` flag is documented but not introduced by this plan — it
 
 ## What this gate does NOT do
 
-- It does not enforce REFACTOR commits. REFACTOR remains optional (per `references/tdd.md`).
+- It does not enforce REFACTOR commits. REFACTOR remains optional (per `gsd-core/references/tdd.md`).
 - It does not check test quality (the test could be trivially passing). That's the planner's job.
 - It does not run tests. The executor only inspects git log + file system. Running tests is the implementation step's job.
 - It does not gate config-only or doc-only tasks (see "behavior-adding task" definition).
 
 ## Compatibility with existing TDD discipline
 
-This gate is additive to `references/tdd.md`. Tasks not under MVP+TDD continue to use the existing advisory TDD discipline (RED/GREEN/REFACTOR commits with end-of-phase review checkpoint). Only the runtime gate and the blocking escalation are new.
+This gate is additive to `gsd-core/references/tdd.md`. Tasks not under MVP+TDD continue to use the existing advisory TDD discipline (RED/GREEN/REFACTOR commits with end-of-phase review checkpoint). Only the runtime gate and the blocking escalation are new.

package/gsd-core/references/execute-phase-between-wave-reset.md

@@ -7,7 +7,9 @@
 
 7c. **Between-wave manifest reset and worktree base refresh (waves 2+ only — #1369):**
 
-   **REQUIRED before each wave transition when `USE_WORKTREES != "false"` and `RUNTIME = "claude"`.**
+   **REQUIRED before each wave transition when `USE_WORKTREES != "false"` and
+   `ISOLATION = "harness-worktree"`** (#2652 — keyed on the negotiated isolation model, not the
+   runtime name).
 
    Wave N's `WAVE_WORKTREE_MANIFEST` was consumed by `worktree.cleanup-wave` in step 5.5. It must be
    unset so wave N+1's step 3 creates a fresh manifest for the new wave's worktrees. Without this,
@@ -26,7 +28,7 @@
    # advanced. Re-assert worktree.baseRef:"head" (idempotent — no-op if already set) so the
    # Claude Code harness re-reads the live HEAD on the next Agent(isolation="worktree") call
    # rather than using a cached session-start commit as the fork base.
-   if [ "$RUNTIME" = "claude" ] && [ "$USE_WORKTREES" != "false" ]; then
+   if [ "$ISOLATION" = "harness-worktree" ] && [ "$USE_WORKTREES" != "false" ]; then
      gsd_run query worktree.set-baseref 2>/dev/null || true
 
      # Safety re-check: evaluate degradation AFTER the wave N commits. If HEAD has diverged
@@ -37,7 +39,9 @@
        _DEGRADE_MSG=$(gsd_run query worktree.base-check --pick message 2>/dev/null || true)
        [ -n "$_DEGRADE_MSG" ] && printf '%s\n' "$_DEGRADE_MSG" >&2
        printf 'Degrading to sequential mode for remaining waves: HEAD advanced past worktree fork base after wave %s merge (#1369).\n' "${N}" >&2
+       # Both must move together (#2652): dispatch keys on ISOLATION.
        USE_WORKTREES=false
+       ISOLATION=none
      fi
    fi
    ```

package/gsd-core/references/execute-phase-context-guard.md

@@ -1,7 +1,7 @@
 0. **Context exhaustion guard — `context_guard` (BEFORE spawning, #1452):**
 
    Before spawning any agents for this wave, self-assess context pressure using the
-   degradation signals in `references/context-budget.md`. Signs of POOR tier (70%+):
+   degradation signals in `gsd-core/references/context-budget.md`. Signs of POOR tier (70%+):
    increasing vagueness, skipped steps, silent partial completion.
 
    Read `workflow.context_guard_mode` from `.planning/config.json` (default `warn`).

package/gsd-core/references/execute-phase-response-language.md

@@ -4,4 +4,4 @@
 
 The literal report templates embedded in this workflow (`## Execution Plan`, `## Phase {X}: {Name} Execution Complete`, `## ⚠ Phase {X}: {Name} — Gaps Found`, etc.) are a structural source, not literal output to copy verbatim — render their prose translated into `{response_language}` while keeping headings' structural markers, table columns, IDs, commands, and file paths unchanged.
 
-This directive was extracted from `workflows/execute-phase.md` to keep that file under the frozen pre-phase-6 byte ceiling (ADR-857 Phase 6 capstone, `tests/fix-2285-claude-orchestration-wiring.test.cjs`). The `@-reference` is eager, so the runtime still loads this content alongside the workflow — the extraction is purely a file-size discipline, not a lazy-load optimization.
+This directive was extracted from `workflows/execute-phase.md` to keep that file under the frozen pre-phase-6 byte ceiling (ADR-857 Phase 6 capstone, `tests/claude-orchestration.test.cjs`). The `@-reference` is eager, so the runtime still loads this content alongside the workflow — the extraction is purely a file-size discipline, not a lazy-load optimization.

package/gsd-core/references/execute-phase-wave-guard.md

@@ -7,16 +7,20 @@
    immediately with a base-mismatch fatal.
 
    **Run this check at the start of every wave when `USE_WORKTREES != "false"` and
-   `RUNTIME = "claude"`**, including Wave 1 (where it mirrors the initialize-step check):
+   `ISOLATION = "harness-worktree"`** (#2652 — the harness caches the fork base, so this is a
+   property of the isolation model, not of the runtime name; Cursor declares it too),
+   including Wave 1 (where it mirrors the initialize-step check):
 
    ```bash
-   if [ "$RUNTIME" = "claude" ] && [ "${USE_WORKTREES:-true}" != "false" ]; then
+   if [ "$ISOLATION" = "harness-worktree" ] && [ "${USE_WORKTREES:-true}" != "false" ]; then
      _WAVE_DEGRADE=$(gsd_run query worktree.base-check --pick shouldDegrade 2>/dev/null || true)
      if [ "$_WAVE_DEGRADE" = "true" ]; then
        _WAVE_DEGRADE_MSG=$(gsd_run query worktree.base-check --pick message 2>/dev/null || true)
        [ -n "$_WAVE_DEGRADE_MSG" ] && printf '%s\n' "$_WAVE_DEGRADE_MSG" >&2
        echo "⚠ [#1369] Worktree fork base diverged from orchestrator HEAD (wave merges advanced HEAD past origin/HEAD). Auto-degrading to sequential mode for this wave to avoid base-mismatch halts." >&2
+       # Both must move together (#2652): dispatch keys on ISOLATION.
        USE_WORKTREES=false
+       ISOLATION=none
      fi
    fi
    ```

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

@@ -2,7 +2,7 @@
 
 Reusable prompt patterns for structured gate checks in workflows and agents.
 
-**For checkpoint box format details, see `references/ui-brand.md`** -- checkpoint boxes use double-line border drawing with 62-character inner width.
+**For checkpoint box format details, see `gsd-core/references/ui-brand.md`** -- checkpoint boxes use double-line border drawing with 62-character inner width.
 
 ## Rules
 

package/gsd-core/references/git-planning-commit.md

@@ -12,7 +12,7 @@ Always use this for `.planning/` files — it handles `commit_docs` and gitignor
 gsd-tools query commit "docs({scope}): {description}" --files .planning/STATE.md .planning/ROADMAP.md
 ```
 
-The CLI will return `skipped` (with reason) if `commit_docs` is `false` or `.planning/` is gitignored. No manual conditional checks needed.
+The CLI will return `skipped` (with reason) if `commit_docs` is `false`, `.planning/` is gitignored, or a per-phase `phase_commit_docs.<phase-id>` override resolves `false` for the phase being committed. No manual conditional checks needed.
 
 ## Amend previous commit
 
@@ -37,4 +37,5 @@ gsd-tools query commit "" --files .planning/codebase/*.md --amend
 
 - `commit_docs: false` in config
 - `.planning/` is gitignored
+- `phase_commit_docs.<phase-id>` resolves `false` for the phase being committed — overrides the project-wide `commit_docs` for that phase only (reason `skipped_commit_docs_phase_false`)
 - No changes to commit (check with `git status --porcelain .planning/`)

package/gsd-core/references/loop-hook-dispatch.md

@@ -31,7 +31,7 @@ Inject `fragment.inline` verbatim into the context for the role named in `into`
 
 ### `step`
 
-Dispatch the referenced unit:
+Dispatch the referenced unit. Exactly one of `ref.skill`, `ref.agent`, or `ref.command` is set.
 
 - `ref.skill` present → dispatch via the Skill tool with skill id `gsd-<ref.skill>`.
 - `ref.agent` present → dispatch via the Agent tool with `subagent_type` = `ref.agent`.
@@ -42,10 +42,47 @@ Dispatch the referenced unit:
   ◆ Spawning <agent>... (runs in a subagent — no output until it returns; expected, not a freeze)
   ```
 
+- `ref.command` present → **validate it IN-CONTEXT first, before any shell use.** It comes
+  from a capability manifest, which may be third-party. Check the value you read from
+  `activeHooks` against `^[a-z][a-z0-9-]*( [a-z][a-z0-9-]*)*$` yourself — **never** by pasting
+  it into a shell command to be tested there, because a value carrying a quote, `;`,
+  `` ` ``, `$(`, or a newline would terminate the assignment and run as its own statement
+  before any shell-side check could execute. A value that fails is a malformed manifest:
+  record a warning, skip that hook, continue to the next entry. Only a value that has passed
+  is run, with the phase number appended:
+
+  ```bash
+  gsd_run ${ref.command} --phase "${PHASE_NUMBER}" --raw
+  ```
+
 Wait for the result before continuing to the next hook or the next step.
 
+A `step` is **advisory by construction**: it never blocks or redirects the host workflow —
+that is what a `gate` is for. Each dispatch is best-effort; on error record a warning and
+continue, honoring `onError`.
+
+**A point whose workflow hand-rolls one `kind` does not implement this contract.** Several
+host workflows historically matched a single hook (e.g. `execute:post` matched only
+`ref.skill == "code-review"`), so any other step registered there was declared and silently
+never run. When a workflow defers to this file, it dispatches **every** active `step` entry,
+not one shape of one.
+
 ### `gate`
 
+**Validate `check` before any shell use.** `check.query` and `check.predicate` come from a
+capability manifest, which may be third-party — and `gates[].check` is **not** one of the
+executable surfaces the install consent prompt discloses (`hooks`, command modules,
+`mcpServers`, reviewer lanes), so a capability can be consented to as declarative-only and
+still reach a shell through a gate. Check the query value you read from `activeHooks` against
+`^[a-z][a-z0-9-]*( [a-z][a-z0-9-]*)*$` yourself, IN-CONTEXT — **never** by pasting it into a
+shell command to be tested there, because a value carrying a quote, `;`, a `` ` ``, `$(`, or a
+newline would terminate the assignment and run as its own statement before any shell-side
+check could execute. A value that fails is a malformed manifest: record a warning, route it
+per the gate's `onError`, and do not run it. Pass `check.predicate` as a **single argv
+element** for the same reason — never re-quote it into a shell string, where an apostrophe
+would close the literal. This is the identical requirement `step` → `ref.command` carries
+above; it was stated there and omitted here, which is the gap #3559 closed.
+
 Evaluate `check` (one of `query`, `predicate`, or `agentVerdict`). Then honor `blocking`:
 
 - `blocking: true` → if the check returns `block: true`, surface `check.message` to the user
@@ -53,7 +90,7 @@ Evaluate `check` (one of `query`, `predicate`, or `agentVerdict`). Then honor `b
 - `blocking: false` → advisory only; surface the message but continue regardless of outcome.
 
 Honor `onError` if the check itself errors: `skip` means treat as non-blocking and continue;
-`fail` means surface the error and stop.
+`halt` means surface the error and stop.
 
 ## Empty / absent `activeHooks`
 

package/gsd-core/references/model-profiles.md

@@ -219,10 +219,18 @@ is (highest → lowest):
 6. Pass model parameter to Task call
 ```
 
-The same precedence applies to `reasoning_effort` resolution on runtimes
-that support it (Codex), so `model` and `reasoning_effort` always derive
-from the same tier source — a `models[phase_type]` or
-`dynamic_routing` override flips both.
+`model` and `effort` resolve through different mechanisms at different
+times — they do not share the ladder above. `model` resolves at runtime,
+per spawn, from `.planning/config.json`; a config change takes effect on
+the next spawn. `effort` (claude runtime) has its own cascade
+(`agent_overrides` → `routing_tier_defaults` → `default`; see
+`docs/CONFIGURATION.md` § "Where effort actually reaches") and is baked at
+install time into the `effort:` frontmatter key of
+`~/.claude/agents/gsd-*.md` — Claude Code's Agent tool has no per-spawn
+effort parameter, so per-agent frontmatter is the only channel. An effort
+config change has no effect until `node gsd-tools.cjs effort sync --apply`
+re-syncs the agent files. Codex agents instead pin
+`model_reasoning_effort` in `~/.codex/agents/*.toml` at install time.
 
 ## Per-Agent Overrides
 

package/gsd-core/references/mvp-concepts.md

@@ -8,12 +8,12 @@ Canonical domain terms for the concepts named below live in [CONTEXT.md](../../C
 
 | File | Purpose | Loaded by |
 |---|---|---|
-| `references/planner-mvp-mode.md` | **Rules.** Vertical-slice planning rules, slice ordering, Walking Skeleton constraints. | `gsd-planner` agent when `MVP_MODE=true` |
-| `references/skeleton-template.md` | **Template.** Shape of `SKELETON.md` for new-project Phase 1 under `--mvp`. | `gsd-planner` agent when the Walking Skeleton gate fires |
-| `references/user-story-template.md` | **Template.** Format and slot definitions for `As a / I want to / So that`. | `gsd-mvp-phase` workflow during interactive prompting; `gsd-planner` when emitting the `## Phase Goal` header |
-| `references/spidr-splitting.md` | **Splitting discipline.** Five-axis decomposition (Spike, Paths, Interfaces, Data, Rules) for stories too large for one phase. | `gsd-mvp-phase` workflow when the user story exceeds size threshold |
-| `references/execute-mvp-tdd.md` | **Gate.** MVP+TDD runtime gate semantics: when it fires, what it checks, halt-and-report protocol, end-of-phase blocking escalation, Behavior-Adding Task definition. | `gsd-executor` agent when `MVP_MODE=true && TDD_MODE=true` |
-| `references/verify-mvp-mode.md` | **UAT framing.** Three-section UAT structure (user-flow → technical → coverage), anti-patterns, `User Flow Coverage` section in VERIFICATION.md. | `gsd-verifier` agent when the phase under verification has `mode: mvp` |
+| `gsd-core/references/planner-mvp-mode.md` | **Rules.** Vertical-slice planning rules, slice ordering, Walking Skeleton constraints. | `gsd-planner` agent when `MVP_MODE=true` |
+| `gsd-core/references/skeleton-template.md` | **Template.** Shape of `SKELETON.md` for new-project Phase 1 under `--mvp`. | `gsd-planner` agent when the Walking Skeleton gate fires |
+| `gsd-core/references/user-story-template.md` | **Template.** Format and slot definitions for `As a / I want to / So that`. | `gsd-mvp-phase` workflow during interactive prompting; `gsd-planner` when emitting the `## Phase Goal` header |
+| `gsd-core/references/spidr-splitting.md` | **Splitting discipline.** Five-axis decomposition (Spike, Paths, Interfaces, Data, Rules) for stories too large for one phase. | `gsd-mvp-phase` workflow when the user story exceeds size threshold |
+| `gsd-core/references/execute-mvp-tdd.md` | **Gate.** MVP+TDD runtime gate semantics: when it fires, what it checks, halt-and-report protocol, end-of-phase blocking escalation, Behavior-Adding Task definition. | `gsd-executor` agent when `MVP_MODE=true && TDD_MODE=true` |
+| `gsd-core/references/verify-mvp-mode.md` | **UAT framing.** Three-section UAT structure (user-flow → technical → coverage), anti-patterns, `User Flow Coverage` section in VERIFICATION.md. | `gsd-verifier` agent when the phase under verification has `mode: mvp` |
 
 ## Concept-to-file map
 
@@ -22,10 +22,10 @@ If you're looking for the canonical statement of a concept, this is where to fin
 - **MVP Mode resolution chain** — `workflows/plan-phase.md` Step 1 (CLI flag → roadmap → config → false). Mirrored in `execute-phase.md` and `verify-work.md`.
 - **`**Mode:** mvp` parser** — `gsd-core/bin/lib/roadmap.cjs` (`searchPhaseInContent` + `cmdRoadmapAnalyze`). Workflows compare against the parser output, never re-parse.
 - **User Story regex** — `/^As a .+, I want to .+, so that .+\.$/` — applied at runtime by `gsd-verifier` (the user-story-format guard) and `gsd-mvp-phase` (interactive validation).
-- **Behavior-Adding Task predicate** — `references/execute-mvp-tdd.md` (the canonical three-check definition). Applied at runtime by `gsd-executor`.
+- **Behavior-Adding Task predicate** — `gsd-core/references/execute-mvp-tdd.md` (the canonical three-check definition). Applied at runtime by `gsd-executor`.
 - **Walking Skeleton gate condition** — `workflows/plan-phase.md` (Phase 1 + new project + `--mvp` + no prior summaries → emit `SKELETON.md`).
-- **MVP+TDD Gate** (RED→GREEN enforcement) — `references/execute-mvp-tdd.md`.
-- **MVP-mode UAT framing** (user-flow first, technical deferred) — `references/verify-mvp-mode.md`.
+- **MVP+TDD Gate** (RED→GREEN enforcement) — `gsd-core/references/execute-mvp-tdd.md`.
+- **MVP-mode UAT framing** (user-flow first, technical deferred) — `gsd-core/references/verify-mvp-mode.md`.
 - **Per-phase mode authoring** — `workflows/mvp-phase.md` (writes `**Mode:** mvp` to ROADMAP.md after collecting the user story).
 - **Project-wide mode prompt at init** — `workflows/new-project.md` (Vertical MVP vs Horizontal Layers question).
 

package/gsd-core/references/planner-guidance.md

@@ -162,24 +162,18 @@ Derive plans from actual work. Granularity determines compression tolerance, not
 Run `/clear` first for a fresh context window, then execute: `/gsd:execute-phase {phase}`
 ```
 
-## Gap Closure Plans Created Return Format
+## Gap Closure Return (artifact-based — #3440)
 
-```markdown
-## GAP CLOSURE PLANS CREATED
+Gap-closure completion has **no completion marker**: nothing consumes one. The return contract is the artifacts themselves — `verify-work.md` spawns you in `--gaps` mode, and your output is complete when the fix plans are on disk carrying `gap_closure: true` in their frontmatter; the spawning workflow detects the files (never a return string), and `/gsd:execute-phase {phase} --gaps-only` consumes them. (The former `GAP CLOSURE PLANS CREATED` completion marker was retired as vestigial — it had no dispatch branch anywhere.)
 
 **Phase:** {phase-name}
 **Closing:** {N} gaps from {VERIFICATION|UAT}.md
 
-### Plans
-
 | Plan | Gaps Addressed | Files |
 |------|----------------|-------|
 | {phase}-04 | [gap truths] | [files] |
 
-### Next Steps
-
-Execute: `/gsd:execute-phase {phase} --gaps-only`
-```
+**Next step for the orchestrator:** `/gsd:execute-phase {phase} --gaps-only`
 
 ## Checkpoint Reached / Revision Complete
 

package/gsd-core/references/planner-preconditions.md

@@ -121,7 +121,7 @@ The executor agent reads `<precondition>` before any other task work:
 |---|---|
 | **Absent** | No visible change — execute the task exactly as today. Back-compat for every existing plan. |
 | **Met** | No visible change — proceed with the task. The precondition is logged in the SUMMARY only if it was non-trivial to verify. |
-| **Unmet** | STOP — return a `checkpoint:human-verify` (use `checkpoint_return_format`) with `**Blocked by:** Precondition not met: <precondition text>`. Do NOT partial-commit the task. Unmet preconditions are NEVER auto-approved — a missing prerequisite is not a verification step a human can rubber-stamp, it is a fact the executor cannot establish on its own. |
+| **Unmet** | STOP — return a `checkpoint:human-verify` reporting `**Gate:** blocking-human` (use `checkpoint_return_format`) with `**Blocked by:** Precondition not met: <precondition text>`. Do NOT partial-commit the task. Unmet preconditions are NEVER auto-approved — a missing prerequisite is not a verification step a human can rubber-stamp, it is a fact the executor cannot establish on its own. |
 
 ## Plan-structure validation
 

package/gsd-core/references/planner-reviews.md

@@ -7,7 +7,7 @@ Triggered when orchestrator sets Mode to `reviews`. Replanning from scratch with
 **Execution contract:** REVIEWS.md is audit trail and feedback input, not a second execution contract. /gsd:execute-phase primarily consumes PLAN.md plus the normal phase context. Every current actionable review finding must therefore be incorporated into the relevant PLAN.md or explicitly deferred/rejected in that PLAN.md.
 
 ### Step 1: Load REVIEWS.md
-Read the reviews file from `<files_to_read>`. Parse:
+Read the reviews file from `<required_reading>`. Parse:
 - Per-reviewer feedback (strengths, concerns, suggestions)
 - Consensus Summary (agreed concerns = highest priority to address)
 - Divergent Views (investigate, make a judgment call)

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

@@ -36,7 +36,7 @@ Configuration options for `.planning/` directory behavior.
 | `git.quick_branch_template` | `null` | Optional branch template for quick-task runs |
 | `workflow.use_worktrees` | `true` | Whether executor agents run in isolated git worktrees. Set to `false` to disable worktrees — agents execute sequentially on the main working tree instead. Recommended for solo developers or when worktree merges cause issues. Note: if your branch is ahead of `origin/HEAD` (a diverged milestone or feature branch), GSD auto-degrades to sequential and prints a warning; set `worktree.baseRef:"head"` in `.claude/settings.local.json` to restore parallel execution. See the branch-divergence note below. |
 | `workflow.subagent_timeout` | `300000` | Timeout in milliseconds for parallel subagent tasks (e.g. codebase mapping). Increase for large codebases or slower models. Default: 300000 (5 minutes). |
-| `workflow.test_command` | `null` | Custom shell command run as the regression/test gate by verify-phase, execute-phase, audit-fix, and post-merge-gate. When unset, GSD auto-detects (Makefile / package.json / Cargo.toml / go.mod / pyproject.toml). Example: `npm test`. |
+| `workflow.test_command` | `null` | Custom shell command run as the regression/test gate by execute-phase, audit-fix, and post-merge-gate. When unset, GSD auto-detects (Makefile / package.json / Cargo.toml / go.mod / pyproject.toml). Example: `npm test`. |
 | `workflow.build_command` | `null` | Custom shell command run as the build gate by the post-merge gate. When unset, the build step is skipped/auto-detected. Example: `npm run build`. |
 | `workflow.inline_plan_threshold` | `2` | Plans with this many tasks or fewer execute inline (Pattern C) instead of spawning a subagent. Avoids ~14K token spawn overhead for small plans. Set to `0` to always spawn subagents. |
 | `manager.flags.discuss` | `""` | Flags passed to `/gsd:discuss-phase` when dispatched from manager (e.g. `"--auto --analyze"`) |
@@ -76,6 +76,8 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 
 **Auto-detection:** If `.planning/` is gitignored, `commit_docs` is automatically `false` regardless of config.json. This prevents git errors when users have `.planning/` in `.gitignore`.
 
+**Per-phase override:** `phase_commit_docs.<phase-id>` (e.g. `phase_commit_docs.03`) overrides `commit_docs` for one phase only, and wins over both the explicit config value and gitignore auto-detection — see `docs/CONFIGURATION.md#per-phase-override-phase_commit_docs` for the full precedence chain and examples.
+
 **Commit via CLI (handles checks automatically):**
 
 ```bash
@@ -266,7 +268,7 @@ Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research":
 | `workflow.skip_discuss` | boolean | `false` | `true`, `false` | Skip discuss phase entirely |
 | `workflow.use_worktrees` | boolean | `true` | `true`, `false` | Run executor agents in isolated git worktrees |
 | `workflow.subagent_timeout` | number | `300000` | Any positive integer (ms) | Timeout for parallel subagent tasks (default: 5 minutes) |
-| `workflow.test_command` | string\|null | `null` | Any shell command | Regression/test gate command run by verify-phase, execute-phase, audit-fix, and post-merge-gate. Unset → GSD auto-detects (Makefile / package.json / Cargo.toml / go.mod / pyproject.toml). |
+| `workflow.test_command` | string\|null | `null` | Any shell command | Regression/test gate command run by execute-phase, audit-fix, and post-merge-gate. Unset → GSD auto-detects (Makefile / package.json / Cargo.toml / go.mod / pyproject.toml). |
 | `workflow.build_command` | string\|null | `null` | Any shell command | Build gate command run by the post-merge gate. Unset → build step auto-detected/skipped. |
 | `workflow.mvp_mode` | boolean | `false` | `true`, `false` | Persist the MVP-mode flag in config so every phase defaults to MVP framing without requiring `--mvp` on the CLI. Resolved via the chain: `--mvp` CLI flag → ROADMAP.md `**Mode:** mvp` field → this config value → `false`. When `true`, the planner, executor, verifier, and discovery surfaces (progress, stats, graphify) all treat the phase as an MVP vertical slice (UI → API → DB) of one user-visible capability. |
 | `workflow.context_guard_mode` | string | `"warn"` | `"auto"`, `"warn"`, `"off"` | Context exhaustion guard mode for `execute-phase`. Before each wave, the orchestrator self-assesses context pressure using degradation signals from `context-budget.md`. `"warn"` (default): emit a warning and recommend `/gsd:pause-work` when POOR tier is detected. `"auto"`: automatically invoke `/gsd:pause-work` before the next wave when POOR tier is detected. `"off"`: disable the guard. The guard is heuristic — no programmatic context-% API exists. |
@@ -275,7 +277,7 @@ Set via `workflow.*` namespace in config.json (e.g., `"workflow": { "research":
 | `workflow.code_review_command` | string\|null | `null` | Any shell command | External code-review command integrated into `/gsd:ship`. The diff is piped to the command via stdin; the command must output JSON with a `verdict` field (`"APPROVED"` or `"REVISE"`). Non-zero exit or `"REVISE"` verdict blocks the ship workflow. When unset, the built-in review flow runs. Example: `my-review-tool --review`. |
 | `workflow.inline_plan_threshold` | number | `2` | `0`–`10` | Plans with ≤N tasks execute inline instead of spawning a subagent |
 | `workflow.code_review` | boolean | `true` | `true`, `false` | Enable built-in code review step in the ship workflow |
-| `workflow.code_review_depth` | string | `"standard"` | `"light"`, `"standard"`, `"deep"` | Depth level for code review analysis in the ship workflow |
+| `workflow.code_review_depth` | string | `"standard"` | `"quick"`, `"standard"`, `"deep"` | Depth level for code review analysis in the ship workflow |
 | `workflow._auto_chain_active` | boolean | `false` | `true`, `false` | Internal: tracks whether autonomous chaining is active |
 | `workflow.security_enforcement` | boolean | `true` | `true`, `false` | Enable threat-model-anchored security verification via `/gsd:secure-phase`. When `false`, security checks are skipped entirely |
 | `workflow.security_asvs_level` | number | `1` | `1`, `2`, `3` | OWASP ASVS verification level. Level 1 = opportunistic, Level 2 = standard, Level 3 = comprehensive. Scales both planner threat-disposition rigor (which threats must be mitigated vs. accepted) and auditor verification depth (grep-level → boundary-placement check → full data-flow trace). See `gsd-core/references/security-asvs-levels.md`. |
@@ -362,7 +364,7 @@ Set via `manager.*` namespace (e.g., `"manager": { "flags": { "discuss": "--auto
 |-----|------|---------|----------------|-------------|
 | `parallelization` | boolean\|object | `true` | `true`, `false`, `{ "enabled": true }` | Enable parallel wave execution; object form allows additional sub-keys |
 | `model_overrides` | object\|null | `null` | `{ "<agent-type>": "<model-id>" }` | Override model selection per agent type |
-| `agent_skills` | object | `{}` | `{ "<agent-type>": "<skill-set>" }` | Assign skill sets to specific agent types |
+| `agent_skills` | object | `{}` | `{ "<agent-type>": "<skill-set>" }` or `{ "<agent-type>": ["<skill-set>", "<skill-set>", ...] }` | Assign skill sets to specific agent types. Each value is a single skill-set path (string) or an array of skill-set paths — the array form assigns multiple skill sets to one agent type. Paths cannot be comma-joined into one string; each path must be its own array element |
 | `sub_repos` | array | `[]` | Array of relative path strings | Child directories with independent `.git` repos (auto-detected) |
 
 ### Planning Fields
@@ -380,7 +382,7 @@ These can be set at top level or nested under `planning.*` (e.g., `"planning": {
 
 Several config fields affect each other or trigger special behavior:
 
-1. **`commit_docs` auto-detection** -- When no explicit value is set in config.json and `.planning/` is in `.gitignore`, `commit_docs` automatically resolves to `false`. An explicit `true` or `false` in config always overrides auto-detection.
+1. **`commit_docs` resolution chain** -- Four tiers, highest wins: (1) `phase_commit_docs.<phase-id>` for the phase being committed, (2) an explicit `commit_docs` (or `planning.commit_docs`) value in config.json, (3) `.gitignore` auto-detection (`.planning/` in `.gitignore` resolves to `false`), (4) the manifest default (`true`). Precedence: per-phase → explicit config → gitignore auto-detect → default.
 
 2. **`branching_strategy` controls branch templates** -- The `phase_branch_template` and `milestone_branch_template` fields are only used when `branching_strategy` is set to `"phase"` or `"milestone"` respectively. When `branching_strategy` is `"none"`, all template fields are ignored.
 
@@ -396,7 +398,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 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.
+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. On a runtime whose declared `dispatch.isolation` is `none`, an explicit `true` is a config the execution workflows fail closed on; `/gsd:health` reports it as warning `W025` and `/gsd:settings` offers to repair it (#2486).
 
 ---
 

package/gsd-core/references/research-documentation-lookup.md

@@ -2,10 +2,12 @@ When you need library or framework documentation, check in this order:
 
 1. If Context7 MCP tools (`mcp__context7__*`) are available in your environment, use them:
    - Resolve library ID: `mcp__context7__resolve-library-id` with `libraryName`
-   - Fetch docs: `mcp__context7__get-library-docs` with `context7CompatibleLibraryId` and `topic`
+   - Fetch docs: `mcp__context7__query-docs` with `libraryId` (the ID from step 1) and `query`
 
-2. If Context7 MCP is not available (upstream bug anthropics/claude-code#13898 strips MCP
-   tools from agents with a `tools:` frontmatter restriction), use the CLI fallback via Bash:
+2. If Context7 MCP is not available (custom subagents cannot see project-scoped
+   `.mcp.json` servers — they only inherit user-scoped `~/.claude/mcp.json`, so a
+   context7 server configured at the project scope is invisible to spawned
+   agents), use the CLI fallback via Bash:
 
    Step 1 — Resolve library ID:
    ```bash

package/gsd-core/references/revision-loop.md

@@ -70,7 +70,7 @@ issues. You must reduce the count or the loop will terminate.
 If issues persist after 3 revision cycles:
 
 1. Present remaining issues to the user
-2. Use gate prompt (pattern: yes-no from `references/gate-prompts.md`):
+2. Use gate prompt (pattern: yes-no from `gsd-core/references/gate-prompts.md`):
    question: "Issues remain after 3 revision attempts. Proceed with current output?"
    header: "Proceed?"
    options:

package/gsd-core/references/specless-probe-fallback.md

@@ -119,16 +119,17 @@ if [ "$APPLICABLE" = "0" ]; then
 fi
 ```
 
-**Edge `--auto` resolution rules (reuse spec-phase 5.5 verbatim, D-06):** auto-`covered` where a
-defensible acceptance criterion can be written (→ a plain `must_haves.truths` string); else
-auto-`backstop` → author it as a **structured flat-scalar marker** `{ statement: <the check>,
+**Edge `--auto` resolution rules (reuse spec-phase 5.5 verbatim, D-06):** auto-`resolved`
+(verification: explicit) where a defensible acceptance criterion can be written (→ a plain
+`must_haves.truths` string); else auto-`resolved` (verification: backstop) → author it as a
+**structured flat-scalar marker** `{ statement: <the check>,
 verification: backstop }` in `must_haves.truths`, NOT a prose note (the verifier branches
 deterministically on the `verification: backstop` field; a parenthetical is unparseable — the #1110
 fragility; flat scalar `verification:` key, never a nested object, ADR-550 #1278). A `backstop` truth
 the verifier cannot confirm with explicit evidence abstains → `human_needed` (reason
-`insufficient_spec`), never a silent pass (#1154; `references/honest-verifier.md`). **Never
+`insufficient_spec`), never a silent pass (#1154; `gsd-core/references/honest-verifier.md`). **Never
 auto-dismiss** (a wrong dismissal is the exact silent failure this eliminates). An `unclassified` row
-stays **`unresolved`** (#1110) — never auto-`backstop`ped — and is surfaced to the planner as a flagged
+stays **`unresolved`** (#1110) — never auto-resolved with backstop — and is surfaced to the planner as a flagged
 assumption. Pass `$COVERAGE` (+ the gate's `$SPECLESS_FALLBACK_DISABLED` note) into the gsd-planner
 prompt (Step 8). When `EDGE_ABSENT=0`, `$COVERAGE` is empty and this does not run.
 
@@ -159,8 +160,8 @@ assumption — never a silent drop.
 Author the fallback report into `must_haves` with the SAME lift the SPEC path uses — only the source
 changes (the fallback report, not the SPEC):
 
-- **Edges →** every `covered` edge's acceptance criterion → `must_haves.truths` as a plain string;
-  every `backstop` edge → `must_haves.truths` as a structured `{ statement, verification: backstop }`
+- **Edges →** every resolved (verification: explicit) edge's acceptance criterion → `must_haves.truths` as a plain string;
+  every resolved (verification: backstop) edge → `must_haves.truths` as a structured `{ statement, verification: backstop }`
   marker (NOT prose; #1110/#1278), which abstains → `human_needed` at verify time when unconfirmed
   (#1154); every `unresolved`/`unclassified` row → an explicit flagged assumption (never a silent drop).
 - **Prohibitions →** every kept prohibition → the `must_haves.prohibitions:` sibling block (NOT

package/gsd-core/references/universal-anti-patterns.md

@@ -8,7 +8,7 @@ Rules that apply to ALL workflows and agents. Individual workflows may have addi
 
 1. **Never** read agent definition files (`agents/*.md`) -- `subagent_type` auto-loads them. Reading agent definitions into the orchestrator wastes context for content automatically injected into subagent sessions.
 2. **Never** inline large files into subagent prompts -- tell agents to read files from disk instead. Agents have their own context windows.
-3. **Read depth scales with context window** -- check `context_window` in `.planning/config.json`. At < 500000: read only frontmatter, status fields, or summaries. At >= 500000 (1M model): full body reads permitted when content is needed for inline decisions. See `references/context-budget.md` for the complete table.
+3. **Read depth scales with context window** -- check `context_window` in `.planning/config.json`. At < 500000: read only frontmatter, status fields, or summaries. At >= 500000 (1M model): full body reads permitted when content is needed for inline decisions. See `gsd-core/references/context-budget.md` for the complete table.
 4. **Delegate** heavy work to subagents -- the orchestrator routes, it does not build, analyze, research, investigate, or verify.
 5. **Proactive pause warning**: If you have already consumed significant context (large file reads, multiple subagent results), warn the user: "Context budget is getting heavy. Consider checkpointing progress."
 
@@ -26,7 +26,7 @@ Rules that apply to ALL workflows and agents. Individual workflows may have addi
 
 ## Questioning Anti-Patterns
 
-Reference: `references/questioning.md` for the full anti-pattern list.
+Reference: `gsd-core/references/questioning.md` for the full anti-pattern list.
 
 12. **Do not** walk through checklists -- checklist walking (asking items one by one from a list) is the #1 anti-pattern. Instead, use progressive depth: start broad, dig where interesting.
 13. **Do not** use corporate speak -- avoid jargon like "stakeholder alignment", "synergize", "deliverables". Use plain language.
@@ -59,5 +59,5 @@ Reference: `references/questioning.md` for the full anti-pattern list.
 
 ## iOS / Apple Platform Rules
 
-28. **NEVER use `Package.swift` + `.executableTarget` (or `.target`) as the primary build system for iOS apps.** SPM executable targets produce macOS CLI binaries, not iOS `.app` bundles. They cannot be installed on iOS devices or submitted to the App Store. Use XcodeGen (`project.yml` + `xcodegen generate`) to create a proper `.xcodeproj`. See `references/ios-scaffold.md` for the full pattern.
+28. **NEVER use `Package.swift` + `.executableTarget` (or `.target`) as the primary build system for iOS apps.** SPM executable targets produce macOS CLI binaries, not iOS `.app` bundles. They cannot be installed on iOS devices or submitted to the App Store. Use XcodeGen (`project.yml` + `xcodegen generate`) to create a proper `.xcodeproj`. See `gsd-core/references/ios-scaffold.md` for the full pattern.
 29. **Verify SwiftUI API availability before use.** Many SwiftUI APIs require a specific minimum iOS version (e.g., `NavigationSplitView` is iOS 16+, `List(selection:)` with multi-select and `@Observable` require iOS 17). If a plan uses an API that exceeds the declared `IPHONEOS_DEPLOYMENT_TARGET`, raise the deployment target or add `#available` guards.