@opengsd/gsd-pi 1.2.0 → 1.3.0-dev.eed73bea

package/src/resources/extensions/gsd/prompts/spec-phase.md

@@ -0,0 +1,29 @@
+You are running the GSD **spec-phase** workflow — clarify WHAT a milestone/slice delivers, with ambiguity scoring, before discussion or planning.
+
+## Target
+
+{{target}}
+
+## Flags
+
+- `--auto` — {{autoFlag}}
+- `--text` — {{textFlag}}
+
+## Process
+
+1. **Load intent.** Read the milestone/slice's stated goal, requirements, and any discuss/research context.
+
+2. **Draft the SPEC.** State, in plain language: what this delivers, for whom, the inputs/outputs, the success criteria, and explicit non-goals.
+
+3. **Score ambiguity.** For each part of the spec, score ambiguity (low/medium/high) and identify the specific phrase causing it. High-ambiguity items become discussion questions.
+
+4. **Resolve ambiguity.** For each high-ambiguity item: in `--auto`, infer and flag; otherwise ask one targeted question at a time to resolve it. Update the spec with the resolved language.
+
+5. **Write the SPEC** to the milestone/slice artifact in `.gsd/`. Recommend `/gsd discuss-phase` (deeper discussion) or `/gsd plan-phase` (the spec is clear enough to plan).
+
+## Success criteria
+
+- The spec states WHAT, not HOW.
+- Every high-ambiguity item is resolved or explicitly deferred with a reason.
+- Non-goals are explicit.
+- The recommended next step reflects remaining ambiguity.

package/src/resources/extensions/gsd/prompts/spike.md

@@ -0,0 +1,59 @@
+You are running the GSD **spike** workflow — experiential exploration that builds focused experiments to validate feasibility and produce verified knowledge for the real build.
+
+## Spike Input
+
+{{input}}
+
+## Flags
+
+- `--quick` — {{quickFlag}} (when true, skip decomposition/alignment and jump straight to building)
+- `--text` — {{textFlag}} (when true, use plain-text numbered lists instead of interactive prompts)
+- Frontier mode — {{frontierFlag}} (when true, analyze existing spikes and propose integration/frontier spikes instead of a new one)
+
+## Process
+
+### 1. Route the input
+
+- If frontier mode is active (no idea given, or the word "frontier"): go to **Frontier mode**.
+- Otherwise: continue to **Setup**.
+
+### 2. Setup
+
+Create `.gsd/spikes/` if it does not exist and determine the next spike number by listing existing `.gsd/spikes/[0-9][0-9][0-9]-*` directories. Use the project's detected stack (check `package.json` / `pyproject.toml` / `Cargo.toml` / `go.mod`) to choose technology. Avoid heavy tooling — pick whatever reaches a runnable result fastest.
+
+### 3. Decompose the idea (skip if `--quick`)
+
+Break the idea into 1–3 focused experiments. Each experiment should validate one specific risk or assumption with a clear **Given/When/Then** validation question. Order by highest risk first.
+
+### 4. Research (brief)
+
+For each experiment, do the minimum research needed to start building — library docs, API shape, known gotchas. Use `resolve_library`/docs lookups. Do not over-research.
+
+### 5. Build
+
+Create `.gsd/spikes/{{spikeId}}/` and build each experiment as a small, self-contained, runnable artifact. Prefer throwaway code that proves the point. Hardcode configuration — do not build config systems.
+
+### 6. Verify
+
+For each experiment, run the validation question and record a verdict: `VALIDATED`, `PARTIAL`, or `INVALIDATED`, with the evidence (command output, observed behavior).
+
+### 7. Document
+
+Write `.gsd/spikes/{{spikeId}}/README.md` with:
+- The original idea and the experiments run
+- Per-experiment verdict + evidence
+- Conclusions and recommendations for the real build
+- Any conventions discovered worth recording (stack, patterns)
+
+Append a one-line summary to `.gsd/CAPTURES.md` linking the README so the spike is discoverable.
+
+### 8. Frontier mode (only when frontier flag is active)
+
+Load the spike landscape: read `.gsd/spikes/*/README.md` and any `CONVENTIONS.md`. Analyze for **integration spikes** (validated spikes that share resources, hand off data, or contend) and **frontier spikes** (gaps, discovered dependencies, alternative approaches). Present concrete candidates with Given/When/Then questions and let the developer choose which to run.
+
+## Success criteria
+
+- Each experiment has a clear validation question and a recorded verdict with evidence.
+- Artifacts live under `.gsd/spikes/{{spikeId}}/`.
+- The README captures conclusions usable by the real build.
+- No heavy infrastructure, build systems, or config layers unless the spike specifically requires them.

