@thebassclef/lite 1.1.0 → 1.2.0-alpha.1

package/dist/lite/.claude/skills/provision-deploy-host/SKILL.md

@@ -0,0 +1,257 @@
+---
+tier: lite
+name: provision-deploy-host
+description: "Run the consumer onboarding chain \u2014 read bassclef-platform.yml plus verify secrets, extend GHA scope, run aws amplify create-app with console-pivot fallback, open the consumer config PR, write an audit row. Replaces the 5-step flow."
+problem: "Consumer onboarding chain runs manually. Secret checks and GHA scope grants get missed."
+value: "Runs the consumer onboarding chain. Reads platform config plus verifies secrets and extends GHA scope."
+inputs: [Consumer name and target host]
+outputs: [Verified secrets, Extended GHA scope, Rollback token]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# /provision-deploy-host — One-Dispatch Consumer Onboarding
+
+Replaces the 5-rumblestrip TwoDo onboarding flow (deploy-keys policy,
+PAT scope ×2, GitHub App scope, Cloudflare token gap) with one
+mechanical chain. Operator dispatches once per consumer; merges one
+PR; consumer is ready for `/launch-preview`.
+
+## When to invoke
+
+- **New consumer onboarding** — after `gh repo create <consumer>`
+  has run, before any prototype work
+- **Re-provisioning** an existing consumer (idempotent — safe no-op
+  if already provisioned)
+- **Adding a deploy tier** to an existing consumer (e.g., wiring up
+  production tier on an app that previously had only prototype)
+
+## When NOT to invoke
+
+- Before the consumer repo exists — agent refuses with "consumer repo
+  must exist; run `gh repo create` first"
+- Before `bassclef-platform.yml` exists — Phase 0 fails fast with
+  remediation hint
+- For internal-only / docs-only repos — those use `hosting_platform: none`
+  in their substrate.config.md and don't need deploy provisioning
+
+## Sources read
+
+- `~/src/<github_org>/platform-config/bassclef-platform.yml` —
+  org-baseline (read via `state_platform_get`)
+- `substrate.secrets.md` (bassclef's; per-consumer if relevant) —
+  required env-var manifest (read via `/secrets-bootstrap`)
+- Consumer's `substrate.config.md` — to determine if already provisioned
+- `bassclef#457`, `bassclef#449`, `bassclef#450` — issues this skill
+  closes / depends on
+- `standards/bassclef-platform.md` — schema + Backstage-positioning frame
+- `standards/secrets-lifecycle.md` — secret storage type discriminator
+- `standards/domain-and-dns.md` — subdomain pattern referenced for next-step
+
+## Prerequisites
+
+1. Consumer repo exists at `sunj-labs/<consumer>`
+2. `bassclef-platform.yml` exists at `~/src/sunj-labs/platform-config/bassclef-platform.yml`
+3. Operator's shell env has every `storage.type: env` secret named in
+   substrate.secrets.md (run `/secrets-bootstrap` to verify; happens
+   automatically as Phase 0 of this skill)
+4. Operator has a fine-grained GitHub PAT with `admin:org` scope (one-time)
+5. `aws amplify list-apps --region <region>` works (auth is set)
+
+## Phase 0 — Pre-flight (fail-fast)
+
+Run before any external API call. Each check produces actionable
+remediation; agent does NOT proceed until all green.
+
+| Check | Command | Pass | Fail |
+|-------|---------|------|------|
+| platform.yml exists | `state_platform_path` resolves to existing file | ✓ | "bassclef-platform.yml not found at <path>; create via bassclef#462 or override BASSCLEF_PLATFORM_CONFIG_PATH" |
+| Required platform.yml fields | `state_platform_get org.aws_account_id` etc. all non-empty | ✓ | "platform.yml is missing <field>; run /scaffold-platform-yml" |
+| `/secrets-bootstrap` exit 0 | `bash scripts/secrets-bootstrap.sh` | ✓ | "secrets gap; rerun with --write to bootstrap, then re-run this skill" |
+| `aws sts get-caller-identity` | shows the org's AWS account id | ✓ | "AWS auth missing or wrong account; run `aws configure` then retry" |
+| `gh auth status` | logged in as expected user | ✓ | "gh not authenticated; run `gh auth login` then retry" |
+| Consumer repo exists | `gh repo view sunj-labs/<consumer>` | ✓ | "consumer repo missing; run `gh repo create sunj-labs/<consumer>` then retry" |
+
+## Phase 0.5 — Extend GHA App scope (one-time per org)
+
+AWS Amplify GitHub App needs `Repository contents: read` + `Pull requests:
+write` + `Metadata: read` on the org. Without this, `aws amplify create-app`
+fails with `Validation Failed` from the GitHub side.
+
+```bash
+# Check current installation scope
+gh api /user/installations --jq '.installations[] | select(.app_slug == "aws-amplify-application") | .repository_selection'
+
+# If "selected" and the consumer repo isn't in the list:
+gh api /user/installations/<id>/repositories \
+  --method POST \
+  -f repository_id=<consumer-repo-id>
+```
+
+Idempotent: if scope already includes the consumer, no-op.
+
+## Phase 1a — `aws amplify create-app` (PAT path)
+
+```bash
+aws amplify create-app \
+  --name <consumer> \
+  --region $(state_platform_get amplify.default_region) \
+  --repository "https://github.com/sunj-labs/<consumer>" \
+  --oauth-token "$AWS_AMPLIFY_GITHUB_PAT" \
+  --platform "$(state_platform_get amplify.default_framework)"
+```
+
+Captures the resulting `appId` for Phase 2.
+
+If this returns `403` / `Resource not accessible`: the deploy-keys
+policy is blocking CLI creation. Pivot to Phase 1b.
+
+## Phase 1b — Console-pivot fallback
+
+When `provisioning.amplify_create_path: console` is set in platform.yml
+(sunj-labs's current state), Phase 1a is SKIPPED and operator is
+directed to the console:
+
+```
+Console-pivot:
+  1. Open https://console.aws.amazon.com/amplify/home?region=eu-north-1
+  2. Click "Create new app" → GitHub
+  3. Select repo "sunj-labs/<consumer>"
+  4. Branch: main
+  5. App name: <consumer>
+  6. Click "Save and deploy"
+  7. Copy the resulting App ID (format: d12345abcdef)
+  8. Paste into operator-prompt below
+```
+
+Agent waits for operator to paste App ID, then resumes Phase 2.
+
+## Phase 2 — Create branch + start build
+
+```bash
+# In Amplify, set the production branch
+aws amplify update-branch \
+  --app-id <app-id> \
+  --branch-name main \
+  --enable-auto-build
+
+# Trigger initial build
+aws amplify start-job \
+  --app-id <app-id> \
+  --branch-name main \
+  --job-type RELEASE
+```
+
+## Phase 3 — Write consumer substrate.config.md
+
+Open a PR against the consumer repo with the Amplify + DNS config block:
+
+```yaml
+hosting_platform: amplify
+amplify_app_id: d12345abcdef
+amplify_region: eu-north-1
+amplify_branch: main
+subdomain: <consumer>.apps.your-domain.com
+dns_provider: cloudflare
+dns_zone: your-domain.com
+cloudflare_token_env: CLOUDFLARE_API_TOKEN
+```
+
+Consumer-side PR title: `chore: substrate.config.md — provisioned by bassclef /provision-deploy-host`
+
+Operator merges. /provision-deploy-host pauses until operator confirms
+merge (idempotent — re-running detects merged PR and skips).
+
+## Phase 4 — Audit row
+
+When `audit.enabled: true` (per bassclef-platform.yml; default true),
+write an audit row to `state/audit/<utc>-<skill>-<short-hash>.json`
+capturing:
+
+- `consumer` (e.g., "your-org/your-app")
+- `env_vars_consulted` (names only, never values)
+- `api_calls` (method + endpoint + status)
+- `arns_created` (Amplify app ID, etc.)
+- `operator_dispatch_context` (session ID, branch, intent)
+
+This row survives a CIO compliance review without retrofit (bassclef#462
+WU-3.5 primitive).
+
+## Phase 5 — Surface next-step
+
+```
+✓ <consumer> provisioned on amplify (eu-north-1)
+✓ App ID: d12345abcdef
+✓ DNS pending: <consumer>.apps.your-domain.com
+
+Next:
+  /launch-preview <consumer>     — bind subdomain + smoke-test
+  cd ~/src/sunj-labs/<consumer>  — switch to consumer repo
+  git pull                       — pull the substrate.config PR you just merged
+```
+
+## Five known failure modes (covered by tests)
+
+| Failure mode | Phase | Detection | Remediation |
+|--------------|-------|-----------|-------------|
+| platform.yml missing | 0 | `state_platform_path` returns no file | "Create bassclef-platform.yml; see standards/bassclef-platform.md" |
+| Required env var unset | 0 | `/secrets-bootstrap` exit 1 | "Rerun with --write or set in shell" |
+| GHA scope insufficient | 0.5 | `gh api` 403 on installation read | "Run `gh auth refresh -s admin:org` and retry" |
+| Deploy-keys policy blocks CLI | 1a | `aws amplify create-app` returns 403 | "platform.yml has amplify_create_path: console — switch to Phase 1b" |
+| Consumer PR conflict | 3 | `gh pr create` fails | "substrate.config.md already provisioned; surface diff for operator" |
+
+## Idempotency
+
+- Phase 0 always runs (cheap)
+- Phase 1a-2: skip if app already exists (`aws amplify list-apps | jq` lookup)
+- Phase 3: skip if substrate.config.md already provisioned
+- Phase 4: always writes audit row (each invocation is auditable)
+- Phase 5: always prints next-steps
+
+## Composes with
+
+| Skill | How it composes |
+|---|---|
+| `/secrets-bootstrap` | Phase 0 prerequisite |
+| `/launch-preview` | Phase 5 next-step |
+| `/bind-subdomain` | Sister skill — `/launch-preview` chains it |
+| `.claude/rules/pr-body-shape.md` | Phase 3 PR body MUST open with Flash + Tweet + `## Goal` per shape contract |
+
+## Test plan
+
+The runner script ships as a STUB that exercises Phase 0 fully but
+stubs Phases 1-5 (per bet out-of-scope guarantee — "first live use
+is the next consumer onboarding, operator-supervised").
+
+Tests cover:
+
+- [x] Phase 0 — platform.yml missing → fail-fast with directive
+- [x] Phase 0 — secrets-bootstrap green → proceed; red → fail-fast
+- [x] Phase 0 — consumer repo missing → fail-fast
+- [x] Phase 0 — all checks green → proceed message
+- [x] Phase 1b console-pivot prompt format (when amplify_create_path: console)
+- [x] Phase 4 — audit row written under state/audit/ with required fields
+- [x] Phase 5 — next-step surface includes correct subdomain pattern
+
+## Override paths
+
+- `SKIP_PROVISION_PREFLIGHT=1` — skip Phase 0 (rare; for testing on
+  pre-provisioned consumers)
+- `--dry-run` — run Phase 0 + print Phase 1-5 plan; don't make any
+  external API calls. Default for V1.
+- `--phase <N>` — start at a specific phase (resume after partial run)
+
+## Refs
+
+- bassclef#457 — issue this skill closes (WU-3 of 2026-05-04 bet)
+- bassclef#449 — sibling: hosting_platform schema (already shipped)
+- bassclef#450 — sibling: deploy-host pre-flight (already shipped 2026-05-03b)
+- bassclef#462 — sibling: bassclef-platform.yml schema (WU-1)
+- bassclef#461 — sibling: /secrets-bootstrap (WU-2)
+- standards/bassclef-platform.md
+- standards/secrets-lifecycle.md
+- standards/domain-and-dns.md
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/dist/lite/.claude/skills/quick-fix/SKILL.md

@@ -0,0 +1,273 @@
+---
+tier: lite
+name: quick-fix
+description: "Compressed fix workflow for trivial bugs with stated entry criteria. Operator-in-loop. Runs /diagnose in skip-criteria mode. Then operator writes the fix. Full /verify still mandatory. Commits carry [quick-fix] footer for audit."
+problem: "Trivial bugs get over-ceremonied by full /diagnose. Small edits shouldn't need the whole chain."
+value: "Compressed fix workflow for trivial bugs. Operator-in-loop with stated entry criteria."
+inputs: [A failing test or error log]
+outputs: [Fix commit, Entry criteria confirmed, Verify pass]
+user_invocable: true
+disable_model_invocation: false
+no_user_modes: true
+---
+
+# /quick-fix — Compressed Fix Workflow
+
+Full bassclef /diagnose ceremony (Repro + Is/Is Not + Resolution Chain +
+Five Whys + Hypothesis + Significance) is the right discipline for
+non-trivial bugs. For trivial bugs it exceeds the bug's stakes.
+
+Without a compressed lane, operators either:
+
+- Grind through the ceremony for a typo (expensive, demoralizing)
+- Skip /diagnose silently (governance erodes; blocked-items pattern we've
+  observed repeatedly)
+
+`/quick-fix` is the compressed lane. Stated entry criteria keep it from
+becoming the default. `[quick-fix]` commit footer enables auditing the
+ratio over time.
+
+## Entry criteria (ALL must hold)
+
+Strict. If any criterion fails, use full /diagnose instead.
+
+1. **Localized**: defect lives in a single file (or two files for
+   rename/type propagation). Cross-cutting concerns disqualify.
+2. **Obvious cause**: you can name the root cause in one sentence
+   without reading logs. Example: "missing null check on user
+   preference loaded from session."
+3. **Obvious fix**: fix is ≤10 lines, no new interfaces, no new
+   abstractions, no schema changes.
+4. **Low blast radius**: not auth, not middleware, not schema, not
+   security, not tenant boundary. If any of those — full /diagnose
+   and/or /auto-fix with blast-radius floors.
+5. **Reproducible OR trivially verifiable**: either Step 0 repro is
+   explicitly skippable (typo / env var / off-by-one) or repro is
+   fast enough to include in the same turn as the fix.
+
+If ALL five hold → /quick-fix is appropriate. If ANY fail → escalate
+to full /diagnose or /auto-fix.
+
+## When to use
+
+- Typo in a rule/standard/skill doc
+- Missing env var with clear error message
+- Off-by-one in a single function
+- Missing null check on a field the error names
+- Broken link in a markdown doc
+- Wrong default value in a config with obvious correct value
+
+## When NOT to use
+
+- Any bug the operator can't describe in one sentence
+- Anything touching auth, middleware, schema, security, tenant paths
+- Intermittent failures (repro work = full /diagnose territory)
+- Bugs that span multiple files or require refactor
+- "I think this might be the fix" — if you're not sure, not trivial
+
+## Usage
+
+```
+/quick-fix [issue-ref]        → with issue context
+/quick-fix for "description"  → freeform description
+/quick-fix                    → agent extracts from recent conversation
+```
+
+## Procedure
+
+### Step 1: Entry-criteria self-check
+
+Before anything else, state explicitly which criteria are met:
+
+```
+## Quick-fix entry check
+- Localized? ✅ / ❌
+- Obvious cause? ✅ / ❌
+- Obvious fix (≤10 lines)? ✅ / ❌
+- Low blast radius? ✅ / ❌
+- Reproducible or trivially verifiable? ✅ / ❌
+
+If any ❌ → escalate to /diagnose (full) or /auto-fix
+If all ✅ → proceed
+```
+
+If escalating, invoke the appropriate skill and stop this procedure.
+
+### Step 2: Compressed diagnosis
+
+Run /diagnose in skip-mode:
+
+- Step 0 Reproduce: explicitly skip with reason ("typo" / "missing env var"
+  / "off-by-one" / "single-site null check with clear error message") OR
+  state a one-line repro
+- Steps 1-4: compress to a one-sentence hypothesis — "Cause: X. Fix: Y.
+  Verify: Z."
+
+Output:
+
+```
+## Compressed diagnosis
+- **Repro**: [one-line OR "skipped — [reason]"]
+- **Cause**: [one sentence]
+- **Fix**: [one sentence]
+- **Verify**: [one sentence — what test/command confirms]
+```
+
+### Step 3: Operator writes the fix
+
+**Not the agent.** /quick-fix is operator-in-loop deliberately. The agent
+surfaces the diagnosis and the proposed fix shape. Operator writes the
+actual code.
+
+Why operator-in-loop: entry criteria are agent-assessed. If the agent
+is wrong about "obvious + localized," the operator catches it at write
+time (not commit time). The human review is the safety net for the
+compressed ceremony.
+
+Exception: doc / config / markdown typos — agent writes, operator
+confirms. (Still a /quick-fix; the "code" is text.)
+
+### Step 4: Full /verify
+
+Skipping /verify is never part of /quick-fix. The ceremony compresses
+at diagnosis, not verification. Fix still goes through:
+
+- Change-type-matched verification (per /verify skill)
+- Production build (if code change)
+- Test suite (if tested code path)
+- Marker write (both /tmp + `state/markers/verify/`)
+
+If /verify fails, /quick-fix escalates to /diagnose full lane.
+
+### Step 5: Commit with audit marker
+
+Commit message MUST carry `[quick-fix]` footer:
+
+```
+fix: missing null check on user.preferences.locale
+
+User object from session can have undefined preferences; guard with
+optional chaining before locale lookup.
+
+[quick-fix] — trivial null check; entry criteria verified.
+
+Closes #NNN
+```
+
+The `[quick-fix]` marker enables grep-able audit:
+
+```bash
+git log --all --grep='\[quick-fix\]' --oneline | wc -l
+```
+
+If quick-fix ratio exceeds 30% of all `fix/` branches in a month, the
+entry criteria are too loose — re-shape.
+
+## Audit discipline
+
+Run monthly or per-iteration:
+
+```bash
+# Total fix branches in the period
+FIX_COUNT=$(git log --all --oneline --since='30 days ago' --grep='^fix:' | wc -l)
+
+# Quick-fix subset
+QF_COUNT=$(git log --all --oneline --since='30 days ago' --grep='\[quick-fix\]' | wc -l)
+
+echo "Quick-fix ratio: $QF_COUNT / $FIX_COUNT"
+```
+
+Target ratio: ≤30%. Most fixes should justify the full /diagnose
+ceremony. /quick-fix is the exception lane.
+
+If the ratio drifts high, review the entry criteria — probably too
+loose. Tighten criteria OR surface a finding that fixes are
+systematically trivial (suggesting some class of defect is
+over-represented and should be addressed architecturally).
+
+## Output format
+
+```markdown
+## /quick-fix — [short description]
+
+### Sources read
+- [issue ref or conversation context]
+- [relevant file paths]
+
+### Entry-criteria check
+- Localized? ✅
+- Obvious cause? ✅
+- Obvious fix (≤10 lines)? ✅
+- Low blast radius? ✅
+- Reproducible or trivially verifiable? ✅ ([criterion]: [reason])
+
+### Compressed diagnosis
+- Repro: [one-line OR "skipped — reason"]
+- Cause: [one sentence]
+- Fix: [one sentence]
+- Verify: [one sentence]
+
+### Fix
+[Operator writes — or for doc/config/markdown, agent writes here]
+
+### Verify evidence
+[/verify output summary]
+
+### Commit
+fix: [imperative subject]
+
+[body]
+
+[quick-fix] — [criteria holds verbatim]
+
+Closes #NNN
+```
+
+## Rules
+
+- Entry criteria are STRICT. "Four out of five" is not a pass.
+- Silence is not a skip. State explicitly which criteria hold.
+- Agent does not write the fix (except for doc/config/markdown typos).
+  Operator writes; agent guides.
+- Full /verify is mandatory. No "it's trivial, skip verify."
+- `[quick-fix]` footer is mandatory. Audit depends on it.
+- Blast-radius floors are hard floors. Auth/middleware/schema/security/
+  tenant paths force full /diagnose or /auto-fix.
+
+## Relationship to other skills
+
+| Skill | Relationship |
+|-------|-------------|
+| `/diagnose` | Quick-fix compresses /diagnose to Step 0 (repro-or-skip) + 1-line summary; full diagnose runs when entry criteria fail |
+| `/auto-fix` | Autonomous counterpart for non-trivial narrow bugs — agent writes; /quick-fix is operator-in-loop for trivial ones |
+| `/verify` | Full verify runs every time, regardless of quick-fix compression |
+| `/incident-report` | Post-merge — if a /quick-fix class of defect warrants stakeholder communication |
+
+## Common pitfalls
+
+- **Criteria creep** — "it's basically localized" / "the fix is mostly
+  obvious" is not a pass. Strict criteria or full /diagnose.
+- **Skipping /verify because "it's a typo"** — never. Typos have
+  /verify markers too.
+- **Missing [quick-fix] footer** — audit invisible. Enforce in commit
+  discipline (could be a future hook).
+- **Using for bugs that are just small rather than trivial** — small
+  fixes (5 lines) in auth middleware are NOT quick-fix; blast radius
+  disqualifies.
+
+## Why this skill exists
+
+Observed repeatedly: operators grinding through /diagnose ceremony for
+typos and missing null checks. When ceremony > bug stakes, operators
+rationalize skipping /diagnose entirely — producing the exact governance
+erosion the ceremony was meant to prevent.
+
+A compressed lane with strict entry criteria + audit marker gives the
+trivial case its own path without eroding the default. The audit
+catches drift.
+
+Closes bassclef #151. Part of fix-workflow family 2026-04-16d.
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.