@opengsd/gsd-core 1.12.0 → 1.14.0

package/gsd-core/workflows/plan-review-convergence.md

@@ -119,7 +119,7 @@ if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 
 Parse JSON for: `phase_dir`, `phase_number`, `padded_phase`, `phase_name`, `has_plans`, `plan_count`, `commit_docs`, `text_mode`, `response_language`.
 
-**If `response_language` is set:** All user-facing output should be in `{response_language}`.
+**If `response_language` is set:** All user-facing output — narration between tool calls, status updates, progress notes, findings, questions, and report prose — should be in `{response_language}`.
 
 Set `TEXT_MODE=true` if `--text` is present in $ARGUMENTS OR `text_mode` from init JSON is `true`. When `TEXT_MODE` is active, replace every `AskUserQuestion` call with a plain-text numbered list and ask the user to type their choice number.
 
@@ -341,13 +341,20 @@ Run this pass whenever the source-grounding pass ran — it is the second axis o
 
 **Coverage, never silence.** If STATE.md or CONTEXT.md is absent, that axis is skipped and the skip is recorded in the same "Verification coverage" block. A clean pass must never mean "nothing was compared."
 
-After agent returns, verify REVIEWS.md exists:
+After agent returns, verify REVIEWS.md exists. Assign the path directly and quote it — an unquoted
+`${phase_dir}` inside `$(ls …)` word-splits and glob-expands, and a discarded stderr hides it (#3899):
 ```bash
-REVIEWS_FILE=$(ls ${phase_dir}/${padded_phase}-REVIEWS.md 2>/dev/null)
+if [ -z "${phase_dir}" ]; then
+  echo "ERROR: phase_dir is empty — cannot resolve the expected REVIEWS.md path." >&2
+  exit 1
+fi
+REVIEWS_FILE="${phase_dir}/${padded_phase}-REVIEWS.md"
+if [ ! -f "${REVIEWS_FILE}" ] || [ ! -r "${REVIEWS_FILE}" ]; then
+  echo "ERROR: expected reviews file is not a readable file: '${REVIEWS_FILE}'. Confirm the phase directory resolved correctly before concluding the review agent produced nothing." >&2
+  exit 1
+fi
 ```
 
-If REVIEWS_FILE is empty: Error — review agent did not produce REVIEWS.md. Exit.
-
 ### 5b. Extract unresolved counts from CYCLE_SUMMARY Contract
 
 **Do NOT grep REVIEWS.md for HIGH or actionable counts.** REVIEWS.md accumulates history across cycles — resolved findings from prior cycles remain in the file as audit trail, inflating a raw grep count and causing false stall detection.
@@ -390,7 +397,68 @@ if [ "${ACTIONABLE_COUNT}" -gt 0 ] && [ -z "${ACTIONABLE_LINES}" ]; then
 fi
 ```
 
-**If HIGH_COUNT == 0 and ACTIONABLE_COUNT == 0 (converged):**
+**Open plan-revision conflicts are part of the converged condition (#3771).** An entry under
+`## Plan-Revision Conflicts` in REVIEWS.md is a checker `fix_hint` that contradicted a locked
+decision, capability guidance, or an existing plan constraint, recorded by `/gsd:plan-phase`
+together with the alternatives the planner considered. It is NOT counted by `CYCLE_SUMMARY`, so
+it must be read from the file directly — evaluate this BEFORE the converged branch below, or a
+run would write `planned-phase` and print the success banner over a conflict nobody resolved:
+
+```bash
+if [ ! -f "${REVIEWS_FILE}" ]; then
+  # Fail CLOSED. A missing/non-file REVIEWS.md is "I cannot tell", never "no conflicts".
+  echo "BLOCKED: cannot read REVIEWS.md ('${REVIEWS_FILE}') to check for open plan-revision conflicts. Refusing to declare convergence on an unverifiable gate." >&2
+  exit 1
+fi
+if OPEN_CONFLICTS=$(awk '
+  BEGIN { saw_title = 0; in_owned = 0; saw_heading = 0; done = 0; count = 0 }
+  { sub(/\r$/, "") }
+  !saw_title && /^# Cross-AI Plan Review — Phase / { saw_title = 1; next }
+  saw_title && !in_owned && !done {
+    if ($0 == "") next
+    if ($0 == "<!-- gsd:plan-revision-conflicts:begin -->") { in_owned = 1; next }
+    exit 2
+  }
+  in_owned && $0 == "<!-- gsd:plan-revision-conflicts:begin -->" { exit 2 }
+  in_owned && !saw_heading && $0 == "" { next }
+  in_owned && !saw_heading && $0 == "## Plan-Revision Conflicts" { saw_heading = 1; next }
+  in_owned && !saw_heading { exit 2 }
+  in_owned && $0 == "<!-- gsd:plan-revision-conflicts:end -->" {
+    done = 1
+    in_owned = 0
+    print count
+    exit
+  }
+  in_owned && /^- \[ \] REVISION_CONFLICT .*required_property:/ { count++ }
+  END { if (!done) exit 2 }
+' "${REVIEWS_FILE}"); then
+  :
+else
+  awk_status=$?
+  echo "BLOCKED: could not parse the writer-owned plan-revision conflict block in '${REVIEWS_FILE}' (awk exit ${awk_status}). Refusing to declare convergence on an unverifiable gate." >&2
+  exit 1
+fi
+```
+
+`/gsd:review` emits exactly one writer-owned slot immediately after the artifact title,
+between `<!-- gsd:plan-revision-conflicts:begin -->` and
+`<!-- gsd:plan-revision-conflicts:end -->`. Inside that slot, `/gsd:plan-phase` records each
+conflict as a `- [ ] REVISION_CONFLICT` checklist line and flips it to
+`- [x] REVISION_CONFLICT` when resolved. The reader counts only the first fixed slot at that
+position and stops at its explicit end delimiter. Reviewer output is rendered after the slot, so
+raw reviewer text containing either the heading or an exact conflict-shaped checklist line cannot
+forge blocking state. There is deliberately no fallback to the prior global line-shape scan: that
+shape never merged to `next`, and accepting both grammars would recreate the reviewer collision.
+
+**Only `/gsd:plan-phase` mutates the contents of this slot.** The review agent preserves the
+existing `## Plan-Revision Conflicts` block byte-for-byte between its delimiters; every other
+agent with write access to REVIEWS.md must leave it alone. Appending, editing, reordering or
+deleting a line there forges the state of a blocking gate. Readers read. If `OPEN_CONFLICTS` > 0, convergence has NOT been
+achieved regardless of the counts: skip the converged branch and continue to 5c so the next cycle
+arbitrates. Escalation at `MAX_CYCLES` is unchanged and still terminates the loop, so an
+unresolvable conflict escalates rather than deadlocking.
+
+**If HIGH_COUNT == 0 and ACTIONABLE_COUNT == 0 and OPEN_CONFLICTS == 0 (converged):**
 
 ```bash
 gsd_run state planned-phase --phase "${PHASE}" --name "${phase_name}" --plans "${PLAN_COUNT}"
@@ -410,11 +478,11 @@ Display:
 
 Exit — convergence achieved.
 
-**If HIGH_COUNT > 0 or ACTIONABLE_COUNT > 0:** Continue to 5c.
+**If HIGH_COUNT > 0 or ACTIONABLE_COUNT > 0 or OPEN_CONFLICTS > 0:** Continue to 5c.
 
 ### 5c. Stall Detection + Escalation Check
 
-Display: `◆ Cycle {cycle}/{MAX_CYCLES} — {HIGH_COUNT} HIGH, {ACTIONABLE_COUNT} actionable non-HIGH review concerns found`
+Display: `◆ Cycle {cycle}/{MAX_CYCLES} — {HIGH_COUNT} HIGH, {ACTIONABLE_COUNT} actionable non-HIGH review concerns, {OPEN_CONFLICTS} open plan-revision conflicts found`
 
 **Stall detection:** If `UNRESOLVED_COUNT >= prev_unresolved_count`:
 ```text
@@ -424,6 +492,29 @@ Display: `◆ Cycle {cycle}/{MAX_CYCLES} — {HIGH_COUNT} HIGH, {ACTIONABLE_COUN
 
 **Max cycles check:** If `cycle >= MAX_CYCLES`:
 
+**If `OPEN_CONFLICTS` > 0 (#3771): "Proceed anyway" is never offered.** An open plan-revision
+conflict is a blocker — this loop's whole purpose is to surface it rather than let a success
+banner paper over it, so escalation cannot end in the same silent acceptance a HIGH/actionable
+concern can. Only "Manual review" is available:
+
+If `TEXT_MODE` is true, present as plain text:
+```text
+Plan convergence did not complete after {MAX_CYCLES} cycles.
+{OPEN_CONFLICTS} open plan-revision conflict(s) remain — these are blockers and cannot be accepted:
+
+{HIGH_LINES}
+
+{ACTIONABLE_LINES}
+
+Review the concerns in: {REVIEWS_FILE}
+
+To replan manually:  /gsd:plan-phase {PHASE} --reviews
+To restart loop:     /gsd:plan-review-convergence {PHASE} {REVIEWER_FLAGS}
+```
+Exit workflow.
+
+**Otherwise (`OPEN_CONFLICTS` == 0):**
+
 If `TEXT_MODE` is true, present as plain-text numbered list:
 ```text
 Plan convergence did not complete after {MAX_CYCLES} cycles.
@@ -478,7 +569,7 @@ Display: `◆ Replanning inline with review feedback... (plan-phase runs here in
 Skill(skill="gsd-plan-phase", args="{PHASE} --reviews --skip-research {GSD_WS}")
 ```
 
-Run plan-phase **inline** (do NOT wrap it in Agent()). Same rationale as step 4: the convergence orchestrator runs at depth 0 with Agent available, so inline plan-phase can spawn gsd-planner and gsd-plan-checker at depth 1. Wrapping in Agent() pushes plan-phase to depth 1 where the Agent tool is absent — the replan loop can never produce a revised plan when HIGHs are found. This is the root cause of bug #936. Actionable MEDIUM/LOW findings must be incorporated into executable PLAN.md content or explicitly deferred/rejected in the relevant PLAN.md before convergence can complete. Wait until plan-phase completes (outputs '## PLANNING COMPLETE') and updated PLAN.md files are committed before continuing.
+Run plan-phase **inline** (do NOT wrap it in Agent()). Same rationale as step 4: the convergence orchestrator runs at depth 0 with Agent available, so inline plan-phase can spawn gsd-planner and gsd-plan-checker at depth 1. Wrapping in Agent() pushes plan-phase to depth 1 where the Agent tool is absent — the replan loop can never produce a revised plan when HIGHs are found. This is the root cause of bug #936. Actionable MEDIUM/LOW findings must be incorporated into executable PLAN.md content or explicitly deferred/rejected in the relevant PLAN.md before convergence can complete. The same holds for any open `## Plan-Revision Conflicts` entry (#3771): the replan must resolve it by adopting one of its recorded alternatives, overriding the named constraint, or amending the constraint — and mark the entry resolved. Re-running the planner against an unchanged conflict cannot resolve it and only burns a cycle. Wait until plan-phase completes (outputs '## PLANNING COMPLETE') and updated PLAN.md files are committed before continuing.
 
 After plan-phase completes → go back to **step 5a** (review again).
 
@@ -497,7 +588,8 @@ After plan-phase completes → go back to **step 5a** (review again).
 - [ ] Abort with clear error if current_actionable is absent or malformed
 - [ ] Warn if ACTIONABLE_COUNT > 0 but ## Current Actionable Non-HIGH Concerns section is absent from return message
 - [ ] The review Agent fully completes gsd-review before returning (plan-phase runs inline — no Agent wrap)
-- [ ] Loop exits on: no HIGH concerns and no actionable non-HIGH concerns (converged) OR max cycles (escalation)
+- [ ] Loop exits on: no HIGH concerns, no actionable non-HIGH concerns, and OPEN_CONFLICTS == 0 (converged) OR max cycles (escalation)
+- [ ] OPEN_CONFLICTS read from REVIEWS.md and evaluated BEFORE the converged branch writes state or prints the banner
 - [ ] Stall detection reported when total unresolved review concern count is not decreasing
 - [ ] STATE.md updated on convergence completion
 </success_criteria>

package/gsd-core/workflows/plant-seed.md

@@ -140,7 +140,7 @@ RESPONSE_LANGUAGE=$(gsd_run query config-get response_language --raw --default "
 gsd_run query commit "docs: plant seed — {$IDEA}" --files .planning/seeds/SEED-{PADDED}-{slug}.md
 ```
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 </step>
 
 <step name="confirm">

package/gsd-core/workflows/pr-branch.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Create a clean branch for pull requests by filtering .planning/ paths out of the
 cherry-picked history. Two modes, selected by the `planning.pr_strict` config key:
@@ -261,7 +263,10 @@ if [ "$PR_STRICT" = "true" ]; then
   FILTER_PATHS=".planning/"
   FORBIDDEN_RE="^\.planning/"
 else
-  FILTER_PATHS=$(for d in $TRANSIENT_DIRS; do printf '.planning/%s/ ' "$d"; done)
+  # Rewrapped through unquoted command substitution (gsd-core#4109): a bare
+  # `$VAR` word-splits under bash but not zsh, collapsing every element onto
+  # one iteration there.
+  FILTER_PATHS=$(for d in $(printf '%s' "$TRANSIENT_DIRS"); do printf '.planning/%s/ ' "$d"; done)
   FORBIDDEN_RE="^\.planning/($(echo "$TRANSIENT_DIRS" | tr ' ' '|'))/"
 fi
 ```
@@ -273,16 +278,27 @@ For each commit, check what it touches:
 FILES=$(git diff-tree --no-commit-id --name-only -r $HASH)
 NON_PLANNING=$(echo "$FILES" | grep -c -v "^\.planning/" || true)
 STRUCTURAL=$(echo "$FILES" | grep -Ec "$STRUCTURAL_RE" || true)
+PLANNING_COUNT=$(echo "$FILES" | grep -c "^\.planning/" || true)
 ```
 
-Classify:
-- **Code commits**: touch at least one non-`.planning/` file → INCLUDE (both modes)
-- **Mixed commits**: touch code + any planning files → INCLUDE (both modes; the planning
-  paths are filtered out by `create_pr_branch`, not the commit)
-- **Structural planning commits**: touch only structural `.planning/` files → INCLUDE in
+Classify, using `NON_PLANNING`, `STRUCTURAL`, and `PLANNING_COUNT` computed above — every arm's
+condition is explicit and computable so no reading of it is ambiguous:
+- **Code commits**: `NON_PLANNING > 0` and `PLANNING_COUNT == 0` → INCLUDE (both modes)
+- **Mixed code+planning commits**: `NON_PLANNING > 0` and `PLANNING_COUNT > 0` → INCLUDE (both
+  modes; the planning paths are filtered out by `create_pr_branch`, not the commit)
+- **Structural-only planning commits**: `NON_PLANNING == 0` and `STRUCTURAL == PLANNING_COUNT`
+  and `PLANNING_COUNT > 0` (every `.planning/` file touched is structural) → INCLUDE in
   **default** mode; **EXCLUDE** in strict mode, which has no structural carve-out
-- **Transient planning commits**: touch only `.planning/` paths that are not structural →
-  EXCLUDE (both modes)
+- **Mixed planning commits (#4447)**: `NON_PLANNING == 0` and `STRUCTURAL > 0` and
+  `STRUCTURAL < PLANNING_COUNT` (some but not all `.planning/` files touched are structural —
+  the rest are transient and/or the "other" bucket, e.g. `config.json`/`intel/`) → INCLUDE in
+  **default** mode (the transient-dir subset of the non-structural paths is filtered out by
+  `create_pr_branch`'s universal per-commit filter exactly as for a mixed code+planning commit;
+  any "other" non-structural, non-transient path — `config.json`, `intel/`, etc. — is simply
+  preserved, same as default mode already does for such paths on any commit); **EXCLUDE** in
+  strict mode
+- **Transient-only planning commits**: `NON_PLANNING == 0` and `STRUCTURAL == 0` and
+  `PLANNING_COUNT > 0` → EXCLUDE (both modes)
 
 In strict mode this collapses to a single rule: `NON_PLANNING > 0` → INCLUDE, else EXCLUDE.
 
@@ -292,6 +308,7 @@ Commits to include: {N} (code changes{, + structural planning — default mode o
 Commits to exclude: {N} (planning-only)
 Mixed commits: {N} (code + planning — included, planning paths filtered)
 Structural planning commits: {N} ({included|excluded — strict mode})
+Mixed planning commits: {N} ({included — structural + transient/other, planning paths filtered|excluded — strict mode})
 ```
 </step>
 
@@ -322,12 +339,15 @@ touching the same planning path makes `git cherry-pick` abort with *"untracked w
 files would be overwritten by merge"*, and every remaining commit is silently dropped.
 
 ```bash
-for HASH in $INCLUDED_COMMITS; do
+# Rewrapped through unquoted command substitution (gsd-core#4109): a bare
+# `$VAR` word-splits under bash but not zsh, collapsing every element onto
+# one iteration there.
+for HASH in $(printf '%s' "$INCLUDED_COMMITS"); do
   # A modify/delete conflict on a filtered path is EXPECTED and is resolved below — the
   # filtered path is absent from HEAD by construction. Do not treat it as a failure here.
   git cherry-pick --no-commit "$HASH" || true
 
-  for P in $FILTER_PATHS; do
+  for P in $(printf '%s' "$FILTER_PATHS"); do
     git rm -r -f -q --ignore-unmatch -- "$P" 2>/dev/null || true
     git checkout HEAD -- "$P" 2>/dev/null || true
   done

package/gsd-core/workflows/profile-user.md

@@ -19,7 +19,7 @@ _GSD_SHIM_NAME="gsd-tools.cjs"; _GSD_RUNTIME_ROOT="${RUNTIME_DIR:-$(git rev-pars
 RESPONSE_LANGUAGE=$(gsd_run query config-get response_language --raw --default "" 2>/dev/null || echo "")
 ```
 
-**If `response_language` is set:** All user-facing questions, prompts, and explanations in this workflow MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
+**If `response_language` is set:** All user-facing output of this workflow — narration between tool calls, status updates, progress notes, findings, questions, prompts, and explanations — MUST be presented in `{response_language}`. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
 
 ## 1. Initialize
 

package/gsd-core/workflows/progress/steps/forensic-audit.md

@@ -89,7 +89,7 @@ Glob every phase directory's SCOPE BOUNDARY log (executor writes out-of-scope di
 ls .planning/phases/*/deferred-items.md 2>/dev/null || true
 ```
 
-For each `deferred-items.md` found, read its entries (bullet list, one entry per top-level `- ` line, continuation lines indented beneath it). An entry is RESOLVED only if it carries an explicit `status: resolved` field (case-insensitive) on one of its lines; every other entry — including one with no `status:` field at all — is UNRESOLVED and must be surfaced (fail-safe: never silently drop a possibly-open item).
+For each `deferred-items.md` found, read its entries (bullet list, one entry per top-level list item — `-`, `*`, `+` or an ordered marker of one to nine digits terminated by a DOT, where an ordered list counts when it starts at `0.` or `1.` or continues a list already open at its level; `1)` is not a marker and neither is a ten-digit ordinal (`999999999.` counts, `1234567890.` does not) — with continuation lines indented beneath it; fenced code blocks at ANY indent, including deeper than CommonMark's three-space cap, and `* * *`-style separators are not entries; an unclosed fence ends with its own entry and never hides the entries after it; a closed pair of delimiters is a fence whatever sits between them). An entry is RESOLVED only if it carries an explicit `status: resolved` field on one of its lines — the bare key lower-case only, or the bolded `**Status:**` form in any case; the VALUE is case-insensitive in both; every other entry — including one with no `status:` field at all — is UNRESOLVED and must be surfaced (fail-safe: never silently drop a possibly-open item).
 
 Emit:
 - ✓ `No unresolved deferred items` — if no `deferred-items.md` files exist, or every entry in every file is `status: resolved`

package/gsd-core/workflows/progress.md

@@ -1,3 +1,5 @@
+@~/.claude/gsd-core/references/response-language-directive.md
+
 <purpose>
 Check project progress, summarize recent work and what's ahead, then intelligently route to the next action — either executing an existing plan or creating the next one. Provides situational awareness before continuing work.
 </purpose>
@@ -18,13 +20,33 @@ INIT=$(gsd_run query init.progress $FORENSIC_PARAM)
 if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
 ```
 
-Extract from init JSON: `project_exists`, `roadmap_exists`, `state_exists`, `phases`, `current_phase`, `next_phase`, `milestone_version`, `completed_count`, `phase_count`, `paused_at`, `state_path`, `roadmap_path`, `project_path`, `config_path`, `phase_mvp_mode`.
+Extract from init JSON: `project_exists`, `roadmap_exists`, `state_exists`, `requirements_exists`, `planning_exists`, `milestones_exists`, `init_incomplete`, `phases`, `current_phase`, `next_phase`, `milestone_version`, `completed_count`, `phase_count`, `paused_at`, `state_path`, `roadmap_path`, `project_path`, `config_path`, `phase_mvp_mode`.
 
 ```bash
 DISCUSS_MODE=$(gsd_run query config-get workflow.discuss_mode --raw 2>/dev/null || echo "discuss")
 ```
 
-If `project_exists` is false (no `.planning/` directory):
+**If `init_incomplete` is true (#4040 — interrupted bootstrap):**
+
+`.planning/` exists but the core initialization artifacts are missing (one or more of `REQUIREMENTS.md`, `ROADMAP.md`, `STATE.md` were never created — a bootstrap that stopped partway, e.g. after PROJECT.md). This is NOT a new project, NOT a missing STATE.md, and NOT a between-milestones state — do not fall through to any of those routes. Route to initialization recovery:
+
+```
+---
+
+## ⚠ Initialization Incomplete
+
+A partial `.planning/` was found: project initialization started but stopped before creating all core artifacts (missing: REQUIREMENTS.md, ROADMAP.md, STATE.md — whichever `requirements_exists` / `roadmap_exists` / `state_exists` report as false).
+
+`/clear` then:
+
+`/gsd:new-project` — resumes initialization from the first missing artifact; existing PROJECT.md (and any already-created artifacts) are kept, not regenerated.
+
+---
+```
+
+Exit. (The payload's `init_incomplete` is computed with the between-milestones archive case excluded — `MILESTONES.md` present means missing ROADMAP/REQUIREMENTS is archival, and that state still routes to Route F below.)
+
+If `init_incomplete` is false and `planning_exists` is false and `project_exists` is false (no `.planning/` directory at all):
 
 ```
 No planning structure found.
@@ -36,7 +58,7 @@ Exit.
 
 If missing STATE.md: suggest `/gsd:new-project`.
 
-**If ROADMAP.md missing but PROJECT.md exists:**
+**If ROADMAP.md missing but PROJECT.md exists (and `init_incomplete` is false):**
 
 This means a milestone was completed and archived. Go to **Route F** (between milestones).
 

package/gsd-core/workflows/quick/steps/plan-checker-loop.md

@@ -56,7 +56,7 @@ Agent(
 **Handle checker return:**
 
 - **`## VERIFICATION PASSED`:** Display confirmation, proceed to step 6.
-- **`## ISSUES FOUND`:** Display issues, check iteration count, enter revision loop.
+- **`## ISSUES FOUND`:** Count BLOCKER + WARNING entries in the YAML issues block; an entry whose severity is missing or unrecognized counts as a BLOCKER (fail closed). If zero — every entry is explicitly INFO — display `ℹ advisory — {dimension}: {description}` per entry and proceed to step 6; INFO is advisory and never enters the loop (#3724). Otherwise display issues, check iteration count, enter revision loop.
 
 **Revision loop (max 2 iterations):**
 
@@ -68,6 +68,8 @@ Display: `Sending back to planner for revision... (iteration ${N}/2)`
 
 Revision prompt:
 
+Reuse the `PLAN_PRE_HOOKS_JSON` snapshot captured by Quick Step 5; do not render hooks again.
+
 ```markdown
 <revision_context>
 **Mode:** quick-full (revision)
@@ -78,12 +80,23 @@ Revision prompt:
 
 ${AGENT_SKILLS_PLANNER}
 
+{For each active entry in `PLAN_PRE_HOOKS_JSON` where `kind == "contribution"` and `into == "planner"` (in array order): inject the entry's `fragment.inline` verbatim here, plus its resolved `configValues` when the entry carries them. If no active planner contributions exist, omit this block entirely.}
+
 **Checker issues:** ${structured_issues_from_checker}
 
 </revision_context>
 
 <instructions>
 Make targeted updates to address checker issues.
+
+`required_property` + evidence + severity BIND. `fix_hint` is ONE non-binding example route: a
+smaller or different mechanism reaching the same property addresses the issue in full — say which
+you used. Re-check ${DISCUSS_MODE ? 'locked decisions in ' + quick_id + '-CONTEXT.md, ' : ''}capability guidance (CLAUDE.md, project skills) and the
+constraints these plans already encode BEFORE editing; if a hint would contradict one, or the
+property is unreachable without breaking one, return `## REVISION_CONFLICT` with the conflict and
+the alternatives rather than applying or working around it. Full contract:
+`gsd-core/references/planner-revision.md`, which you load in revision mode.
+
 Do NOT replan from scratch unless issues are fundamental.
 Return what changed.
 </instructions>
@@ -100,7 +113,29 @@ Agent(
 
 > **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above, stop working on this task immediately. Do not read more files, edit code, or run tests related to this task while the subagent is active. Wait for the subagent to return its result. This prevents duplicate work, conflicting edits, and wasted context. Only resume when the subagent result is available.
 
-After planner returns → spawn checker again, increment iteration_count.
+**If the planner returns `## REVISION_CONFLICT`:** a conflict is not resolvable by re-running the
+same loop, so it must not consume retry budget. Do NOT increment `iteration_count` and do NOT
+re-spawn the checker yet. Present the conflict table and its alternatives to the user and ask
+which to take: adopt a named alternative / override the named constraint and apply the hint /
+amend the constraint itself. Every option resolves the conflict. Accepting the plan with the
+blocker still open is NOT offered here — the blocking `required_property` still fails, and that
+choice belongs to the max-iteration escalation below, which is unchanged.
+
+A quick task has no REVIEWS.md and no phase, so `workflow.plan_review_convergence` has nothing to
+arbitrate over here; the user is the only route. `plan-phase` is where the convergence hand-off
+lives.
+
+Re-spawn the planner with the chosen resolution, then **re-evaluate its return from the top of
+this handler** — do not fall through to the checker spawn below. A second conflict is still a
+conflict, not a revised plan.
+
+**Bounded:** A conflict naming the SAME `required_property` twice in a row (no successful revision in between) is a stall, and so is the
+THIRD conflict return of this loop whatever property it names — alternating property names
+would otherwise never trip the repeat rule and the path would be unbounded. Stop re-spawning and
+route it to the same iteration-count check below, so declining to spend an iteration cannot make
+this path unbounded.
+
+**Otherwise (the planner returns a revised plan, not `## REVISION_CONFLICT`):** spawn checker again, increment `iteration_count`.
 
 **If iteration_count >= 2:**
 

package/gsd-core/workflows/quick/steps/research-phase.md

@@ -13,7 +13,7 @@ Spawn a single focused researcher (not 4 parallel researchers like full phases
 
 <!-- #2517 model-omit-on-inherit -->
 
-> **Model omission (#2517).** Omit the `model` parameter entirely when the value it would carry (`planner_model`, `checker_model`, `executor_model`, `reviewer_model`, `verifier_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.
+> **Model omission (#2517).** Omit the `model` parameter entirely when the value it would carry (`planner_model`, `checker_model`, `executor_model`, `reviewer_model`, `verifier_model`, `researcher_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.
 
 <!-- #2508 runtime-aware-dispatch -->
 
@@ -35,7 +35,7 @@ Agent(
 ${DISCUSS_MODE ? '- ' + QUICK_DIR + '/' + quick_id + '-CONTEXT.md (User decisions — research should align with these. #3894: when workflow.research_before_questions is enabled research runs BEFORE discussion, so this file will not exist yet — read it only if present)' : ''}
 </required_reading>
 
-${AGENT_SKILLS_PLANNER}
+${AGENT_SKILLS_RESEARCHER}
 
 </research_context>
 
@@ -56,7 +56,7 @@ Return: ## RESEARCH COMPLETE with file path
 </output>
 ",
   subagent_type="gsd-phase-researcher",
-  model="{planner_model}",
+  model="{researcher_model}",
   description="Research: ${DESCRIPTION}"
 )
 ```

package/gsd-core/workflows/quick-batch/steps/batch-init.md

@@ -0,0 +1,55 @@
+**Step 2b: Create a new batch (only when `$RESUME_BATCH_ID` is empty)**
+
+Skip this step entirely if `$RESUME_BATCH_ID` is set (resume-mode.md owns
+that path instead).
+
+**Get the task list.** If `--file <path>` was present in `$ARGUMENTS`, use its
+value as `$TASK_FILE`. Otherwise the remaining, non-flag text of `$ARGUMENTS`
+IS the inline task list (a bulleted/numbered list, ≥2 items — the same
+grammar `parseTaskList` enforces).
+
+If `$TASK_FILE` is set:
+```bash
+_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}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif _gsd_at "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd_run is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; case "$(gsd_run runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@opengsd/gsd-core"'*'}') GSD_IDENTITY_STATUS=ok;; esac; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @opengsd/gsd-core - it is either a different package or an @opengsd/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; 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
+QB_CREATE_JSON=$(gsd_run quick-batch create --file "$TASK_FILE" --base-revision "$(git rev-parse HEAD)" --raw)
+```
+
+Otherwise, the inline list must land on disk first — `quick-batch create`
+only accepts `--file` (path-confined, same as `/gsd:quick-batch`'s own
+security posture): write it to a scratch file under `.planning/` before
+calling the verb.
+```bash
+TASK_FILE="${quick_dir%/quick}/.quick-batch-task-list.tmp"
+mkdir -p "$(dirname "$TASK_FILE")"
+printf '%s\n' "$INLINE_TASK_LIST" > "$TASK_FILE"
+QB_CREATE_JSON=$(gsd_run quick-batch create --file "$TASK_FILE" --base-revision "$(git rev-parse HEAD)" --raw)
+rm -f "$TASK_FILE"
+```
+
+```bash
+QB_CREATE_RC=$?
+if [[ "$QB_CREATE_JSON" == @file:* ]]; then QB_CREATE_JSON=$(cat "${QB_CREATE_JSON#@file:}"); fi
+```
+
+**If `$QB_CREATE_RC` is non-zero:** the task list failed to parse (fewer than
+2 items — row 2/12) or the dependency DAG was invalid. Print the CLI's error
+message verbatim and STOP. Do not dispatch anything.
+
+**Otherwise:** parse `$QB_CREATE_JSON` for `batchId` and `manifest` (every
+item starts `pending`, wave `0` — no dependency/file-overlap signal exists
+yet before planning; this is expected, not a bug, per the design's negative-
+space note).
+
+```bash
+BATCH_ID="$batchId"
+BATCH_MANIFEST_JSON=$(printf '%s' "$QB_CREATE_JSON" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{const j=JSON.parse(s);process.stdout.write(JSON.stringify(j.manifest))}catch{process.stdout.write("")}})')
+ITEM_COUNT=$(printf '%s' "$BATCH_MANIFEST_JSON" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{const j=JSON.parse(s);process.stdout.write(String(j.items.length))}catch{process.stdout.write("0")}})')
+```
+
+Report to user:
+```
+Creating quick batch ${BATCH_ID}: ${ITEM_COUNT} item(s).
+Manifest: .planning/quick-batches/${BATCH_ID}/BATCH.json
+```
+
+Continue to Step 3 in `quick-batch.md`.

package/gsd-core/workflows/quick-batch/steps/completion.md

@@ -0,0 +1,65 @@
+**Step 9: Completion**
+
+For every item that merged successfully in Step 7 AND (NOT `$VALIDATE_MODE`,
+OR Step 8 routed it to `complete`): call `completeQuickItem` via its CLI verb
+— this is the ONLY writer of a "Quick Tasks Completed" STATE.md row and the
+item's `complete` status; both happen inside ONE lock transaction, exactly
+once per item (idempotent — re-running this step for an already-complete
+item is a no-op, same guarantee `/gsd:quick` relies on):
+
+```bash
+_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}"; _gsd_at() { for _p; do if [ -f "$_p" ]; then GSD_TOOLS="$_p"; return 0; fi; done; return 1; }; if _gsd_at "${_GSD_RUNTIME_ROOT}/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.claude/gsd-core/bin/${_GSD_SHIM_NAME}" "${_GSD_RUNTIME_ROOT}/.codex/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; elif unset -f gsd_run; _G="$(command -v gsd_run)"; then GSD_TOOLS="$_G"; gsd_run() { "$GSD_TOOLS" "$@"; }; elif _gsd_at "${CLAUDE_CONFIG_DIR:-$HOME/.claude}/gsd-core/bin/${_GSD_SHIM_NAME}" "${HERMES_HOME:-$HOME/.hermes}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CURSOR_CONFIG_DIR:-$HOME/.cursor}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEX_HOME:-$HOME/.codex}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GEMINI_CONFIG_DIR:-$HOME/.gemini}/gsd-core/bin/${_GSD_SHIM_NAME}" "${COPILOT_CONFIG_DIR:-$HOME/.copilot}/gsd-core/bin/${_GSD_SHIM_NAME}" "${WINDSURF_CONFIG_DIR:-$HOME/.codeium/windsurf}/gsd-core/bin/${_GSD_SHIM_NAME}" "${AUGMENT_CONFIG_DIR:-$HOME/.augment}/gsd-core/bin/${_GSD_SHIM_NAME}" "${TRAE_CONFIG_DIR:-$HOME/.trae}/gsd-core/bin/${_GSD_SHIM_NAME}" "${QWEN_CONFIG_DIR:-$HOME/.qwen}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CODEBUDDY_CONFIG_DIR:-$HOME/.codebuddy}/gsd-core/bin/${_GSD_SHIM_NAME}" "${CLINE_CONFIG_DIR:-$HOME/.cline}/gsd-core/bin/${_GSD_SHIM_NAME}" "${GROK_AGENTS_HOME:-$HOME/.agents}/gsd-core/bin/${_GSD_SHIM_NAME}" "${ANTIGRAVITY_CONFIG_DIR:-$HOME/.gemini/antigravity}/gsd-core/bin/${_GSD_SHIM_NAME}" "${OPENCODE_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/opencode}/gsd-core/bin/${_GSD_SHIM_NAME}" "${KILO_CONFIG_DIR:-${XDG_CONFIG_HOME:-$HOME/.config}/kilo}/gsd-core/bin/${_GSD_SHIM_NAME}"; then gsd_run() { node "$GSD_TOOLS" "$@"; }; else echo "ERROR: gsd-tools.cjs not found at $GSD_TOOLS and gsd_run is not on PATH. Run: npx -y @opengsd/gsd-core@latest --claude --local" >&2; exit 1; fi; GSD_IDENTITY_STATUS=unverified; case "$(gsd_run runtime-identity --raw 2>/dev/null || true)" in '{"packageName":"@opengsd/gsd-core"'*'}') GSD_IDENTITY_STATUS=ok;; esac; export GSD_IDENTITY_STATUS; [ "$GSD_IDENTITY_STATUS" = ok ] || echo "WARNING: \"$GSD_TOOLS\" did not prove it is @opengsd/gsd-core - it is either a different package or an @opengsd/gsd-core older than the runtime-identity verb. See docs/how-to/diagnose-a-foreign-gsd-tools.md" >&2; 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
+gsd_run quick-batch complete \
+  --batch "$BATCH_ID" \
+  --quick-id "$quick_id" \
+  --description "$description" \
+  --date "$date" \
+  --commit "$commit_hash" \
+  --directory "$ITEM_DIR" \
+  --raw
+```
+
+Items NOT reaching this call — `human_needed`, `failed` (planner/checker/
+merge/verification failure), or still `blocked`/`pending` (a dependency
+failed, row 32) — are left exactly as their respective routing step set
+them. No STATE row, no `complete` status, worktree preserved where
+applicable.
+
+**Final commit.** Stage every artifact produced this run (PLAN.md, SUMMARY.md,
+`--research` RESEARCH.md, `--validate` VERIFICATION.md, per item, plus
+`.planning/STATE.md`) and commit:
+`$BATCH_ARTIFACT_FILES` is a bash ARRAY (not a plain string — a plain
+space-joined string re-splits unpredictably under `set -f`/globbing and
+diverges between bash and zsh, the #4109 word-splitting bug class):
+```bash
+COMMIT_DOCS=$(gsd_run query config-get commit_docs --raw 2>/dev/null || echo "true")
+if [ "$COMMIT_DOCS" != "false" ]; then
+  git add "${BATCH_ARTIFACT_FILES[@]}" 2>/dev/null
+  gsd_run query commit "docs(quick-batch-${BATCH_ID}): ${ITEM_COUNT} item(s)" --files "${BATCH_ARTIFACT_FILES[@]}"
+fi
+```
+
+**Final report.** Re-load the batch (`gsd_run quick-batch resume --batch
+"$BATCH_ID" --raw` — read-only in effect when nothing changed) and summarize
+by status:
+
+```
+---
+GSD > QUICK BATCH COMPLETE
+
+Batch ${BATCH_ID}: ${ITEM_COUNT} item(s)
+  Complete: ${complete_count}
+  Failed: ${failed_count}${failed_count > 0 ? ' (' + failed_reasons + ')' : ''}
+  Needs review: ${human_needed_count}
+  Blocked: ${blocked_count}
+
+${failed_count + human_needed_count > 0 ? 'Resume after resolving: /gsd:quick-batch --resume ' + BATCH_ID : ''}
+---
+```
+
+If EVERY item is `complete`, this is a clean finish — no further action
+needed. If any item is `failed`/`human_needed`/`blocked`, the batch stays
+resumable: fix the underlying issue (or accept the failure), then re-run
+`/gsd:quick-batch --resume ${BATCH_ID}` — `resumeBatch`'s own propagation
+(unmodified from Phase 3) re-evaluates eligibility from the current state, no
+special quick-batch-side recovery logic needed.