package/src/resources/extensions/gsd/prompts/stats.md

@@ -0,0 +1,43 @@
+You are running the GSD **stats** workflow — display comprehensive project statistics.
+
+## Process
+
+Read the canonical gsd-pi state and present a statistics summary. Use gsd-pi's own tooling to gather the data — do not hand-parse files when a command or query exists.
+
+Gather:
+- Active milestone id/title and overall milestone progress (completed/total).
+- Slice and task progress for the active milestone (completed/total per slice where available).
+- Requirements coverage if tracked.
+- Git metrics: total commits, first commit date, last activity date, current branch.
+- Project age in days.
+
+Present the summary in this shape:
+
+```
+# 📊 Project Statistics — {milestone} {title}
+
+## Progress
+[████████░░] X/Y milestones (Z%)
+
+## Slices (active milestone)
+| Slice | Tasks | Completed | Status |
+
+## Requirements
+✅ X/Y requirements complete
+
+## Git
+- Commits: N
+- Started: YYYY-MM-DD
+- Last activity: YYYY-MM-DD
+
+## Timeline
+- Project age: N days
+```
+
+If no `.gsd/` project exists, say so and suggest `/gsd init`.
+
+## Success criteria
+
+- Numbers come from canonical gsd-pi state, not estimates.
+- The summary is readable in a terminal (ASCII progress bar, tables).
+- Missing sections are omitted rather than printed with zeroes.

package/src/resources/extensions/gsd/prompts/surface.md

@@ -0,0 +1,25 @@
+You are running the GSD **surface** workflow — manage which skills/extensions are surfaced in the active session.
+
+## Action
+
+{{action}}
+
+## Process
+
+Parse the action:
+
+- **list / status** (default): Show every installed skill/extension with its current surfaced state (enabled/disabled) and source (bundled, project, global). Group by cluster where applicable.
+- **profile <name>**: Apply a named surfacing profile — enable a curated cluster of skills and disable the rest. Confirm the change set before applying.
+- **disable <cluster>**: Disable a cluster of skills so they stop loading into context. Record the change so it persists.
+- **enable <cluster>**: Re-enable a previously disabled cluster.
+- **reset**: Restore the default surfacing state.
+
+Use gsd-pi's own extension/skill management (`/gsd extensions`, `/gsd skill-health`) as the backing store for these changes — do not invent a separate state file.
+
+If the action names an unknown cluster or profile, list the valid options rather than failing silently.
+
+## Success criteria
+
+- The current surfaced state is reported accurately from the backing store.
+- Changes persist via gsd-pi's extension/skill management, not a parallel mechanism.
+- Unknown names produce a helpful list of valid options.

package/src/resources/extensions/gsd/prompts/system.md

@@ -110,9 +110,12 @@ Templates are in `{{templatesDir}}`.
 
 **External facts:** Use `search-the-web` + `fetch_page`, or `search_and_read`; use `freshness` for recency. Never state current facts from training data without verification.
 
-**Background processes:** Use `bg_shell` `start` + `wait_for_ready` for servers/watchers/daemons. Never use `bash` with `&` or `nohup`; inherited stdout can hang. Never poll with `sleep`; use `wait_for_ready`. For status use `digest`, `highlights` for significant lines, and `output` only when debugging.
+**Choosing a shell tool — decide by how the command runs, not how long it takes:**
 
