diff --git a/.claude/rules/tooling-reference.md b/.claude/rules/tooling-reference.md index 59231dc..f42766e 100644 --- a/.claude/rules/tooling-reference.md +++ b/.claude/rules/tooling-reference.md @@ -90,6 +90,14 @@ Different purposes: Subagents with `memory: project` in this setup: `scout`, `triage`, `planner`, `plan-reviewer`, `adversarial`, `persona-qa`. Stages where pattern recognition across many runs helps; not enabled on `test-writer` / `test-reviewer` / `implementer` / `verifier` / `desloppifier` because those should be driven by current plan + current code, not accumulated preference. +## Operator commands + +Operator-only slash commands (`disable-model-invocation: true` — never auto-invoked) that sit on top of the pipeline. The cron `op-pipeline-orchestrator` keeps driving the pipeline forward in the background; these are the on-demand surface for operating it. + +- **`/run [--repo ] [--since ] [--stage ] [--fix-mode]`** — drives the pipeline forward across in-scope items, dispatches the right subagent per stage, classifies every touched item, writes a structured report to `~/.claude/orchestrator-log/run-.md`. `/merge` and `/unblock` consume this report shape. +- **`/merge [--risky] [--repo ]`** — read-only ranked merge queue. Reads the latest `/run` report (or derives via gh if stale), computes calibrated HIGH/MED/LOW confidence per PR, emits copy-paste merge commands. Never merges itself; the calibration is built so MED is the median outcome, not HIGH. +- **`/unblock [--section credentials|decisions|sensitivity] [--repo ]`** — surfaces every pending decision only the operator can make: missing credentials, decision conflicts against `$OP_CONTEXT_REPO`, sensitivity escalations. Every row has a specific actionable next step. Sensitivity section never leaks private content per `context-repo.md` STAGE 13. + ## Context repo `github.com/Open-Paws/context` (env var: `$OP_CONTEXT_REPO`). Single source of truth for WHY (decisions, priorities, org overview, proposals). This stack is HOW. Context repo wins conflicts. Org-wide read safety rules in `context-repo.md`. Key files inside the repo: diff --git a/claude-code/.claude/skills/unblock/SKILL.md b/claude-code/.claude/skills/unblock/SKILL.md new file mode 100644 index 0000000..673dafe --- /dev/null +++ b/claude-code/.claude/skills/unblock/SKILL.md @@ -0,0 +1,148 @@ +--- +name: unblock +description: Surfaces every pending decision that only the operator can make, with copy-paste-ready next actions. Three sections — credentials needed, decisions needed, sensitivity escalations. Reads the latest /run report (<30min) or derives directly. Every item has a specific actionable next step; if it doesn't, it doesn't belong here. Operator-only. +disable-model-invocation: true +argument-hint: "[--section credentials|decisions|sensitivity] [--repo ]" +allowed-tools: Bash(gh:*), Bash(ls:*), Bash(date:*), Bash(stat:*), Read, Grep, Glob +model: sonnet +--- + +# /unblock — operator decisions queue + +Surfaces only items that need the operator. Filters out everything else. If `/unblock` lists something, the operator has a specific action to take — not "wait", not "rerun later". + +`/unblock` does NOT apply override labels. Does NOT close PRs. Does NOT merge. It surfaces; the operator executes. + +Read these every fire (auto-load via `InstructionsLoaded`; cite by name in any followup): + +- `~/.claude/rules/context-repo.md` — **STAGE 13 confidentiality leak rule applies to the sensitivity section. Re-read before formatting any sensitivity item.** No private content goes in the report — repo+number + non-sensitive summary only. +- `~/.claude/rules/pipeline-nevers.md` — override labels are human-only; never apply them +- `~/.claude/rules/git-identity.md` — for credential references (e.g. when an item needs OpenGaryBot to gain a permission) + +## Argument parsing + +`$ARGUMENTS`: +- `--section ` — show only one of: `credentials`, `decisions`, `sensitivity` +- `--repo ` — single-repo scope (`Open-Paws/`) + +## Algorithm + +### 1. Find the input + +```bash +LATEST=$(ls -t ~/.claude/orchestrator-log/run-*.md 2>/dev/null | head -1) +``` + +If `LATEST` exists AND mtime within last 30 minutes: +- Pull `### Stopped at credential gate` rows → credentials section +- Pull `### Stopped at decision conflict` rows → decisions section +- Pull `### Stopped at human gate` rows whose reason matches `sensitivity-escalation:*` or whose label list includes `sensitivity:*` (excluding `sensitivity:public-ok`/`staff-ok`) → sensitivity section +- Also pull any `auto:requires-human` items from `### Stopped at human gate` into the appropriate section based on the `needs:` reason + +Otherwise (no recent log, or `--repo` set forcing fresh derivation): +```bash +gh issue list --repo Open-Paws/ --state open --label 'auto:requires-human' --json number,title,labels,url,body --limit 100 +gh pr list --repo Open-Paws/ --state open --label 'auto:requires-human' --json number,title,labels,url,body --limit 100 +gh issue list --repo Open-Paws/ --state open --label 'sensitivity-escalation' --json number,title,labels,url,body --limit 100 +``` + +### 2. Per-item action generation + +Every item must have a SPECIFIC actionable next step. Generic instructions are not allowed. + +**Credentials section:** +- Identify the specific missing credential from the `missing:` field. Look it up: + - GCP service account / IAM role → fix at `https://console.cloud.google.com/iam-admin/iam?project=` + - GitHub Actions secret → fix command: `gh secret set --repo Open-Paws/` + - Supabase service role key → fix at the project's Supabase dashboard (look up project ref via `mcp__claude_ai_Supabase__list_projects` if available, otherwise label as "operator looks up project ref") + - npm / PyPI / Cargo publish token → fix at the corresponding registry settings + - Vercel deploy hook / token → fix at Vercel project settings + - API key for external service (Stripe, SendGrid, etc.) → fix at the service's dashboard, with specific URL where derivable +- Count downstream items waiting on this credential — items whose `missing:` field references the same credential — and link to a `--fix-mode` filtered run report so the operator can confirm unblocking after rotation: + ``` + Confirm with: /run --fix-mode --repo + ``` + +**Decisions section:** +- Identify the conflicting decision/proposal from the `conflicts with:` field +- Resolve to one of three concrete operator actions (offer all three; operator picks): + - **a)** Update the decision/proposal: cite the decision-id (e.g. `decisions.md#sync-labels-pr-mode`) and suggest a one-line revision in the resolution column + - **b)** Close the PR/issue: provide `gh issue close / --comment ""` or `gh pr close / --comment ""` + - **c)** Apply override label: `gh pr edit / --add-label override: