@opengsd/gsd-core 1.7.0 → 1.9.0

package/gsd-core/references/debugger-sbfl.md

@@ -0,0 +1,110 @@
+# Spectrum-Based Fault Localization (SBFL) Pre-filter
+
+Loaded by `gsd-debugger` via `@-include`. A deterministic ranked "where to look
+first" list derived from existing test pass/fail coverage, computed before LLM
+reasoning over an unranked search space.
+
+## Why this exists
+
+`investigation_loop` Phase 1 searches the codebase and reads files to seed
+hypotheses via (expensive, non-deterministic) LLM reasoning over an unranked
+space. When a runnable test suite with per-test coverage exists, there is a
+cheap, deterministic signal being left on the table: which code is
+disproportionately executed by **failing** vs **passing** tests. SBFL turns
+that coverage spectrum into a suspiciousness ranking. The agent currently has no
+fault-localization step at all.
+
+## When to run it (Phase 1.25 — after initial evidence, before hypothesis formation)
+
+Run only when ALL hold:
+- A runnable test suite exists for the failing area.
+- At least one failing test AND at least one passing test exist (a spectrum
+  requires both).
+- Per-test coverage is available (which tests executed which code
+  element — function, line, or branch).
+
+If any precondition fails, **skip** this step with a logged note (see
+Degradation) and proceed with Phase 1's normal evidence gathering unchanged.
+
+## The Ochiai formula
+
+For each code element `s` executed by the test suite:
+
+```
+ochiai(s) = failed(s) / sqrt(totalFailed × (failed(s) + passed(s)))
+```
+
+where:
+- `failed(s)` = number of **failing** tests that executed `s`
+- `passed(s)` = number of **passing** tests that executed `s`
+- `totalFailed` = total number of failing tests in the suite
+
+The score is in `[0, 1]`. An element executed by every failing test and no
+passing test scores `1.0` (maximum suspiciousness). An element touched only by
+passing tests scores `0`. Ochiai is empirically stronger than Tarantula across
+the SBFL literature; **Tarantula** is the documented fallback formula
+(`tarantula(s) = (failed(s)/totalFailed) / ((failed(s)/totalFailed) + (passed(s)/totalPassed))`)
+if a comparison or secondary signal is wanted.
+
+## Output — top-N shortlist seeded into the hypothesis space
+
+Rank all executed elements by descending Ochiai score and take the **top-N**
+(N is judgment — 5–10 is typical; bounded by what narrows the search without
+flooding it). Append each top-N element to the debug file's **Evidence**
+section as a first-class hypothesis candidate:
+
+```
+- timestamp: <now>
+  checked: SBFL Ochiai ranking (Phase 1.25)
+  found: top-N suspicious locations —
+    1. path/to/file.cts:LINE (score 0.89) — <symbol>
+    2. path/to/other.cts:LINE (score 0.77) — <symbol>
+    ...
+  implication: investigate these before forming broader hypotheses
+```
+
+This narrows the search space by orders of magnitude before any LLM tokens are
+spent forming hypotheses. Each top-N entry becomes a candidate for Phase 2
+hypothesis formation, ranked ahead of un-evidenced guesses.
+
+## Degradation (Gall's Law — optional step, degrades onto the working agent)
+
+This step is **purely additive**. Every miss degrades to today's behavior; a
+skipped step is logged, never a silent pass (Kernighan — the debugger stays
+auditable).
+
+| Condition | Behavior |
+|---|---|
+| No test suite for the failing area | **skip** with a logged note in Evidence ("SBFL skipped: no test suite"); Phase 1 proceeds unchanged |
+| Test suite but no failing tests | **skip** with a logged note ("SBFL skipped: no failing tests — no spectrum"); Phase 1 proceeds unchanged |
+| Test suite but no passing tests | **skip** with a logged note ("SBFL skipped: no spectrum — no passing tests"); Phase 1 proceeds unchanged (Tarantula would divide by `totalPassed=0`; do not run it) |
+| Test suite but no per-test coverage | **skip** with a logged note ("SBFL skipped: no per-test coverage available"); Phase 1 proceeds unchanged |
+| Coverage exists but is coarse (file-level, not line/function) | run anyway, rank at the available granularity, and note the granularity in Evidence |
+
+## Bug-class gating (pairs with Phase 2B bug-taxonomy routing)
+
+SBFL is the go-to pre-filter for **deterministic failures (Bohrbugs)** — bugs
+that reproduce reliably. It is explicitly **not trusted** on
+**Heisenbug/Mandelbug** spectra (timing, races, environment-dependent failures):
+a flaky suite pollutes the spectrum (a "failing" test that sometimes passes
+poisons `failed(s)`), so the ranking becomes noise. When the failure is
+non-deterministic (Phase 2B classifies it), **skip SBFL** and route to
+record-replay or stability-stress instead. If SBFL has already run before
+classification and the class later resolves to Heisenbug/Mandelbug, mark the
+prior SBFL Evidence entry as revoked (do not delete it — Kernighan
+auditability) and note why in Evidence.
+
+## Scope boundary (Zawinski's Law)
+
+This is a deterministic pre-filter that reuses the project's existing
+test/coverage runner — it adds **no new coverage framework** and no new
+subsystem. It narrows the LLM's search space; it does not replace hypothesis
+formation, fix-and-verify, or the knowledge base. Coverage acquisition is the
+agent's adaptive job (use whatever coverage the project produces); the formula
+above is the canonical ranking.
+
+**Bound the coverage run** (CLAUDE.md gauntlet — unbounded subprocess): a
+coverage run is often 2–3× slower than a plain test run due to instrumentation,
+so cap it (60s for npm-tier suites; scale with suite size) and **degrade to
+skip with a logged note on timeout** — never let coverage acquisition hang the
+debug session.