-**One-shot commands:** Use `async_bash` for builds, tests, and installs. Results are pushed on exit; use `await_job` only to block on a specific job.
+- **Runs and exits (a batch command):** anything that does work and finishes — `terraform apply`, DB migrations, builds, tests, installs, long scripts. Use synchronous `bash` when you want to block and read the result now (uncapped; in auto-mode genuine hangs are caught by the stalled-tool watchdog, interactively they end on human ESC). Use `async_bash` when you want it non-blocking — it returns a job ID immediately and you `await_job` later. **Never** put a run-to-completion command under `bg_shell` `wait_for_ready`: it exits instead of staying alive, so readiness never trips and a clean exit looks like a failure.
+- **Stays alive and you interact with it over time:** servers, watchers, daemons, REPLs. Use `bg_shell` `start`, then `wait_for_ready` (block until it listens/prints its ready pattern), `output`/`digest`/`highlights` to inspect, `send`/`send_and_wait` to drive it, and `kill`/`restart` to manage it. Never use `bash` with `&` or `nohup` (inherited stdout can hang); never poll with `sleep` (use `wait_for_ready`).
+
+Quick rule of thumb: if the command would exit on its own, it's `bash`/`async_bash`; if it would keep running until you stop it, it's `bg_shell`.
 
 **Stale job hygiene:** After editing source to fix a failure, `cancel_job` every in-flight `async_bash` job before rerunning. Changed inputs make in-flight outputs untrusted.
 
@@ -158,7 +161,7 @@ Fix root causes, not symptoms. If applying temporary mitigation, label it and pr
 - State uncertainty plainly: "Not sure this handles X - testing it." No performed confidence, no hedging paragraphs.
 - All user-visible narration must be grammatical English. Do not emit compressed planner notes like "Need inspect X". If it fits a commit comment or standup note, it is acceptable.
 - When debugging, stay curious. Problems are puzzles. Say what's interesting about the failure before reaching for fixes.
-- After completing a task, give a brief summary and 2-4 numbered next-step options; last option is always "Other". Omit the list for strict output formats.
+- After completing a task, give a brief summary and 2-4 numbered next-step options; last option is always "Other". Omit the list for strict output formats, or when the active workflow prompt already ends with its own explicit "Next steps:" handoff block — in that case follow the workflow's handoff and do not add a second list.
 
   If any next step is destructive/outward-facing, present it via `ask_user_questions` and wait for the user's answer before execution. Do not execute a next-step item from a prior plain-text numbered list without fresh confirmation.
 

package/src/resources/extensions/gsd/prompts/thread.md

@@ -0,0 +1,24 @@
+You are running the GSD **thread** workflow — manage persistent context threads for cross-session work, backed by the memory store so threads survive across sessions.
+
+## Action
+
+{{action}}
+
+## Process
+
+A thread is a named, resumable context line: a topic, the open question, decisions so far, and the next step. Threads live in the gsd-pi memory store so they persist and are queryable.
+
+Parse the action:
+
+- **list [--open|--resolved]** (default): list threads filtered by state. Each entry: slug, status, last-updated, one-line topic.
+- **close <slug>**: mark a thread resolved (record the resolution as a knowledge lesson if durable).
+- **status <slug>**: show a thread's full context (topic, decisions, open question, next step).
+- **<name> / <description>** (bare text): create or update a thread with the given name/description, stamping the current state and next step.
+
+Use `/gsd memory` as the backing store for thread persistence. When closing a thread whose resolution is a reusable lesson, also record it via `/gsd knowledge lesson`.
+
+## Success criteria
+
+- Threads persist in the memory store, not in a throwaway file.
+- Listing honors the open/resolved filter.
+- Resolved threads with durable lessons feed the knowledge store.

package/src/resources/extensions/gsd/prompts/triage-captures.md

@@ -65,4 +65,4 @@ Classify each capture as one of:
 
 **Important:** Do NOT execute any resolutions. Only classify and update CAPTURES.md. Resolution execution happens separately (in auto-mode dispatch or manually by the user).
 
-When done, say: "Triage complete."
+When done, say: "Triage closeout submitted." Do not say triage is complete — GSD announces completion only after post-unit verification passes. Say this exactly once — if you already said it in a prior message, do not repeat it.

package/src/resources/extensions/gsd/prompts/ui-phase.md

