@opengsd/gsd-core 1.6.0 → 1.7.0-rc.1

package/gsd-core/bin/lib/surface.cjs

@@ -43,6 +43,9 @@ const runtimeArtifactLayout = require("./runtime-artifact-layout.cjs");
 const { findInstallSourceRoot } = runtimeArtifactLayout;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const runtimeArtifactConversion = require("./runtime-artifact-conversion.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const runtimeArtifactInstallPlan = require("./runtime-artifact-install-plan.cjs");
+const { assertDestWithinConfigHome } = runtimeArtifactInstallPlan;
 const SURFACE_FILE_NAME = '.gsd-surface.json';
 /**
  * Read the surface state from a runtime config directory.
@@ -302,7 +305,7 @@ function applySurface(runtimeConfigDir, layout, manifest, clusterMap, registry)
                     tempDirsToClean.push(rewritten);
                 }
             }
-            const dest = node_path_1.default.join(layout.configDir, kind.destSubpath);
+            const dest = assertDestWithinConfigHome(layout.configDir, kind.destSubpath);
             _syncGsdDir(staged, dest, kind, skillManifest);
         }
     }

package/gsd-core/bin/lib/workstream.cjs

@@ -67,7 +67,7 @@ function migrateToWorkstreams(cwd, workstreamName) {
             const src = node_path_1.default.join(baseDir, item.name);
             if (node_fs_1.default.existsSync(src)) {
                 const dest = node_path_1.default.join(wsDir, item.name);
-                node_fs_1.default.renameSync(src, dest);
+                (0, shell_command_projection_cjs_1.retryRenameSync)(src, dest);
                 filesMoved.push(item.name);
             }
         }
@@ -75,7 +75,7 @@ function migrateToWorkstreams(cwd, workstreamName) {
     catch (err) {
         for (const name of filesMoved) {
             try {
-                node_fs_1.default.renameSync(node_path_1.default.join(wsDir, name), node_path_1.default.join(baseDir, name));
+                (0, shell_command_projection_cjs_1.retryRenameSync)(node_path_1.default.join(wsDir, name), node_path_1.default.join(baseDir, name));
             }
             catch { /* ignore */ }
         }
