@opengsd/gsd-core 1.12.0 → 1.14.0

package/gsd-core/workflows/execute-phase/steps/executor-isolation-dispatch.md

@@ -149,8 +149,12 @@ Assign the composed prompt to a shell variable so it can be passed as one argume
 #      An unreadable source file is a halt condition (#3637 fail-closed),
 #      never a skip — a child without these texts is not a gsd-executor.
 #   2. Substitute this plan's {plan_number}, {phase_number}, {phase_name},
-#      {phase_dir}, and {plan_file} placeholders (same values the harness
-#      path substitutes into its Agent() prompt).
+#      {phase_dir}, {plan_file}, and {plan_id} placeholders (same values the
+#      harness path substitutes into its Agent() prompt). {plan_id} is this
+#      plan's `id` field from the phase-plan-index JSON — the guard hooks
+#      compare it verbatim against the sentinel the per-plan gate wrote, so a
+#      paraphrase or omission costs the dispatch its recorded isolation
+#      decision.
 #   3. Inline the gsd-executor ROLE DEFINITION: read `agents/gsd-executor.md`
 #      (resolved against the install root the same way the harness runtime
 #      resolves subagent types) and inline it verbatim at the provenance
@@ -161,8 +165,21 @@ Assign the composed prompt to a shell variable so it can be passed as one argume
 #      no host subagent machinery, so the role definition must ride the prompt
 #      (#3637 acceptance: resolved agent instructions as launch-level
 #      instructions + provenance of which role definition was used).
+# Resolve TDD-applicability for THIS plan (#4266/#4272) — fail closed on
+# command failure, mirroring the ISOLATION resolution above: an absent
+# verdict must never silently resolve to "not TDD" (ADR-3473 §8.4), since
+# that would silently drop a real TDD plan's RED/GREEN/REFACTOR procedure.
+_TDD_APPLICABLE_RAW=$(gsd_run query phase.tdd-applicable "{phase_dir}/{plan_file}" --pick applicable 2>/dev/null)
+_TDD_APPLICABLE_RC=$?
+if [ $_TDD_APPLICABLE_RC -ne 0 ]; then
+  echo "FATAL: could not resolve TDD-applicability for plan {plan_number} — 'gsd_run query phase.tdd-applicable' failed. Refusing to guess whether this dispatch needs the TDD procedure. Halting." >&2
+  exit 1
+fi
+TDD_APPLICABLE="$_TDD_APPLICABLE_RAW"
+
 EXECUTOR_PROMPT='<objective>
 Execute plan {plan_number} of phase {phase_number}-{phase_name}.
+[gsd:dispatch phase="{phase_number}" plan="{plan_id}"]
 Commit each task atomically. Create SUMMARY.md.
 Do NOT update STATE.md or ROADMAP.md — the orchestrator owns those writes after all worktree agents in the wave complete.
 </objective>
@@ -181,7 +198,7 @@ the executor workflow from repository search.
   SUMMARY commit semantics and the gitignored-planning skip contract)
 - summary.md template
 - checkpoints.md
