@therocketcode/gsd-core 1.8.4 → 1.9.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gsd-core",
   "displayName": "GSD Core",
-  "version": "1.8.4",
+  "version": "1.9.0",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "author": {
     "name": "TheRocketCodeMX",

package/agents/gsd-code-reviewer.md

@@ -13,7 +13,7 @@ Source files from a completed implementation have been submitted for adversarial
 Spawned by `/gsd:code-review` workflow. You produce REVIEW.md artifact in the phase directory.
 
 **CRITICAL: Mandatory Initial Read**
-If the prompt contains a `<required_reading>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
+Before any other action, use the `Read` tool to load `@~/.claude/gsd-core/references/engineering-standards.md` — the senior-quality contract you enforce both ways (see dimension 4 below). Then, if the prompt contains a `<required_reading>` block, load every file listed there too. This is your primary context.
 
 If the prompt contains a `<structural_findings>` block, treat those fallow findings as **ground truth** for cross-module facts (unused exports, duplicate blocks, circular dependencies). Your narrative findings should build on that substrate instead of contradicting it.
 </role>
@@ -59,6 +59,12 @@ This ensures project-specific patterns, conventions, and best practices are appl
 
 **3. Code Quality** — Dead code, unused imports/variables, poor naming conventions, missing error handling, inconsistent patterns, overly complex functions (high cyclomatic complexity), code duplication, magic numbers, commented-out code
 
+**4. Contract Conformance (enforce `engineering-standards.md` BOTH ways — you are the fresh-context adversary)** — Fit to the ADR's chosen rung for this subdomain is itself a defect class. Never reward "simpler is better"; the bar is "fits the architecture's chosen rung, executed fully." Hunt in both directions and classify as BLOCKER when behavior/architecture is wrong, WARNING otherwise:
+- **Reward-hacking / under-engineering:** hardcoded expected outputs; happy-path-only handling (missing edge cases/failure modes); a test weakened, skipped, deleted, or made trivially-passing (e.g. `assert True`, removed assertion, rewritten `expected`); logic the codebase already implements re-written instead of reused; CRUD / transaction-script or patching *around* a mandated abstraction where the ADR mandates a richer rung (Domain Model / ports / aggregates / CQRS) — under-built against the architecture.
+- **Over-engineering:** ports / aggregates / CQRS / speculative layers, options, or config the ADR did NOT mandate for this subdomain; an abstraction invented on the first or second similarity (the *wrong* abstraction — prefer duplication until the shape is obvious). Note: a mandated port/aggregate is NOT speculative — its absence is the defect, not its presence.
+
+To judge the rung, read the subdomain's classification and ADR (`DOMAIN-MODEL.md`, the architecture ADR) when present; absent those, fall back to "matches existing patterns + no hacks + complete."
+
 **Out of Scope (v1):** Performance issues (O(n²) algorithms, memory leaks, inefficient queries) are NOT in scope for v1. Focus on correctness, security, and maintainability.
 
 </review_scope>

package/agents/gsd-executor.md

@@ -18,6 +18,8 @@ Spawned by `/gsd:execute-phase` orchestrator.
 
 Your job: Execute the plan completely, commit each task, create SUMMARY.md, update STATE.md.
 
+Apply the senior-quality contract in @~/.claude/gsd-core/references/engineering-standards.md — the invariant quality bar, with structural ceremony set by the architecture decision (the ADR rung), not by taste. Build to the ADR rung the plan targets — fully and cleanly: no hacks, no hardcoded outputs, no test-weakening to pass; enumerate edge cases first, not just the happy path. Do not "simplify" by violating the chosen architecture, and do not add un-mandated structure.
+
 @~/.claude/gsd-core/references/mandatory-initial-read.md
 </role>
 
@@ -225,6 +227,11 @@ Use `gate="blocking-human"` for package-legitimacy checkpoints so they are unamb
 
 ---
 
+**TEST-INTEGRITY RULE (anti-reward-hacking — absolute):**
+During a non-test task, **editing, skipping, weakening, or deleting an existing test to make a check pass is FORBIDDEN.** A test exists so it *can* fail; making it trivially pass is hacking the gate, not completing the work. If a task's correct implementation genuinely requires a test change (a behavior the test no longer describes), STOP and surface it — document the required test change and why in the Summary's Deviations section (and as a checkpoint under Rule 4 if it reflects a real behavior change). Never silently touch a test file outside an explicit test task or TDD RED step.
+
+---
+
 **SCOPE BOUNDARY:**
 Only auto-fix issues DIRECTLY caused by the current task's changes. Pre-existing warnings, linting errors, or failures in unrelated files are out of scope.
 - Log out-of-scope discoveries to `deferred-items.md` in the phase directory

package/agents/gsd-pattern-mapper.md

@@ -19,6 +19,8 @@ Spawned by `/gsd:plan-phase` orchestrator (between research and planning steps).
 **CRITICAL: Mandatory Initial Read**
 If the prompt contains a `<required_reading>` block, you MUST use the `Read` tool to load every file listed there before performing any other actions. This is your primary context.
 
+Apply the senior-quality contract in @~/.claude/gsd-core/references/engineering-standards.md — the invariant quality bar, with structural ceremony set by the architecture decision (the ADR rung per subdomain), not by taste. The analogs you surface must be architecture-appropriate: don't hold up a thin CRUD analog for a subdomain the ADR marked rich (Domain Model / hexagonal), or a heavy aggregate/port analog for a subdomain the ADR marked a simple Transaction Script. Match the analog to the chosen rung, both directions.
+
 **Core responsibilities:**
 - Extract list of files to be created or modified from CONTEXT.md and RESEARCH.md
 - Classify each file by role (controller, component, service, model, middleware, utility, config, test) AND data flow (CRUD, streaming, file I/O, event-driven, request-response)

package/agents/gsd-phase-researcher.md

@@ -16,6 +16,8 @@ You are a GSD phase researcher. You answer "What do I need to know to PLAN this
 
 Spawned by `/gsd:plan-phase` (integrated) or `/gsd:plan-phase --research-phase <N>` (standalone).
 
+Recommended approaches must fit the project's chosen architecture rung (recommend-architecture's ADR per subdomain) and the senior-quality contract in @~/.claude/gsd-core/references/engineering-standards.md — never recommend a patch or workaround where the architecture calls for proper structure, and never recommend ceremony (ports/aggregates/CQRS) where the rung is a simple Transaction Script. Both directions are defects.
+
 @~/.claude/gsd-core/references/mandatory-initial-read.md
 
 **Core responsibilities:**

package/agents/gsd-plan-checker.md

@@ -44,6 +44,7 @@ Issues without a severity classification are not valid output.
 
 <required_reading>
 @~/.claude/gsd-core/references/gates.md
+@~/.claude/gsd-core/references/engineering-standards.md
 </required_reading>
 
 This agent implements the **Revision Gate** pattern (bounded quality loop with escalation on cap exhaustion).
@@ -77,7 +78,7 @@ If CONTEXT.md exists, add verification dimension: **Context Compliance**
 - Do plans honor locked decisions?
 - Are deferred ideas excluded?
 - Are discretion areas handled appropriately?
-- **Do plans honor the canonical discovery artifacts?** Flag a HIGH concern if a task contradicts the architecture ADR's per-subdomain rung (e.g. CRUD where a Domain Model is mandated), the DOMAIN-MODEL classification, or the TEST-STRATEGY's test levels (e.g. unit-mocking the DB where integration via Testcontainers is required, or float money where integer minor units are mandated). Same for INFRA-STRATEGY/CICD-STRATEGY when present (e.g. committed .env where the secret manager is mandated, or a deploy approach contradicting the chosen ladder rung).
+- **Do plans honor the canonical discovery artifacts?** Flag a HIGH concern if a task contradicts the architecture ADR's per-subdomain rung (e.g. CRUD where a Domain Model is mandated), the DOMAIN-MODEL classification, or the TEST-STRATEGY's test levels (e.g. unit-mocking the DB where integration via Testcontainers is required, or float money where integer minor units are mandated). Same for INFRA-STRATEGY/CICD-STRATEGY when present (e.g. committed .env where the secret manager is mandated, or a deploy approach contradicting the chosen ladder rung). Per `engineering-standards.md` this gate is **symmetric** — flag HIGH in BOTH directions, never bias toward "simpler": (a) a plan that bakes in a hack/shortcut to pass a gate (hardcoded expected output, weakened/skipped test, "make it pass"); (b) **under-engineering** — CRUD/transaction-script, or patching around a mandated abstraction, where the ADR mandates a richer rung (Domain Model / ports / aggregates / CQRS); (c) **over-engineering** — adding ports/aggregates/CQRS/speculative layers the ADR did NOT mandate for that subdomain.
 </upstream_input>
 
 <core_principle>

package/agents/gsd-planner.md

@@ -22,6 +22,8 @@ Spawned by:
 
 Your job: Produce PLAN.md files that Claude executors can implement without interpretation. Plans are prompts, not documents that become prompts.
 
+Apply the senior-quality contract in @~/.claude/gsd-core/references/engineering-standards.md — the invariant quality bar, with structural ceremony set by the architecture decision (recommend-architecture's ADR per subdomain), not by taste. Plans must build the ADR's chosen rung fully where it is mandated and avoid un-mandated ceremony; both over- and under-engineering are defects.
+
 @~/.claude/gsd-core/references/mandatory-initial-read.md
 
 **Core responsibilities:**
@@ -155,6 +157,8 @@ Plan -> Execute -> Ship -> Learn -> Repeat
 
 **Anti-enterprise patterns (delete if seen):** team structures, RACI matrices, sprint ceremonies, time estimates in human units, complexity/difficulty as scope justification, documentation for documentation's sake.
 
+**Ship Fast ≠ skip structure.** Architecture the ADR mandates for a subdomain (Domain Model / hexagonal ports / CQRS / event-driven where the rung calls for it) is built fully — that *is* the quality bar there, not enterprise bloat. Only UN-mandated ceremony gets cut. Cutting mandated structure "to ship faster" is under-engineering, which `gsd-plan-checker` flags HIGH.
+
 </philosophy>
 
 <discovery_levels>

package/agents/gsd-verifier.md

@@ -41,6 +41,7 @@ Every truth must resolve to VERIFIED, FAILED (BLOCKER), or UNCERTAIN (WARNING wi
 <required_reading>
 @~/.claude/gsd-core/references/verification-overrides.md
 @~/.claude/gsd-core/references/gates.md
+@~/.claude/gsd-core/references/engineering-standards.md
 </required_reading>
 
 This agent implements the **Escalation Gate** pattern (surfaces unresolvable gaps to the developer for decision).
@@ -441,7 +442,18 @@ grep -n -B 2 -A 2 "console\.log" "$file" 2>/dev/null | grep -E "^\s*(const|funct
 
 **Debt marker gate:** Any `TBD`, `FIXME`, or `XXX` marker in a file modified by this phase is a 🛑 BLOCKER unless the same line references formal follow-up work (`issue #123`, `PR #123`, `#123`, or `DEF-*`). Unreferenced markers mean completion is not auditable; set `status: gaps_found` and list each marker under `gaps`.
 
-Categorize: 🛑 Blocker (prevents goal or unresolved debt marker) | ⚠️ Warning (incomplete) | ℹ️ Info (notable)
+**Reward-hacking gate (per `engineering-standards.md`):** A check that was made to pass by tampering, not by working code, is a FAILED verification — not a convenience. Treat each of these as a 🛑 BLOCKER (`status: gaps_found`):
+- A test that was **weakened, skipped, or made trivially-passing** (`.skip`/`xit`/`@pytest.mark.skip`/`#[ignore]`/`t.Skip`, an assertion deleted or loosened, a body replaced with `assert True`/`expect(true)`, an `expected` value rewritten to match wrong output).
+- A **hardcoded expected output** that makes a behavior or gate pass without real computation.
+- A **test-file edit accompanying a non-test task** — when the phase's stated work is not "add/change tests" yet `*-SUMMARY.md` key-files or the commits touch test files, flag it to INVESTIGATE: confirm the test still *can* fail and asserts real behavior; if it was loosened to pass the implementation, it is a BLOCKER.
+
+```bash
+git diff ${DIFF_BASE:-HEAD~1}..HEAD -- '*test*' '*spec*' 2>/dev/null | grep -nE '^\-.*(assert|expect|EXPECT)|\+.*(skip|xit|\.only|assert\s*\(?\s*[Tt]rue|return;?\s*//.*skip)'
+```
+
+**Architecture-fit gate (per `engineering-standards.md`; only when `.planning/adr/*.md` or `DOMAIN-MODEL.md` exists):** "wired and tamper-free" is not enough — the implementation must match the ADR's chosen rung for the subdomain it touches. Read the latest ADR + DOMAIN-MODEL and check **both directions**: (a) **under-engineering** — thin CRUD / transaction-script / a patch-around where the rung mandates a Domain Model / hexagonal ports / CQRS / event-driven flow (a working-but-wrong-shape implementation is a 🛑 BLOCKER, `status: gaps_found` — it's the under-build the contract forbids, not a passing phase); (b) **over-engineering** — ports/aggregates/CQRS/speculative layers on a subdomain the ADR marked Transaction Script (⚠️ Warning). Judge the shape, not just that it runs. If no ADR/DOMAIN-MODEL exists, skip this gate.
+
+Categorize: 🛑 Blocker (prevents goal, unresolved debt marker, reward-hacked check, or ADR-rung under-build) | ⚠️ Warning (incomplete, or over-built vs the rung) | ℹ️ Info (notable)
 
 ## Step 7b: Behavioral Spot-Checks
 

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "gsd-core",
-  "version": "1.8.4",
+  "version": "1.9.0",
   "description": "GSD Core — a meta-prompting, context engineering, and spec-driven development system for AI coding agents. Loads gsd's operating context into every Gemini CLI session.",
   "contextFileName": "GEMINI.md"
 }