package/gsd-core/references/debugger-semantic-recall.md

@@ -0,0 +1,81 @@
+# Semantic Knowledge-Base Recall via MemPalace
+
+Loaded by `gsd-debugger` via `@-include` from the `knowledge_base_protocol`
+Matching Logic. Replaces keyword-overlap matching with **semantic recall** so a
+prior session that resolved "requests hang under load" surfaces for a new "API
+times out when many users connect" — same root cause, no shared keywords.
+
+## Why this exists
+
+The knowledge base's self-noted limitation was explicit: *"Matching is keyword
+overlap, not semantic similarity."* Keyword overlap only fires on lexical
+coincidence — the highest-value recalls (same root cause, different wording)
+are exactly the ones it misses, and its value decays as the corpus grows.
+
+## The approach — reuse MemPalace, add no new infrastructure
+
+Layer semantic recall on top of the existing knowledge base by **reusing
+MemPalace** (the semantic-memory capability already in this environment) —
+**without adding new embedding or vector infrastructure** (Choose Boring /
+Zawinski: spend no new "innovation token" on a bespoke vector store the
+debugger would own).
+
+`.planning/debug/knowledge-base.md` remains the **durable plain-text source of
+truth**; semantic recall is an additive layer over it, not a replacement.
+
+## Write — index resolved sessions at archive
+
+At `archive_session`, after appending the entry to `knowledge-base.md` (the KB
+append + commit MUST succeed first — `knowledge-base.md` is the durable source
+of truth; skip indexing on KB-write failure), **index the resolved session into
+MemPalace**.
+
+**Index the agent-authored `Resolution` summary — `root_cause(s)` + `fix` + the
+Prevention `recurrence_guard` — NOT the raw user-supplied `Symptoms`.** The
+Resolution is the post-investigation, agent-synthesized signal; indexing it
+(rather than raw symptoms) excludes attacker-controlled prose from the
+cross-session index and reduces secret/PII leakage. Even so, **redact
+secret-shaped values** (API keys, bearer tokens, JWTs, passwords, credentials)
+from the summary before indexing — a bug report's error string can echo a
+secret, and MemPalace is a cross-session, cross-project store.
+
+## Invocation (the agent has no MCP tools — use the CLI)
+
+The `gsd-debugger` `tools:` frontmatter grants no MCP tools, so query and index
+via the **Bash CLI** (the headless/autonomous path): `mempalace search
+"<symptoms>" --wing <wing>` to recall, and the matching index command on
+archive. If an `mempalace_search(query, wing)` MCP tool is registered in the
+runtime, prefer it. **Resolve the wing** from `config.mempalace.wing` → else the
+project's `project_code` → else the project directory name (the same precedence
+every other MemPalace integration uses).
+
+## Read — query MemPalace at Phase 0
+
+At Phase 0, **query MemPalace semantically with the current symptoms** and
+surface the **top-k meaning-similar prior resolutions** as candidate
+hypotheses. Each surfaced candidate flows into Evidence exactly as a
+keyword-match candidate would — a hypothesis to test first, not a confirmed
+diagnosis.
+
+This catches the **same-root-cause / different-wording** case: a prior
+"requests hang under load" resolution surfaces for "API times out when many
+users connect" even though no keywords overlap.
+
+## Graceful degradation — MemPalace absent
+
+When MemPalace is unavailable (not installed, not configured, or the query
+errors), **fall back to keyword-overlap matching** against
+`knowledge-base.md`: extract nouns, error substrings, and **identifiers**
+(function/variable names — often the highest-signal token) from
+`Symptoms.errors` and `Symptoms.actual`, and scan each entry's `Error patterns`
+field for **2+ token overlap (case-insensitive)**. The fallback is logged
+(Kernighan — never a silent skip), and `knowledge-base.md` continues to be
+written regardless, so no session is lost to a missing palace.
+
+## Scope boundary (Zawinski's Law)
+
+An additive recall layer over the existing knowledge base, reusing an existing
+semantic-memory capability. Not a new command, not a vector database, not an
+embedding pipeline the debugger owns. Where MemPalace is absent the debugger
+behaves exactly as it did before this layer — keyword matching against the
+plain-text knowledge base.

