@opengsd/gsd-core 1.6.1 → 1.7.0-rc.2

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/validate.cjs

@@ -93,7 +93,8 @@ function buildRoadmapPhaseVariants(roadmapContent) {
     const roadmapPhaseVariants = new Set();
     // Matches both legacy numeric (Phase 1:), decimal (Phase 2.1:), milestone-prefixed (Phase 2-01:),
     // and bracket-prefixed (### [GSD] Phase 2-01:) headings.
-    const phasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)\s*:/gi;
+    // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+    const phasePattern = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]*\))?\s*:/gi;
     let m;
     while ((m = phasePattern.exec(roadmapContent)) !== null) {
         roadmapPhases.add(m[1]);

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

@@ -40,7 +40,7 @@ const configLoaderMod = require("./config-loader.cjs");
 const { loadConfig, CONFIG_DEFAULTS } = configLoaderMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseIdMod = require("./phase-id.cjs");
-const { normalizePhaseName, phaseTokenMatches, escapeRegex, getMilestoneFromPhaseId } = phaseIdMod;
+const { normalizePhaseName, phaseTokenMatches, escapeRegex, getMilestoneFromPhaseId, OPTIONAL_PHASE_TAG_SOURCE } = phaseIdMod;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const phaseLocatorMod = require("./phase-locator.cjs");
 const { findPhaseInternal } = phaseLocatorMod;
@@ -992,7 +992,8 @@ function checkMilestonePrefixMismatches(roadmapContent, { getMilestoneFromPhaseI
     }
     for (const section of sections) {
         const content = roadmapContent.slice(section.start, section.end);
-        const phaseRx = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)\s*:/gi;
+        // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+        const phaseRx = /#{2,4}\s*(?:\[[^\]]+\]\s*)?Phase\s+([\w][\w.-]*)(?:\s*\([^)\n]*\))?\s*:/gi;
         let pm;
         while ((pm = phaseRx.exec(content)) !== null) {
             const phaseId = pm[1];
@@ -1351,7 +1352,7 @@ function cmdValidateHealth(cwd, options, raw) {
                 stateContent.match(/Current Phase:\s*(\S+)/i);
             if (currentPhaseMatch) {
                 const statePhase = currentPhaseMatch[1].replace(/^0+/, '');
-                const phaseCheckboxRe = new RegExp(`-\\s*\\[x\\].*Phase\\s+0*${escapeRegex(statePhase)}[:\\s]`, 'i');
+                const phaseCheckboxRe = new RegExp(`-\\s*\\[x\\].*Phase\\s+0*${escapeRegex(statePhase)}${OPTIONAL_PHASE_TAG_SOURCE}[:\\s]`, 'i');
                 if (phaseCheckboxRe.test(roadmapContentFull)) {
                     const stateStatus = stateContent.match(/\*\*Status:\*\*\s*(.+)/i);
                     const statusVal = stateStatus ? stateStatus[1].trim().toLowerCase() : '';
@@ -1509,7 +1510,8 @@ function cmdValidateHealth(cwd, options, raw) {
             if (isMarkedComplete) {
                 const roadmapRaw = node_fs_1.default.readFileSync(roadmapPath, 'utf-8');
                 const scopedContent = extractCurrentMilestone(roadmapRaw, cwd);
-                const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)\s*:\s*([^\n]+)/gi;
+                // #1729: `(?:\s*\([^)\n]*\))?` tolerates a pre-colon ( ) tag (literal mirror of OPTIONAL_PHASE_TAG_SOURCE).
+                const phasePattern = /#{2,4}\s*Phase\s+(\d+[A-Z]?(?:\.\d+)*)(?:\s*\([^)\n]*\))?\s*:\s*([^\n]+)/gi;
                 const unstarted = [];
                 let pm;
                 // Non-hoisted: load-order matters (circular dep guard)

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

@@ -28,7 +28,7 @@ function isCompletedInventory(status) {
     return /\bmilestone\s+complete\b/.test(s) || /\barchived\b/.test(s);
 }
 function buildWorkstreamInventory(inputs) {
-    const { name, projectDir, workstreamDir, phaseDirNames, activeWorkstreamName, phaseFilesCounts, roadmapPhaseCount, stateProjection, filesExist, } = inputs;
+    const { name, projectDir, workstreamDir, phaseDirNames, activeWorkstreamName, phaseFilesCounts, roadmapPhaseCount, stateProjection, filesExist, milestoneShipped, } = inputs;
     // Index counts by directory for O(1) lookup during sort/iteration
     const countsMap = new Map();
     for (const entry of phaseFilesCounts) {
@@ -56,6 +56,14 @@ function buildWorkstreamInventory(inputs) {
             summary_count: counts.summaryCount,
         });
     }
+    // #1913: derive status from authoritative shipped signals rather than trusting
+    // the mutable STATE.md `Status` field. When a shipped signal is present, the
+    // workstream is "milestone complete" regardless of a stale field value.
+    const fieldStatus = stateProjection.status;
+    const useDerived = milestoneShipped;
+    const status = useDerived ? 'milestone complete' : fieldStatus;
+    const status_source = useDerived ? 'derived' : 'field';
+    const status_conflict = useDerived && !isCompletedInventory(fieldStatus);
     return {
         name,
         path: toPosixPath(node_path_1.default.relative(projectDir, workstreamDir)),
@@ -65,7 +73,9 @@ function buildWorkstreamInventory(inputs) {
             state: filesExist.state,
             requirements: filesExist.requirements,
         },
-        status: stateProjection.status,
+        status,
+        status_source,
+        status_conflict,
         current_phase: stateProjection.current_phase,
         last_activity: stateProjection.last_activity,
         phases,

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

@@ -63,6 +63,33 @@ function readStateProjection(statePath) {
         };
     }
 }
+/**
+ * #1913: detect an authoritative shipped signal for a workstream so the
+ * inventory status is never trusted from the mutable STATE.md `Status` field
+ * alone. Returns true when EITHER an archived milestone snapshot is present
+ * under `<planningBase>/milestones/` OR the workstream ROADMAP carries a
+ * SHIPPED marker — both are hard to desync, unlike the hand-maintained field.
+ */
+function workstreamMilestoneShipped(roadmapPath, planningBase) {
+    try {
+        const milestonesDir = node_path_1.default.join(planningBase, 'milestones');
+        for (const entry of node_fs_1.default.readdirSync(milestonesDir, { withFileTypes: true })) {
+            if (entry.isFile() && /-ROADMAP\.md$/i.test(entry.name))
+                return true;
+        }
+    }
+    catch {
+        /* no milestones archive dir */
+    }
+    try {
+        if (/SHIPPED/i.test(node_fs_1.default.readFileSync(roadmapPath, 'utf-8')))
+            return true;
+    }
+    catch {
+        /* no roadmap */
+    }
+    return false;
+}
 function sortWorkstreamInventories(inventories, activeWorkstreamName) {
     return [...inventories].sort((a, b) => {
         const aActive = a.name === activeWorkstreamName ? 1 : 0;
@@ -99,6 +126,7 @@ function inspectWorkstream(cwd, name, options = {}) {
             state: node_fs_1.default.existsSync(p.state),
             requirements: node_fs_1.default.existsSync(p.requirements),
         },
+        milestoneShipped: workstreamMilestoneShipped(p.roadmap, p.planning),
     });
 }
 function listWorkstreamInventories(cwd) {

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/agent-skills-bootstrap.md

@@ -0,0 +1,60 @@
+# Agent Skills Self-Load (Bootstrap)
+
+> **Shared contract.** Every `agent_skills` consumer agent self-loads its configured
+> skills in its mandatory init step, so a project's `.planning/config.json`
+> `agent_skills.<agent-type>` mapping reaches the agent that actually does the work —
+> even when the orchestrator did not run bash init (e.g. a runtime whose `Skill()`
+> delegation does not reliably execute the delegated workflow's bash, such as Cursor;
+> see open-gsd/gsd-core#1600 / #1601). This is the durable counterpart to the
+> orchestrator-side injection documented under
+> [Agent Skills Injection](../../docs/CONFIGURATION.md#agent-skills-injection).
+
+## When to run
+
+In your mandatory init step — right after `mandatory-initial-read.md` / the
+`Project skills` discovery, before any other work.
+
+## Steps
+
+1. **Dedup guard (MANDATORY).** Look at your own prompt. If it already contains an
+   `<agent_skills>` block, the orchestrator already injected one — **skip self-load
+   entirely.** Loading a second copy wastes context on runtimes where orchestrator-side
+   injection also runs (e.g. Claude Code). The guard is what keeps the two seams from
+   doubling the block.
+
+2. **Query your configured skills.** Use **your own agent type** — the `name:` value in
+   your frontmatter (e.g. an agent whose frontmatter says `name: gsd-executor` queries
+   `gsd-executor`). The query is read-only and idempotent — it exits 0 with an empty
+   block when nothing is configured for your type:
+
+   ```bash
+   _AGENT_SKILLS=$(gsd_run query agent-skills <YOUR-FRONTMATTER-NAME> 2>/dev/null || true)
+   ```
+
+   The runtime `gsd_run` resolver is the standard one from
+   `_runtime-launcher.snippet.sh`; your own init already defines it.
+
+3. **Read every listed skill.** The block emits entries as `@<path>/SKILL.md`
+   includes — `Read` each one before starting work. If the block is empty, there is
+   nothing to do (zero overhead).
+
+## What self-load does and does not cover
+
+| Skill form | Self-loads? | Notes |
+|---|---|---|
+| Project-relative path (`skills/my-skill`) | ✅ everywhere | `Read` the `@`-include |
+| Global personal (`global:<name>`) | ✅ everywhere | resolves to the runtime global skills dir, then `Read` |
+| Plugin-provided (`global:<plugin>:<skill>`) | Claude only | emitted as a Skill-tool directive on Claude; **skipped with a warning on all other runtimes** — the plugin/Skill-tool model has no equivalent elsewhere (#1601, #1258). Not closeable on Cursor. |
+
+## Notes
+
+- **Idempotent and read-only.** `query agent-skills` never mutates state; calling it
+  twice (once by the orchestrator, once by the agent) is harmless because the dedup
+  guard suppresses the second load.
+- **No new config keys.** This reuses the existing `agent_skills` map and the existing
+  `buildAgentSkillsBlock` / `cmdAgentSkills` machinery (`src/init.cts`). The 22 consumer
+  agent types are mirrored in `tests/agent-skills.test.cjs` (`CONSUMER_AGENTS`) and
+  guarded against drift by `tests/agent-skills-bootstrap.test.cjs`.
+- **Checkers / read-only agents.** Bash is universal across consumer agents, so
+  self-load works for plan-checkers, verifiers, and auditors too; the bootstrap assumes
+  no tool an agent lacks.

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/model-profiles.md

@@ -133,6 +133,33 @@ If you're using Claude Code with OpenRouter, a local model, or any non-Anthropic
 
 Without `inherit`, GSD's default `balanced` profile spawns specific Anthropic models (`opus`, `sonnet`, `haiku`) for each agent type, which can result in additional API costs through your non-Anthropic provider.
 
+## Advisor Tool (Claude Code)
+
+Claude Code (v2.1.98+) can pair the session's executor model with a stronger **advisor** model that it consults mid-generation for strategy and course-correction (Anthropic's [advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool)). This is a host-runtime feature, not a GSD setting — GSD selects each agent's *executor* model through the profile/tier system above; Claude Code supplies the advisor.
+
+Set it once at the session level with `/advisor <model>` (or the `advisorModel` setting / `--advisor` flag). **Subagents inherit the session advisor automatically**, so every GSD subagent an orchestrator spawns gets the same advisor with no per-agent configuration. It composes cleanly with GSD's tiering: the profile keeps executors cheap where the work is mechanical, and the advisor adds a stronger reviewer inline on the turns that benefit.
+
+### Candidate pairings
+
+Per Anthropic's advisor-tool docs the advisor must be at least as capable as the executor. Candidate pairings by profile — evaluate on your own workload; the quality/cost characterizations below are Anthropic-reported, not GSD guarantees:
+
+| Profile | Typical executors | Candidate advisor | Rationale (per Anthropic docs) |
+|---|---|---|---|
+| `budget` | Haiku / Sonnet | Fable 5 or Opus | A step up in intelligence over Haiku alone, at lower cost than switching the executor to a larger model |
+| `balanced` | Sonnet | Fable 5 or Opus | A quality lift at similar or lower total cost than Sonnet-solo on complex tasks |
+| `quality` / `adaptive` | Opus (planning), Sonnet | Fable 5 or Opus | Marginal on turns already at top capability; most valuable on the Sonnet-executor agents |
+
+Fable 5 is a valid advisor for Haiku 4.5, Sonnet 4.6/5, and Opus 4.8 executors, so it pairs with any tier a profile assigns.
+
+### When it's worth enabling
+
+- **Worth it:** long, multi-step agent loops where the plan matters but most turns are mechanical — e.g. `execute-phase` and `debug`. Anthropic's docs note advisor prompt-caching pays off at roughly three or more advisor calls, which these long loops make.
+- **Skip it:** short, one-shot agents (mappers, quick audits, single-file checks) — there is little to plan, and the advisor adds cost without a commensurate quality gain.
+
+### Constraint: session-level only (today)
+
+The advisor is a single session-wide setting inherited by all subagents; there is **no per-agent advisor selection**, so GSD cannot vary the advisor by role the way it varies the executor model (e.g. "no advisor on the Haiku mapper, a Fable 5 advisor on the Sonnet executor"). Per-agent advisor control is tracked upstream at [anthropics/claude-code#73072](https://github.com/anthropics/claude-code/issues/73072); until it lands, pick one session advisor that fits the most valuable agents in your run.
+
 ## Dynamic Routing with Failure-Tier Escalation (#3024)
 
 When `dynamic_routing.enabled = true` in `.planning/config.json`, the resolver picks a model from a tier-mapped table based on the agent's *default tier* (light / standard / heavy) and escalates to the next tier up on orchestrator-detected soft failure.

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.`