@@ -0,0 +1,29 @@
+You are running the GSD **ui-phase** workflow — produce a UI design contract (UI-SPEC) for a frontend milestone/slice before implementation.
+
+## Target
+
+{{target}}
+
+## Process
+
+1. **Load intent.** Read the milestone/slice goal, requirements, and any existing brand/design references.
+
+2. **Inventory the surfaces.** List every screen/state/component the milestone touches: pages, key states (empty, loading, error, success), and shared components.
+
+3. **Define the design contract per surface:**
+   - Layout (structure, responsive behavior)
+   - Key interactions and their feedback states
+   - Content/copy essentials
+   - Accessibility requirements
+   - Entry/exit points to other surfaces
+
+4. **Align on constraints.** Brand, type scale, color tokens, spacing system, component library — use existing design tokens where they exist; flag gaps.
+
+5. **Write the UI-SPEC** to the milestone/slice artifact in `.gsd/`. Recommend `/gsd sketch` to prototype high-uncertainty surfaces, or `/gsd plan-phase` to plan implementation.
+
+## Success criteria
+
+- Every surface the milestone touches is inventoried.
+- Each surface's contract is concrete enough to implement against.
+- Existing design tokens are reused; gaps are flagged.
+- The recommended next step reflects design readiness.

package/src/resources/extensions/gsd/prompts/ui-review.md

@@ -0,0 +1,29 @@
+You are running the GSD **ui-review** workflow — retroactive visual audit of implemented frontend code against design intent.
+
+## Target
+
+{{target}}
+
+## Process
+
+Audit the implemented UI across these pillars, grounding each finding in actual code (component files, styles, markup) with file paths:
+
+1. **Layout & spacing** — alignment, grid/flex correctness, responsive behavior, spacing rhythm.
+2. **Color & contrast** — palette consistency, accessible contrast ratios, dark/light coherence.
+3. **Typography** — type scale, hierarchy, line-height, legibility.
+4. **Interaction & feedback** — hover/focus/active states, loading/empty/error states, motion.
+5. **Consistency** — shared components reused, design tokens applied, no one-off magic numbers.
+6. **Accessibility** — semantic markup, keyboard navigation, ARIA correctness, focus management.
+
+For each pillar, give a score (0–5) with bullet findings (location + issue + suggested fix).
+
+## Output
+
+Write `.gsd/reviews/{{reviewId}}-UI-REVIEW.md` with the per-pillar scores, findings, and a prioritized fix list (critical first). Print the overall score and the critical findings.
+
+## Success criteria
+
+- Every finding cites a component/file path.
+- Each pillar has an explicit score, not just prose.
+- Critical findings are surfaced first and are actionable.
+- The review lives under `.gsd/reviews/`.

package/src/resources/extensions/gsd/prompts/ultraplan-phase.md