package/gsd-core/references/execute-phase-quota-recovery.md

@@ -0,0 +1,55 @@
+**Step 7.1 detail — `class == "quota-exceeded"` recovery.**
+
+Do not offer "retry now". Run the step-5 spot-check first; if SUMMARY.md is missing but
+commits exist, route to safe-resume (`state.verify-against-disk`) instead of an immediate
+redispatch.
+
+**7.1a — provider escalation (#2296, opt-in).** A heavier tier on the same throttled
+provider is still throttled, so when `dynamic_routing.provider_escalation` is configured
+GSD swaps PROVIDER rather than waiting for a reset. `QUOTA_ATTEMPT` starts at 1 on the
+first quota failure of this phase and increments on each subsequent one.
+
+```bash
+ESC_JSON=$(gsd_run query resolve-execution gsd-executor --attempt "${QUOTA_ATTEMPT:-1}" --failure-class quota-exceeded)
+ESCALATED=$(echo "$ESC_JSON" | jq -r '.escalation.escalated')
+EXHAUSTED=$(echo "$ESC_JSON" | jq -r '.escalation.exhausted')
+ESC_FROM=$(echo "$ESC_JSON" | jq -r '.escalation.from')
+ESC_TO=$(echo "$ESC_JSON" | jq -r '.escalation.to')
+ESC_TRIED=$(echo "$ESC_JSON" | jq -r '.escalation.attempted | join(" -> ")')
+```
+
+- **`ESCALATED == "true"`** — log the switch, honor the provider's own backoff
+  (`sleep "$RETRY_AFTER"` when `RETRY_AFTER` is set), then re-dispatch the failed plan with
+  `executor_model` overridden to `$ESC_TO` and `QUOTA_ATTEMPT` incremented. Do not prompt —
+  this is the configured, opt-in path.
+
+  ```text
+  ⚡ Provider quota hit — escalating model: {ESC_FROM} → {ESC_TO}
+    Runtime sentinel: {SENTINEL}
+    {RETRY_HINT}
+  ```
+
+- **`EXHAUSTED == "true"`** — the ladder is spent. Fail loudly naming every model tried,
+  then fall through to the manual options below. Never silently retry the last one.
+
+  ```text
+  ⛔ Provider escalation exhausted — tried: {ESC_TRIED}
+  ```
+
+- **`ESCALATED == "false"` and not exhausted** — escalation is not configured for this
+  project; use the manual path below. This is the default.
+
+**7.1b — manual recovery (default when escalation is not configured).**
+
+```text
+⚠ Plan {plan_id} terminated by provider quota / rate limit
+  Runtime sentinel: {SENTINEL}
+  {RETRY_HINT}
+  Partial commits on worktree branch: {N}
+  SUMMARY.md present: {yes|no}
+  1. Wait for quota reset, then resume (recommended)
+2. Switch to a different runtime / model and resume
+3. Abort phase and report partial state
+```
+
+Re-run `/gsd:execute-phase` after the quota resets for Option 1.

package/gsd-core/references/execute-phase-requirement-revert.md

@@ -0,0 +1,8 @@
+**Revert this phase's own requirement IDs out of `Complete` before rendering the gap report (#2388).** A shared requirement ID can already read `Complete` at this point (its first-declaring plan finished before this verification ran) — a `gaps_found` verdict must not leave that premature `Complete` sitting in REQUIREMENTS.md. Scoped strictly to `PHASE_REQ_IDS` (this phase's own citations from `init.execute-phase`), so another phase's `Complete` row is never touched:
+
+```bash
+if [ -n "${PHASE_REQ_IDS}" ]; then
+  gsd_run query requirements.revert-phase ${PHASE_REQ_IDS} >/dev/null 2>&1 || true
+  gsd_run query commit "docs(phase-{X}): revert premature Complete requirements after gaps found" --files .planning/REQUIREMENTS.md >/dev/null 2>&1 || true
+fi
+```

