@soleur/opencode 0.0.0-stage → 3.354.2

package/skills/trigger-cron/scripts/trigger.sh

@@ -0,0 +1,198 @@
+#!/usr/bin/env bash
+# trigger-cron — fire an allowlisted cron manual-trigger via the internal HTTP
+# route (no SSH). See plugins/soleur/skills/trigger-cron/SKILL.md.
+#
+# The no-SSH replacement for the on-host `inngest send` loopback path (#4734,
+# #4742). Reads INNGEST_MANUAL_TRIGGER_SECRET read-only from Doppler and POSTs
+# to https://app.soleur.ai/api/internal/trigger-cron.
+#
+# Allowlisted events are derived from EXPECTED_CRON_FUNCTIONS in
+# apps/web-platform/server/inngest/cron-manifest.ts — there is NO second
+# hand-maintained list here (mirrors lib/inngest/manual-trigger-allowlist.ts).
+
+set -euo pipefail
+
+# (#7797) Refuse to run under shell tracing. UNCONDITIONAL — deliberately NOT
+# gated on a non-emptiness test of the credential variable, because
+# INNGEST_MANUAL_TRIGGER_SECRET is acquired by `doppler secrets get` BELOW this
+# point, so a conditional arm would test an empty variable at guard time, open,
+# and then trace the acquisition itself.
+#
+# STREAM CONTRACT: this script's stdout is a DATA channel — it prints `HTTP <code>`
+# then the response body, and SKILL.md's preflight block grep-parses
+# `SOLEUR_TRIGGER_CRON_HALT reason=…` markers on stdout. So the refusal is emitted
+# in that documented marker shape rather than as a bare `[FATAL] …` line, which the
+# preflight consumer would read as a data row. Stdout, not stderr, because agent
+# runtimes surface stdout and swallow stderr (constitution.md > Code Style).
+case "$-" in
+  *x*)
+    printf 'SOLEUR_TRIGGER_CRON_HALT reason=xtrace-credential-bound issue=7797\n'
+    printf 'trigger-cron: refusing to run under xtrace — this script handles a live credential and -x would print it. No event has been fired and no secret has been read.\n'
+    exit 78
+    ;;
+esac
+
+# (#7873) `--disable` closes ~/.curlrc and `--noproxy '*'` closes the proxy vars,
+# but neither touches the env that subverts TLS ITSELF. SSLKEYLOGFILE writes the
+# session keys and the CA vars substitute the trust store, so a CURL_CA_BUNDLE
+# MITM of the manual-trigger secret works with every other guard fully intact.
+unset SSLKEYLOGFILE CURL_CA_BUNDLE SSL_CERT_FILE SSL_CERT_DIR CURL_HOME \
+      HOSTALIASES LOCALDOMAIN RES_OPTIONS
+
+ROUTE_URL="https://app.soleur.ai/api/internal/trigger-cron"
+SECRET_NAME="INNGEST_MANUAL_TRIGGER_SECRET"
+DOPPLER_PROJECT="soleur"
+
+usage() {
+  cat <<'EOF'
+Usage:
+  trigger.sh --list
+  trigger.sh --event cron/<name>.manual-trigger [--data '<json-object>'] \
+             [--config prd|dev] [--dry-run]
+
+Flags:
+  --list            Print allowlisted events (from cron-manifest.ts) and exit.
+  --event <name>    The cron/<name>.manual-trigger event to fire.
+  --data '<json>'   Optional per-cron event.data (JSON object). The route stamps
+                    trigger/at over it; caller cannot override them.
+  --config <env>    Doppler config to read the secret from (default: prd).
+  --dry-run         Print the curl invocation without firing.
+EOF
+}
+
+# Locate the cron manifest from the repo root (works from any CWD inside the repo).
+repo_root() {
+  git rev-parse --show-toplevel 2>/dev/null || {
+    echo "trigger.sh: not inside a git repo (cannot locate cron-manifest.ts)" >&2
+    exit 2
+  }
+}
+
+# Extract the allowlisted manual-trigger events from cron-manifest.ts.
+# Parses the EXPECTED_CRON_FUNCTIONS array literal (cron-<name>) and applies the
+# same transform as manualTriggerEventFor: cron-<name> -> cron/<name>.manual-trigger.
+list_events() {
+  local manifest="$1"
+  [[ -f "$manifest" ]] || { echo "trigger.sh: manifest not found: $manifest" >&2; exit 2; }
+  awk '
+    /EXPECTED_CRON_FUNCTIONS/ { inarr=1 }
+    inarr && /\];/ { inarr=0 }
+    inarr {
+      while (match($0, /"cron-[a-z0-9-]+"/)) {
+        tok = substr($0, RSTART+1, RLENGTH-2)   # strip surrounding quotes
+        sub(/^cron-/, "", tok)
+        print "cron/" tok ".manual-trigger"
+        $0 = substr($0, RSTART+RLENGTH)
+      }
+    }
+  ' "$manifest" | sort -u
+}
+
+LIST=0
+EVENT=""
+DATA=""
+CONFIG="prd"
+DRY_RUN=0
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --list) LIST=1; shift ;;
+    --event) EVENT="${2:-}"; shift 2 ;;
+    --data) DATA="${2:-}"; shift 2 ;;
+    --config) CONFIG="${2:-}"; shift 2 ;;
+    --dry-run) DRY_RUN=1; shift ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "trigger.sh: unknown flag: $1" >&2; usage >&2; exit 2 ;;
+  esac
+done
+
+ROOT="$(repo_root)"
+MANIFEST="$ROOT/apps/web-platform/server/inngest/cron-manifest.ts"
+
+if [[ "$LIST" -eq 1 ]]; then
+  list_events "$MANIFEST"
+  exit 0
+fi
+
+if [[ -z "$EVENT" ]]; then
+  echo "trigger.sh: --event is required (or use --list)" >&2
+  usage >&2
+  exit 2
+fi
+
+case "$CONFIG" in
+  prd|dev) ;;
+  *) echo "trigger.sh: --config must be 'prd' or 'dev' (got: $CONFIG)" >&2; exit 2 ;;
+esac
+
+# Validate the event against the manifest-derived allowlist (fail fast before
+# minting a Doppler read or hitting the route). The `--` stops grep from
+# interpreting an event string that begins with `-` as an option.
+if ! grep -qxF -- "$EVENT" < <(list_events "$MANIFEST"); then
+  echo "trigger.sh: '$EVENT' is not an allowlisted manual-trigger event." >&2
+  echo "Run 'trigger.sh --list' to see valid events." >&2
+  exit 2
+fi
+
+# Build the JSON body. --data must be a JSON object if provided.
+if [[ -n "$DATA" ]]; then
+  if ! echo "$DATA" | jq -e 'type == "object"' >/dev/null 2>&1; then
+    echo "trigger.sh: --data must be a JSON object (got: $DATA)" >&2
+    exit 2
+  fi
+  BODY=$(jq -nc --arg ev "$EVENT" --argjson d "$DATA" '{event: $ev, data: $d}')
+else
+  BODY=$(jq -nc --arg ev "$EVENT" '{event: $ev}')
+fi
+
+if [[ "$DRY_RUN" -eq 1 ]]; then
+  printf '%s\n' "# dry-run (config=$CONFIG): would POST to $ROUTE_URL"
+  printf '%s\n' "TOKEN=\$(doppler secrets get $SECRET_NAME -p $DOPPLER_PROJECT -c $CONFIG --plain)"
+  # The printed recipe carries a live bearer, so it must TEACH the confined form:
+  # `--disable` literally first (it aborts ~/.curlrc parsing, and later is too
+  # late) and `--noproxy '*'` (#7873), with the bearer on curl's stdin config
+  # channel so a copy-paste never puts the token on argv (#7843).
+  printf '%s\n' "curl --disable --noproxy '*' -sS -X POST $ROUTE_URL \\"
+  printf '%s\n' "  -H 'content-type: application/json' \\"
+  printf '%s\n' "  -d '$BODY' -w '\\n%{http_code}\\n' \\"
+  printf '%s\n' "  --config - < <(printf 'header = \"Authorization: Bearer %s\"\\n' \"\$TOKEN\")"
+  exit 0
+fi
+
+# Read the secret read-only and fire. The token reaches curl on its stdin config
+# channel (never its argument list), is unset right after the call, and is never
+# echoed.
+TOKEN="$(doppler secrets get "$SECRET_NAME" -p "$DOPPLER_PROJECT" -c "$CONFIG" --plain)"
+if [[ -z "$TOKEN" ]]; then
+  echo "trigger.sh: $SECRET_NAME is empty in Doppler $DOPPLER_PROJECT/$CONFIG" >&2
+  exit 2
+fi
+
+# Token-shape guard (never echoes the value): the token is written into curl's stdin
+# config below, so a quote or newline in it would inject a config directive. An unusable
+# token makes zero curl calls and exits 2, the same code as an empty secret, never 0.
+_bearer_ok() { local LC_ALL=C; case "${1:-}" in ''|*[!A-Za-z0-9._~+/=-]*) return 1 ;; esac; }
+if ! _bearer_ok "$TOKEN"; then
+  echo "trigger.sh: $SECRET_NAME in Doppler $DOPPLER_PROJECT/$CONFIG has an unexpected shape; nothing was sent" >&2
+  exit 2
+fi
+
+# mktemp, not $$: a PID is predictable and reused across concurrent runs in shared shells
+# (same reason token-efficiency-report.sh's SHORTSTAT_TMP mktemp+EXIT-trap block rejects it).
+# See ADR-009 Amendment.
+RESP=$(mktemp -t trigger-cron-resp.XXXXXXXX)
+trap 'rm -f "$RESP"' EXIT INT TERM
+HTTP_CODE=$(curl --disable --noproxy '*' -sS -o "$RESP" -w '%{http_code}' \
+  -X POST "$ROUTE_URL" \
+  -H 'content-type: application/json' \
+  -d "$BODY" \
+  --config - \
+  < <(printf 'header = "Authorization: Bearer %s"\n' "$TOKEN"))
+unset TOKEN
+
+echo "HTTP $HTTP_CODE"
+cat "$RESP" 2>/dev/null && echo
+rm -f "$RESP"
+
+# 202 = dispatched. Anything else is a failure the caller must act on.
+[[ "$HTTP_CODE" == "202" ]] || exit 1