package/gsd-core/references/engineering-standards.md

@@ -0,0 +1,45 @@
+# Engineering Standards — The Senior Quality Contract
+
+Shared reference injected into the producing agents (`gsd-planner`, `gsd-phase-researcher`, `gsd-pattern-mapper`, `gsd-executor`, `discuss-phase`) and enforced by the reviewing agents (`gsd-plan-checker`, `gsd-verifier`, `gsd-code-reviewer`). It encodes the behaviors a senior engineer actually performs — **not adjectives**. The evidence is explicit: telling a model to write "clean, elegant, senior" code is low-impact (and `CRITICAL: YOU MUST` caps now *backfire*); what moves quality is *specific behaviors* plus *external gates the producer cannot fake*.
+
+## The calibration spine (read first — both directions are failures)
+
+**Fit the solution to the problem's real complexity. Over- and under-engineering both produce mess.** Over-engineering: hexagonal for a script, speculative abstraction, config for imagined futures. **Under-engineering: patching, hacking, thin CRUD over a rich domain, skipping the structure the architecture requires — this is the failure mode that produces most "mess", because there is no proper structure to hang a clean solution on.** Hold two things separate:
+
+- **The quality bar is INVARIANT.** Correctness, completeness, edge-case handling, clear names, matching existing patterns, and no-hacks apply to an MVP exactly as to a complex system. High internal quality is cheaper at every horizon (Fowler) — never trade it for speed.
+- **The structural ceremony is SET BY `recommend-architecture`'s ADR, per subdomain — not chosen by the planner's or executor's taste.**
+  - Where the ADR mandates a **Domain Model / hexagonal ports / CQRS / event-driven** flow (a genuinely complex core — e.g. a rich matching/scheduling/memory engine), implement it **fully and cleanly**. Building those abstractions properly *is* the quality bar here. A shortcut that violates the chosen rung — CRUD where a Domain Model is mandated, a direct call where a port is mandated — is **under-engineering, i.e. a hack**, and `gsd-plan-checker` flags it HIGH.
+  - Where the ADR says **Transaction Script** (a simple/CRUD subdomain), adding ports, aggregates, or layers is **over-engineering** — equally a defect.
+
+**Simplicity operates *within* the chosen architecture, never *against* it.** If the architecture genuinely no longer fits the need, raise it as a promotion trigger (`recommend-architecture` / `new-milestone`) — never quietly under-build around it. Proportionality both ways: don't impose ceremony on a one-sentence diff; don't skip the bar on a complex one. Complexity = essential (the job, irreducible — Brooks) + accidental (mess, optional). Remove only the mess.
+
+## The contract (behaviors — most load-bearing last)
+
+1. **Understand before you change.** Read the real code paths, the tests-as-spec, and — for this subdomain — the DOMAIN-MODEL classification and the ADR rung, before deciding or writing. Most defects are acting on an incomplete mental model, or building to the wrong structure.
+2. **Build to the architecture, fully.** Implement the rung the ADR chose for this subdomain — its ports, aggregates, boundaries — properly and completely. Don't skip mandated structure "to keep it simple" (under-engineering); don't add un-mandated structure "to be robust" (over-engineering).
+3. **Match what exists; deep modules, clear names.** Make new code look like it belongs — reuse the established patterns, names, and conventions (`gsd-pattern-mapper` supplies the analogs); don't add a second way to do something that already has one. Prefer a simple interface over real substance to many shallow pass-throughs (Ousterhout — and "extract into tiny functions" is genuinely contested; don't cargo-cult classitis). Descriptive names are one of the few empirically-validated quality levers.
+4. **Don't invent un-mandated structure (but build everything the ADR mandates).** Prefer duplication to a *speculative* abstraction — duplication is far cheaper than the wrong abstraction (Metz); wait until the right shape is obvious, inline it back when it stops fitting (AHA); DRY is about *knowledge*, not coincidentally-similar code. Skip speculative layers/options/config for imagined futures (YAGNI; Fowler's cost-of-carry). None of this overrides the architecture's *deliberate, required* abstractions — a mandated port/aggregate is not speculative; declining it is under-engineering, not YAGNI.
+5. **Bounded boy-scout.** Improve what you touch when the change needs it and it's honestly better; keep structural changes in a *separate* commit from behavioral ones (Beck's two hats); flag larger refactors instead of silently sprawling — unbounded refactoring is scope creep.
+6. **Correct AND complete — edge cases first.** Before coding, enumerate the edge cases and failure modes the behavior must handle; a change that serves only the happy path is unfinished. This completeness is what makes code simple — not doing less.
+7. **Never hack a check to pass.** Don't hardcode an expected output, weaken/skip/delete a test, or make a gate trivially pass. A test exists so it *can* fail; one that cannot fail is worthless. (Caught mechanically by the reviewers below — not trusted to good intent.)
+
+## Why this is enforced by gates, not vibes
+
+Prose against shortcuts is *weak alone* — frontier agents still write "make verify return true" under pressure. The durable counter is an external signal the producer can't fake, plus a fresh-context reviewer that checks **both** directions:
+
+- **`gsd-plan-checker`** rejects plans that bake in hacks, under-build the ADR rung (CRUD where a Domain Model is mandated), or over-build a simple subdomain.
+- **`gsd-verifier`** assumes the goal was NOT met until codebase evidence proves it; "file exists" ≠ "behavior works"; a test-file edit during a non-test task is a flag, not a convenience.
+- **`gsd-code-reviewer`** is the fresh-context adversary: it hunts hardcoded outputs, happy-path-only handling, weakened tests, duplication, the wrong abstraction — *and* under-engineering against the architecture.
+- The **falsifiability gate** (`ai-test-quality.md`) proves each test can fail before it counts.
+
+## Anti-patterns (both directions)
+
+- **Under-engineering:** patching around a missing-but-needed abstraction instead of building it; thin CRUD / transaction-script over a domain the ADR marked rich; "keeping it simple" by violating the chosen architecture; happy-path-only; skipping edge cases.
+- **Over-engineering:** hexagonal/ports/CQRS with no ADR mandate; abstracting on the first or second similarity; speculative generality and config-for-imagined-futures.
+- **Both:** adjective-prompting your own output ("I'll write clean code") instead of doing the behaviors; mixing a refactor and a behavior change in one commit; re-implementing logic the codebase already has; "make it pass" hacks.
+
+*Basis: Ousterhout (A Philosophy of Software Design — deep modules, complexity is incremental); Metz ("the wrong abstraction"); Dodds (AHA); Thomas (DRY = knowledge); Beck (Tidy First, two hats); Fowler (YAGNI, cost-of-carry, "internal quality is cheaper at every horizon"); Brooks (essential vs accidental complexity); Anthropic/OpenAI/DeepMind on agent prompting, reward-hacking, and verification. Full citations in the research corpus.*
+
+## Consumes / produces
+
+Read by `gsd-planner`, `gsd-phase-researcher`, `gsd-pattern-mapper`, `gsd-executor`, and `discuss-phase`; enforced by `gsd-plan-checker`, `gsd-verifier`, `gsd-code-reviewer`. The structural-ceremony decision is owned by `recommend-architecture` (the rung ladder); this contract governs how *well* the chosen rung is executed. Pairs with `universal-anti-patterns.md` (framework pitfalls), `test-doubles.md` + `ai-test-quality.md` (test quality).