package/gsd-core/references/execute-phase-response-language.md

@@ -0,0 +1,7 @@
+# Execute-Phase Response-Language Directive (#2402)
+
+**If `response_language` is set:** User-facing orchestrator output (questions, narration, report-template prose) in `{response_language}`; technical terms, code, file paths, and subagent prompts stay in English. Pass `response_language: {value}` into every spawned subagent prompt so any user-facing output they produce stays in the configured language.
+
+The literal report templates embedded in this workflow (`## Execution Plan`, `## Phase {X}: {Name} Execution Complete`, `## ⚠ Phase {X}: {Name} — Gaps Found`, etc.) are a structural source, not literal output to copy verbatim — render their prose translated into `{response_language}` while keeping headings' structural markers, table columns, IDs, commands, and file paths unchanged.
+
+This directive was extracted from `workflows/execute-phase.md` to keep that file under the frozen pre-phase-6 byte ceiling (ADR-857 Phase 6 capstone, `tests/fix-2285-claude-orchestration-wiring.test.cjs`). The `@-reference` is eager, so the runtime still loads this content alongside the workflow — the extraction is purely a file-size discipline, not a lazy-load optimization.

package/gsd-core/references/gate-prompts.md

@@ -90,11 +90,14 @@ Up to 4 suggested next actions with selection (status, resume workflows).
 3-option handler for existing CONTEXT.md in discuss workflow.
 - question: "Phase {N} already has a CONTEXT.md. How should we handle it?"
 - header: "Context"
-- options: Overwrite | Append | Cancel
+- options: Update it | View it | Skip
 
 ## Pattern: gray-area-option
 Dynamic template for presenting gray area choices in discuss workflow.
 - question: "{Gray area title}"
 - header: "Decision"
-- options: {Option 1} | {Option 2} | Let Claude decide
-- Note: Options generated at runtime. Always include "Let Claude decide" as last option.
+- options: {Option 1} | {Option 2}
+- Note: Options generated at runtime. Present real choices only — do NOT include a
+  "skip" or "you decide" option (the user ran discuss-phase to decide). An "Other"
+  free-text escape hatch may be offered per modes/default.md, but never a
+  "Let Claude decide" cop-out.

package/gsd-core/references/model-profile-resolution.md