package/skills/user-set-role/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: user-set-role
+description: "This skill should be used to promote or demote a user's flag-targeting role across Supabase users.role and the Flagsmith identity trait."
+disable-model-invocation: true
+---
+
+<!-- soleur-cloud-mode:start -->
+**Cloud Mode (Devin):** before pipeline work run `bash "${CLAUDE_PLUGIN_ROOT}/scripts/cloud-detect.sh"`. If `CLAUDE_PLUGIN_ROOT` is unset (cloud exec shells do not export it), resolve the root by IDENTITY, never by script basename: for `d` in `"$HOME/.local/share/devin/cli/plugins/cache"` and `/opt/.devin/plugins`, skip unless `[ -d "$d" ]`, then `MANIFEST="$(find "$d" -path '*/.claude-plugin/plugin.json' -exec grep -l '"name"[[:space:]]*:[[:space:]]*"soleur"' {} + 2>/dev/null | head -1)"`, `ROOT="${MANIFEST%/.claude-plugin/plugin.json}"` — one resolution, two consumers: `$ROOT/scripts/cloud-detect.sh` and `$ROOT/scripts/precommit-guard.sh`. (Shape check, not authentication: a planted `{"name":"soleur"}` dir passes — ADR-179 A11.) `local` or `not-local:no-devin-env` proceeds normally; any other `not-local:<reason>` applies `<plugin-root>/devin/INSTRUCTIONS.md` §Cloud Mode: emit the `--banner`, fan out sequentially with `Reviewed-Coverage: sequential-fallback` disclosure (never claim an independent review ran), `message_user` ack before any secrets read or production mutation, and run `precommit-guard.sh` before any `git commit` — hooks do not fire in cloud.
+<!-- soleur-cloud-mode:end -->
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# user-set-role
+
+The only approved path for mutating `public.users.role`. Migration 054's
+trigger blocks non-service-role connections from updating that column, so
+direct PostgREST writes from authenticated users always fail — this skill
+runs the service-role write + the Flagsmith identity trait write together
+to keep the two sides aligned.
+
+## When to use
+
+- Promoting yourself or a teammate to the `dev` cohort so you receive
+  per-role flag previews before flags promote to `prd`.
+- Demoting a user back to `prd` when they no longer need preview access.
+
+## When NOT to use
+
+- Bulk role changes (>5 users at once) — script doesn't batch; run
+  individually for now.
+- Trying to promote a Supabase user that doesn't exist — skill fails
+  early with a clear error.
+
+## Arguments
+
+<arguments> #$ARGUMENTS </arguments>
+
+Required positional args: `<email-or-userId> <prd|dev>`.
+
+- `<email-or-userId>`: email address (resolved to UUID via Supabase) OR
+  a Supabase auth UUID directly.
+- `<prd|dev>`: target role.
+
+Flag `--dry-run` runs lookup + diff (no writes).
+
+## Prerequisites
+
+- `doppler` CLI authenticated; access to `soleur/prd` config (for
+  `SUPABASE_SERVICE_ROLE_KEY` + `NEXT_PUBLIC_SUPABASE_URL`).
+- `doppler` access to `soleur/cli_ops` (for
+  `FLAGSMITH_MANAGEMENT_API_KEY`).
+- `curl` + `python3` on PATH.
+
+## Procedure
+
+The agent runs only the preview (`--dry-run` is honoured in the third position
+only; anything else there, or a fourth argument, exits `2`):
+
+```bash
+bash "${CLAUDE_PLUGIN_ROOT}/skills/user-set-role/scripts/set-role.sh" <email|uuid> <prd|dev> --dry-run
+```
+
+## The write is the one typed-`yes` handoff (ADR-249)
+
+The write path asks for a typed `yes` through the operator-script library's TTY
+acknowledgement, because the audit row this script writes records only that kind of
+acknowledgement (ADR-249); moving it to the staged agent-run approval gate that
+generated operator scripts use is tracked in #9387. It has no skip variable and no
+flag. An agent's shell has no TTY, so a write run there stops with exit `64` and `SOLEUR_BOOTSTRAP_INPUT_REQUIRED` on
+stdout, before any credential is fetched. Exit `64` is a refusal, never a success.
+The agent therefore does every other step itself (reads, the dry-run preview,
+preflight, verification) and hands over only the typed-`yes` write:
+
+1. Runs the script with `--dry-run` and shows the preview. That mode needs no TTY
+   and makes no writes.
+2. Prints the exact write command below, in a fenced block, for the operator to type
+   at a terminal prompt (Warp), the one step an agent cannot take. It replaces `<WORKTREE>` with the absolute path of
+   the worktree that holds this change (`git rev-parse --show-toplevel`) and
+   `<ARGS>` with `<email|uuid> <prd|dev>`, without `--dry-run`. It never prints a
+   `${CLAUDE_PLUGIN_ROOT}` or repo-relative form. A plugin-root or repo-relative path resolves against whatever directory the operator's terminal happens to be in; the absolute worktree path does not.
+3. Does not run the command, and does not run it through Claude Code's `!` prefix
+   either (whether that gives the command a TTY is unmeasured, ADR-249). The
+   printed command is an undone operator step under
+   `wg-block-pr-ready-on-undeferred-operator-steps`: record it where the pipeline
+   tracks operator steps, and do not mark a PR ready until the operator says it ran.
+
+<!-- operator-write-command -->
+```bash
+cd <WORKTREE> && bash <WORKTREE>/plugins/soleur/skills/user-set-role/scripts/set-role.sh <ARGS>
+```
+
+The operator types `yes` at the prompt. Any other answer stops the script with exit
+`1` and `SOLEUR_BOOTSTRAP_ABORTED stage=ack`, before anything is written.
+
+The script (full procedure in [scripts/set-role.sh](./scripts/set-role.sh)):
+
+1. **Validate args** — role in `{prd, dev}`; identifier looks like
+   email-or-UUID.
+2. **Resolve userId** — if input is an email, look up via service-role
+   Supabase REST: `GET /rest/v1/users?email=eq.<email>&select=id,role`.
+   If input is UUID, use directly + read current role for the diff.
+3. **Diff** — if `current_role == target_role`, exit 0 ("no change").
+4. **Print pre/post** — user UUID + email + current role + target role.
+5. **Operator ack** — a typed `yes` at the TTY prompt per
+   `hr-menu-option-ack-not-prod-write-auth` (no flag skips it; no TTY means exit
+   `64` before any credential fetch). Both role values change a PRD user.
+6. **Update Supabase** — `PATCH /rest/v1/users?id=eq.<uuid>` with
+   `{ "role": "<target>" }`. Service-role JWT bypasses the trigger.
+7. **Update Flagsmith identity trait** — POST to
+   `/api/v1/environments/{env_id}/identities/{userId}/traits/` with
+   `trait_key=role`, `trait_value=<target>`. Done for BOTH dev (env 90722)
+   and prd (env 90721) so the user's flag resolution matches in either
+   environment.
+8. **Re-verify** — re-read `users.role` AND the Flagsmith identity trait
+   in each env. Assert matches `<target>`.
+
+## Exit codes
+
+- `0` — success / no-op / dry-run clean.
+- `1` — validation failure (bad role, malformed identifier), or the operator did
+  not type `yes` (`SOLEUR_BOOTSTRAP_ABORTED stage=ack`; nothing written).
+- `2` — prerequisite missing (Doppler, env vars), or a bad third/fourth argument.
+- `3` — user not found in Supabase.
+- `4` — Supabase write failed.
+- `5` — Flagsmith trait write failed (Supabase already updated;
+  re-run is idempotent on Supabase side and will re-apply the trait).
+- `64` — a write run with no TTY (`SOLEUR_BOOTSTRAP_INPUT_REQUIRED`): hand the
+  command to the operator (above).
+
+## Sharp edges
+
+- **30s flag-cache TTL.** The user's resolved flag values won't pick up
+  the new role until the per-replica per-role cache TTL elapses (max 30s).
+  Skill prints this hint after success.
+- **Trait write is fire-and-forget on the identity side.** Flagsmith
+  upserts traits; calling with the same value twice is a no-op.
+- **Email collision.** If two users somehow share an email (shouldn't
+  happen — `public.users(email)` is unique), the skill aborts with
+  exit 3 + the conflicting UUIDs.
+
+## Cross-references
+
+- Migration: `apps/web-platform/supabase/migrations/054_users_role_column.sql`
+- ADR: `knowledge-base/engineering/architecture/decisions/ADR-038-feature-flags-flagsmith.md`
+- Sibling skills: `soleur:flag-set-role`, `soleur:flag-create`

