feat(github-agent): add maintainer queue digest commands

[oktofeesh1]

Summary

• Adds maintainer-only GitHub mention commands for queue summaries, review-now candidates, needs-author PRs, confirmed-miner PRs, and duplicate/WIP clusters.
• Builds the digest from cached public GitHub metadata, cached check summaries, PR age, queue pressure, duplicate clusters, and cached confirmed-miner status.
• Records usage and feedback-prompt audit events while keeping public output sanitized and pointing private detail to the authenticated maintainer dashboard.

What changed

• Expanded the @gittensory command parser/catalog with maintainer digest commands.
• Enforced maintainer-only authorization before public comment writes.
• Added cached queue digest rendering with public-safe summaries and private-detail dashboard pointers.
• Added unit/webhook regression coverage for authorization, sorting, sanitizer boundaries, telemetry, and no-leak public output.

Why

• Closes feat(github-agent): add maintainer digest and queue commands #143 by giving maintainers queue-level command answers instead of only per-PR responses.

Validation

• npm run typecheck
• npm run test:unit -- test/unit/github-commands.test.ts test/unit/queue.test.ts
• npm run test:coverage
• npm run test:ci
• Codex Security diff scan: no findings; report generated and validated.

Notes

• Confirmed-miner queue status is intentionally cache-backed so queue commands do not fan out live official API calls for every open PR author.

[JSONbored]

@oktofeesh1 This needs a rebase. Current main now conflicts in test/unit/queue.test.ts.

The maintainer queue digest command shape is still useful, and CI is green on the branch, but the queue test overlap means I need to review the version that would actually land. Please rebase and rerun the full gate.

[oktofeesh1]

Rebased onto current main after #192 merged and force-pushed 47b8c61. GitHub now reports #193 as mergeable; validate, Contributor trust, and Superagent Security Scan are green.

Local validation run from the repo root:

• npm run test -- test/unit/github-commands.test.ts test/unit/queue.test.ts
• npm run test:ci

Codex Security diff scan against current main completed with no findings.

@oktofeesh1 This is ready from my side. The branch was rebased after the queue-test conflict, current checks are green, and the merge tree is clean.

A few notes:

• The maintainer queue digest command has command-parser, queue-processor, and output-shape coverage.
• The public command surface stays narrow and test-backed.
• No requested changes from me.

[dosubot]

Documentation Updates

2 document(s) were updated by changes in this PR:

For Maintainers

View Changes

@@ -336,7 +336,11 @@
 
 ### Available Commands
 