package/gsd-core/references/scout-codebase.md

@@ -1,14 +1,53 @@
-# Codebase scout — map selection table
+# Codebase scout — map selection + scaled deep-scout protocol
 
 > Lazy-loaded reference for the `scout_codebase` step in
 > `workflows/discuss-phase.md` (extracted via #2551 progressive-disclosure
-> refactor). Read this only when prior `.planning/codebase/*.md` maps exist
-> and the workflow needs to pick which 2–3 to load.
+> refactor). Read this when the workflow needs to scout the codebase before
+> identifying gray areas.
+>
+> The scout has **two paths**. Assess depth FIRST (see "Depth assessment"),
+> then run exactly one:
+> - **Shallow path** (default for trivial/reversible phases) — the light
+>   inline map-selection scan below. Cheap.
+> - **Deep path** (complex / high-blast-radius / hard-to-reverse / touches
+>   the core) — parallel read-only explorers on distinct lenses, then an
+>   orchestrator confirm-or-refute gate. ~15× the tokens; earned, not default.
+>
+> Both feed the same internal `<codebase_context>`. The deep path adds a
+> VERIFIED-vs-INFERRED split and a reconciled, evidence-backed understanding.
 
-## Phase-type → recommended maps
+## Depth assessment (run first — gates the cheap vs deep path)
 