package/skills/user-set-role/scripts/set-role.sh

@@ -0,0 +1,218 @@
+#!/usr/bin/env bash
+# Promote/demote a Soleur user's flag-targeting role.
+#
+# Contract: SKILL.md in the parent directory.
+# Usage: bash set-role.sh <email|uuid> <prd|dev> [--dry-run]
+#
+# Every write run changes a PRD user (both role values). Run it in your OWN
+# terminal: the ack below needs a person to type yes. An agent runs only
+# `--dry-run` and prints this command for the operator.
+#
+# Exit codes:
+#   0 — success / dry-run
+#   1 — usage error, or the operator did not type yes at the ack
+#       (stdout: SOLEUR_BOOTSTRAP_ABORTED stage=ack; nothing mutated)
+#   2 — prerequisite missing, or more than three arguments / a third argument
+#       other than --dry-run
+#   3 — user lookup failed
+#   4 — audit append or Supabase update failed
+#   5 — Flagsmith trait write failed
+#  64 — no TTY on stdin for a write run (stdout: SOLEUR_BOOTSTRAP_INPUT_REQUIRED);
+#       refused before any credential fetch or network call (#8486)
+
+set -euo pipefail
+
+# (#7797) Refuse to run under shell tracing. UNCONDITIONAL — deliberately NOT
+# gated on a non-emptiness test of the credential variable, because
+# every credential this script handles (SUPABASE_SERVICE_ROLE_KEY for soleur/prd,
+# which bypasses RLS across every customer's rows, plus the Flagsmith management
+# key) is acquired by `doppler secrets get` BELOW this point, so a conditional arm
+# would test an empty variable at guard time, open, and then trace the acquisition
+# itself. The refusal prints on STDOUT because agent runtimes surface stdout and
+# swallow stderr (knowledge-base/project/constitution.md > Code Style); a swallowed
+# refusal leaves the operator with a bare exit 78 and no explanation.
+case "$-" in
+  *x*)
+    printf '[FATAL] refusing to run under xtrace: this script handles a live credential and -x would print it (see #7797)\n'
+    exit 78
+    ;;
+esac
+
+# (#7873) `--disable` closes ~/.curlrc and `--noproxy '*'` closes the proxy vars,
+# but neither touches the env that subverts TLS ITSELF. SSLKEYLOGFILE writes the
+# session keys and the CA vars substitute the trust store, so a CURL_CA_BUNDLE
+# MITM of the service-role key works with every other guard fully intact.
+unset SSLKEYLOGFILE CURL_CA_BUNDLE SSL_CERT_FILE SSL_CERT_DIR CURL_HOME \
+      HOSTALIASES LOCALDOMAIN RES_OPTIONS
+
+# Shared WORM audit-append helper (PostgREST RPC; no DB-CLI binary). See #4581 PR-1.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/../../../scripts/audit-flag-flip.sh"
+
+# Human-presence gate (#8486, ADR-249). Every production write below waits on the
+# operator-script library's class-2 ack, which has NO skip variable and no flag:
+# it needs a person typing `yes` at a terminal, so an agent's tool subprocess
+# (no TTY) is refused with exit 64 before any credential fetch. Clear anything an
+# inherited environment could use to pre-empt the library's double-source guard
+# or to stand in for its ack before sourcing it. (BASH_ENV runs before this
+# script and cannot be cleared from inside it — recorded in ADR-249 as a
+# hijack-class residual.)
+unset _SOLEUR_OPERATOR_SCRIPT_LOADED SOLEUR_OP_ACKED
+unset -f soleur_op_ack_or_die soleur_op_input_required soleur_op_aborted
+# shellcheck source=../../../scripts/lib/operator-script.sh
+source "$SCRIPT_DIR/../../../scripts/lib/operator-script.sh"
+[[ ${SOLEUR_OP_LIB_API:-0} -eq 1 ]] || {
+  printf 'SOLEUR_BOOTSTRAP_LIB_INCOMPATIBLE need=1 got=%s\n' "${SOLEUR_OP_LIB_API:-0}"
+  exit 64
+}
+
+readonly FLAGSMITH_API="https://api.flagsmith.com/api/v1"
+readonly FLAGSMITH_ENV_DEV_ID=90722
+readonly FLAGSMITH_ENV_PRD_ID=90721
+
+# The parser honours --dry-run ONLY in position 3, so anything else there (or a
+# fourth argument) is refused rather than silently read as a write (#8486).
+[[ $# -le 3 ]] || { echo "set-role.sh takes at most three arguments (got $#)" >&2; exit 2; }
+[[ -z "${3:-}" || "${3:-}" == "--dry-run" ]] || { echo "third argument must be --dry-run (got: ${3})" >&2; exit 2; }
+DRY_RUN=0
+if [[ "${3:-}" == "--dry-run" ]]; then DRY_RUN=1; fi
+
+IDENT="${1:-}"
+TARGET="${2:-}"
+
+usage() {
+  echo "Usage: set-role.sh <email|uuid> <prd|dev> [--dry-run]" >&2
+  exit 1
+}
+
+[[ -z "$IDENT" || -z "$TARGET" ]] && usage
+[[ "$TARGET" != "prd" && "$TARGET" != "dev" ]] && { echo "role must be prd|dev (got: $TARGET)" >&2; usage; }
+
+# UUID v4 regex (loose — Supabase auth uses standard v4).
+UUID_RE='^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'
+
+# --- no TTY, no write: refuse before any credential fetch or network call ---
+if [[ $DRY_RUN -eq 0 ]]; then [[ -t 0 ]] || soleur_op_input_required "destructive-write-ack(no-skip-variable-by-design)" ack; fi
+
+command -v curl >/dev/null || { echo "missing: curl" >&2; exit 2; }
+command -v doppler >/dev/null || { echo "missing: doppler" >&2; exit 2; }
+command -v python3 >/dev/null || { echo "missing: python3" >&2; exit 2; }
+
+SUPA_URL=$(doppler secrets get NEXT_PUBLIC_SUPABASE_URL -p soleur -c prd --plain 2>/dev/null || true)
+SUPA_KEY=$(doppler secrets get SUPABASE_SERVICE_ROLE_KEY -p soleur -c prd --plain 2>/dev/null || true)
+FLAGSMITH_TOKEN=$(doppler secrets get FLAGSMITH_MANAGEMENT_API_KEY -p soleur -c cli_ops --plain 2>/dev/null || true)
+[[ -z "$SUPA_URL" || -z "$SUPA_KEY" ]] && { echo "missing Supabase secrets in soleur/prd" >&2; exit 2; }
+[[ -z "$FLAGSMITH_TOKEN" ]] && { echo "missing FLAGSMITH_MANAGEMENT_API_KEY in soleur/cli_ops" >&2; exit 2; }
+
+# Token-shape guard: a newline in the key would inject a curl config directive on the stdin
+# channel below. Never echoes the value.
+_bearer_ok() { local LC_ALL=C; case "${1:-}" in ''|*[!A-Za-z0-9._~+/=-]*) return 1 ;; esac; }
+_bearer_ok "$SUPA_KEY" || { echo "SUPABASE_SERVICE_ROLE_KEY has an unexpected shape" >&2; exit 2; }
+
+# The service-role key travels on curl's stdin config channel (both headers), never on argv.
+supa() {
+  curl --disable --noproxy '*' -sS -H "Content-Type: application/json" "$@" --config - \
+    < <(printf 'header = "apikey: %s"\nheader = "Authorization: Bearer %s"\n' "$SUPA_KEY" "$SUPA_KEY")
+}
+
+# The Flagsmith management key travels the same way: a stdin config header, never argv.
+_bearer_ok "$FLAGSMITH_TOKEN" || { echo "FLAGSMITH_MANAGEMENT_API_KEY has an unexpected shape" >&2; exit 2; }
+fs_api() {
+  curl --disable --noproxy '*' -sS -H "Content-Type: application/json" "$@" --config - \
+    < <(printf 'header = "Authorization: Api-Key %s"\n' "$FLAGSMITH_TOKEN")
+}
+
+# --- resolve user ----------------------------------------------------------
+if [[ "$IDENT" =~ $UUID_RE ]]; then
+  USER_ID="$IDENT"
+  echo "→ Using UUID directly: $USER_ID"
+else
+  echo "→ Resolving email '$IDENT' to UUID via Supabase…"
+  # URL-encode the email (`+` → `%2B` etc.) so PostgREST receives it intact.
+  EMAIL_ENC=$(python3 -c "import urllib.parse, sys; print(urllib.parse.quote(sys.argv[1], safe=''))" "$IDENT")
+  ROWS=$(supa "${SUPA_URL}/rest/v1/users?email=eq.${EMAIL_ENC}&select=id,email,role")
+  COUNT=$(echo "$ROWS" | python3 -c 'import json,sys; d=json.load(sys.stdin); print(len(d))')
+  [[ "$COUNT" == "0" ]] && { echo "no user with email '$IDENT'" >&2; exit 3; }
+  [[ "$COUNT" -gt "1" ]] && { echo "MULTIPLE users with email '$IDENT' — abort." >&2; echo "$ROWS" >&2; exit 3; }
+  USER_ID=$(echo "$ROWS" | python3 -c 'import json,sys; print(json.load(sys.stdin)[0]["id"])')
+fi
+
+# USER_ID is interpolated into the request URL: only a literal-anchored UUID may reach it.
+[[ "$USER_ID" =~ ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ ]] || { echo "refusing: resolved user id is not a UUID" >&2; exit 3; }
+
+# Read current role.
+CUR_ROWS=$(supa "${SUPA_URL}/rest/v1/users?id=eq.${USER_ID}&select=id,email,role")
+[[ "$(echo "$CUR_ROWS" | python3 -c 'import json,sys; print(len(json.load(sys.stdin)))')" == "0" ]] && { echo "no users.row for UUID $USER_ID" >&2; exit 3; }
+CUR_ROLE=$(echo "$CUR_ROWS" | python3 -c 'import json,sys; print(json.load(sys.stdin)[0]["role"])')
+EMAIL=$(echo "$CUR_ROWS" | python3 -c 'import json,sys; print(json.load(sys.stdin)[0]["email"])')
+
+echo "  user: $EMAIL ($USER_ID)  current role: $CUR_ROLE  target: $TARGET"
+
+if [[ "$CUR_ROLE" == "$TARGET" ]]; then
+  echo "✓ No change — role is already '$TARGET'. Re-applying Flagsmith trait anyway for idempotency."
+  if [[ $DRY_RUN -eq 1 ]]; then exit 0; fi
+fi
+
+# --- ack ------------------------------------------------------------------
+if [[ $DRY_RUN -eq 1 ]]; then
+  echo "(dry-run — exiting 0)"
+  exit 0
+fi
+
+soleur_op_ack_or_die "Set the role of ${EMAIL} (${USER_ID}) to '${TARGET}' in Supabase prd and Flagsmith (dev + prd) now? Type yes: "
+
+# --- audit append (WORM) — BEFORE the users.role mutation (append-before-flip) -------
+# A failed audit must abort the script before any prod mutation; otherwise a role
+# change could land in prd with no WORM accountability row (#4581 review FINDING 1).
+ACTOR=$(doppler secrets get OPERATOR_EMAIL -p soleur -c cli_ops --plain 2>/dev/null | tr '[:upper:]' '[:lower:]')
+[[ -z "$ACTOR" ]] && { echo "FATAL: OPERATOR_EMAIL not in Doppler soleur/cli_ops" >&2; exit 4; }
+
+# Audit DB target = soleur/dev (preserves the historical dev-DB audit destination);
+# distinct from the prd SUPA_URL/SUPA_KEY used for the users.role PATCH below.
+# `|| true` normalizes a Doppler auth/network failure to the exit-4 contract (the
+# [[ -z ]] guard) instead of letting `set -e` abort at the assignment with exit 1.
+AUDIT_URL=$(doppler secrets get SUPABASE_URL -p soleur -c dev --plain 2>/dev/null) || true
+AUDIT_SRK=$(doppler secrets get SUPABASE_SERVICE_ROLE_KEY -p soleur -c dev --plain 2>/dev/null) || true
+[[ -z "$AUDIT_URL" || -z "$AUDIT_SRK" ]] && { echo "FATAL: SUPABASE_URL / SUPABASE_SERVICE_ROLE_KEY not in Doppler soleur/dev" >&2; exit 4; }
+
+# NOTE(#4581): AUDIT_ACTION tautology (both branches "on") is a pre-existing bug,
+# out of scope for the transport swap; see #4593. Role assignment records "on".
+AUDIT_ACTION=$([[ "$CUR_ROLE" == "$TARGET" ]] && echo "on" || echo "on")
+AUDIT_ID=$(audit_flag_flip_rpc "$AUDIT_URL" "$AUDIT_SRK" "user-role" "prd" "user:$USER_ID" "$AUDIT_ACTION" null null "$ACTOR") || exit 4
+echo "  audit_id=$AUDIT_ID"
+
+# --- update Supabase (AFTER the audit row is committed) -------------------------------
+if [[ "$CUR_ROLE" != "$TARGET" ]]; then
+  echo "→ Updating Supabase users.role…"
+  RESP=$(supa -X PATCH "${SUPA_URL}/rest/v1/users?id=eq.${USER_ID}" \
+    -H 'Prefer: return=representation' \
+    -d "{\"role\": \"$TARGET\"}")
+  echo "$RESP" | python3 -c '
+import json, sys
+d = json.load(sys.stdin)
+if not isinstance(d, list) or not d:
+    print(json.dumps(d), file=sys.stderr); sys.exit(4)
+print("  updated:", d[0]["email"], "role →", d[0]["role"])
+' || exit 4
+fi
+
+# --- update Flagsmith identity trait (both envs) --------------------------
+for ENV_PAIR in "dev:$FLAGSMITH_ENV_DEV_ID" "prd:$FLAGSMITH_ENV_PRD_ID"; do
+  ENV_NAME=${ENV_PAIR%:*}
+  ENV_ID=${ENV_PAIR#*:}
+  echo "→ Writing Flagsmith trait role=$TARGET for identity $USER_ID in env=$ENV_NAME ($ENV_ID)…"
+  fs_api -X POST "${FLAGSMITH_API}/environments/${ENV_ID}/identities/${USER_ID}/traits/" \
+    -d "{\"trait_key\":\"role\",\"trait_value\":\"$TARGET\"}" \
+    | python3 -c '
+import json, sys
+d = json.load(sys.stdin)
+if isinstance(d, dict) and d.get("trait_key") == "role":
+    print("  ✓ wrote:", d)
+else:
+    print("  ! response:", json.dumps(d), file=sys.stderr); sys.exit(5)
+' || exit 5
+done
+
+echo
+echo "✓ Done. The per-role flag cache TTL is 30s; user's resolved flags update within that window."
+exit 0

package/skills/user-story-writer/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: user-story-writer
+description: "This skill should be used when decomposing feature requirements into granular, implementable user stories. It applies Elephant Carpaccio slicing, INVEST criteria, and story prioritization."
+---
+
+<!-- grok-harness-invoke:start -->
+**Grok Build (`plugins/soleur/lib/harness.ts` `invokeSkill()`):** Read this SKILL.md in this process and run it to completion. A one-segment `soleur:<name>` in this document names a SKILL — on Grok Build, Read `plugins/soleur/skills/<name>/SKILL.md` in this process; it is not a nested tool_use. A multi-segment id such as `soleur:<domain>:<name>` names an AGENT: spawn it, never Read it, and on Grok Build spawn_subagent takes the id with its colons replaced by hyphens (`agentIdToGrokSubagentType`). **Claude Code:** Skill tool for a skill (`soleur:<name>`), Task tool with `subagent_type` for an agent. Forbidden is executing a subset, not the Read.
+<!-- grok-harness-invoke:end -->
+
+# User Story Writer
+
+Decompose a problem statement or feature requirement into thin, vertical user stories that deliver end-to-end value.
+
+## When to Use
+
+- Breaking down a feature into sprint-sized work items
+- Decomposing a vague requirement into concrete stories
+- Prioritizing a backlog by risk and value
+
+## Constraints
+
+This is a story-writing role. Do not suggest implementation details, code examples, technical architectures, or testing frameworks. Focus exclusively on user needs, business value, and acceptance criteria in user terms.
+
+## Process
+
+### 1. Analyze the Problem
+
+- Identify the core user need and key stakeholders
+- Map the problem domain and user personas
+- Clarify scope boundaries
+
+### 2. Slice with Elephant Carpaccio
+
+Break the problem into the thinnest possible vertical slices. Each slice must deliver a complete, working capability a user can interact with -- not a technical layer.
+
+### 3. Write INVEST-Compliant Stories
+
+Every story must satisfy all six INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable).
+
+### 4. Structure Each Story
+
+```
+**Story Title**: [Descriptive name]
+**As a** [user type]
+**I want** [functionality]
+**So that** [business value]
+
+**Acceptance Criteria**:
+- [Specific, testable criterion 1]
+- [Specific, testable criterion 2]
+
+**Definition of Done**:
+- [User-facing quality requirement]
+- [Business completion criterion]
+```
+
+### 5. Prioritize and Sequence
+
+Order stories by:
+
+1. Risk reduction -- tackle unknowns early
+2. User value delivery
+3. Dependencies between stories
+4. Learning opportunities
+
+### 6. Validate Completeness
+
+Confirm the full set of stories covers the original problem without gaps or overlaps.
+
+## Output Format
+
+Produce a structured document containing:
+
+- Problem summary and user personas
+- Prioritized list of user stories (using the template above)
+- Rationale for decomposition approach and sequencing
+- Summary of how stories collectively solve the original problem