feat(commands): register PR control-surface action verbs in the @gittensory parser

[JSONbored]

Summary

Registers the @gittensory PR control-surface action verbs (review/re-review,
pause, resume, resolve, configuration, explain) as first-class action
commands, alongside the existing gate-override. This is the shared foundation
issues #2160, #2161, and #2162 (part of #1960) — pure parsing, a shared classifier,
and default authorization roles. No dispatch/side effects land in this PR; each
verb's handler is a separate follow-up bounty.

• feat(commands): register review/pause/resume/resolve/configuration/explain in the @gittensory action-command registry + parser #2160 — extends GITTENSORY_ACTION_COMMANDS and parseGittensoryMentionCommand
  to recognize the six new verbs, alias re-review → review, and capture the
  trailing free text as reason (gate-override-shaped verbs) or argument
  (explain, a lookup key rather than free-form prose). Unknown verbs and a bare
  mention still resolve to help, unchanged.
• feat(commands): shared PR-comment command-handler preamble helper (bot/action/missing-target skip recording) #2161 — adds classifyPrCommandRequest (src/github/pr-command-request.ts),
  a pure classifier mirroring classifyPlanCommandRequest that extracts the guard
  preamble duplicated across maybeProcessGateOverrideCommand and
  maybeProcessPlanCommand (reject a non-created comment action, a Bot/[bot]
  author, or a payload missing the repo/PR/installation/actor) into one ok/skip
  union with a stable reason per skip cause. Not wired into any handler yet —
  pure add + tests only, per the issue's scope.