@@ -275,14 +275,14 @@ function cmdWorkstreamComplete(cwd, name, options, raw) {
     try {
         const entries = node_fs_1.default.readdirSync(wsDir, { withFileTypes: true });
         for (const entry of entries) {
-            node_fs_1.default.renameSync(node_path_1.default.join(wsDir, entry.name), node_path_1.default.join(archivePath, entry.name));
+            (0, shell_command_projection_cjs_1.retryRenameSync)(node_path_1.default.join(wsDir, entry.name), node_path_1.default.join(archivePath, entry.name));
             filesMoved.push(entry.name);
         }
     }
     catch (err) {
         for (const fname of filesMoved) {
             try {
-                node_fs_1.default.renameSync(node_path_1.default.join(archivePath, fname), node_path_1.default.join(wsDir, fname));
+                (0, shell_command_projection_cjs_1.retryRenameSync)(node_path_1.default.join(archivePath, fname), node_path_1.default.join(wsDir, fname));
             }
             catch { /* ignore */ }
         }

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

@@ -10,6 +10,10 @@
     "brave_search",
     "firecrawl",
     "exa_search",
+    "tavily_search",
+    "ref_search",
+    "perplexity",
+    "jina",
     "workflow.plan_check",
     "workflow.verifier",
     "workflow.auto_advance",
@@ -172,6 +176,11 @@
       "source": "^review\\.max_prompt_tokens_per_reviewer\\.[a-zA-Z0-9_-]+$",
       "description": "review.max_prompt_tokens_per_reviewer.<reviewer-slug>"
     },
+    {
+      "topLevel": "review",
+      "source": "^review\\.reviewer_instances\\.[a-zA-Z0-9_-]+\\.(cli|model|agent)$",
+      "description": "review.reviewer_instances.<instance-name>.<cli|model|agent> (#1517)"
+    },
     {
       "topLevel": "model_policy",
       "source": "^model_policy\\.runtime_tiers\\.[a-zA-Z0-9_-]+\\.(opus|sonnet|haiku)$",

package/gsd-core/references/honest-verifier.md

@@ -0,0 +1,105 @@
+# Honest Verifier — Abstention on Non-Inferable Checks
+
+Shared reference for the **verify** phase. The verify-time companion to the spec-time
+`@~/.claude/gsd-core/references/edge-probe.md` (which *classifies* non-inferable checks) and
+`@~/.claude/gsd-core/references/prohibition-probe.md` (whose judgment-tier disposition this mirrors).
+This doc is written in generic `spec → predicate → verifier` terms with no tool-specific vocabulary,
+so it is portable: copy it into any verification process.
+
+## The problem it solves
+
+A verifier is trustworthy on **inferable** checks — defects determined by the stated spec. On a
+**non-inferable** check the correct answer is *not derivable from the spec alone* (e.g. "does `[1,2]`
+touching `[2,3]` merge?", "is a 'character' a grapheme or a code unit?"). On these the verifier *does
+not know that it does not know*: measured behavior is a **confident PASS on the blind-spot check ~100%
+of the time** (mean confidence ~0.93), because a model cannot self-detect a gap it does not perceive.
+
+The edge-probe already detects these at spec time and tags them `verification: backstop` (ADR-550
+D7a). The honest verifier consumes that tag so the verifier **abstains** instead of confidently
+false-passing — converting a silent false-pass (the worst failure: you don't know to look) into an
+explicit, actionable "write a held-out test." Measured: the confident-false-pass rate on the blind
+spot drops **100% → 17%** (N17).
+
+## The two properties that define the design
+
+1. **Exogenous, not endogenous.** The trigger is the *external tag* (`backstop`), never the verifier's
+   self-judgment. Asking the verifier to "abstain if unsure" barely moves the number (100% → 67%) and
+   only on ambiguity it already notices; on a true blind spot it stays confidently wrong. A confidence
+   gate cannot reach a blind spot the model does not feel — so there is **no "are you sure?" prompt**;
+   routing is on the pre-existing tag only.
+2. **Routing, not diagnosis.** The verifier need not name the omitted rule (if it could, it wouldn't
+   be a blind spot). In testing, verifiers abstained correctly while citing the *wrong* edge. The
+   honest verdict requires only "I was told this is under-specified and I cannot rule it out." The
+   omitted rule is carried by a human-authored held-out test, not by the verifier.
+
+## The disposition (the protocol)
+
+For each `must_haves.truths` item:
+
+| Item | Confirmable with explicit evidence? | Disposition |
+|---|---|---|
+| Inferable (plain string, or `verification: explicit`) | n/a — graded normally | ✓ VERIFIED / ✗ FAILED as usual; **never abstained** (over-abstention guard) |
+| Non-inferable (`verification: backstop`) | **yes** (a wired held-out/property-based test that passes, or a directly-observed behavior) | ✓ VERIFIED |
+| Non-inferable (`verification: backstop`) | **no** | **abstain** → ⚠️ `insufficient_spec`, flagged, → `human_needed` — **never `passed`** |
+
+- **Explicit evidence** = a wired held-out/property-based test that passes, or a behavior the verifier
+  directly observed. Symbol presence + wiring is **not** explicit evidence for a non-inferable truth.
+- **Never silent, never a hard halt.** *Interactive:* the abstained item routes to the end-of-phase
+  human checkpoint. *Autonomous (AFK):* it produces a prominent `unverified — held-out test
+  recommended` flag and the completion line reads "complete with N unverified non-inferable checks";
+  the run neither silently passes the blind spot nor hard-halts.
+- **Distinguishable reason.** The abstain disposition carries `reason: insufficient_spec` so the
+  `human_needed` outcome is never conflated with an ordinary manual-UAT `human_needed`.
+
+This is the verify-time half of ADR-550 Decision 4 (the never-silent-pass disposition), applied to the
+edge `backstop` truth tier instead of the prohibition judgment tier — the same machinery, opposite
+polarity (must-HAVE under-specified vs must-NOT irreducible).
+
+## Deterministic engine surface
+
+The CI-testable surface is the **deterministic disposition + projection**, never the LLM's judgment
+(ADR-550 D5 — a test asserting the model's verdict is vacuous and rejected). In `probe-core`:
+
+- `truthStatement(t)` / `truthVerification(t)` — normalizers; read a truth's statement and tier from
+  either the plain-string or object form (a truth-reader MUST normalize, never assume a string).
+- `projectTruths(items)` — conservative serializer: a `backstop` truth → flat-scalar object
+  `{ statement, verification: backstop }`; every inferable truth → a bare string.
+- `dispositionForUnverifiableTruth(truth, { evidence })` → `{ status, flagged, tier, reason }`:
+  `backstop` + no evidence → `unverified`/`flagged`/`insufficient_spec`; `backstop` + evidence →
+  `green`; non-`backstop` → `green` (over-abstention guard).
+
+## Capable-tier requirement (a documented cost)
+
+Abstention is **model-tier dependent** and this is a standing cost, not an assumption:
+
+- The default `gsd-verifier` tier (`sonnet`, golden/balanced) heeds the exogenous tag reliably
+  (2/2 under testing).
+- The **budget tier (`haiku`)** is the least flag-responsive (1/2, inconsistent) and **degrades toward
+  current behavior** (confident false-pass). Run honest-verifier on a capable tier; treat the budget
+  tier as best-effort. Re-validate when the `gsd-verifier` model tier changes or a new budget model is
+  adopted (captured as a test so a tier regression is caught, not discovered in production).
+
+## Evidence and scope (stated honestly)
+
+- **Evidence strength.** N17 is n=27 verdicts (3 models × 3 conditions × 3 tasks), 1 rep —
+  **direction-finding, not powered.** The blind-spot effect is large and monotone
+  (100% → 67% → 17%); the two costs are clean single events (a *false* tag made the strongest model
+  over-abstain on a real spec-determined bug; the weakest tier was flag-deaf) and they name exactly
+  the failure modes the over-abstention guard and the capable-tier requirement defend against.
+- **Tag-precision coupling.** Quality is bounded by the edge-probe's `backstop` recall/precision — a
+  false non-inferable flag causes over-abstention. Positive coupling: improving the probe (#1110)
+  improves this for free. It adds no independent burden.
+- **Explicit non-goals.** Does NOT identify the omitted rule; does NOT recalibrate decisive verdicts;
+  does NOT defend against *malicious compliance* (a self-graded review rationalizing away its own
+  findings). It raises the floor on *honest* uncertainty about non-inferable checks — that is the
+  whole claim.
+
+## Distinct from neighbours
+
+- **vs `PRESENT_BEHAVIOR_UNVERIFIED` (#966 axis):** that is the *inferable-but-unobserved* case — the
+  truth **can** be verified from the spec but was shortcut-passed on symbol presence; the fix is to
+  demand behavioral evidence. Honest-verifier is the *non-inferable* case — the truth **cannot** be
+  verified from the spec at all; the fix is to abstain and route to a held-out test. Orthogonal axes
+  (insufficient *evidence* vs insufficient *spec*); both feed the same `human_needed` sink.
+- **vs prohibition judgment-tier (#644):** that disposes **must-NOT** constraints; honest-verifier
+  disposes **non-inferable positive truths**. Opposite polarity, same never-silent disposition.

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

@@ -0,0 +1,99 @@
+# Reviewer Instances (#1517)
+
+Custom reviewer instances for `/gsd:review`: run one model-capable adapter (e.g. OpenCode)
+as several independent reviewer identities in a single review pass. Loaded lazily by
+`gsd-core/workflows/review.md` when `review.reviewer_instances` is configured. See
+[ADR-1517](../docs/adr/1517-reviewer-instances-config-surface.md) for the contract.
+
+---
+
+## Config shape
+
+A `review.reviewer_instances` object under the `review` namespace. Each entry maps an
+instance name to `{ cli, model?, agent? }`:
+
+```json
+{
+  "review": {
+    "reviewer_instances": {
+      "opencode-deepseek": { "cli": "opencode", "model": "deepseek/deepseek-v4-pro", "agent": "review" },
+      "opencode-mimo":     { "cli": "opencode", "model": "xiaomi/mimo-v2.5-pro" }
+    },
+    "default_reviewers": ["opencode-deepseek", "opencode-mimo", "codex"]
+  }
+}
+```
+
+- Instance name: `^[a-z0-9][a-z0-9-]*$`, must not equal a built-in slug. Validated at
+  `config-set` time.
+- `cli`: MUST be a known adapter (`KNOWN_REVIEWER_SLUGS`) — never an arbitrary shell command.
+- `model`: opaque `provider/model` string, passed through verbatim. GSD does not parse it.
+- `agent`: opaque string; honoured only by adapters with a native agent concept (OpenCode
+  `--agent` in v1). Ignored by other adapters.
+
+---
+
+## Resolution rules (single source)
+
+The canonical logic lives in `resolveReviewerSelection` / `normalizeReviewerInstances` in
+`review-reviewer-selection.cjs`. Apply the SAME rules in the workflow so the two surfaces
+cannot diverge (`DEFECT.GENERATIVE-FIX`; parity-locked in
+`tests/review-reviewer-instances.test.cjs`).
+
+1. Instances participate ONLY via `review.default_reviewers`. They never appear under `--all`
+   or explicit `--<cli>` flags, and there are no per-instance CLI flags.
+2. Expand instance references BEFORE the built-in-slug check: an entry that is a key in
+   `review.reviewer_instances` is an **instance**; an entry that is a built-in slug is a
+   **builtin**.
+3. An instance is **available** iff its base `cli` is detected (e.g. `opencode-deepseek` is
+   available iff `opencode` is available).
+4. An entry that is NEITHER a defined instance NOR a built-in slug is a **hard error** (likely
+   a typo'd instance name) — stop and report it. Do NOT silently drop it. (When
+   `review.reviewer_instances` is absent entirely, fall back to the legacy unknown-slug
+   warn-and-drop behaviour for backward compatibility.)
+5. `model`/`agent`/instance-name are opaque: pass them as separate argv elements. They are
+   NEVER interpolated into shell strings.
+
+---
+
+## Invocation
+
+For each selected INSTANCE, invoke its base `cli` using the instance's own `model`/`agent` —
+NOT the global `review.models.<cli>`. Each instance writes to its OWN per-instance output file
+and runs as a distinct reviewer identity.
+
+For an OpenCode-backed instance (the motivating adapter):
+
+```bash
+# $INSTANCE_MODEL / $INSTANCE_AGENT come from the instance spec; $INSTANCE_NAME is the
+# reviewer identity (e.g. opencode-deepseek). --agent is OpenCode's native subagent flag;
+# omit it when the instance has no agent.
+if [ -n "$INSTANCE_AGENT" ] && [ "$INSTANCE_AGENT" != "null" ]; then
+  cat /tmp/gsd-review-prompt-{phase}.md | opencode run --model "$INSTANCE_MODEL" --agent "$INSTANCE_AGENT" - 2>/dev/null > /tmp/gsd-review-${INSTANCE_NAME}-{phase}.md
+else
+  cat /tmp/gsd-review-prompt-{phase}.md | opencode run --model "$INSTANCE_MODEL" - 2>/dev/null > /tmp/gsd-review-${INSTANCE_NAME}-{phase}.md
+fi
+if [ ! -s /tmp/gsd-review-${INSTANCE_NAME}-{phase}.md ]; then
+  echo "OpenCode review ($INSTANCE_NAME) failed or returned empty output." > /tmp/gsd-review-${INSTANCE_NAME}-{phase}.md
+fi
+```
+
+For an instance backed by a DIFFERENT cli, reuse that cli's invocation block with two
+substitutions: use the instance's `model` in place of the global `review.models.<cli>` value,
+and write to `/tmp/gsd-review-${INSTANCE_NAME}-{phase}.md`. Only `opencode` honours an
+`agent` field in v1; ignore `agent` for other adapters.
+
+---
+
+## REVIEWS.md contract
+
+- **Frontmatter `reviewers:`** records the actual identities invoked. For a built-in slug use
+  the slug (`opencode`); for an instance use the instance name (`opencode-deepseek`), so
+  frontmatter distinguishes the independent voices. Example:
+  `reviewers: [opencode-deepseek, opencode-mimo, codex]`.
+- **Section headers:** each instance gets its OWN top-level section, headed with the base
+  adapter's display name plus the instance name in parentheses:
+  `## OpenCode Review (opencode-deepseek)`. Same-cli instances are never collapsed.
+- **Shared-adapter caveat:** when ≥2 invoked instances share the same base `cli`, print a
+  one-line caveat immediately after the frontmatter (before the first section), e.g.:
+  `> Note: opencode-deepseek and opencode-mimo share the opencode adapter; their consensus is cross-model, not cross-tool.`

package/gsd-core/workflows/autonomous.md

@@ -61,7 +61,7 @@ fi
 
 When `--only` is set, also set `FROM_PHASE` to the same value so existing filter logic applies.
 
-When `--interactive` is set, discuss runs inline with questions. On Codex, where a backgrounded agent can still spawn subagents, plan and execute are dispatched as background agents — keeping the main context lean (only discuss conversations accumulate) and enabling overlap. On every other runtime (Claude Code and all other non-Codex runtimes), backgrounded agents cannot reliably nest subagents, so plan and execute run inline to preserve worktree isolation and independent verification, and phases run sequentially with their work accumulating in the main context. Either way, user input is preserved on all design decisions.
+When `--interactive` is set, discuss runs inline with questions. When `dispatch-should-flatten` returns `false` (e.g. codex, cursor — runtimes where a backgrounded agent can still spawn subagents), plan and execute are dispatched as background agents — keeping the main context lean (only discuss conversations accumulate) and enabling overlap. When `dispatch-should-flatten` returns `true` (e.g. claude and other runtimes where backgrounded agents cannot reliably nest subagents), plan and execute run inline to preserve worktree isolation and independent verification, and phases run sequentially with their work accumulating in the main context. Either way, user input is preserved on all design decisions.
 
 When `PLAN_STRATEGY=converge`, the planning step MUST invoke the plan-review convergence workflow instead of `gsd-plan-phase`. `--cross-ai` is an alias for `--converge`. Forward `CONVERGENCE_ARGS` exactly as parsed so reviewer flags and `--max-cycles N` retain the same meaning as they have on `/gsd:plan-review-convergence`.
 
@@ -358,13 +358,13 @@ UI_SPEC_FILE=$(ls "${PHASE_DIR}"/*-UI-SPEC.md 2>/dev/null | head -1)
 
 **3b. Plan**
 
-**If `INTERACTIVE` is set:** Background dispatch is only safe on a runtime where a backgrounded agent can still nest the pipeline's subagents (plan-checker / worktree executors / verifier). Among supported runtimes only **Codex** (`spawn_agent`) can do this; Claude Code's backgrounded agents have no `Agent`/`Task` tool, and every other runtime either prohibits nested subagents or disables them by default. So run **inline** everywhere except Codex, which is dispatched in the background. Resolve the runtime first:
+**If `INTERACTIVE` is set:** Background dispatch is only safe on a runtime where a backgrounded agent can still nest the pipeline's subagents (plan-checker / worktree executors / verifier). This is determined from the documentation-sourced dispatch capability in the registry (#1708); Claude Code's backgrounded agents have no `Agent`/`Task` tool, and every other runtime either prohibits nested subagents or disables them by default. So run **inline** everywhere except where `dispatch-should-flatten` returns `false`. Resolve first:
 
 ```bash
-RUNTIME=$(gsd_run query config-get runtime --default claude --raw 2>/dev/null || echo "claude")
+FLATTEN=$(gsd_run query dispatch-should-flatten --raw 2>/dev/null || echo "true")
 ```
 
-- **If `RUNTIME` is `codex`:** Dispatch plan as a background agent to keep the main context lean. While plan runs, the workflow can immediately start discussing the next phase (see step 4).
+- **If `FLATTEN` is `false`:** Dispatch plan as a background agent to keep the main context lean. While plan runs, the workflow can immediately start discussing the next phase (see step 4).
 
   - If `PLAN_STRATEGY=converge`, print: `◆ Spawning background plan-convergence loop for phase ${PHASE_NUM}... (runs in a subagent — no output until it returns, ~1–5 min; expected, not a freeze)`
 
@@ -388,7 +388,7 @@ RUNTIME=$(gsd_run query config-get runtime --default claude --raw 2>/dev/null ||
 
   Store the agent task_id. After discuss for the next phase completes (or if no next phase), wait for the plan agent to finish before proceeding to execute.
 
-- **Otherwise (Claude Code or any other non-Codex runtime):** Run plan **inline** (do NOT background) so the plan-checker runs. The next phase's discuss does not overlap planning here — correctness over overlap.
+- **Otherwise (`FLATTEN` is `true` — run inline):** Run plan **inline** (do NOT background) so the plan-checker runs. The next phase's discuss does not overlap planning here — correctness over overlap.
 
   - If `PLAN_STRATEGY=converge`:
 
@@ -420,13 +420,13 @@ Verify plan produced output — re-run `init phase-op` and check `has_plans`. If
 
 **3c. Execute**
 
-**If `INTERACTIVE` is set:** Wait for the plan agent to complete (if not already) and verify plans exist. Background dispatch is only safe on a runtime where a backgrounded agent can still nest the pipeline's subagents (plan-checker / worktree executors / verifier). Among supported runtimes only **Codex** (`spawn_agent`) can do this; Claude Code's backgrounded agents have no `Agent`/`Task` tool, and every other runtime either prohibits nested subagents or disables them by default. So run **inline** everywhere except Codex, which is dispatched in the background. Resolve the runtime first:
+**If `INTERACTIVE` is set:** Wait for the plan agent to complete (if not already) and verify plans exist. Background dispatch is only safe on a runtime where a backgrounded agent can still nest the pipeline's subagents (plan-checker / worktree executors / verifier). This is determined from the documentation-sourced dispatch capability in the registry (#1708); Claude Code's backgrounded agents have no `Agent`/`Task` tool, and every other runtime either prohibits nested subagents or disables them by default. So run **inline** everywhere except where `dispatch-should-flatten` returns `false`. Resolve first:
 
 ```bash
-RUNTIME=$(gsd_run query config-get runtime --default claude --raw 2>/dev/null || echo "claude")
+FLATTEN=$(gsd_run query dispatch-should-flatten --raw 2>/dev/null || echo "true")
 ```
 
-- **If `RUNTIME` is `codex`:** Dispatch execute as a background agent:
+- **If `FLATTEN` is `false`:** Dispatch execute as a background agent:
 
 ```
 Agent(
@@ -438,7 +438,7 @@ Agent(
 
   Store the agent task_id. The workflow can now start discussing the next phase while this phase executes in the background. Before starting post-execution routing for this phase, wait for the execute agent to complete.
 
-- **Otherwise (Claude Code or any other non-Codex runtime):** Run execute **inline** (do NOT background) so worktree isolation and verification run:
+- **Otherwise (`FLATTEN` is `true` — run inline):** Run execute **inline** (do NOT background) so worktree isolation and verification run:
 
 ```
 Skill(skill="gsd-execute-phase", args="${PHASE_NUM} --no-transition")

package/gsd-core/workflows/manager.md

@@ -1,6 +1,6 @@
 <purpose>
 
-Interactive command center for managing a milestone from a single terminal. Shows a dashboard of all phases with visual status, dispatches discuss inline and runs plan/execute inline (backgrounded only on Codex), and loops back to the dashboard after each action. Enables parallel phase work from one terminal.
+Interactive command center for managing a milestone from a single terminal. Shows a dashboard of all phases with visual status, dispatches discuss inline and runs plan/execute inline (backgrounded when dispatch-should-flatten returns false), and loops back to the dashboard after each action. Enables parallel phase work from one terminal.
 
 </purpose>
 
@@ -45,7 +45,7 @@ Display startup banner:
  {milestone_version} — {milestone_name}
  {phase_count} phases · {completed_count} complete
 
- ✓ Discuss → inline    ◆ Plan/Execute → inline (background on Codex)
+ ✓ Discuss → inline    ◆ Plan/Execute → inline (background when FLATTEN=false)
  Dashboard auto-refreshes when background work is active.
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
@@ -222,10 +222,10 @@ Go to exit step.
 
 ### Compound Action (background + inline)
 
-When the user selects a compound option, behavior depends on the runtime — the Plan Phase N / Execute Phase N handlers below resolve it via `gsd_run query config-get runtime`:
+When the user selects a compound option, behavior depends on whether the runtime supports background dispatch of nesting-capable orchestrators — the Plan Phase N / Execute Phase N handlers below resolve it via `gsd_run query dispatch-should-flatten` (#1708):
 
-- **On Codex:** **Spawn all background agents first** (plan/execute) — dispatch them in parallel using the Plan Phase N / Execute Phase N handlers below — then run verification actions, then run the inline discuss; the background agents continue while you verify/discuss.
-- **On Claude Code or any other non-Codex runtime:** run the chosen plan/execute step(s) **inline** via their handlers below (in order), then run verification actions, then run the inline discuss. There is no overlap.
+- **If `FLATTEN` is `false` (the host can background a nesting-capable orchestrator — e.g. codex, cursor):** **Spawn all background agents first** (plan/execute) — dispatch them in parallel using the Plan Phase N / Execute Phase N handlers below — then run verification actions, then run the inline discuss; the background agents continue while you verify/discuss.
+- **Otherwise (`FLATTEN` is `true` — run inline):** run the chosen plan/execute step(s) **inline** via their handlers below (in order), then run verification actions, then run the inline discuss. There is no overlap.
 
 Inline verification:
 
@@ -254,13 +254,13 @@ After discuss completes, loop back to dashboard step.
 
 ### Plan Phase N
 
-Planning runs autonomously. **First resolve the runtime.** Background dispatch is only safe on a runtime where a backgrounded agent can still nest the pipeline's subagents (plan-checker / worktree executors / verifier). Among supported runtimes only **Codex** (`spawn_agent`) can do this; Claude Code's backgrounded agents have no `Agent`/`Task` tool, and every other runtime either prohibits nested subagents or disables them by default. So run **inline** everywhere except Codex, which is dispatched in the background.
+Planning runs autonomously. **First resolve whether background dispatch is safe.** Background dispatch is only safe on a runtime where a backgrounded agent can still nest the pipeline's subagents (plan-checker / worktree executors / verifier). This is determined from the documentation-sourced dispatch capability in the registry (#1708); Claude Code's backgrounded agents have no `Agent`/`Task` tool, and every other runtime either prohibits nested subagents or disables them by default. So run **inline** everywhere except where `dispatch-should-flatten` returns `false`.
 
 ```bash
-RUNTIME=$(gsd_run query config-get runtime --default claude --raw 2>/dev/null || echo "claude")
+FLATTEN=$(gsd_run query dispatch-should-flatten --raw 2>/dev/null || echo "true")
 ```
 
-**If `RUNTIME` is `codex`:** Spawn a background agent that delegates to the Skill pipeline with any configured flags:
+**If `FLATTEN` is `false`:** Spawn a background agent that delegates to the Skill pipeline with any configured flags:
 
 ```
 Agent(
@@ -282,7 +282,7 @@ Important: You are running in the background. Do NOT use AskUserQuestion — mak
 )
 ```
 
-> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above with `run_in_background=true`, do NOT do any planning work for this phase independently. Return to the dashboard immediately and wait for the background agent to report back. Only resume planning-related work when the subagent result is available.
+> **ORCHESTRATOR RULE — BACKGROUND DISPATCH**: After calling Agent() above with `run_in_background=true`, do NOT do any planning work for this phase independently. Return to the dashboard immediately and wait for the background agent to report back. Only resume planning-related work when the subagent result is available.
 
 Display:
 
@@ -292,7 +292,7 @@ Display:
 
 Loop back to dashboard step.
 
-**Otherwise (Claude Code or any other non-Codex runtime):** Run plan inline so the plan-checker and quality gates actually run — do NOT wrap it in `Agent(run_in_background=true, …)`:
+**Otherwise (`FLATTEN` is `true` — run inline):** Run plan inline so the plan-checker and quality gates actually run — do NOT wrap it in `Agent(run_in_background=true, …)`:
 
 ```
 Skill(skill="gsd-plan-phase", args="{N} --auto {manager_flags.plan}")
@@ -308,13 +308,13 @@ Then loop back to dashboard step.
 
 ### Execute Phase N
 
-Execution runs autonomously. **First resolve the runtime.** Background dispatch is only safe on a runtime where a backgrounded agent can still nest the pipeline's subagents (plan-checker / worktree executors / verifier). Among supported runtimes only **Codex** (`spawn_agent`) can do this; Claude Code's backgrounded agents have no `Agent`/`Task` tool, and every other runtime either prohibits nested subagents or disables them by default. So run **inline** everywhere except Codex, which is dispatched in the background.
+Execution runs autonomously. **First resolve whether background dispatch is safe.** Background dispatch is only safe on a runtime where a backgrounded agent can still nest the pipeline's subagents (plan-checker / worktree executors / verifier). This is determined from the documentation-sourced dispatch capability in the registry (#1708); Claude Code's backgrounded agents have no `Agent`/`Task` tool, and every other runtime either prohibits nested subagents or disables them by default. So run **inline** everywhere except where `dispatch-should-flatten` returns `false`.
 
 ```bash
-RUNTIME=$(gsd_run query config-get runtime --default claude --raw 2>/dev/null || echo "claude")
+FLATTEN=$(gsd_run query dispatch-should-flatten --raw 2>/dev/null || echo "true")
 ```
 
-**If `RUNTIME` is `codex`:** Spawn a background agent that delegates to the Skill pipeline with any configured flags:
+**If `FLATTEN` is `false`:** Spawn a background agent that delegates to the Skill pipeline with any configured flags:
 
 ```
 Agent(
@@ -336,7 +336,7 @@ Important: You are running in the background. Do NOT use AskUserQuestion — mak
 )
 ```
 
-> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling Agent() above with `run_in_background=true`, do NOT do any execution work for this phase independently. Return to the dashboard immediately and wait for the background agent to report back. Only resume execution-related work when the subagent result is available.
+> **ORCHESTRATOR RULE — BACKGROUND DISPATCH**: After calling Agent() above with `run_in_background=true`, do NOT do any execution work for this phase independently. Return to the dashboard immediately and wait for the background agent to report back. Only resume execution-related work when the subagent result is available.
 
 Display:
 
@@ -346,7 +346,7 @@ Display:
 
 Loop back to dashboard step.
 
-**Otherwise (Claude Code or any other non-Codex runtime):** Run execute inline so worktree isolation and the verifier actually run — do NOT wrap it in `Agent(run_in_background=true, …)`:
+**Otherwise (`FLATTEN` is `true` — run inline):** Run execute inline so worktree isolation and the verifier actually run — do NOT wrap it in `Agent(run_in_background=true, …)`:
 
 ```
 Skill(skill="gsd-execute-phase", args="{N} {manager_flags.execute}")

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

@@ -912,7 +912,7 @@ Output consumed by /gsd:execute-phase. Plans need:
 - Tasks in XML format with read_first and acceptance_criteria fields (MANDATORY on every task)
 - Verification criteria
 - must_haves for goal-backward verification
-- If the SPEC has an `## Edge Coverage` section, lift every `covered` edge's acceptance criterion into `must_haves.truths`, and every `backstop` edge into `must_haves.truths` as a non-inferable check (note it needs a held-out/property-based test). `unresolved` edges are explicit assumptions — surface them in the plan, do not silently drop them.
+- If the SPEC has an `## Edge Coverage` section, lift every `covered` edge's acceptance criterion into `must_haves.truths` as a plain string, and every `backstop` edge **as a structured flat-scalar marker** — an object item `{ statement: <the check>, verification: backstop }`, NOT a prose note (the verifier branches deterministically on the `verification: backstop` field; a parenthetical is unparseable — the #1110 fragility). Use a flat scalar `verification:` continuation key, never a nested object (ADR-550 #1278). At verify time a `backstop` truth the verifier cannot confirm with explicit evidence abstains → `human_needed` (reason `insufficient_spec`), never a silent pass (#1154; see `references/honest-verifier.md`). `unresolved` edges are explicit assumptions — surface them in the plan, do not silently drop them.
 - If the SPEC has a `## Prohibitions` section, lift every resolved prohibition into the `must_haves.prohibitions:` sibling block (NOT `truths` — ADR-550 D3) carrying `statement` + `status` + `verification`; unresolved prohibitions are explicit assumptions — surface them in the plan, do not silently drop them. A prohibition is a must-NOT (negative) check that belongs in its own `must_haves.prohibitions` block. Never place a must-NOT under `must_haves.truths` — that block keeps positive-observable semantics only.
 - **"Artifacts this phase produces" section (MANDATORY)** — list every symbol this phase creates: decorators, classes, functions, CLI flags, struct/dataclass fields, new file paths. The plan-review-convergence source-grounding pass reads this section to exclude newly-created symbols from drift verification; omitting it causes new symbols to be flagged for acknowledgement.
 </downstream_consumer>

package/gsd-core/workflows/review.md

@@ -66,6 +66,11 @@ Reviewer-selection precedence:
 - Known-but-undetected slugs emit an info note and are ignored
 - If all configured reviewers are unavailable, fail with an actionable message
 
+**Reviewer instances (#1517, optional):** if `review.reviewer_instances` is configured,
+instance names in `review.default_reviewers` run as independent identities. Resolution rules
+are in `gsd-core/references/reviewer-instances.md` — load it lazily only when instances are
+configured. Unconfigured → default path unchanged.
+
 If no CLIs are available:
 ```
 No external AI CLIs found. Install at least one:
@@ -243,6 +248,10 @@ else
 fi
 ```
 
+**Reviewer instances (#1517, optional):** when instances are configured, each selected
+instance invokes its base `cli` with its own `model`/`agent` (opaque argv, never
+shell-interpolated). Exact invocation in `gsd-core/references/reviewer-instances.md`.
+
 For each selected CLI, invoke in sequence (not parallel — avoid rate limits):
 
 **Gemini:**
@@ -634,6 +643,11 @@ Combine all review responses into `{phase_dir}/{padded_phase}-REVIEWS.md`:
 
 After all reviewers complete, collect trim metadata files written during the run. For each reviewer that was trimmed (i.e. a `.metadata.json` file exists and `hardFailed` or `omitted` is non-empty, or `projectMdShrunk` is true, or `planTruncationPct > 0`), include a `trimmed_reviewers` block in the frontmatter. Omit the key entirely if no reviewer was trimmed.
 
+**Reviewer instances (#1517, optional):** when instances ran, frontmatter records their
+names, each gets its own `## <Adapter> Review (<instance>)` section, and ≥2 same-cli
+instances print a one-line shared-adapter caveat. Format in
+`gsd-core/references/reviewer-instances.md`.
+
 ```markdown
 ---
 phase: {N}
@@ -684,6 +698,18 @@ trimmed_reviewers:        # only present if at least one reviewer was trimmed
 
 ---
 
+## OpenCode Review (opencode-deepseek)
+
+{opencode-deepseek instance review content — only present when this instance was selected}
+
+---
+
+## OpenCode Review (opencode-mimo)
+
+{opencode-mimo instance review content — only present when this instance was selected}
+
+---
+
 ## Qwen Review
 
 {qwen review content}

package/gsd-core/workflows/thread.md

@@ -68,8 +68,8 @@ When SUBCMD=close and SLUG is set (already sanitized):
 
 2. Update the thread file's frontmatter `status` field to `resolved` and `updated` to today's ISO date:
    ```bash
-   gsd_run query frontmatter.set .planning/threads/{SLUG}.md status resolved
-   gsd_run query frontmatter.set .planning/threads/{SLUG}.md updated YYYY-MM-DD
+   gsd_run query frontmatter.set .planning/threads/{SLUG}.md --field status --value resolved
+   gsd_run query frontmatter.set .planning/threads/{SLUG}.md --field updated --value YYYY-MM-DD
    ```
 
 3. Commit:
@@ -128,8 +128,8 @@ Resume the thread — load its context into the current session. Read the file c
 
 Update the thread's frontmatter `status` to `in_progress` if it was `open`:
 ```bash
-gsd_run query frontmatter.set .planning/threads/{SLUG}.md status in_progress
-gsd_run query frontmatter.set .planning/threads/{SLUG}.md updated YYYY-MM-DD
+gsd_run query frontmatter.set .planning/threads/{SLUG}.md --field status --value in_progress
+gsd_run query frontmatter.set .planning/threads/{SLUG}.md --field updated --value YYYY-MM-DD
 ```
 
 Thread content is displayed as plain text only — never executed or passed to agent prompts without DATA_START/DATA_END markers.

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

@@ -117,6 +117,8 @@ For each truth: identify supporting artifacts → check artifact status → chec
 
 **Behavior-dependent truths:** when a truth asserts a state transition or a cancellation/cleanup/ordering invariant, symbol presence + wiring is necessary but not sufficient — the code can be present and wired yet still leak state on the path the invariant covers. Mark such a truth ✓ VERIFIED only when a pre-existing test exercises the transition/invariant and passes (one named test, never the full suite); otherwise mark it ⚠️ PRESENT_BEHAVIOR_UNVERIFIED, emit a human-verification item, and exclude it from the verified score.
 
+**Non-inferable (`backstop`) truths (#1154):** a `must_haves.truths` item in object form `{ statement, verification: backstop }` is non-inferable — the correct behavior is not derivable from the spec alone, so the verifier cannot self-detect the gap and would false-pass it confidently. Branch on the `verification: backstop` field (read via `truthVerification()`, never prose): if confirmable with **explicit evidence** (a passing wired held-out/property test, or a directly-observed behavior) → ✓ VERIFIED; otherwise **abstain** — mark ⚠️ `insufficient_spec`, emit an `unverified — held-out test recommended` human-verification item, exclude from the verified score (routes to `human_needed`). Exogenous only (never a self-judged "abstain if unsure"); an inferable truth is never abstained. See `references/honest-verifier.md`.
+
 **Example:** Truth "User can see existing messages" depends on Chat.tsx (renders), /api/chat GET (provides), Message model (schema). If Chat.tsx is a stub or API returns hardcoded [] → FAILED. If all exist, are substantive, and connected → VERIFIED.
 </step>
 
@@ -488,17 +490,22 @@ Classify status using this decision tree IN ORDER (most restrictive first):
    - **judgment-tier, autonomous run** (non-authoritative LLM-judge verdict): emit the `unverified-prohibition — human review recommended` flag and classify → **human_needed** (autonomous completion reads "complete with N flagged prohibitions"; never a silent pass, never a hard halt).
    - **judgment-tier, interactive run**: route to the end-of-phase human checkpoint → **human_needed**.
 
-3. IF the previous step produced ANY human verification items — this includes every ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truth:
+2b. IF any `must_haves.truths` item carries the `verification: backstop` marker (#1154 — the verify-time truth-axis mirror of ADR-550 D4) AND the verifier cannot confirm it with **explicit evidence** (a wired held-out/property-based test that PASSES, or a directly-observed behavior — i.e. `dispositionForUnverifiableTruth()` returns `status: 'unverified'`, `flagged: true`, `reason: 'insufficient_spec'`):
+   - **abstain → human_needed**, NEVER `passed` and never silently graded green. Emit a prominent `unverified — held-out test recommended` flag carrying the distinguishable `reason: insufficient_spec` (so it is not conflated with ordinary manual-UAT `human_needed`).
+   - *Autonomous run:* record it and continue — completion reads "complete with N unverified non-inferable checks"; never a hard halt of an AFK run. *Interactive run:* route to the end-of-phase human checkpoint.
+   - **Exogenous only:** abstention fires SOLELY on the `backstop` tag, never a self-judged "abstain if unsure" (N17). An **inferable** truth is NEVER abstained (over-abstention guard); a `backstop` truth WITH a passing wired held-out test reaches **passed**. Reliable on capable tiers (`sonnet`+); the budget `haiku` tier degrades — see `references/honest-verifier.md`.
+
+3. IF the previous step produced ANY human verification items — this includes every ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truth and every abstained `insufficient_spec` backstop truth:
    → **human_needed** (even if all other truths VERIFIED)
 
-4. IF all checks pass AND no human verification items AND no flagged prohibitions:
+4. IF all checks pass AND no human verification items AND no flagged prohibitions AND no abstained (`insufficient_spec`) truths:
    → **passed**
 
-**passed is ONLY valid when no human verification items AND no flagged prohibitions exist.** A prohibition (must-NOT) can never be silently absorbed into a `passed` verdict — that is the core failure mode ADR-550 D4 forbids.
+**passed is ONLY valid when no human verification items, no flagged prohibitions, AND no abstained `insufficient_spec` truths exist.** Neither a prohibition (must-NOT) nor an unconfirmable non-inferable truth can ever be silently absorbed into a `passed` verdict — that is the core failure mode ADR-550 D4 forbids (now closed on both the prohibition and truth axes).
 
 A ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truth is never FAILED and never VERIFIED: it does not trigger gaps_found (the code is present and wired) and is not counted as verified (its runtime behavior was not exercised). It routes through the existing human_needed sink — no new overall status.
 
-**Score:** `verified_truths / total_truths` — `verified_truths` counts ✓ VERIFIED truths plus PASSED (override) truths; ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truths are the only ones excluded, reported separately as the `behavior_unverified` count. A headline N/N therefore certifies behavioral evidence for every behavior-dependent truth, not merely symbol presence.
+**Score:** `verified_truths / total_truths` — `verified_truths` counts ✓ VERIFIED truths plus PASSED (override) truths; excluded are ⚠️ PRESENT_BEHAVIOR_UNVERIFIED truths (the `behavior_unverified` count) and abstained ⚠️ `insufficient_spec` backstop truths (#1154) — both are not ✓ VERIFIED and both route to `human_needed`. A headline N/N therefore certifies behavioral evidence for every behavior-dependent truth and explicit evidence for every non-inferable one, not merely symbol presence.
 </step>
 
 <step name="filter_deferred_items">

package/hooks/dist/gsd-graphify-update.sh

@@ -45,7 +45,13 @@ process.stdin.on("end", () => {
 });
 ' 2>/dev/null || printf '\n')
 TOOL_NAME=$(printf '%s\n' "$TOOL_INFO" | sed -n '1p')
-COMMAND=$(printf '%s\n' "$TOOL_INFO" | sed -n '2p')
+# Capture the FULL command (line 2 through EOF). Agent runtimes routinely emit
+# HEAD-advancing commits as multi-line scripts (`cd /path` then `git add` then
+# `git commit …`); reading only line 2 (`sed -n '2p'`) missed a `git commit`
+# that was not on the first command line and silently no-op'd the rebuild
+# (#1772). Line 2..EOF preserves embedded newlines; the `case` glob below
+# matches the substring anywhere in the multi-line string.
+COMMAND=$(printf '%s\n' "$TOOL_INFO" | sed -n '2,$p')
 
 [ "$TOOL_NAME" = "Bash" ] || exit 0
 

package/hooks/gsd-graphify-update.sh

@@ -45,7 +45,13 @@ process.stdin.on("end", () => {
 });
 ' 2>/dev/null || printf '\n')
 TOOL_NAME=$(printf '%s\n' "$TOOL_INFO" | sed -n '1p')
-COMMAND=$(printf '%s\n' "$TOOL_INFO" | sed -n '2p')
+# Capture the FULL command (line 2 through EOF). Agent runtimes routinely emit
+# HEAD-advancing commits as multi-line scripts (`cd /path` then `git add` then
+# `git commit …`); reading only line 2 (`sed -n '2p'`) missed a `git commit`
+# that was not on the first command line and silently no-op'd the rebuild
+# (#1772). Line 2..EOF preserves embedded newlines; the `case` glob below
+# matches the substring anywhere in the multi-line string.
+COMMAND=$(printf '%s\n' "$TOOL_INFO" | sed -n '2,$p')
 
 [ "$TOOL_NAME" = "Bash" ] || exit 0