@@ -1,38 +1,89 @@
 # Model Profile Resolution
 
-Resolve model profile once at the start of orchestration, then use it for all Task spawns.
+Resolve each agent's model through `gsd-tools`, then pass it to the `Agent()` spawn — or
+omit the parameter entirely when nothing resolved.
 
 ## Resolution Pattern
 
+Prefer the field your workflow's own `init.*` payload already emits (every orchestrator
+init that spawns subagents carries one — `mapper_model`, `planner_model`,
+`executor_model`, `doc_writer_model`, …). Declare it in the workflow's parse line so the
+binding is stated, not implied:
+
+```
+Parse JSON for: `mapper_model`, …
+```
+
+When the agent type is only known at runtime — a capability hook naming its own agent, for
+example — resolve it directly instead:
+
 ```bash
-MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+AGENT_MODEL=$(gsd_run query resolve-model "<agent-type>" --raw)
 ```
 
-Default: `balanced` if not set or config missing.
+Both surfaces return the same thing: a model string for the active runtime, or the **empty
+string** when nothing resolved.
 
 ## Lookup Table
 
 @~/.claude/gsd-core/references/model-profiles.md
 
-Look up the agent in the table for the resolved profile. Pass the model parameter to Task calls:
+## Passing the model to a spawn
 
 ```
-Task(
+Agent(
   prompt="...",
   subagent_type="gsd-planner",
-  model="{resolved_model}"  # "inherit", "sonnet", or "haiku"
+  model="{planner_model}"
+)
+```
+
+Substitute the field **this workflow bound** — never a generic placeholder name.
+
+**#2517 — omit, do not emit an empty model.** When the resolved value is `"inherit"` or
+empty, **omit the `model=` parameter entirely**:
+
+```
+Agent(
+  prompt="...",
+  subagent_type="gsd-planner"
 )
 ```
 
-**Note:** Opus-tier agents resolve to `"inherit"` (not `"opus"`). This causes the agent to use the parent session's model, avoiding conflicts with organization policies that may block specific opus versions.
+No model parameter is passed at all — `planner_model` resolved to `"inherit"` or empty, and
+omitting it inherits the orchestrator's model. Passing either value through as an argument
+instead 404s on non-Claude runtimes.
+
+This is not cosmetic, and both values really occur. `model_profile: "inherit"` — and any
+opus-tier agent — resolves to the literal string `"inherit"`. `resolve_model_ids: "omit"`
+resolves to the **empty string** whenever the project sets it explicitly or the active
+runtime has no native tier aliases; an agent type absent from the profile table takes that
+same empty-string path, because it has no tier for the earlier steps to resolve. Emitting
+either value verbatim fails the spawn on every runtime without native tier aliases.
+
+**#2684 — substitute a field your workflow actually bound.** `model="{…}"` must name a key
+your own `init.*` payload emits, a shell variable you assigned, or a field on your declared
+parse line. A placeholder that resolves to nothing does not fail loudly — the orchestrator
+silently invents a value, which is the invisible partial application ADR-1411 prohibits.
+`tests/model-omit-when-inherit-guard.test.cjs` enforces both rules.
+
+## Profile semantics
+
+**Note:** Opus-tier agents resolve to `"inherit"` (not `"opus"`). This causes the agent to
+use the parent session's model, avoiding conflicts with organization policies that may
+block specific opus versions — and, per the rule above, means the `model=` parameter is
+omitted rather than set.
 
-If `model_profile` is `"adaptive"`, agents resolve to role-based assignments (opus/sonnet/haiku based on agent type).
+If `model_profile` is `"adaptive"`, agents resolve to role-based assignments (opus/sonnet/
+haiku based on agent type).
 
-If `model_profile` is `"inherit"`, all agents resolve to `"inherit"` (useful for OpenCode `/model`).
+If `model_profile` is `"inherit"`, all agents resolve to `"inherit"` (useful for OpenCode
+`/model`).
 
 ## Usage
 
