/triage

description: Weekly autonomous triage of claude-usage — merge no-brainers to DEV, run tests, Codex collab, close duplicates / scope-violations, bump CHANGELOG by patch, push DEV. Leaves DEV→main release decision for the maintainer.

/triage — weekly claude-usage triage

Designed to be run **headless** via Windows Task Scheduler (`claude -p "/triage"`) once a week. Operates in the local working copy on the `DEV` branch only. **Never pushes to `main`.**

Identity & tone

• Sign every public-facing comment with `_— Claude Code & Codex collab_` on its own italicized line.
• Mention the version that ships next (the bumped patch version, e.g. `v1.1.1`) in close messages so contributors know where to look.
• Friendly, brief, honest. No emojis.
• Never dismiss a contributor's work as "wrong" when it duplicates a landed fix — they got there independently; thank them.

Hard safety rails (do not violate)

1. **Dirty-worktree guard.** Before any `checkout` / `reset` / `merge`, run `git status --porcelain`. If output is non-empty, **abort immediately** — there is local maintainer work the routine would otherwise destroy. Do not stash, do not `--force`. Exit with a self-comment (step 8) explaining why the run was skipped. 2. **Never push to `main`.** Final release is the maintainer's call. DEV gets pushed; main never does. 3. **Never close a PR or issue opened by the repo owner** (`gh repo view --json owner --jq .owner.login`). Those are intentional, not triageable. 4. **Never auto-merge a PR** that:

• touches more than 8 files, OR
• has more than 200 added lines, OR
• mentions any of these keywords in title / body / diff (security or contract-sensitive — escalate): `auth`, `password`, `credential`, `cookie`, `token`, `secret`, `api key`, `oauth`, `bearer`, `login`, `permission`, `encrypt`, `session`, `csrf`, OR
• introduces new top-level dependencies (`requirements.txt`, `pyproject.toml`, `package.json`), OR
• modifies anything under `.github/workflows/`, `scripts/`, `.claude/`, OR
• includes deletions or renames of existing files (not just additions/edits), OR
• includes a database schema change (`init_db` body, new `CREATE TABLE`, new `ALTER TABLE`).

5. **Never push DEV if `python -m unittest discover -s tests -v` fails on `main` first.** Baseline must be green before any work. 6. **Never push DEV if the final test sweep after merges fails.** Roll back, leave nothing on DEV. 7. **Stop if any external dependency is missing** (`gh`, `codex`, `python`) — exit cleanly with a noted error rather than partial state. 8. **Codex sign-off is mechanical, not advisory.** Before any `gh pr close` / `gh issue close` fires, a file at `/tmp/triage-codex-signoff.md` must exist containing (a) every item on the close list, and (b) the exact phrase `Codex sign-off: close list approved` on its own line. Codex generates this in step 2. No file → no closes. If Codex says "uncertain" on any item, that item stays open regardless. 9. **If unclear, leave it open and comment.** Don't guess. Surfacing as "needs maintainer review" is always preferable to a wrong close.

Workflow

0. Pre-flight

Examples are bash; use the PowerShell equivalents on Windows (`Get-Command codex`, `if ((git status --porcelain).Length -gt 0)`, `$env:TEMP` instead of `/tmp`, etc.). Headless Claude must translate to the host shell — never literal-run the wrong syntax.

gh auth status                                   || exit 1
command -v codex                                 || exit 1
[ -z "$(git status --porcelain)" ]               || exit 1   # SAFETY RAIL 1
git fetch origin
git checkout main && git pull --ff-only
python -m unittest discover -s tests             || exit 1   # SAFETY RAIL 5
git checkout DEV
git merge --ff-only origin/DEV                                # fast-forward to remote DEV
git merge --ff-only main                                      # bring DEV up to date with main

If either `merge --ff-only` fails (DEV diverged from origin/DEV or from main), **stop**: divergence means there's unreleased work the maintainer staged. Don't touch it. Post a self-comment (step 8) noting the routine paused.

**Never run `git reset --hard` anywhere in this workflow.** It can silently destroy local work even after the dirty-worktree check. The temp-branch pattern in step 3 makes reset unnecessary.

1. Survey

gh issue list --state open --limit 100 --json number,title,author,body,createdAt > /tmp/triage-issues.json
gh pr list   --state open --limit 100 --json number,title,author,body,additions,deletions,changedFiles,headRefName,createdAt > /tmp/triage-prs.json

2. Triage with Codex (mandatory)

Write the survey to a brief file and consult Codex. The brief must:

• List every open PR and issue with its title, author, additions/deletions, and 1-line summary.
• Propose a per-item classification: **bug-fix in scope** / **duplicate of landed fix** / **feature (out of scope per project policy)** / **support question (leave open)** / **deferred refactor (close as out of scope for routine triage)** / **needs maintainer judgment (escalate via self-comment, do not close)**.
• For each "bug-fix in scope": say whether it should be merged whole (`gh pr checkout` + `git merge --no-ff`), cherry-picked (specific commit SHA), or applied manually with co-author trailer.
• For each "duplicate": which landed PR supersedes it.

Use `~/.claude/skills/codex-ideation/scripts/codex.py --new --read <brief-file> --sandbox workspace-write`. Then iterate (`codex.py "<reaction>"`) until you and Codex agree on every line. Convergence = both of you would defend the punch list.

**Generate the sign-off artifact required by safety rail 8.** Once converged, write `/tmp/triage-codex-signoff.md` with the full close list (one item per line: `<#> — <action> — <reason>`) and the literal line `Codex sign-off: close list approved` at the end. Step 4 reads this file before each close and aborts if anything is missing or if