diff --git a/MEMORY.md b/MEMORY.md index 25889c0..595e10a 100644 --- a/MEMORY.md +++ b/MEMORY.md @@ -16,6 +16,8 @@ - [extract-transcripts](memory/script-extract-transcripts.md) — Manages transcript backup tracking: register, list, extract, mark-processed. Used by /log and pre-compact hook - [explore-minimax-run](memory/script-explore-minimax-run.md) — Hardened read-only MiniMax exploration wrapper: root scoping, secrets refusal, JSON answer channel, citation gate (lives in small-scripts) - [list-transcripts-here](memory/script-list-transcripts-here.md) — Wrapper calling extract-transcripts.py --list $(pwd); exists to avoid $() in SKILL.md bang commands +- [review-minimax-run](memory/script-review-minimax-run.md) — Hardened wrapper: first-pass branch review in a MiniMax M3 sub-session, findings file + result gate (lives in small-scripts) +- [ci-triage-minimax-run](memory/script-ci-triage-minimax-run.md) — Hardened wrapper: gac log fetch + redaction + MiniMax CI failure triage file (lives in small-scripts) ## Skills @@ -35,6 +37,8 @@ - [/ask-minimax](memory/skill-ask-minimax.md) — Delegate file-heavy tasks to a MiniMax M3 sub-session; only a concise result returns - [/ask-minimax-with-context](memory/skill-ask-minimax-with-context.md) — Bundle CONTEXT/CLAUDE.md hierarchy via shell redirects, then ask MiniMax a one-line question - [/spawn-session](memory/skill-spawn-session.md) — Spawn a new detached tmux Claude Code session with Remote Control, named after a project (wraps claude-tmux) +- [/review-minimax](memory/skill-review-minimax.md) — First-pass MiniMax code review of agent branches; findings file adjudicated in-session; pre-filter before /code-review +- [/ci-triage-minimax](memory/skill-ci-triage-minimax.md) — MiniMax triage of failed Gitea Actions runs via gac; failing step + cause file; after `gac tail` exits 1 ## References diff --git a/claude/ask-minimax-usage.md b/claude/ask-minimax-usage.md index acf0f30..3d2f907 100644 --- a/claude/ask-minimax-usage.md +++ b/claude/ask-minimax-usage.md @@ -10,6 +10,8 @@ - Format conversion of large files (CSV↔JSON, XML↔YAML, etc.) - Bulk find-and-extract across many files where only the matches matter - Broad read-only codebase exploration ("where does X live", "how is Y wired up") — use the specialised `/explore-minimax` skill, which enforces read-only, requires `file:line` citations, and falls back to the Explore agent on failure +- First-pass code review of agent-produced branches — use the specialised `/review-minimax` skill (findings file, credential gates, adjudicated in-session; pre-filter before `/code-review`, never final authority) +- CI failure triage of failed Gitea Actions runs — use the specialised `/ci-triage-minimax` skill (gac log fetch + redaction; failing step/cause file; canonical after `gac tail --until run-complete` exits 1) ## Skip it for diff --git a/memory/script-ci-triage-minimax-run.md b/memory/script-ci-triage-minimax-run.md new file mode 100644 index 0000000..c2d11a3 --- /dev/null +++ b/memory/script-ci-triage-minimax-run.md @@ -0,0 +1,23 @@ +# ci-triage-minimax-run + +## Quick reference + +``` +ci-triage-minimax-run --repo --run [--job ] + [--out ] [--tail 2000] [--max-turns 25] [--timeout 300] [--dryrun|-n] +``` + +Exit: 0 triage written · 1 usage/gac-usage · 2 gac auth-API-notfound / MiniMax failed / timeout · 3 gate failure. Spec: `small-scripts/specs/ci-triage-minimax-run.spec.md`. + +## How it works + +Fetches `gac inspect --run --logs --json --tail ` (token discovery entirely inside gac) into a scratch dir; redacts credential patterns in place; extracts `failed_step`/`sliced` from the NDJSON envelope to steer the prompt (null → contract demands literal `UNKNOWN`); runs the same locked-down `ask-minimax-run` shape as review-minimax-run (no Bash/Edit, Write for the triage file only); gates on `## Failing step` present + non-blank `## Probable cause`; retry-once semantics, rc 124 never retried. The gac fetch happens once and is reused across both attempts. + +Test seams: `CI_TRIAGE_FAKE_LOGS` (bypass gac), `CI_TRIAGE_FAKE_JSON` (canned envelope), `CI_TRIAGE_FAKE_TRIAGE` (plays the Write) — `tests/test-ci-triage-minimax-run.sh` covers exits 0/1/2/3 and the null-failed_step path offline. + +## Gotchas + +- gac exit mapping is deliberate: 2→1 (fix invocation), 3→2 (transient-capable — auth, API, run-not-found) so callers retry/fall back instead of giving up. +- Redaction is sed-in-place on the NDJSON; patterns stop at quotes/whitespace so the JSON stays parseable. +- Dryrun runs *before* any fetch — it shows the gac command it would run, with a `` placeholder. +- gac v0.0.2.10 does NOT auto-discover the secrets-path token (despite the root CLAUDE.md description); the wrapper exports `GITEA_TOKEN_FILE=~/dev/claude/secrets/gitea/ai_admin/token` (path only) when no token env is set. Note the secret is `ai_admin/token`, a file inside a directory — pointing GITEA_TOKEN_FILE at the directory errors. diff --git a/memory/script-review-minimax-run.md b/memory/script-review-minimax-run.md new file mode 100644 index 0000000..cc7c89e --- /dev/null +++ b/memory/script-review-minimax-run.md @@ -0,0 +1,23 @@ +# review-minimax-run + +## Quick reference + +``` +review-minimax-run --worktree [--base main] [--out ] + [--profile agent-runtimes] [--max-diff-lines 6000] [--max-turns 40] + [--timeout 540] [--dryrun|-n] +``` + +Exit: 0 findings written · 1 usage/secrets/credential-diff/empty/oversize · 2 MiniMax failed / timeout / dirtied tree · 3 gate failure. Spec: `small-scripts/specs/review-minimax-run.spec.md`. + +## How it works + +Materialises `git diff base...HEAD` (secret-excluding pathspecs) + log + stat into a scratch dir; runs `ask-minimax-run --model "MiniMax-M3[1m]" --permission-mode default --allowedTools "Read,Glob,Grep,Write" --disallowedTools "…,Bash,…"` from that dir with `--add-dir` for worktree (context reads) and out-dir; gates the findings file (severity block + resolvable citation, or `NO FINDINGS`); asserts the worktree is still clean; one retry with the out-file removed first (catches the exit-0-no-file MiniMax mode); never retries rc 124. + +Test seams: `REVIEW_MINIMAX_FAKE_JSON` (canned envelope) + `REVIEW_MINIMAX_FAKE_FINDINGS` (plays the sub-session's Write) — gates still run, so tests cover exits 0/2/3 offline (`tests/test-review-minimax-run.sh`). + +## Gotchas + +- Credential-shaped diff content is a hard abort (exit 1), not a redaction — a credential in a branch diff is itself a finding for in-session review. +- The citation gate requires a `Location:` path that resolves against the worktree; a bare `:NNN` (timestamps, counters) is not accepted. +- Telemetry line on stderr reports `contextWindow` — should read 1000000; 200k means the `[1m]` pin or provider.env override is broken. diff --git a/memory/skill-ci-triage-minimax.md b/memory/skill-ci-triage-minimax.md new file mode 100644 index 0000000..6c9cfc4 --- /dev/null +++ b/memory/skill-ci-triage-minimax.md @@ -0,0 +1,33 @@ +# /ci-triage-minimax Skill + +**Purpose:** Delegate triage of a failing Gitea Actions run to a MiniMax M3 sub-session: logs fetched via `gitea-agent-companion`, analysed in MiniMax, and a short triage file (failing step, error excerpt, probable cause, suggested action, confidence) returns. Classic payload-dwarfs-answer offload. Canonical placement: after `gac tail --until run-complete` exits 1. + +**Location:** `custom-claude-skills/skills/ci-triage-minimax/` — thin wrapper over `ci-triage-minimax-run` (small-scripts), which owns all mechanics. + +## Usage + +`/ci-triage-minimax owner/repo [run-number] [job]` → the skill picks the newest `failure` row from `gac inspect owner/repo` if no run number, then runs: + +``` +ci-triage-minimax-run --repo owner/repo --run [--job ] +``` + +Triage lands in `${XDG_RUNTIME_DIR:-/tmp}/ci-triage-minimax/-/run--triage.md`. + +## Key design points + +- **Token boundary stays inside gac** (env → token file → secrets path); the wrapper never reads or passes the Gitea token. Logs are **redacted** (credential patterns → `[REDACTED]`) before reaching MiniMax — CI logs carry unmasked clone URLs. +- **gac's `failed_step` steers the prompt:** when non-null MiniMax analyses *why*, not *which*; when null the contract requires the literal `UNKNOWN` — no fabricated step names. +- **gac exit mapping:** gac 2 (usage) → 1, gac 3 (auth/API/not-found, often transient) → 2, so the skill's retry/fallback logic fires correctly. +- **Exit contract** 0/1/2/3; fallback on 2/3 = `gac inspect --logs` directly, triage in-session. +- **`## Suggested next action` is advisory only** — the operator re-derives commands, never copy-runs third-party model output shaped by anyone who can trigger CI. + +## Which modes use it + +Any mode doing post-push CI watching (`gac tail` pattern in root CLAUDE.md). Related: [[script-ci-triage-minimax-run]], [[skill-review-minimax]], [[skill-ask-minimax]]. + +## Gotchas + +- The run number is the web-UI number, not the API id; gac resolves it within its `--limit` window — very old runs may report not-found (exit 2 here). +- Multi-job runs with no failed job need `--job` (gac CLI-17); the skill passes the third argument through. +- Run-picking (newest failure) is done by the skill reading gac's human table — deliberately not automated in the script (unversioned parse). diff --git a/memory/skill-review-minimax.md b/memory/skill-review-minimax.md new file mode 100644 index 0000000..3b161a2 --- /dev/null +++ b/memory/skill-review-minimax.md @@ -0,0 +1,33 @@ +# /review-minimax Skill + +**Purpose:** Delegate a first-pass code review of a git branch (agent-produced worktrees from mm-worktree-task, ralph, container agents) to a MiniMax M3 sub-session. The diff and context reads cost MiniMax tokens; only a findings file returns, which the operator adjudicates. A pre-filter before `/code-review` or an in-session review — never the final authority. + +**Location:** `custom-claude-skills/skills/review-minimax/` — thin wrapper over `review-minimax-run` (small-scripts), which owns all mechanics. + +## Usage + +`/review-minimax [--profile agent-runtimes]` → runs: + +``` +review-minimax-run --worktree [--base main] [--profile agent-runtimes] +``` + +Findings land in `${XDG_RUNTIME_DIR:-/tmp}/review-minimax//-findings.md`. + +## Key design points + +- **The wrapper materialises the diff itself** (`base...HEAD`, three-dot, with `:(exclude)` pathspecs for secrets/keys); the sub-session gets `Read,Glob,Grep,Write` only — no Bash, no Edit — so it can't run git, inherit the wrong branch, or modify the tree. A post-run `git status --porcelain` assertion catches any unexpected write (exit 2). +- **Credential gate:** a diff matching credential patterns (`ghp_`, `AKIA…`, private-key headers, `x-access-token:` …) aborts with exit 1 — review in-session instead. +- **Result gate:** findings need a `### [BLOCKER|SHOULD-FIX|NIT]` block plus at least one citation resolving against the worktree, or the literal `NO FINDINGS`; otherwise exit 3. +- **Checklist is explicit patterns** (llm-code-security §10/§12 distilled), not "find problems" — MiniMax reasoning-loops on open-ended analysis. The 5 recurring MiniMax test-file bugs load only under `--profile agent-runtimes`. +- **Exit contract** 0/1/2/3 mirrors explore-minimax-run; fallback on 2/3 is a Claude Sonnet subagent review. +- **Adjudication is mandatory:** findings are untrusted data; spot-check 1–2 citations; `NO FINDINGS` does not certify the branch. + +## Which modes use it + +`deep`/`deep-fable` post-agent-merge review, `orch` for reviewing container-agent branches before merge. Related: [[script-review-minimax-run]], [[skill-explore-minimax]], [[skill-ci-triage-minimax]]. + +## Gotchas + +- Synchronous with a 540s internal timeout (harness Bash 600s cap) — the diff budget (`--max-diff-lines`, default 6000) keeps runs inside that; oversize diffs exit 1 rather than half-review. +- `Write` must stay in the sub-session allowlist: without it MiniMax exits 0 and the findings file silently never appears (gotchas-minimax).