-1. Resolve once at orchestration start
-2. Store the profile value
-3. Look up each agent's model from the table when spawning
-4. Pass model parameter to each Task call (values: `"inherit"`, `"sonnet"`, `"haiku"`)
+1. Bind the model once — from the `init.*` payload field, or `query resolve-model` when the
+   agent type is runtime-determined
+2. Declare the bound field on the workflow's parse line
+3. Pass `model="{bound_field}"` on each `Agent()` spawn
+4. Omit `model=` entirely whenever the bound value is `"inherit"` or empty

package/gsd-core/references/offer-next.md

@@ -0,0 +1,88 @@
+<!--
+  offer-next.md — extracted from execute-phase.md step "offer_next" (#2537).
+  Eagerly @-referenced from execute-phase.md so runtime behavior is unchanged; the
+  extraction restores byte-budget headroom the frozen ceiling exists to provide.
+-->
+
+
+**Exception:** If `gaps_found`, the `verify_phase_goal` step already presents the gap-closure path (`/gsd:plan-phase {X} --gaps`). No additional routing needed — skip auto-advance.
+
+**No-transition check (spawned by auto-advance chain):**
+
+Parse `--no-transition` flag from $ARGUMENTS.
+
+**If `--no-transition` flag present:**
+
+Execute-phase was spawned by plan-phase's auto-advance. Do NOT run transition.md.
+After verification passes and roadmap is updated, return completion status to parent:
+
+```
+## PHASE COMPLETE
+
+Phase: ${PHASE_NUMBER} - ${PHASE_NAME}
+Plans: ${completed_count}/${total_count}
+Verification: {Passed | Gaps Found}
+
+[Include aggregate_results output]
+```
+
+STOP. Do not proceed to auto-advance or transition.
+
+**If `--no-transition` flag is NOT present:**
+
+**Auto-advance detection:**
+
+1. Parse `--auto` flag from $ARGUMENTS
+2. Read consolidated auto-mode (`active` = chain flag OR user preference; chain flag already synced in init step):
+   ```bash
+   AUTO_MODE=$(gsd_run query check auto-mode --pick active 2>/dev/null || echo "false")
+   ```
+
+**If `--auto` flag present OR `AUTO_MODE` is true (AND verification passed with no gaps):**
+
+```
+╔══════════════════════════════════════════╗
+║  AUTO-ADVANCING → TRANSITION             ║
+║  Phase {X} verified, continuing chain    ║
+╚══════════════════════════════════════════╝
+```
+
+Execute the transition workflow inline (do NOT use Agent — orchestrator context is ~10-15%, transition needs phase completion data already in context):
+
+Read and follow `~/.claude/gsd-core/workflows/transition.md`, passing through the `--auto` flag so it propagates to the next phase invocation.
+
+**If neither `--auto` nor `AUTO_MODE` is true:**
+
+**STOP. Do not auto-advance. Do not execute transition. Do not plan next phase. Present options to the user and wait.**
+
+**IMPORTANT: There is NO `/gsd-transition` command. Never suggest it. The transition workflow is internal only.**
+
+Check whether CONTEXT.md already exists for the next phase:
+
+```bash
+ls .planning/phases/*{next}*/{next}-CONTEXT.md 2>/dev/null || echo "no-context"
+```
+
+If CONTEXT.md does **not** exist for the next phase, present:
+
+```
+## ✓ Phase {X}: {Name} Complete
+
+/gsd:progress ${GSD_WS} — see updated roadmap
+/gsd:discuss-phase {next} ${GSD_WS} — start here: discuss next phase before planning  ← recommended
+/gsd:plan-phase {next} ${GSD_WS} — plan next phase (skip discuss)
+/gsd:execute-phase {next} ${GSD_WS} — execute next phase (skip discuss and plan)
+```
+
+If CONTEXT.md **exists** for the next phase, present:
+
+```
+## ✓ Phase {X}: {Name} Complete
+
+/gsd:progress ${GSD_WS} — see updated roadmap
+/gsd:plan-phase {next} ${GSD_WS} — start here: plan next phase (CONTEXT.md already present)  ← recommended
+/gsd:discuss-phase {next} ${GSD_WS} — re-discuss next phase
+/gsd:execute-phase {next} ${GSD_WS} — execute next phase (skip planning)
+```
+
+Only suggest the commands listed above. Do not invent or hallucinate command names.

package/gsd-core/references/planner-antipatterns.md

@@ -5,6 +5,12 @@
 
 ## Checkpoint Anti-Patterns
 
+### Writing guidelines
+
+**DO:** Automate everything before checkpoint, be specific ("Visit https://myapp.vercel.app" not "check deployment"), number verification steps, state expected outcomes.
+
+**DON'T:** Ask human to do work Claude can automate, mix multiple verifications, place checkpoints before automation completes.
+
 ### Bad — Asking human to automate
 
 ```xml

package/gsd-core/references/planner-mvp-mode.md

@@ -1,32 +1,31 @@
-# Planner — MVP Mode (Vertical Slice Strategy)
+# Planner — Tracer-First Decomposition (Vertical Slices)
 
-> Loaded by `gsd-planner` only when `MVP_MODE=true`. Standard horizontal-layer planning rules continue to apply for all other phases.
+> Loaded by `gsd-planner` for the **default** tracer-first decomposition: every phase LEADS with one thin end-to-end `type="tracer"` slice, then expansion tasks. `--no-tracer` (`TRACER_MODE=false`) restores standard horizontal-layer planning. The MVP enrichment (user-story framing) and Walking Skeleton mode apply *on top* when `MVP_MODE=true` / `WALKING_SKELETON=true`.
 
 ## Core Rule
 
 **Decompose by feature slice, not by technical layer.** Every task must move the user-facing capability forward. After each task, a real user can click through more of the feature than they could before.
 
-**Forbidden** in MVP mode:
+**Forbidden** under tracer-first:
 - "Create the database schema" as a standalone task
 - "Build the API layer" as a standalone task
 - "Wire up the UI" as a final integration task
 
-**Required** in MVP mode:
-- The first non-test task produces a working end-to-end path. Stubs are allowed for non-critical branches; the happy path must be real.
-- Each subsequent task either adds a new slice OR refines an existing slice (validation, error states, edge cases).
-- The phase goal is framed as a user story: "**As a** [user], **I want to** [do X], **so that** [Y]."
+**Required** under tracer-first:
+- The leading `tracer` task produces a working end-to-end path — production-quality, not a prototype. Stubs are allowed ONLY where they can later be filled without an architectural change; the happy path must be real.
+- Each subsequent expansion task either adds a new slice OR refines an existing slice (validation, error states, edge cases).
+- *(MVP enrichment, `MVP_MODE=true`)* The phase goal is framed as a user story: "**As a** [user], **I want to** [do X], **so that** [Y]."
 
 ## Task Order Pattern
 
 For a feature `F`:
 
-1. **Failing end-to-end test** for the happy path of `F`.
-2. **Thinnest viable slice** — UI form → API endpoint → DB read/write — that makes the test pass. Hard-coded values, missing validation, no error states are fine here.
-3. **Real data layer** — replace any stubs from Task 2 with real queries.
-4. **Validation + error states** — invalid input, network failure, empty states.
-5. **Production polish** — loading indicators, edge cases, accessibility checks.
+1. **Tracer slice** — the thinnest end-to-end path (UI form → API endpoint → DB read/write), wired through every layer with a real runnable `<verify>`. This task is always `type="tracer"`; production-quality, not a prototype; stubs only where later-fillable without an architectural change. Under `--tdd` it *also* starts red — its first move is a failing end-to-end test for the happy path of `F`.
+2. **Real data layer** — replace any stubs from the tracer with real queries.
+3. **Validation + error states** — invalid input, network failure, empty states.
+4. **Production polish** — loading indicators, edge cases, accessibility checks.
 
-Tasks 3-5 are not always all needed; gate by the phase's acceptance criteria.
+Tasks 2-4 are not always all needed; gate by the phase's acceptance criteria.
 
 ## Walking Skeleton Mode (`WALKING_SKELETON=true`)