@@ -0,0 +1,24 @@
+You are running the GSD **ultraplan-phase** workflow — offload heavy planning of a milestone/slice to an extended-reasoning plan pass, review the result, and import it back. This uses a local extended-reasoning pass (an external cloud service is not available in this runtime).
+
+## Target
+
+{{target}}
+
+## Process
+
+1. **Assemble the planning brief.** Gather the milestone/slice goal, CONTEXT, RESEARCH, decisions, requirements, and a codebase snapshot into a single self-contained brief.
+
+2. **Run the extended-reasoning plan pass.** Produce a thorough plan from the brief using high reasoning effort: full task decomposition, dependency graph, verification per task, risks. This is the "ultraplan" — more exhaustive than a standard plan pass.
+
+3. **Review in the open.** Present the plan for review (the human reviews it before it's imported). Flag anything uncertain, risky, or that diverges from the stated goal.
+
+4. **Import.** On approval, write the plan to the milestone/slice plan artifact in `.gsd/` and record durable decisions. Note that this replaces the cloud review-and-import with a local review.
+
+5. **Route.** Recommend `/gsd dispatch execute` or `/gsd plan-review-convergence` for a convergence pass.
+
+## Success criteria
+
+- The plan is more exhaustive than a standard pass (that's the point of the offload).
+- The human reviews before import (no silent overwrite of an existing plan).
+- The brief is self-contained so the reasoning isn't context-starved.
+- Durable decisions are persisted on import.

package/src/resources/extensions/gsd/prompts/validate-milestone.md

@@ -87,4 +87,4 @@ If verdict is `needs-remediation`:
 
 **File system safety:** When scanning milestone directories, use `ls` or `find` first. Never pass a directory path such as `tasks/` or `slices/` directly to `read`; it only accepts files.
 
-When done, say: "Milestone {{milestoneId}} validation complete — verdict: <verdict>."
+When done, say: "Milestone {{milestoneId}} validation complete — verdict: <verdict>." Say this exactly once — if you already said it in a prior message, do not repeat it.

package/src/resources/extensions/gsd/prompts/validate-phase.md

@@ -0,0 +1,26 @@
+You are running the GSD **validate-phase** workflow — retroactively audit and fill validation coverage gaps for completed work, using Nyquist-style coverage sampling.
+
+## Target
+
+{{target}}
+
+## Process
+
+1. **Map the verification surface.** For the target's tasks, list what behaviors/outputs each claims to verify, and the test (or manual check) that verifies it.
+
+2. **Find coverage gaps.** Identify: behaviors with no test, error/edge paths untested, boundaries between slices untested, and claims verified only by happy-path tests. Apply a Nyquist lens — sample at the rate needed to catch the behavior changing, not just once.
+
+3. **Generate the missing tests.** For each gap that is safe to fill deterministically, write the test (matching the project's test framework and conventions). Run the test suite after adding tests. For gaps that need a human (UI, exploratory), record them as UAT items instead of auto-generating.
+
+4. **Update the validation record.** Write/append the slice's VALIDATION note (or `.gsd/` equivalent) with the coverage map before/after, the tests added, and the remaining human-UAT items.
+
+5. **Report.** Summarize: gaps found, tests added (passing), and remaining human-UAT items.
+
+Prefer delegating test generation to `/gsd add-tests` where it fits, rather than hand-writing every test.
+
+## Success criteria
+
+- Every claimed behavior is mapped to a test (or flagged as needing human UAT).
+- Generated tests pass and match the project's conventions.
+- The validation record reflects the new coverage honestly.
+- Human-only gaps are recorded as UAT items, not silently skipped.

package/src/resources/extensions/gsd/prompts/verify-work.md

@@ -0,0 +1,24 @@
+You are running the GSD **verify-work** workflow — validate built features through conversational UAT.
+
+## Target
+
+{{target}}
+
+## Process
+
+1. **Load what was built.** Read the target slice/milestone plan and SUMMARY to understand what features were delivered and what their acceptance criteria are.
+
+2. **Draft a UAT script.** Turn each acceptance criterion into a concrete, observable test step the human can perform (or that you can perform via tooling where possible). Group by feature; order so earlier steps set up later ones.
+
+3. **Walk through the script conversationally.** Present one step (or a small group) at a time. For each, record the outcome: `pass`, `fail` (with what happened), `blocked` (with the blocker), or `skipped` (intentionally). Do not advance past a fail without acknowledging it.
+
+4. **Where you can self-verify** (deterministic checks: type checks, tests, lint, schema), run them and include the result alongside the human step.
+
+5. **Produce the verdict.** After all steps: `pass` (all criteria met), `needs-attention` (some steps failed but none blocking), or `needs-remediation` (a blocking failure). Record the UAT outcome against the slice via the appropriate gsd-pi mechanism.
+
+## Success criteria
+
+- Every acceptance criterion becomes a concrete, observable step.
+- Outcomes are recorded honestly — fails are not hidden.
+- Deterministic checks are run where possible, not just asked about.
+- The final verdict maps to a canonical gsd-pi outcome.

package/src/resources/extensions/gsd/prompts/workflow-start.md

@@ -25,4 +25,5 @@ Follow the workflow defined below. Execute each phase in order, completing one b
 3. **Atomic commits.** Commit working code after each meaningful change. Use conventional commit format: `<type>(<scope>): <description>`.
 4. **Verify before shipping.** Run the project's test suite and build before marking the workflow complete.
 5. **Decision gates, not ceremony.** After each phase, summarize what changed. For low/medium complexity, ask for confirmation only when the next phase depends on a real user choice or external approval. For high complexity, confirm before proceeding to each new phase.
-6. **Stay focused.** This is a {{complexity}}-complexity workflow. Match your ceremony level to the task — don't over-engineer or under-deliver.
+6. **Persist workflow state.** If the artifact directory contains `STATE.json`, update it after each phase: mark the finished phase `completed`, mark the next phase `active`, set `currentPhase` to the active phase index, and refresh `updatedAt`. When every phase is completed, set `completedAt` to the completion timestamp.
+7. **Stay focused.** This is a {{complexity}}-complexity workflow. Match your ceremony level to the task — don't over-engineer or under-deliver.

package/src/resources/extensions/gsd/prompts/workspace.md

@@ -0,0 +1,22 @@
+You are running the GSD **workspace** workflow — manage isolated workspace environments for parallel or experimental work.
+
+## Action
+
+{{action}}
+
+## Process
+
+A workspace is an isolated environment backed by a git worktree. Map workspace actions onto worktrees:
+
+- **--list / list** (default): show all worktrees with state (current, merged, clean, dirty) — `/gsd worktree list`.
+- **--remove <name>**: remove a worktree — `/gsd worktree remove`.
+- **--merge <name>**: merge a worktree — `/gsd worktree merge`.
+- **--clean / clean**: clean stale worktree records — `/gsd worktree clean`.
+
+Route every structural action to `/gsd worktree` rather than hand-managing git worktrees.
+
+## Success criteria
+
+- Listing reflects canonical worktree state.
+- Structural actions route to `/gsd worktree`, keeping state canonical.
+- Removing a dirty worktree is guarded (confirm first).

package/src/resources/extensions/gsd/prompts/workstreams.md

@@ -0,0 +1,24 @@
+You are running the GSD **workstreams** workflow — manage parallel workstreams that run multiple milestones concurrently with isolation.
+
+## Action
+
+{{action}}
+
+## Process
+
+A workstream is a parallel worker running its own milestone in its own branch/worktree. Map workstream actions onto parallel workers:
+
+- **list / status** (default): show all parallel workers — milestone, branch/worktree, progress, state (running/paused/done/failed).
+- **create / start**: start parallel workers for all eligible milestones (`/gsd parallel start`). Does not accept a milestone target; use `/gsd parallel start` directly to start all eligible milestones.
+- **switch**: focus the dashboard on the most active worker (`/gsd parallel watch`). Does not accept a milestone target; use `/gsd parallel watch` directly to monitor workers.
+- **progress**: show all workers' progress (`/gsd parallel status`). Does not accept a milestone target; use `/gsd parallel status` directly for worker status.
+- **pause / resume <milestone>**: pause or resume a worker (`/gsd parallel pause|resume`).
+- **complete <milestone>**: complete and merge a worker's milestone (`/gsd parallel merge`).
+
+Route every structural action to `/gsd parallel <subcommand>` rather than reimplementing worktree/merge logic.
+
+## Success criteria
+
+- Status reflects canonical parallel-worker state.
+- Structural actions route to `/gsd parallel`, not duplicates.
+- Unknown milestones list the valid options rather than failing silently.

package/src/resources/extensions/gsd/provider-error-guidance.ts

@@ -1,7 +1,10 @@
 /**
  * Actionable remediation hints when auto-mode pauses on provider/model errors.
+ * Render with formatGuidance from the Guidance module.
  */
 
+import type { Guidance } from "./guidance.js";
+
 export interface ProviderErrorGuidanceInput {
   errorMsg: string;
   provider?: string;
@@ -12,10 +15,7 @@ export interface ProviderErrorGuidanceInput {
   hasConfiguredFallbacks?: boolean;
 }
 
-export interface ProviderErrorGuidance {
-  summary: string;
-  steps: string[];
-}
+export type ProviderErrorGuidance = Guidance;
 
 /** Map auto unit types to the `models:` key in PREFERENCES.md. */
 export function unitTypeToPrefsPhaseKey(unitType: string | undefined): string | undefined {
@@ -60,6 +60,34 @@ function defaultAlternateModel(provider: string | undefined, modelId: string | u
   return undefined;
 }
 
+function isGeminiCliDeprecatedError(errorMsg: string): boolean {
+  return (
+    /IneligibleTierError/i.test(errorMsg)
+    || /UNSUPPORTED_CLIENT/i.test(errorMsg)
+    || /no longer supported for Gemini Code Assist for individuals/i.test(errorMsg)
+    || /migrate to the Antigravity suite/i.test(errorMsg)
+  );
+}
+
+function resolveGeminiCliDeprecationGuidance(input: ProviderErrorGuidanceInput): ProviderErrorGuidance {
+  const { provider, modelId, unitType } = input;
+  const modelLabel =
+    provider && modelId ? `${provider}/${modelId}` : modelId ?? provider ?? "google-gemini-cli";
+  const unitSuffix = unitType ? ` during ${unitType}` : "";
+
+  return {
+    summary:
+      `Provider error on ${modelLabel}${unitSuffix}. ` +
+      "Google no longer supports Gemini CLI for individual-tier users — migrate to Antigravity CLI.",
+    steps: [
+      "Install Antigravity CLI: curl -fsSL https://antigravity.google/cli/install.sh | bash",
+      "Run `agy` in a terminal and complete authentication.",
+      "In GSD, run `/login` and select Antigravity, or restart GSD to auto-migrate when `agy` is on PATH.",
+      "Run /gsd next to resume the paused unit.",
+    ],
+  };
+}
+
 /**
  * Build concrete next steps for a provider/model rejection pause.
  */
@@ -73,6 +101,10 @@ export function resolveProviderErrorGuidance(input: ProviderErrorGuidanceInput):
     hasConfiguredFallbacks,
   } = input;
 
+  if (isGeminiCliDeprecatedError(errorMsg)) {
+    return resolveGeminiCliDeprecationGuidance(input);
+  }
+
   const modelLabel =
     provider && modelId ? `${provider}/${modelId}` : modelId ?? provider ?? "current model";
   const phaseKey = unitTypeToPrefsPhaseKey(unitType);
@@ -129,8 +161,3 @@ export function resolveProviderErrorGuidance(input: ProviderErrorGuidanceInput):
   return { summary, steps };
 }
 
-/** Flatten guidance into a pause banner / notification string. */
-export function formatProviderErrorGuidance(guidance: ProviderErrorGuidance): string {
-  const numbered = guidance.steps.map((step, index) => `${index + 1}. ${step}`).join("\n");
-  return `${guidance.summary}\n\n${numbered}`;
-}

package/src/resources/extensions/gsd/provider-payload-policy.ts

@@ -0,0 +1,140 @@
+/**
+ * Provider Payload Policy - ordered shaping of provider request payloads.
+ *
+ * The order is intentional:
+ * 1. observation budgeting masks old tool results in auto-mode,
+ * 2. display truncation caps tool-result text for every mode,
+ * 3. the protected Source Context Block is appended after truncation,
+ * 4. supported models receive the configured service tier.
+ */
+
+import type { ContextManagementConfig } from "./preferences-types.js";
+import type { ServiceTierSetting } from "./service-tier.js";
+
+import {
+  createObservationMask,
+  createResponsesInputObservationMask,
+  truncateContextResultMessages,
+  truncateResponsesInputResultItems,
+} from "./context-masker.js";
+import { getSourceObservationStore, isAutoActive } from "./auto-runtime-state.js";
+import { loadEffectiveGSDPreferences } from "./preferences.js";
+import { getEffectiveServiceTier, supportsServiceTier } from "./service-tier.js";
+import { injectSourceContextBlockIntoPayload } from "./source-observations.js";
+
+const DEFAULT_OBSERVATION_MASK_TURNS = 8;
+const DEFAULT_TOOL_RESULT_MAX_CHARS = 800;
+
+type MessagePayload = Parameters<ReturnType<typeof createObservationMask>>[0];
+type ResponsesInputPayload = Parameters<ReturnType<typeof createResponsesInputObservationMask>>[0];
+
+export interface ProviderPayloadPolicyDeps {
+  isAutoActive(): boolean;
+  loadContextManagementConfig(): ContextManagementConfig | undefined;
+  renderSourceContextBlock(): string | null;
+  getEffectiveServiceTier(): ServiceTierSetting;
+  supportsServiceTier(modelId: string): boolean;
+}
+
+export interface ProviderPayloadPolicyInput {
+  payload: Record<string, unknown>;
+  modelId?: string;
+  deps?: Partial<ProviderPayloadPolicyDeps>;
+}
+
+export const DEFAULT_PROVIDER_PAYLOAD_POLICY_DEPS: ProviderPayloadPolicyDeps = {
+  isAutoActive,
+  loadContextManagementConfig: () => loadEffectiveGSDPreferences()?.preferences.context_management,
+  renderSourceContextBlock: () => getSourceObservationStore().renderActiveBlock(),
+  getEffectiveServiceTier,
+  supportsServiceTier,
+};
+
+export function applyProviderPayloadPolicy({
+  payload,
+  modelId,
+  deps: overrides,
+}: ProviderPayloadPolicyInput): Record<string, unknown> {
+  const deps = { ...DEFAULT_PROVIDER_PAYLOAD_POLICY_DEPS, ...overrides };
+
+  try {
+    applyContextManagement(payload, deps);
+  } catch {
+    // Provider payload shaping should not block a request when optional
+    // context management preferences or adapters fail.
+  }
+
+  try {
+    applySourceContextBlock(payload, deps);
+  } catch {
+    // Source observations are opportunistic; execution can continue without
+    // an injected block.
+  }
+
+  applyServiceTier(payload, modelId, deps);
+  return payload;
+}
+
+function applyContextManagement(
+  payload: Record<string, unknown>,
+  deps: ProviderPayloadPolicyDeps,
+): void {
+  const config = deps.loadContextManagementConfig();
+  applyObservationBudget(payload, config, deps.isAutoActive());
+  applyDisplayTruncation(payload, config);
+}
+
+function applyObservationBudget(
+  payload: Record<string, unknown>,
+  config: ContextManagementConfig | undefined,
+  autoActive: boolean,
+): void {
+  if (!autoActive || config?.observation_masking === false) return;
+
+  const keepTurns = config?.observation_mask_turns ?? DEFAULT_OBSERVATION_MASK_TURNS;
+  if (Array.isArray(payload.messages)) {
+    payload.messages = createObservationMask(keepTurns)(payload.messages as MessagePayload);
+  }
+  if (Array.isArray(payload.input)) {
+    payload.input = createResponsesInputObservationMask(keepTurns)(payload.input as ResponsesInputPayload);
+  }
+}
+
+function applyDisplayTruncation(
+  payload: Record<string, unknown>,
+  config: ContextManagementConfig | undefined,
+): void {
+  const maxChars = config?.tool_result_max_chars ?? DEFAULT_TOOL_RESULT_MAX_CHARS;
+
+  if (Array.isArray(payload.messages)) {
+    payload.messages = truncateContextResultMessages(payload.messages as MessagePayload, maxChars);
+  }
+  if (Array.isArray(payload.input)) {
+    payload.input = truncateResponsesInputResultItems(payload.input as ResponsesInputPayload, maxChars);
+  }
+}
+
+function applySourceContextBlock(
+  payload: Record<string, unknown>,
+  deps: ProviderPayloadPolicyDeps,
+): void {
+  if (!deps.isAutoActive()) return;
+
+  const sourceContextBlock = deps.renderSourceContextBlock();
+  if (!sourceContextBlock) return;
+
+  Object.assign(payload, injectSourceContextBlockIntoPayload(payload, sourceContextBlock));
+}
+
+function applyServiceTier(
+  payload: Record<string, unknown>,
+  modelId: string | undefined,
+  deps: ProviderPayloadPolicyDeps,
+): void {
+  if (!modelId) return;
+
+  const tier = deps.getEffectiveServiceTier();
+  if (!tier || !deps.supportsServiceTier(modelId)) return;
+
+  payload.service_tier = tier;
+}

package/src/resources/extensions/gsd/provider-switch-observer.ts

@@ -128,7 +128,7 @@ function emitAudit(report: ProviderSwitchReport): void {
 
 function emitNotification(report: ProviderSwitchReport): void {
   try {
-    appendNotification(summarize(report), "warning", "workflow-logger");
+    appendNotification(summarize(report), "warning", "workflow-logger", { kind: "provider-switch" });
   } catch {
     // Notification persistence is best-effort.
   }