-- tdd.md
+${TDD_APPLICABLE ? "- tdd.md" : ""}  # #3990/#4265: only when this dispatch is TDD (plan type: tdd, a tdd="true" task, or workflow.tdd_mode config)
 - worktree-path-safety.md
 - agents/gsd-executor.md (the ROLE DEFINITION you are executing — its steps
   0/0a/0b per-commit HEAD/cwd-drift/path-guard discipline applies to every
@@ -257,6 +274,10 @@ printf '%s' "$EXECUTOR_PROMPT" | grep -q '\${AGENT_SKILLS}' && {
   echo "FATAL: executor prompt for plan {plan_number} still contains the un-substituted \${AGENT_SKILLS} marker — the role definition was not spliced in (#3637). Halting." >&2
   exit 1
 }
+printf '%s' "$EXECUTOR_PROMPT" | grep -q '\${TDD_APPLICABLE' && {
+  echo "FATAL: executor prompt for plan {plan_number} still contains the un-substituted \${TDD_APPLICABLE marker — the TDD-applicability decision was not resolved into the prompt (#4266). Halting." >&2
+  exit 1
+}
 ```
 
 The prompt body must contain no single-quote character, since the assignment above is single-quoted; keep apostrophes out of it when editing.

package/gsd-core/workflows/execute-phase/steps/executor-progress-policy.md

@@ -0,0 +1,43 @@
+Apply response_language to all user-facing prose — narration between tool calls, status updates, progress notes, and findings included; preserve code, paths, and identifiers.
+
+# Executor Progress Policy (#4218)
+
+Read this before treating any executor as stalled.
+
+## A working executor is never steered
+
+The stall threshold measures a period **without meaningful progress**. It is not a maximum
+total runtime, and it is not a budget the executor has to finish inside. A plan with a long
+verification or closeout tail legitimately spends many minutes between its last commit and
+its SUMMARY.
+
+Reconcile activity as well as artifacts:
+
+- **Commits exist and SUMMARY.md is missing, with recent meaningful activity → KEEP
+  WAITING.** Do not steer it, do not interrupt it, do not re-dispatch it. Recent
+  RED/GREEN/REFACTOR commits, passing verification, or ongoing reasoning/tool telemetry
+  from the child are all meaningful activity.
+- **Only after `${EXECUTOR_STALL_THRESHOLD_MINUTES}` of no meaningful progress** — measured
+  from the LAST sign of progress, not from dispatch — may the pause in step 3 fire, and it
+  asks the user; it does not act on its own.
+
+## Never inject urgency or finalization instructions into a live executor
+
+Messages of the "Finalize immediately", "wrap up now", "you are taking too long" family are
+forbidden: they arrive mid-verification and turn a correct run into a truncated one. If an
+executor must be stopped, the pause in step 3 is the only route, and `kill and retry` is a
+clean restart — not a nudge.
+
+## The absence of a local OS test/build process is NOT idleness
+
+The orchestrator cannot see the child's work that way. A native subagent runs in the
+runtime's own session, not as a visible local process, and an executor between two tool
+calls — reasoning, reading a file, waiting on a runtime round-trip — shows no process at
+all. Judge progress ONLY by the signals this workflow names: commits on the expected
+branch, the SUMMARY, and the child's own activity. A process listing is not one of them.
+
+## If a stalled executor ran in an isolated worktree
+
+`kill and switch to inline execution` edits the primary checkout — see worktree recovery
+policy (`execute-phase/steps/worktree-recovery-policy.md`). Prefer `kill and retry` in a
+fresh worktree; inline execution requires explicit confirmation, never the default.

package/gsd-core/workflows/execute-phase/steps/per-plan-worktree-gate.md

@@ -48,12 +48,18 @@ if [ -n "$SUBMODULE_PATHS" ] && [ "$USE_WORKTREES_FOR_PLAN" != "false" ]; then
     # submodule "vendor/foo".
     INTERSECT=""
     set -f  # disable globbing while iterating literal patterns
-    for sm_raw in $SUBMODULE_PATHS; 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 sm_raw in $(printf '%s' "$SUBMODULE_PATHS"); do
       # Normalize submodule path: strip ./ prefix and trailing /
       sm="${sm_raw#./}"
       sm="${sm%/}"
       [ -z "$sm" ] && continue
-      for pf_raw in $PLAN_SCOPE_PATHS; 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 pf_raw in $(printf '%s' "$PLAN_SCOPE_PATHS"); do
         # Normalize planned path the same way
         pf="${pf_raw#./}"
         pf="${pf%/}"

package/gsd-core/workflows/execute-phase/steps/regression-gate-run.md

@@ -1,3 +1,5 @@
+Apply response_language to all user-facing prose — narration between tool calls, status updates, progress notes, and findings included; preserve code, paths, and identifiers.
+
 # Step: regression_gate_run
 
 Run the resolved prior-phase test command one-shot, bounded by a timeout, so a

package/gsd-core/workflows/execute-phase/steps/sequential-root-pin.md

@@ -0,0 +1,35 @@
+# Sequential root pin (#4254)
+
+Apply response_language to all user-facing prose — narration between tool calls, status
+updates, progress notes, and findings included; preserve code, paths, and identifiers.
+
+Read and execute this fragment from `execute-phase.md`'s **Sequential mode** branch before
+composing any sequential dispatch prompt. It owns the sequential root-pin build-time embed,
+the `<required_reading>` root substitution, and the wave serialization rules.
+
+## Root pin — ORCHESTRATOR build-time embed (#4254; NOT a sub-agent runtime step)
+
+Before this dispatch, read `gsd-core/references/worktree-path-safety.md` step 0p
+("Supplied-root pin") and copy its guard template into this prompt inside a
+`<project_root_pin>` block, substituting `{PINNED_ROOT}` with the literal value of
+`$ORCHESTRATOR_WT` resolved at execute_waves entry, shell-single-quoted per that section's
+composition contract — the dispatched prompt must carry the bound, runnable guard verbatim;
+do not pass this instruction through in its place.
+
+In this dispatch's `<required_reading>`, also replace the self-derivation line
+`PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)` with
+`PROJECT_ROOT='<the same literal $ORCHESTRATOR_WT>'` — a sequential executor must never
+re-derive its root from its own (possibly drifted) cwd. This substitution is sequential-mode
+ONLY: worktree-mode dispatches keep the self-derived line — an isolated executor's own
+toplevel IS its correct (and intentionally different) worktree, and substituting the
+orchestrator's root there would break every worktree-mode dispatch.
+
+## Wave serialization (moved verbatim from the host step — ADR-857 Phase 6 ceiling, #1168)
+
+When worktrees are disabled for a plan (per-plan or project-level), that plan's executor runs
+on the main working tree. If **any** plan in the current wave dropped to sequential mode,
+execute the affected plan(s) **one at a time** to avoid concurrent writes to the main working
+tree — plans in the same wave that retained worktree isolation can still run in parallel
+alongside the sequential ones, but two non-worktree plans in the same wave must serialize.
+When the project-level `USE_WORKTREES=false`, all plans in the wave serialize regardless of
+the `PARALLELIZATION` setting.

package/gsd-core/workflows/execute-phase/steps/tdd-applicability-resolution.md

@@ -0,0 +1,25 @@
+# TDD-applicability resolution (#4266/#4272)
+
+Run for each plan, immediately after executor routing and before composing
+that plan's `Agent()` prompt in step 3. Resolves whether this dispatch is TDD
+— fail closed, do not guess.
+
+## Resolution
+
+```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
+TDD_APPLICABLE_RAW=$(gsd_run query phase.tdd-applicable "{phase_dir}/{plan_file}" --pick applicable 2>/dev/null)
+TDD_APPLICABLE_RC=$?
+if [ $TDD_APPLICABLE_RC -ne 0 ]; then
+  echo "FATAL: could not resolve TDD-applicability for plan {plan_number} — 'gsd_run query phase.tdd-applicable' failed. Refusing to guess whether this dispatch needs the TDD procedure. Halting." >&2
+  exit 1
+fi
+TDD_APPLICABLE="$TDD_APPLICABLE_RAW"
+```
+
+## Pre-dispatch check (MANDATORY)
+
+Before calling Agent(), confirm every `${...}` conditional in the prompt below
+(`TDD_APPLICABLE`, `CONTEXT_WINDOW`, `AGENT_SKILLS`) was resolved to concrete
+text for THIS plan. If any marker's value was not computed, HALT — do not
+dispatch a prompt containing literal `${...}` template syntax (#4266).

package/gsd-core/workflows/execute-phase/steps/worktree-recovery-policy.md

@@ -1,3 +1,5 @@
+Apply response_language to all user-facing prose — narration between tool calls, status updates, progress notes, and findings included; preserve code, paths, and identifiers.
+
 # Worktree Recovery Policy
 
 ## ORCHESTRATOR FAIL-CLOSED RULE (#48)