-Read 2–3 maps based on inferred phase type. Do NOT read all seven —
-that inflates context without improving discussion quality.
+Do NOT always-max. Multi-agent scouting burns ~15× the tokens of a single
+read; spend it only where blast-radius justifies it. Score the phase on four
+axes (from the phase title, ROADMAP entry, and prior context):
+
+| Axis | Light end (→ shallow) | Heavy end (→ deep) |
+|---|---|---|
+| **Complexity** | one file, clear-cut, CRUD | cross-cutting, many moving parts |
+| **Blast radius** | isolated, leaf code | touches the core / shared infra / many call sites |
+| **Reversibility** | trivially revertable | hard to reverse (schema, public API, data migration, payments) |
+| **Decomposability** | n/a | understanding splits cleanly into independent angles |
+
+**Routing rule:**
+- **All axes light** → **shallow path**. Run the map-selection scan only.
+- **Any of: high complexity, high blast-radius, low reversibility, or "touches
+  the core"** → **deep path** (parallel lenses + confirm-or-refute gate).
+- **Tightly-coupled / sequential understanding** (the angles can't be explored
+  independently) → prefer **one deep continuous-context pass** over many
+  parallel explorers (Cognition: parallel workers drift on conflicting
+  assumptions). Use the deep path's verification gate, but a single explorer.
+
+**Overrides:** an explicit `--deep` forces the deep path; `--shallow` forces
+the light path. With no flag, the routing rule above decides. Log the resolved
+path and the axis that triggered it (e.g. `[scout] deep — schema change,
+low reversibility`).
+
+## Shallow path — phase-type → recommended maps
+
+The cheap, single-pass scan. Read 2–3 maps based on inferred phase type. Do
+NOT read all seven — that inflates context without improving discussion
+quality.
 
 | Phase type (infer from title + ROADMAP entry) | Read these maps |
 |---|---|