-#### `@gittensory help`
+Commands are grouped into two categories: **public commands** (available to PR authors who are confirmed Gittensor miners and to maintainers) and **maintainer-only commands** (restricted to OWNER, MEMBER, or COLLABORATOR association).
+
+#### Public Commands
+
+##### `@gittensory help`
 
 Shows the complete list of available commands with brief descriptions [[47]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/src/github/commands.ts#L135-L149).
 
@@ -346,7 +350,7 @@
 @gittensory help
 ```
 
-#### `@gittensory preflight`
+##### `@gittensory preflight`
 
 Summarizes PR hygiene and validation readiness. Shows up to 3 relevant actions from preflight analysis, including linked context, branch freshness, and validation status [[48]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/src/github/commands.ts#L165-L180).
 
@@ -356,7 +360,7 @@
 @gittensory preflight
 ```
 
-#### `@gittensory blockers`
+##### `@gittensory blockers`
 
 Lists public-safe readiness blockers that might prevent a PR from being ready for review. Shows up to 4 actions with blocker details. Useful when you need to understand exactly what is blocking a PR from moving forward [[49]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/src/github/commands.ts#L182-L197).
 
@@ -366,7 +370,7 @@
 @gittensory blockers
 ```
 
-#### `@gittensory duplicate-check`
+##### `@gittensory duplicate-check`
 
 Detects duplicate risks, work-in-progress collisions, and related overlap signals. This command helps you avoid spending review effort on potentially redundant work before diving into a detailed review [[50]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/src/github/commands.ts#L199-L228).
 
@@ -376,7 +380,7 @@
 @gittensory duplicate-check
 ```
 
-#### `@gittensory miner-context`
+##### `@gittensory miner-context`
 
 Confirms Gittensor miner status for the PR author. Shows the confirmed miner's GitHub username, total PR count in registered repos, and merged PR count [[51]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/src/github/commands.ts#L151-L163).
 
@@ -392,7 +396,7 @@
 - Registered-repo PRs observed by Gittensor: 47.
 - Merged registered-repo PRs observed by Gittensor: 23.
 
-#### `@gittensory next-action`
+##### `@gittensory next-action`
 
 Suggests the next public-safe work step, cleanup action, or monitoring recommendation. Useful for guiding a contributor toward their next move or deciding what action to take next as a maintainer [[52]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/src/github/commands.ts#L230-L250).
 
@@ -402,7 +406,7 @@
 @gittensory next-action
 ```
 
-#### `@gittensory reviewability`
+##### `@gittensory reviewability`
 
 Summarizes maintainer-friendly PR readiness without exposing private review internals. Shows PR readiness status and validation details for up to 3 actions. This command was introduced in the [command router v2](https://github.com/JSONbored/gittensory/pull/190) update [[53]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/src/github/commands.ts#L252-L267).
 
@@ -412,7 +416,7 @@
 @gittensory reviewability
 ```
 
-#### `@gittensory repo-fit`
+##### `@gittensory repo-fit`
 
 Analyzes repository fit from cached public-safe signals. Shows the target repository and fit assessment for up to 4 actions. Introduced in [command router v2](https://github.com/JSONbored/gittensory/pull/190) [[54]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/src/github/commands.ts#L269-L284).
 
@@ -422,7 +426,7 @@
 @gittensory repo-fit
 ```
 
-#### `@gittensory packet`
+##### `@gittensory packet`
 
 Prepares public-safe PR packet guidance for up to 3 actions. The packet includes a structured document with summary, linked context, branch freshness, GitHub status, overlap/WIP checks, changed paths, validation, and next steps. Introduced in [command router v2](https://github.com/JSONbored/gittensory/pull/190) [[55]](https://github.com/JSONbored/gittensory/blob/1e7506f4c5226d0b9b5da8fcd219309d84bacfcd/src/github/commands.ts#L286-L301).
 
@@ -433,6 +437,92 @@
 ```
 @gittensory packet
 ```
+
+#### Maintainer-Only Commands
+
+Maintainer-only commands are restricted to users with OWNER, MEMBER, or COLLABORATOR association. These commands provide queue digest functionality from cached GitHub metadata and are designed to give maintainers queue-level intelligence without requiring agent runs.
+
+All maintainer-only commands build digests from cached public GitHub metadata, cached check summaries, PR age, queue pressure, duplicate clusters, and cached confirmed-miner status. Output is public-safe and points to the authenticated maintainer dashboard for private details.
+
+##### `@gittensory queue-summary`
+
+Posts a maintainer-only queue digest with overall statistics. Shows queue level (low, medium, high, critical), open issues, open PRs, review-now candidates, needs-author items, confirmed-miner PRs, duplicate clusters, unlinked PRs, stale PRs, and maintainer-authored PRs.
+
+**Example:**
+
+```
+@gittensory queue-summary
+```
+
+**Authorization:** Maintainer-only (OWNER, MEMBER, or COLLABORATOR association).
+
+**Data sources:** Cached GitHub issues, pull requests, recent merges, checks, PR age, and official-miner cache entries.
+
+##### `@gittensory review-now`
+
+Lists cached PRs that look ready for maintainer review. PRs in this list have linked issues, are not drafts, and don't have obvious cleanup needs blocking review. Sorted by confirmed-miner status, linked issue count, age, and PR number.
+
+**Example:**
+
+```
+@gittensory review-now
+```
+
+**Authorization:** Maintainer-only (OWNER, MEMBER, or COLLABORATOR association).
+
+**Data sources:** Cached GitHub metadata and official-miner cache.
+
+##### `@gittensory needs-author`
+
+Lists cached PRs that need author cleanup before detailed review. This includes PRs with missing linked issues, duplicate/overlap concerns, stale status (14+ days without update), draft state, or failed checks. Sorted by signal rank (duplicate/overlap > checks > missing issue > draft > stale), then by age and PR number.
+
+**Example:**
+
+```
+@gittensory needs-author
+```
+
+**Authorization:** Maintainer-only (OWNER, MEMBER, or COLLABORATOR association).
+
+**Data sources:** Cached GitHub metadata, check summaries, and official-miner cache.
+
+##### `@gittensory confirmed-miners`
+
+Lists open PRs whose authors are confirmed in the official-miner cache. Sorted by linked issue count, age, and PR number. Shows author login, linked issues, labels, age, and confirmation signals.
+
+**Example:**
+
+```
+@gittensory confirmed-miners
+```
+
+**Authorization:** Maintainer-only (OWNER, MEMBER, or COLLABORATOR association).
+
+**Data sources:** Official-miner cache and cached GitHub PR metadata.
+
+##### `@gittensory duplicate-clusters`
+
+Lists duplicate or WIP clusters visible from cached GitHub metadata. Clusters are identified by overlapping linked issues, title similarity, or term-overlap heuristics. Shows risk level (medium or high), reason, and affected items (issues, PRs, recent merges).
+
+**Example:**
+
+```
+@gittensory duplicate-clusters
+```
+
+**Authorization:** Maintainer-only (OWNER, MEMBER, or COLLABORATOR association).
+
+**Data sources:** Cached GitHub issues, PRs, and recent merged PRs.
+
+### Digest vs. Agent Commands
+
+Maintainer-only digest commands differ from public agent commands in several ways:
+
+- **No agent runs:** Digest commands build output directly from cached GitHub metadata without triggering agent orchestration.
+- **Queue-level perspective:** Public commands focus on individual PR intelligence; maintainer commands surface queue-level patterns and prioritization.
+- **Authorization enforcement:** Maintainer commands check association before execution and deny non-maintainers silently.
+- **Cached data sources:** Digest commands use cached GitHub metadata, check summaries, PR age, and official-miner cache to avoid live API fan-out for every open PR author.
+- **Public-safe output:** Like all GitHub comment output, maintainer digest responses pass through the sanitizer and never expose wallet, hotkey, payout, or private scoring terms.
 
 ### Privacy Guarantee
 

Gittensory Architecture

View Changes

@@ -80,7 +80,7 @@
 - `backfill.ts`: Syncs repos, issues, and PRs from GitHub's REST API
 - `webhook.ts`: Handles incoming GitHub webhook events
 - `app.ts`: Manages GitHub App installation and token generation
-- `commands.ts`: Parses @gittensory mention commands (help, preflight, blockers, duplicate-check, miner-context, next-action, reviewability, repo-fit, packet) [[25]](https://github.com/JSONbored/gittensory/pull/190)
+- `commands.ts`: Parses @gittensory mention commands (help, preflight, blockers, duplicate-check, miner-context, next-action, reviewability, repo-fit, packet, queue-summary, review-now, needs-author, confirmed-miners, duplicate-clusters). The last five commands are maintainer-only queue digest commands that build from cached GitHub metadata rather than agent runs [[25]](https://github.com/JSONbored/gittensory/pull/190)
 - `comments.ts`: Posts public-safe intelligence comments to PRs/issues
 - `labels.ts`: Applies Gittensor labels based on repository settings
 - `public.ts`: Fetches public GitHub user profiles

^{How did I do? Any feedback?}