• feat(commands): default command-authorization policy entries for review/pause/resume/resolve/configuration/explain #2162 — adds default commandAuthorization policy entries for all six new
  verbs. pause/resume/resolve/configuration/explain default to
  [maintainer, collaborator]; review is additionally widenable to
  confirmed_miner, mirroring the existing review-now self-rerun precedent
  (refactor(github-app): extract a shared withAuthorizedPrAction scaffold for action commands #824). All six flow through the existing MAINTAINER_ONLY_DEFAULT_COMMANDS
  clamp automatically (it derives from the policy's own keys), so a spoofable
  pr_author override is dropped with a warning the same way gate-override's is.

Necessary follow-on in this PR: since the new verbs are now recognized by the
parser, the existing Q&A mention-command handler's command.name === "gate-override"
exclusion (which kept action commands from being misrendered as a Q&A "help" card)
had to widen to cover every action command, not just gate-override. Added
isGittensoryActionCommand (in src/github/commands.ts) and used it at the one
call site in src/queue/processors.ts. Until each verb's own dispatch handler
lands, a bare @gittensory pause (etc.) is now a recognized-but-unhandled command:
it is not misrendered as help, and it is not yet actioned. A regression test
locks this in.

Scope

• The PR title follows type(scope): short summary Conventional Commit format, for example fix(api): restore profile access checks.
• This PR is focused and does not mix unrelated backend, UI, MCP, docs, dependency, and deploy changes.
• This follows CONTRIBUTING.md and does not reintroduce GitHub Pages, VitePress, site/, or CNAME.
• I linked an issue, or this is small enough that the summary explains why an issue is not needed.

Validation

• git diff --check
• npm run actionlint
• npm run typecheck
• npm run test:coverage locally; codecov/patch requires ≥99% coverage of the lines AND branches you changed (aim for 100% on your diff so CI variance does not fail near the threshold). Global coverage is a non-blocking trend with a loose 90% backstop, not the gate.
• npm run test:workers
• npm run build:mcp
• npm run test:mcp-pack
• npm run ui:openapi:check
• npm run ui:lint
• npm run ui:typecheck
• npm run ui:build
• npm audit --audit-level=moderate
• New or changed behavior has unit/integration tests for new branches, fallback paths, and sanitizer boundaries

Ran the full npm run test:ci gate locally (all steps green) plus npm audit --audit-level=moderate (0 vulnerabilities). Targeted coverage checks on the three changed src/** files (src/github/commands.ts, src/github/pr-command-request.ts, src/settings/command-authorization.ts) show 100% coverage on every changed line/branch; the two lines the v8 report still flags (commands.ts isAiCostBearingCommand, command-authorization.ts commandAuthorizationNeedsMinerDetection) are pre-existing code this diff does not touch.

Safety

• No secrets, wallet details, hotkeys, coldkeys, user PATs, private keys, raw trust scores, private rankings, or private maintainer evidence are exposed.
• Public GitHub text stays sanitized, low-noise, and does not imply compensation guarantees or optimization tactics.
• Auth, cookie, CORS, GitHub App, Cloudflare, or session changes include negative-path tests.
• API/OpenAPI/MCP behavior is updated and tested where needed.
• UI changes use live API data or real empty/error/loading states, not production mock/demo fallbacks.
• Visible UI changes include a UI Evidence section below with JPG/JPEG or PNG screenshots arranged as organized, captioned, clickable thumbnails. SVG screenshots are not used as review evidence. Review-only screenshots or recordings are not committed to the repository.
• Public docs/changelogs are updated where needed; changelogs are only edited for release-prep PRs.

No UI/frontend/docs changes in this PR (backend command-registry plumbing only), so UI Evidence is not applicable.

Notes

• Closes feat(commands): register review/pause/resume/resolve/configuration/explain in the @gittensory action-command registry + parser #2160
• Closes feat(commands): shared PR-comment command-handler preamble helper (bot/action/missing-target skip recording) #2161
• Closes feat(commands): default command-authorization policy entries for review/pause/resume/resolve/configuration/explain #2162
• Advances PR command surface — @gittensory review / pause / resume / resolve / help / configuration / explain #1960 (the parent epic) — not closed here; the per-verb dispatch handlers (feat(commands): @gittensory review / re-review command — parse + classify + dispatch to existing re-review action #2163-feat(commands): unknown-@gittensory-verb suggestion (did-you-mean) in the help fallback #2170) and docs (docs(commands): document the @gittensory PR command surface (verbs, roles, auto-review-vs-gate boundary) #2171) are separate follow-up PRs.

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 93.42%. Comparing base (ca6a6d7) to head (850cd60).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #3826   +/-   ##
=======================================
  Coverage   93.41%   93.42%           
=======================================
  Files         326      327    +1     
  Lines       32855    32872   +17     
  Branches    12035    12043    +8     
=======================================
+ Hits        30691    30710   +19     
  Misses       1530     1530           
+ Partials      634      632    -2     

Files with missing lines	Coverage Δ
src/github/commands.ts	97.91% <100.00%> (+0.23%)	⬆️
src/github/pr-command-request.ts	100.00% <100.00%> (ø)
src/queue/processors.ts	94.49% <100.00%> (+0.03%)	⬆️
src/settings/command-authorization.ts	98.75% <ø> (ø)

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[loopover-orb]

Warning

🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨🟨

⏸️ Gittensory review result - manual review recommended

_{Review updated: 2026-07-06 14:14:11 UTC}

8 files · 1 AI reviewer · 1 blocker · readiness 82/100 · CI green · clean

⏸️ Suggested Action - Manual Review

• AI reviewers agree on a likely critical defect: src/github/commands.ts: parseGittensoryMentionCommand checks ACTION_COMMANDS before COMMANDS, and this PR adds 'explain' to GITTENSORY_ACTION_COMMANDS
• if 'explain' is already a Q&A command name dispatching to explainBlockersWithAgent (strongly implied by the unchanged comment block listing explainBlockersWithAgent alongside planNextWork/preflightBranchWithAgent as orchestrator-backed mention commands), this PR silently regresses `@​gittensory explain` from a working AI answer-card into a no-op bail in maybeProcessGittensoryMentionCommand (src/queue/processors.ts:12128) since no action-command handler for 'explain' is wired yet. — Resolve the flagged defect, or override if the AI reviewers are mistaken, then re-run the gate.

Review summary
This PR extends GITTENSORY_ACTION_COMMANDS from just gate-override to six new PR control-surface verbs (review/re-review, pause, resume, resolve, configuration, explain), adds a re-review alias, splits trailing text into reason vs argument (explain), adds a pure classifyPrCommandRequest helper (unwired), and wires default authorization roles. The parsing/aliasing/argument-vs-reason logic is correctly implemented and well tested. The most notable risk is that 'explain' is very likely already an existing Q&A mention-command wired to explainBlockersWithAgent (per the unchanged comment in commands.ts referencing 'planNextWork / explainBlockersWithAgent / preflightBranchWithAgent ... in buildMentionCommandBundle'), and since parseGittensoryMentionCommand now checks ACTION_COMMANDS before COMMANDS, registering 'explain' as an action command with no dispatch handler yet would silently swallow the previously-working `@​gittensory explain` Q&A flow.

Blockers

• src/github/commands.ts: parseGittensoryMentionCommand checks ACTION_COMMANDS before COMMANDS, and this PR adds 'explain' to GITTENSORY_ACTION_COMMANDS; if 'explain' is already a Q&A command name dispatching to explainBlockersWithAgent (strongly implied by the unchanged comment block listing explainBlockersWithAgent alongside planNextWork/preflightBranchWithAgent as orchestrator-backed mention commands), this PR silently regresses `@​gittensory explain` from a working AI answer-card into a no-op bail in maybeProcessGittensoryMentionCommand (src/queue/processors.ts:12128) since no action-command handler for 'explain' is wired yet.

Nits — 6 non-blocking

• The external scan flags test/unit/queue.test.ts:21591 as a possible secret, but it's just a mocked `{ token: "installation-token" }` fetch response in a test stub, not a real credential — verify and suppress the false positive rather than rotating anything.
• codecov/patch failed at 95.65% vs the 99% target; worth checking which branch is uncovered (e.g. the bot_author regex arm or an alias-miss path) even though it's advisory here.
• ARGUMENT_ACTION_COMMANDS is a Set with a single member ('explain'); fine for future extensibility but a plain `name === "explain"` check would be simpler today.
• The `/* v8 ignore next */` comment on the match[2] fallback in commands.ts is a reasonable noUncheckedIndexedAccess guard but slightly clutters a line that's provably always defined per the accompanying comment.
• Before merging, confirm whether 'explain' already exists as a GittensoryMentionCommandName mapped to explainBlockersWithAgent; if so, either pick a different verb name for the PR-control-surface 'explain' or explicitly retire/replace the old Q&A explain command in this same PR rather than silently shadowing it.
• PR author also opened the linked issue — Link an issue that was opened by a different contributor, or provide a rationale for why this self-authored issue represents genuine discovery work.

Concerns raised — review before merging

• src/github/commands.ts: parseGittensoryMentionCommand checks ACTION_COMMANDS before COMMANDS, and this PR adds 'explain' to GITTENSORY_ACTION_COMMANDS; if 'explain' is already a Q&A command name dispatching to explainBlockersWithAgent (strongly implied by the unchanged comment block listing explainBlockersWithAgent alongside planNextWork/preflightBranchWithAgent as orchestrator-backed mention commands), this PR silently regresses `@​gittensory explain` from a working AI answer-card into a no-op bail in maybeProcessGittensoryMentionCommand (src/queue/processors.ts:12128) since no action-command handler for 'explain' is wired yet.

Signal	Result	Evidence
Code review	❌ 1 blocker	1 reviewer
Linked issue	✅ Linked	#2160, #2161, #2162
Related work	⚠️ 3 scoped overlaps	Top overlaps are listed below; lower-confidence bulk is hidden.
Change scope	❌ 8/20	High review scope from cached public metadata (3 linked issues).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 54 registered-repo PR(s), 46 merged, 399 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 54 PR(s), 399 issue(s).
Gate result	❌ Blocking	Repo-configured hard blocker found.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: Python, TypeScript, JavaScript, Ruby, Go, Kotlin, MDX, Shell
• Official Gittensor activity: 54 PR(s), 399 issue(s).
• Related work: Titles/paths share 9 meaningful terms. (issue #2163, issue #2165)
• Related work: Titles/paths share 10 meaningful terms. (issue #2163, issue #2166)
• Related work: Titles/paths share 8 meaningful terms. (issue #2160, issue #2163)
• Additional title-only matches omitted; title-only overlap does not block.

Contributor next steps

• Treat this as maintainer-lane context rather than normal contributor-lane activity.
• Review top overlaps.
• Add a concise scope and risk note.
• Check active issues and PRs before submitting.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by Gittensory, a quiet PR intelligence layer for OSS maintainers.

• Re-run Gittensory review