stack-provider-guard

What It Does

Holds the line on the four invariants that make a single-provider model
actually single-provider. It is the check /stack:select runs before it
proposes anything, and the audit /stack:status runs before it declares a
state healthy.

The invariants:

1. Exactly one enabled. Both gt-workflow and github-workflow may be
   installed at once. At most one may be enabled. Two enabled is CONFLICT,
   not a preference to be resolved by ranking.
2. Managed scope fails closed. A plugin at managed scope is
   administrator-controlled and cannot be modified — --plugin-dir cannot
   override it either. When a switch would require changing a managed
   entry, refuse with MANAGED_CONFLICT and emit no commands. Never
   emit a claude plugin disable the CLI will reject.
3. Never edit settings JSON directly. ~/.claude/settings.json,
   .claude/settings.json, and .claude/settings.local.json are off
   limits. Provider state changes go through
   claude plugin install|enable|disable and take effect via
   /reload-plugins.
4. Never fall back. If the intended provider cannot be made active, the
   result is a reported failure. Not the other provider. Not "the one that
   is installed". Not "the one whose CLI exists".

When to Use

• Before presenting a provider switch plan to the user.
• After executing a switch, to confirm the end state is single-provider.
• When auditing why a stack workflow refused to run.

Usage

Step 1: Build the plan (never execute it here)

plugins/yellow-core/lib/stack-provider-state.js owns the preconditions.
Ask it for a plan rather than assembling claude plugin commands by hand —
the module is what the fixture tests cover.

set -uo pipefail

LIB="${CLAUDE_PLUGIN_ROOT}/lib/stack-provider-state.js"
if [ ! -f "$LIB" ]; then
  printf 'stack_provider_error: state library not found at %s\n' "$LIB"
  exit 0
fi

repo_root=$(git rev-parse --show-toplevel 2>/dev/null || printf '')

if ! plugin_json=$(claude plugin list --json 2>/dev/null); then
  printf 'stack_provider_error: `claude plugin list --json` failed — refusing to plan a switch\n'
  exit 0
fi

# TARGET_PROVIDER and TARGET_SCOPE are substituted by the calling command
# from validated user input (graphite|github and user|project|local).
printf '%s' "$plugin_json" | node "$LIB" plan \
  --plugins-file - \
  --target "$TARGET_PROVIDER" \
  --scope "$TARGET_SCOPE" \
  --project-path "$repo_root" \
  || printf 'stack_provider_error: planning failed — no commands were produced\n'

If the output contains a stack_provider_error: line, print that line and
stop. There is no plan, and a missing plan is not an empty one — do not
proceed to Step 2's refusal contract, which applies only to a status: "refused" JSON result.

Step 2: Enforce the refusal contract

A plan with status: "refused" carries steps: [] — by construction, not
by convention. Never reconstruct a partial plan from a refusal:

reason	What to say	What NOT to do
managed-conflict	Name the managed plugin; the fix is with whoever controls managed settings	Do not emit any claude plugin command; do not suggest editing settings files
unknown-provider	List the known ids (graphite, github)	Do not guess the closest match
invalid-scope	List user, project, local	Do not silently fall back to user

Step 3: Enforce the confirmation contract

Any step with requiresConfirmation: true (installs) must be shown to the
user and approved before execution. Show the whole plan — every command,
in order — before running the first one. A user who approves a switch is
approving these exact commands.

Step 4: Enforce the abort contract

If a step fails, stop. Do not run later steps, do not retry with a
different scope, and do not enable the other provider to "leave things
working". Report which step failed, which were completed, and which were
not run, then tell the user to re-run /stack:status. A half-applied
switch is a state the user must see, not one to be papered over.

Step 5: Audit the end state

After a switch, re-classify (see stack-provider-router) and confirm the
state is READY_GRAPHITE or READY_GITHUB and matches the requested
target. If it is anything else, report it — including when the commands all
reported success, since /reload-plugins may not have run yet.

Red flags this skill exists to catch

• A proposed command that writes to a settings JSON file.
• A claude plugin disable targeting a managed-scope entry.
• A plan that enables a provider without disabling the other one.
• Any sentence of the form "GitHub isn't ready, so using Graphite instead".
• Treating claude plugin list --json project/local rows from another
  repository as this repository's state (rows carry a projectPath).

Boundaries

• Produces plans and verdicts. Executes nothing.
• Never writes .yellow-stack.yml; recording repository intent is the
  user's decision, made explicitly.
• Never uninstalls a provider. Disabling is reversible; uninstalling
  discards a user's install.