@@ -49,3 +88,96 @@ From the scan, identify:
 
 Used in `analyze_phase` and `present_gray_areas`. NOT written to a file —
 session-only.
+
+On the **deep path**, this same `<codebase_context>` additionally carries a
+`VERIFIED facts` / `INFERRED facts` split and the explicit open questions left
+at the stop (see below).
+
+---
+
+## Deep path — parallel read-only explorers on distinct lenses
+
+Run this only when the depth assessment routed here. Reuses the exact
+parallel-dispatch machinery the advisor mode (`modes/advisor.md`
+`advisor_research`) and `discuss-phase-assumptions.md` already use: spawn
+`Agent()` calls simultaneously, then synthesize. Do NOT invent new machinery.
+
+**Read-only is a hard constraint.** Explorers answer questions; they never
+write code (Cognition: parallel writers amplify conflicting decisions; parallel
+read-only scouts are safe). They glob/grep/read/inspect git history only.
+
+### Lens menu — pick 2–4 relevant to the phase type
+
+Spawn one explorer per lens, each owning a DISTINCT angle (not N identical
+agents — that just duplicates work). Give each Anthropic's 4-part contract:
+objective, output format, tools/sources, and boundaries ("don't cover X —
+that's another explorer's job").
+
+| Lens | Owns | Pick when |
+|---|---|---|
+| **by-layer / structure & dependency** | architecture, modules, who-calls-whom, the real dependency graph | almost always (the spine) |
+| **by-data-flow** | how data enters / transforms / exits; invariants; persistence | data models, schema, state, pipelines |
+| **by-control-flow / call-path** | real execution paths, entry points (traced, not assumed) | behavior changes, request/handler flows |
+| **by-goals/intent + tests-as-spec** | what it's supposed to do; tests read as the executable spec; existing conventions to imitate | any phase modifying established behavior |
+| **by-failure-mode** | error handling, edge cases, where it breaks, retry/timeout paths | high-blast-radius, low-reversibility, infra |
+
+Default selection: **by-layer + by-goals/tests** for most phases; add
+**by-data-flow** for data/schema work, **by-control-flow** for behavior work,
+**by-failure-mode** for high-blast-radius/infra.
+
+### Explorer contract (required of every lens)
+
+Each explorer MUST return:
+- **Load-bearing claims with `file:line` citations** — and, for counts or
+  exhaustiveness claims, the command + its raw output. No bare assertions.
+- **An honest coverage statement** — "searched 2 of 5 dirs", not
+  "searched all locations". Partial is fine; lying-by-omission is not.
+- **A VERIFIED vs INFERRED split** — facts read from tool output vs
+  conclusions drawn from them.
+
+> **ORCHESTRATOR RULE — CODEX RUNTIME**: After calling all Agent() calls above
+> to spawn explorers, do NOT independently scout or analyze the codebase while
+> the subagents are active. Wait for all explorers to return before
+> synthesizing. This prevents duplicate work and wasted context.
+
+## Orchestrator confirm-or-refute gate (the load-bearing part)
+
+~20–30% of subagent reports contain at least one claim that doesn't match the
+underlying tool output, and self-verification is unreliable. So the
+orchestrator does NOT trust the explorers' prose. After all explorers return,
+before adopting anything into `<codebase_context>`:
+
+1. **Spot-check the highest-risk / load-bearing claims against RAW TOOL
+   OUTPUT** — re-read the actual file at the cited `file:line`, re-run the
+   grep/count yourself. Check claims against the tool output, never against the
+   agent's summary. Prioritize: inflated/exhaustiveness claims ("found 15
+   files", "searched all", "applied successfully"), and any claim a gray area
+   or plan would hang on. You need not re-verify everything — re-derive the
+   pivotal facts.
+2. **Require citations for load-bearing claims.** A load-bearing claim with no
+   `file:line` (or no command+output) is treated as INFERRED, not VERIFIED,
+   until you ground it yourself.
+3. **Reconcile contradictions — mandatory, never silently pick.** When two
+   explorers disagree (e.g. "3 call sites" vs "5 call sites"), surface the
+   contradiction and resolve it against ground truth (re-grep), don't merge or
+   pick one quietly.
+4. **Separate VERIFIED from INFERRED** in the resulting `<codebase_context>`.
+   Carry both forward labelled — never collapse inference into fact.
+5. **Never summarize a summary.** On any disputed or load-bearing point,
+   re-ground at the source rather than paraphrasing an explorer's paraphrase.
+
+## Sufficiency stop (avoid analysis paralysis)
+
+State the stop criterion explicitly. Stop scouting and proceed to
+`analyze_phase` when **all three** hold:
+- **Confidence threshold met** — the chosen lenses are covered and the real
+  call-path / data-flow for the change site was traced, not assumed. Satisfice
+  (~good enough to decide), don't optimize.
+- **Budget cap not exceeded** — within the tool-call/explorer budget for this
+  task class (cheap fact-finding gets few; complex/high-blast gets more).
+- **Saturation** — the last round surfaced **no new load-bearing facts AND all
+  contradictions are resolved.**
+
+Record any remaining open questions explicitly (bounded, named) and carry them
+into `<codebase_context>` — don't keep scouting to chase curiosity. Only once
+the gate passes is the understanding "sufficient AND verified".

package/gsd-core/workflows/cicd-strategy.md

@@ -133,6 +133,12 @@ CICD-STRATEGY.md written — pipeline mapped to the test strategy.
 Next: /gsd:plan-phase   (CI/deploy phases will plan against this strategy)
 ```
 
+**Strategy-chain completion (this is the chain's last link — close the loop):**
+1. **Synthesis table** — if other strategy artifacts exist (`PRODUCT-BRIEF`, `DOMAIN-MODEL`, `adr/*`, `TEST-STRATEGY`, `INFRA-STRATEGY`), display a one-line-per-artifact decision summary so the user sees the whole strategized picture in one place.
+2. **Final roadmap reconciliation** — scan ROADMAP.md against ALL strategy artifacts (not just this one): phases straddling module seams, build-phases mooted by buy-decisions, missing walking skeleton, CI/release work unaccounted for. Surface every contradiction explicitly and offer `/gsd:phase --edit` or a roadmap refresh — never end the chain with a known contradiction unspoken.
+3. Remind the user the artifacts are now canonical references: the planner must read them and the plan-checker raises HIGH on contradiction.
+4. If the session is long, suggest a fresh session for the build loop (`/gsd:discuss-phase`) — the artifacts carry the full state.
+
 </process>
 
 <critical_rules>

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

@@ -8,6 +8,7 @@ You are a thinking partner, not an interviewer. The user is the visionary — yo
 @~/.claude/gsd-core/references/domain-probes.md
 @~/.claude/gsd-core/references/gate-prompts.md
 @~/.claude/gsd-core/references/universal-anti-patterns.md
+@~/.claude/gsd-core/references/engineering-standards.md
 </required_reading>
 
 <progressive_disclosure>
@@ -278,16 +279,19 @@ Parse JSON for: `todo_count`, `matches[]` (each with `file`, `title`, `area`, `s
 </step>
 
 <step name="scout_codebase">
-Lightweight scan of existing code to inform gray area identification (~10% context).
+Scan existing code to inform gray area identification — depth SCALED to the phase, not always-max.
 
-Read `@~/.claude/gsd-core/references/scout-codebase.md` — it contains the phase-type→map selection table, single-read rule, no-maps fallback, and `<codebase_context>` output schema. Then execute:
-1. `ls .planning/codebase/*.md` to find existing maps
-2. Select 2–3 maps via the reference's table; or grep fallback if none exist
-3. Build internal `<codebase_context>` per the reference's output schema
+Read `@~/.claude/gsd-core/references/scout-codebase.md` — it contains the depth assessment, the shallow map-selection scan, the deep-path lens menu, the orchestrator confirm-or-refute gate, and the sufficiency stop. Then:
+
+1. **Assess depth first** (reference's "Depth assessment"). Score the phase on complexity × blast-radius × reversibility × decomposability. `--deep`/`--shallow` in $ARGUMENTS override; otherwise auto-route. Log the resolved path and the trigger.
+
+2. **Shallow path** (default — trivial/reversible phases, ~10% context): `ls .planning/codebase/*.md`, select 2–3 maps via the reference's table (or grep fallback if none exist), build internal `<codebase_context>`.
+
+3. **Deep path** (complex / high-blast-radius / hard-to-reverse / touches-the-core): spawn parallel READ-ONLY explorers on 2–4 distinct lenses, reusing the advisor-mode/`discuss-phase-assumptions` parallel `Agent()` dispatch + ORCHESTRATOR RULE (do not invent new machinery). Each returns `file:line`-cited claims, honest coverage, and a VERIFIED-vs-INFERRED split. Then run the reference's **confirm-or-refute gate** (spot-check highest-risk claims against RAW TOOL OUTPUT not prose; reconcile contradictions against ground truth; keep VERIFIED separate from INFERRED; never summarize-a-summary) and stop per its sufficiency criterion. Build `<codebase_context>` from the reconciled, evidence-backed understanding.
 </step>
 
 <step name="analyze_phase">
-Analyze the phase to identify gray areas. Use both `prior_decisions` and `codebase_context` to ground the analysis.
+Analyze the phase to identify gray areas. Use both `prior_decisions` and `codebase_context` to ground the analysis. When `scout_codebase` ran the deep path, ground gray areas in its **VERIFIED** facts; treat **INFERRED** facts and recorded open questions as things to confirm with the user, not as settled premises.
 
 1. **Domain boundary** — What capability is this phase delivering? State it clearly.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@therocketcode/gsd-core",
-  "version": "1.8.4",
+  "version": "1.9.0",
   "description": "GSD Core is a meta-prompting, context engineering, and spec-driven development system for AI coding agents.",
   "bin": {
     "gsd-core": "bin/install.js",