For Maintainers#

What Maintainers Get#

Gittensory helps maintainers review Gittensor-driven PRs with less noise. Instead of wading through a flood of contributions with no context on who the contributor is or whether the PR is ready for review, maintainers see structured intelligence pre-surfaced on each PR from a confirmed miner 1.

The system provides confirmed-miner context without check noise: one sticky public-safe comment and a configured label on demand, plus access to private reviewability packets through the API 1. Gittensory does not edit code, open PRs, close, merge, or label without an explicit user or maintainer-triggered flow. It is deterministic and auditable, not an autonomous PR bot 1.

Three Pillars for Maintainers#

1. PR Intelligence — Automatic sticky comment on PR threads for confirmed Gittensor miners with contributor context, hygiene signals, and duplicate/WIP risk 1.

2. Maintainer Commands — Invoke @gittensory commands on any PR to get on-demand intelligence 1.

3. Control Panel — Private reviewability packets, reviewability queue, installation health, and settings preview at /app/maintainer 2 1.

Quiet by Default#

The GitHub App is quiet by default: no automatic public output until configured 3. Once installed, there are no public check runs, no comments, no labels — you control what gets published and when. Every output surface is opt-in.

Why This Matters#

Open source maintainers often face a high volume of PRs with varying quality and readiness. Gittensor-driven contributions compound this challenge by introducing mining incentives that can lead to premature submissions, duplicate work, and incomplete context. Gittensory addresses this by surfacing structured intelligence at the PR level:

• Contributor identity: Know which PRs come from official Gittensor miners versus outside contributors.
• Review readiness: See hygiene signals, duplicate risk, and validation status before investing time in review.
• Private context: Access detailed reviewability scoring and advisory findings through the control panel without polluting the public PR thread.
• On-demand intelligence: Invoke @gittensory commands to get specific answers about any PR, from preflight checks to duplicate analysis.

The system respects your workflow. It does not force check runs, comments, or labels on you. It waits until you explicitly enable each output channel 1. This quiet-by-default posture ensures Gittensory fits into your existing review process without adding noise.

GitHub App Integration#

The Gittensory GitHub App is the installation point for all maintainer-facing features. It connects your repository to Gittensory's signals engine, enables PR intelligence comments, and powers the @gittensory command interface.

Installation#

1. Navigate to the Gittensory GitHub App listing.
2. Select the repositories to grant access.
3. Approve the requested permissions:
   • Metadata: read 4
   • Pull requests: read 4
   • Issues: write 4
4. Optional permission: Checks: write — only required when check runs are enabled in repo settings 5

The app subscribes to four required webhook events: issues, issue_comment, pull_request, and repository 6.

Post-Installation Behavior#

After installation, Gittensory is quiet by default. No public checks, no comments, no labels are created automatically 3. The app listens to webhook events but does not produce any public output until explicitly configured.

Webhook events are queued for asynchronous processing 7. Each event is verified using an x-hub-signature-256 HMAC signature before processing 8.

Installation Health#

Installation health is available in the control panel at /app/maintainer 2. The system shows per-installation status: healthy, needs_attention, or broken 9.

Health checks verify:

• Required permissions are granted
• Required webhook events are subscribed
• Installation metadata is current

When permissions or events are missing, use the new installation repair diagnostics endpoints to diagnose and resolve configuration issues systematically 10.

Installation Repair Diagnostics#

The installation repair endpoints provide comprehensive diagnostics for GitHub App configuration issues, including mode-specific impact analysis and structured repair steps.

GET /v1/installations/{id}/repair — Returns detailed diagnostics for the installation:

• Current installation health — Status (healthy, needs_attention, broken), missing permissions, missing events, and installed repository count.
• Installed repositories — List of repositories with their settings (publicSurface, commentMode, checkRunMode, autoLabelEnabled).
• Required and optional permissions — Permission map showing which permissions are required given the current configuration. For example, if check run mode is enabled for any repo, Checks: write moves from optional to required.
• Required and optional webhook events — Event lists showing which webhook subscriptions are needed.
• Mode-specific impact analysis — For each mode (comment, label, check_run):
  • Whether the mode is enabled across installed repos
  • How many repos use the mode
  • Which permissions the mode requires
  • Whether those permissions are missing
  • Actionable guidance for resolving missing permissions
• Event diagnostics — For each webhook event:
  • Whether the event subscription is missing
  • Whether the event is optional or required
  • Summary explaining why the event is needed
  • Action guidance for subscribing to missing events
• Repair steps — Structured list of steps tailored to the current health status:
  1. Update the GitHub App permissions and subscribed events listed in diagnostics.
  2. Approve the changed permissions or reinstall the app on the target account.
  3. Run POST /v1/installations/{id}/repair/refresh after GitHub applies the changes.
  4. Recheck GET /v1/installations/{id}/repair.

POST /v1/installations/{id}/repair/refresh — Refreshes the installation health by rechecking live GitHub App metadata:

• Calls the GitHub API to fetch the latest installation permissions and webhook events.
• Updates the local installation health record.
• Returns the same diagnostics structure as the GET endpoint with a refreshed: true flag.
• Use this endpoint after updating GitHub App permissions or webhook subscriptions to verify that the changes have been applied and the installation is now healthy.

The diagnostics are mode-aware: if you enable check run mode for any installed repository, the repair diagnostics will show Checks: write as a required permission rather than optional. Similarly, if comment or label modes are enabled, Issues: write is required. This mode-specific logic helps maintainers understand exactly why certain permissions are needed and which repos are driving those requirements.

If the installation is healthy, the repair steps simply show "No repair needed."

Fallback remediation steps:

If the repair endpoints are unavailable, follow these manual steps:

1. Update the GitHub App permissions and subscribed events.
2. Approve the changed permissions or reinstall the app on the target account.
3. Run refresh-installation-health after GitHub sends the updated installation payload.
4. Recheck /v1/readiness and the installation health endpoint.

Settings Preview#

The settings preview endpoint allows maintainers to dry-run what Gittensory would do for a sample PR without mutating GitHub 11:

POST /v1/repos/:owner/:repo/settings-preview

This endpoint returns:

• Current repo settings
• Installation health status
• Missing permissions or events
• Remediation guidance
• Dry-run decision (skip, comment, label, or check run)
• Preview label and check-run state
• Sanitized public comment preview
• installPreview: A maintainer trust checklist covering permissions, public outputs, private context, command authorization, audit behavior, sanitizer boundaries, and manual controls

Install Preview Checklist#

The installPreview field provides a comprehensive pre-enablement checklist for maintainers. It includes:

Overall status: ready, needs_attention, or blocked

Summary: Human-readable install readiness summary

Read scope: What data is accessed from the cached repository

Computed context: What context is computed for the preview

Preview behavior: Notes about the read-only nature of the preview

Permissions: Nested object containing:

• status: Permission readiness status (ready, needs_attention, blocked)
• required: List of required permissions for the previewed behavior
• missing: List of missing permissions
• missingEvents: List of missing webhook events
• summary: Permission status summary

Public outputs: Array describing what will be publicly visible (e.g., "One sanitized sticky PR comment", "Configured label "gittensor"", "Minimal GitHub check run")

Private-only context: Array of data that remains authenticated-only (decision packs, blocker details, maintainer packet evidence, scoring evidence)

Command authorization: Array describing authorization rules for commands (maintainer-only, confirmed PR author, private API access)

Audit behavior: Array describing audit logging behavior (read-only preview, webhook skip logging, command handling logs)

Sanitizer boundaries: Array describing what content gets sanitized (public comments, credential/key material, compensation estimates, trust metrics, score-prediction claims, private review evidence, gaming language)

Manual controls: Array of settings that remain under maintainer control (public surface mode, comment mode, label name, check-run mode, maintainer-author inclusion, linked-issue requirements)

Checklist: Array of checklist items, each containing:

• id: Unique identifier
• category: One of permissions, public_outputs, private_context, command_authorization, audit, sanitizer, manual_control
• status: Item status (ready, needs_attention, blocked)
• label: Display label
• summary: Description of the item
• action: What the maintainer should do

The checklist covers seven key areas that maintainers should review before enabling repo commands:

1. Permissions and webhook events — Verifies required GitHub App permissions and webhook event subscriptions are in place
2. Public outputs — Shows what will be posted publicly (comments, labels, check runs) and warns if all-PR mode is enabled
3. Private-only context — Confirms that decision packs, blocker details, maintainer packet evidence, and scoring evidence stay authenticated-only
4. Command authorization — Describes who can invoke commands (maintainer-only commands, confirmed PR author commands, private API commands)
5. Audit behavior — Clarifies that the preview is read-only and explains what gets logged in production
6. Sanitizer boundaries — Ensures maintainers understand what content gets sanitized before public posting
7. Manual controls — Lists the repo settings that remain under maintainer control

This information helps maintainers understand what will happen when they enable Gittensory for their repository, particularly around security, privacy, and permission requirements.

Repository Configuration Options#

Settings are stored in the repositorySettings table 12 and control how Gittensory behaves per repository 13:

The default label is "gittensor" with description "Gittensor contributor context" 14.

Maintainer Focus Manifest#

Maintainers can create a .gittensory.json file (or .github/gittensory.json) in their repository to declare wanted paths, blocked paths, preferred labels, linked-issue policy, test expectations, issue-discovery policy, and maintainer notes. This focus manifest allows maintainers to signal their preferences to contributors before they open a PR.

Supported Fields#

• wantedPaths (string array) — Path patterns for changes the maintainer wants to see. Supports exact paths, directory prefixes (e.g., src/), and wildcards (e.g., docs/**).
• blockedPaths (string array) — Path patterns for areas the maintainer wants contributors to avoid. Matched paths trigger critical severity findings in preflight checks.
• preferredLabels (string array) — Labels the maintainer prefers on PRs for triage alignment.
• linkedIssuePolicy (string: "required", "preferred", or "optional") — Whether PRs must link to a tracked issue.
• testExpectations (string array) — Free-form guidance on what test evidence the maintainer expects (e.g., "Run npm test locally before opening a PR").
• issueDiscoveryPolicy (string: "encouraged", "neutral", or "discouraged") — Whether the maintainer welcomes new issue-discovery reports or prefers direct fixes.
• maintainerNotes (string array) — Private review context for maintainers. Can be defined in the manifest configuration file to document internal review context, but is explicitly omitted from guidance objects returned to contributors and is never persisted in snapshots. This field was removed from the FocusManifestGuidance response schema for security reasons to prevent leaking private maintainer context to contributors, since guidance responses are contributor-facing.
• publicNotes (string array) — Public guidance for contributors; shown in packet "Next Steps" and decision-pack recommendations after sanitization.

Example#

{
  "wantedPaths": ["src/", "test/"],
  "blockedPaths": ["config/secrets.yaml", "internal/**"],
  "preferredLabels": ["bug", "enhancement"],
  "linkedIssuePolicy": "required",
  "testExpectations": ["Run `npm test` locally", "Include test coverage for new features"],
  "issueDiscoveryPolicy": "encouraged",
  "publicNotes": ["Small, focused PRs are preferred", "Link discussion in issue thread"]
}

Parsing and Defaults#

The manifest uses tolerant parsing with safe defaults. Malformed config degrades gracefully with warnings instead of crashing analysis. Missing or invalid fields fall back to deterministic defaults:

• Missing manifest or empty config → present: false
• Invalid JSON → warning logged, empty manifest returned
• Invalid field type → field ignored, warning logged
• Unrecognized policy value → falls back to safe default

All public notes are sanitized to remove forbidden terms (wallet, hotkey, reward, payout, etc.) before appearing in packets or decision-pack guidance.

How It Works#

When a contributor prepares a PR packet or runs a local branch analysis, Gittensory:

1. Loads the manifest from the repo file (.gittensory.json or .github/gittensory.json) or a cached snapshot.
2. Matches the contributor's changed paths against wantedPaths and blockedPaths patterns.
3. Checks labels against preferredLabels.
4. Evaluates linked issues, test evidence, and validation results against manifest policies.
5. Generates findings with severity levels (info, warning, critical) and actionable guidance.
6. Adds a "Maintainer Focus" section to the PR packet (when the manifest is present) with public-safe next steps.
7. Merges manifest-driven recommendations into the decision pack's per-repo guidance.

Blocked paths trigger critical severity findings that surface as branch-quality blockers, preventing contributors from opening PRs in maintainer-off-limits areas without explicit confirmation.

PR Intelligence#

Gittensory surfaces structured, public-safe contribution context directly on GitHub PR threads for confirmed Gittensor miners. This intelligence is deterministic, metadata-only, and deliberately low-noise: maintainers receive one sticky comment with a configured label by default, with private reviewability scoring available separately via the API and control panel.

Sticky Comment Mechanism#

PR intelligence is delivered through a single, sticky comment that updates in place rather than creating duplicates. The comment uses an HTML marker <!-- gittensory-pr-intelligence --> to identify itself for future updates 15. When a PR receives new activity, Gittensory refreshes the comment body in place rather than posting a new comment, keeping maintainer notification noise minimal.

The comment is only posted for contributors confirmed as official Gittensor miners via the Gittensor API 16. Non-miners, bots, and maintainers (unless includeMaintainerAuthors is enabled) receive no public output.

Comment Structure#

The sticky comment follows a consistent five-section structure with the header "## Gittensory contribution context" 17. An advisory notice at the top clarifies that the content is generated from public GitHub metadata and the local Gittensory cache and does not constitute an endorsement 18.

1. Contributor Context#

This section provides maintainers with the contributor's identity and Gittensor activity profile:

• Author login — GitHub username
• Confirmed Gittensor miner status — "yes" if confirmed via the official Gittensor API, "not confirmed" otherwise 19
• Role context — Classification as outside contributor, collaborator, maintainer, or owner, plus whether this is maintainer-lane work 20
• Gittensory signal — Detection reason ("Official Gittensor API confirms this GitHub user" for confirmed miners, or "No confirmed Gittensor miner activity detected" for unconfirmed authors) 21
• Prior cached PRs/issues — Count of prior pull requests and issues from the contributor in registered repos 22
• Public profile languages — Top programming languages from the contributor's public GitHub profile 23

2. PR Hygiene#

This section summarizes the PR's structural quality:

• Linked issues — List of issue numbers the PR closes via keywords (e.g. #42, #57), "None detected" if the repo requires linked issues but none are present, or "Not required by this repo setting" if the repository has requireLinkedIssue disabled 24
• Lane context — Summary of the repository's Gittensor participation lane (direct_pr, issue_discovery, split, inactive, or unknown) with guidance appropriate to the lane 25
• Review burden — Classification as low, medium, or high based on changed file count and collision signals 26

3. Duplicate/WIP Risk#

This section alerts maintainers to potential duplicate or overlapping work:

• Collision clusters found — Count of collision clusters that include this PR or its linked issues, computed from overlapping titles, shared linked issues, or term-overlap heuristics 27
• Queue level — Repo-wide burden level (low, medium, high, critical) derived from open PR count, unlinked PRs, stale PRs, and collision signals 28

4. Maintainer Notes#

This section lists up to 5 public-safe advisory findings (or 2 if the repo's publicSignalLevel is set to "minimal"). Findings are filtered to exclude critical severity items and any text containing private scoring terms 29. If no public-safe findings are available, the section displays "No public-safe advisory findings were generated from cached metadata" 30.

Advisory findings include codes like:

• missing_linked_issue — No linked issue detected when the repo requires one
• possible_duplicate_work — Collision clusters suggest overlapping work
• missing_test_evidence — Code changes without test file evidence
• checks_need_attention — Failing or cancelled CI checks

5. Contributor Next Steps#

This section provides actionable guidance for the contributor, filtered to ensure no private scoring terms appear 31:

• Link issues or explain no-issue PRs (if requireLinkedIssue is enabled and no issues are linked)
• Check overlapping issues/PRs before review continues (if collision clusters are present)
• Address specific findings from the maintainer notes (if actions are provided)
• Maintainer-lane context notice (if the contributor is detected as a maintainer)

If no steps are generated, a default message appears: "Keep the PR focused and include validation evidence before maintainer review" 32.

Reviewability Scoring#

Gittensory computes a private reviewability score (0-100) for each PR, starting at 100 and deducting points based on noise sources 33:

• Base calculation: 100 minus (14 × noise sources count)
• Deductions:
  • −12 per collision cluster 34
  • −18 per failing check 35
  • −18 for broad diffs (≥12 files or ≥800 total changes) 36
• Bonuses:
  • +12 for existing approvals 37

The score maps to five maintainer actions 38:

1. review_now (≥75): "Reviewing now is efficient because cached signals show linked context and manageable friction."
2. needs_author (45-74): Ask the author to address concrete missing context before deep review.
3. likely_duplicate: Check for overlapping work before reviewing.
4. close_or_redirect: Non-open or stale PRs that should be redirected.
5. watch: Lower-cost monitoring until signals improve.

This private reviewability scoring is available only through the API and control panel, not in public GitHub comments 33.

Contributor Context Depth#

Gittensory builds a multi-dimensional picture of contributor history for maintainer review, sourced from the official Gittensor API when available or from cached GitHub data 39:

• Role context: Classification as outside contributor, collaborator, maintainer, or owner based on GitHub association and prior work patterns
• Outcome context: Merged PR count, closed PR rate, and open PR count specific to the repository
• Credibility signals: Derived from prior merged PRs, closed PR rate, and open PR pressure

For example, if a contributor has a 37% closed PR rate in the repo, that signals potential credibility risk 40.

Risk Signals and Flags#

Gittensory flags multiple categories of risk to help maintainers triage PRs efficiently 41:

Hygiene & Linkage:

• Missing linked issue or no-issue rationale
• Unlinked PRs (0 linked issues)
• Duplicate/WIP collision clusters

Technical & Process:

• Code changes without cached test files
• Failing or cancelled checks
• Broad diffs (≥12 files or ≥800 changes)

Contributor History:

• High closed PR rate (≥35%) in the repo
• Maintainer association (which requires separate maintainer-lane review)

Repo Queue:

• Stale PRs (14+ days without update)
• High collision clusters
• Strained or blocked contributor intake health

These signals are derived deterministically from cached GitHub metadata—no AI or subjective judgment is involved.

Maintainer Noise Report (Repo-Wide)#

At the repository level, Gittensory aggregates queue pressure into a single "noise score" (0-100) with a corresponding level: low, medium, high, or critical 42. This report is available via the control panel and includes:

• Count of unlinked PRs
• Collision cluster count
• Stale PRs (14+ days without update)
• Broad-diff patterns
• Contributor intake strain level

The noise report helps maintainers understand whether their repo is under queue pressure and should delay inviting additional Gittensor contribution flow 42.

Optional AI Layer#

Gittensory includes an optional AI rewrite layer that translates deterministic signal bundles into friendlier prose using Llama 3.1 43. This layer is disabled by default (AI_SUMMARIES_ENABLED=false, AI_PUBLIC_COMMENTS_ENABLED=false).

When enabled, the AI layer:

• Rewrites compact signal bundles into conversational text
• Falls back to deterministic templates on any error, quota exceeded, or unsafe output
• Never changes the facts—only restates them in friendlier language
• Operates on metadata-only signal bundles that deliberately exclude PR titles, bodies, diffs, and source code

The deterministic facts remain authoritative. AI output is sanitized through the same public/private boundary enforcement used for all public comments 43.

Public/Private Data Boundary#

All public GitHub output routes through a sanitizer that strips forbidden terms including wallet, hotkey, coldkey, reward, scoreability, farming, and payout 44. Private scoring context—including exact reviewability scores, reward/risk projections, and detailed credibility breakdowns—remains accessible only via the API and control panel with session authentication 29.

The public sticky comment provides enough context for maintainers to triage effectively without exposing private contributor scoring data.

Maintainer Commands#

Maintainers can interact with Gittensory directly in GitHub PR and issue threads by mentioning @gittensory with a command. These commands provide public-safe intelligence about PRs, contributors, and repository fit without exposing private scoring internals.

Command Response Preview API#

Before posting commands publicly on PR threads, maintainers can preview what Gittensory would respond using the protected /v1/app/commands/preview endpoint. This allows dry-running command responses to test output before comments, labels, or checks are posted to GitHub.

Access control:

• Protected endpoint requiring maintainer, owner, or operator role
• Repository-scoped access checks: users can only preview commands for repositories they have access to
• Operators can preview for any repository

Request:

POST /v1/app/commands/preview

Request body:

• command — The command to preview (e.g., "preflight", "help", "queue-summary")
• repoFullName — Target repository (e.g., "entrius/allways-ui")
• pullNumber — Target pull request number
• login — Optional user login for context
• sample — Optional sample context to simulate different scenarios:
  • authorLogin — Simulate a specific PR author
  • authorType — "User" or "Bot"
  • authorAssociation — Simulated author association (OWNER, MEMBER, COLLABORATOR, CONTRIBUTOR, NONE)
  • commenterLogin — Simulate a specific commenter
  • commenterAssociation — Simulated commenter association
  • minerStatus — "confirmed", "not_found", or "unavailable"
  • title, body, labels, linkedIssues — Simulated PR metadata
  • permissions — Simulated GitHub App permission map
  • missingPermissions — Array of missing permissions to simulate

Response:

The API returns a CommandPreviewResponse with:

• Sanitized response body — The exact comment text that would be posted to GitHub, with all forbidden terms (wallet, hotkey, payout, reward, farming, scoreability) removed
• Decision information:
  • status — "ready", "skipped", "missing_permission", or "private_api"
  • willComment, willLabel, willCheckRun — Boolean flags indicating what Gittensory would do
  • skipReason — Why the command would be skipped (if applicable)
  • actions — Array of actions: "comment", "label", "check_run", "skip", or "none"
  • summary — Human-readable decision summary
• Missing permissions diagnostics — List of missing GitHub App permissions that would block the command, with specific remediation actions
• Sample context used — Confirmation of the author, commenter, associations, miner status, PR details, and permissions used to generate the preview
• Sanitizer diagnostics — Shows if any forbidden terms were detected in the response body

What can be previewed:

All @gittensory mention commands including:

• Public commands: help, preflight, blockers, duplicate-check, miner-context, next-action, reviewability, repo-fit, packet
• Maintainer-only commands: queue-summary, review-now, needs-author, confirmed-miners, duplicate-clusters
• The public-summary command (simplified version of help)

What is NOT previewed:

Private API commands such as plan-next-work, preflight-branch, prepare-pr-packet show a simplified "private API preview only" response indicating the endpoint that would be called, with no GitHub comment, label, or check run.

Preview guarantees:

• No GitHub state is mutated: previews never post comments, create labels, update check runs, or call GitHub APIs
• Responses are sanitized using the same public/private boundary enforcement as live commands
• Missing GitHub App permissions are detected and reported before the preview is generated
• Authorization checks are enforced: maintainer-only commands require maintainer associations in the sample context
• Repo access scope is validated: users cannot preview commands for repositories they don't have access to (unless they have operator role)

Use cases:

• Test command responses before they're posted publicly on pull requests
• Verify output text for maintainer-only digest commands before invoking them in PR threads
• Simulate different contributor scenarios (confirmed miner vs. non-miner, maintainer vs. outside contributor) to understand how Gittensory would respond
• Debug missing permissions or authorization issues before live invocation
• Validate that forbidden terms are properly sanitized from responses

How Commands Work#

Comment @gittensory <command> on any PR or issue thread in an installed repository 45. Commands are case-insensitive and parsed using the pattern /(?:^|\s)@gittensory(?:\s+([a-z-]+))?/i. If no command is specified or an unknown command is provided, the system defaults to the help command.

All commands were centralized and standardized in PR #190: feat(github-agent): complete command router v2.

Authorization#

Command access is role-based 46:

• Maintainers (OWNER, MEMBER, or COLLABORATOR): Full access to all commands, no additional checks required
• PR authors: Access granted only if they are confirmed official Gittensor miners
• Bots: Silently skipped
• Non-PR threads from non-maintainers: Silently skipped

Available Commands#

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.

Example:

@gittensory help

@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.

Example:

@gittensory preflight

@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.

Example:

@gittensory blockers

@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.

Example:

@gittensory duplicate-check

@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.

Example:

@gittensory miner-context

Sample response:

• GitHub user alice is confirmed by the official Gittensor API.
• Registered-repo PRs observed by Gittensor: 47.
• Merged registered-repo PRs observed by Gittensor: 23.

@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.

Example:

@gittensory next-action

@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 update 53.

Example:

@gittensory reviewability

@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 54.

Example:

@gittensory repo-fit

@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 55.

The response includes an explicit disclaimer: "Use this as public PR-thread guidance only; keep private scorer context in MCP or the control panel."

Example:

@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#

All command responses pass through sanitizePublicComment() 44 which strips sensitive terms including:

• Wallet, hotkey, coldkey, seed phrase, mnemonic
• Public score estimates, reward estimates, payout, farming, scoreability
• Private reviewability and private ranking terms

Private scoring context is never exposed in public PR threads. All financial and scoring language is filtered before any response is posted 56.

Usage Telemetry#

Commands are tracked using privacy-safe telemetry. Actor IDs are hashed with SHA-256, and only the command name, role (maintainer/author/none), and outcome (replied/skipped/error) are stored 57 58.

Repo Configuration Quality#

Gittensory evaluates every registered repository's setup for Gittensor compatibility using a config-quality signal. This signal determines whether a repository is correctly configured to participate in contribution mining and helps maintainers identify setup problems before they penalize contributor intake health.

What It Is#

The config-quality signal is one of eight signal types generated every six hours during scheduled signal snapshot generation 1. It is computed by the buildConfigQuality() function in the signals engine 59. The function takes a repository record, cached issues, cached pull requests, and the repo's full name as inputs, then evaluates four aspects of the repository's setup.

Four Aspects Evaluated#

1. Registry Lane Status#

Gittensory checks whether the repository is registered with an active Gittensor allocation 60:

• Unknown status — If buildLaneAdvice() returns a lane of "unknown", the config loses 45 points. This happens when the repository is not registered or registry data is unavailable in the local cache. The finding code is registry_unknown with severity "warning" and the title "Registry config is unavailable".

• Inactive allocation — If the lane is "inactive" because the emission share is zero, the config loses 35 points. The finding code is inactive_allocation with severity "info" and the title "Repo has no active allocation".

The lane is determined by buildLaneAdvice() 61, which returns one of five values: unknown, inactive, issue_discovery, direct_pr, or split.

2. Trusted Label Pipeline#

If the repository has enabled the trusted label pipeline but no label multipliers are configured, the config loses 25 points 62. The finding code is trusted_labels_without_multipliers with severity "warning" and the title "Trusted label pipeline has no configured multipliers".

3. Label Observation vs. Configuration Gap#

Gittensory compares the labels configured in the registry with the labels actually observed in cached issues and PRs 63. If configured labels are not observed in practice, the config is penalized up to 30 points total: 8 points per unobserved label, capped at 30. The finding code is configured_labels_not_observed with severity "info", and the finding includes the specific labels not seen in practice.

4. Lane Alignment#

The overall participation lane (direct_pr, issue_discovery, split, inactive, unknown) is included in the output but does not directly deduct points beyond the penalties already covered in the registry lane status evaluation 64.

Scoring#

Config quality uses a deduction-based scoring system starting at 100 points 65:

• Base: 100
• Unknown lane: -45
• Inactive allocation: -35
• Trusted labels without multipliers: -25
• Unconfigured/unobserved labels: up to -30 (8 points each, capped at 30)

The final score is clamped between 0 and 100, then mapped to a quality level:

• excellent: 90–100
• good: 70–89
• needs_attention: 45–69
• fragile: 0–44

Output#

The buildConfigQuality() function returns a ConfigQuality object 66 with the following fields:

• repoFullName — The repository's full name
• generatedAt — ISO timestamp of generation
• score — Numeric score (0-100)
• level — Quality level: "excellent" | "good" | "needs_attention" | "fragile"
• lane — The LaneAdvice object describing the participation lane
• configuredLabels — Array of labels configured in the registry
• observedLabels — Array of labels observed in cached issues/PRs
• notObservedConfiguredLabels — Array of configured labels not observed in practice
• findings — Array of SignalFinding objects, each with code, severity, title, detail, and optional action guidance

Why It Matters#

Config quality directly impacts contributor intake health. When buildContributorIntakeHealth() computes the intake health score, it penalizes repositories based on their config quality level 67:

• Fragile config: -30 points
• Needs attention: -18 points
• Good: -6 points
• Excellent: 0 points

Fragile config quality also blocks registration readiness. Maintainer lane reports include config quality as a component to help maintainers understand whether their repository setup is healthy for Gittensor contribution mining.

How Maintainers View and Act On It#

Maintainers can view config quality through the maintainer dashboard at /app/maintainer 2. The dashboard shows installation health and settings previews. Each finding includes specific action guidance — not just a score but what to fix.

For example:

• If configured labels are not observed, the finding suggests: "Verify those labels exist and are actually used by maintainers or trusted automation."
• If the registry config is unavailable, the finding advises: "Refresh the registry snapshot or install the GitHub App so Gittensory can evaluate the repo."

Settings preview endpoints also show suggested configuration changes, allowing maintainers to dry-run adjustments before applying them.

Best Practices for Gittensor-Compatible Repos#

To maintain a healthy config quality score:

1. Ensure the repo is registered with an active Gittensor allocation — Unknown or inactive lanes immediately reduce the score to 55 or lower.
2. Configure labels and use them consistently in issues and PRs — Configured labels that are never observed in practice are a red flag.
3. If using the trusted label pipeline, define multipliers — A trusted label pipeline without multipliers loses 25 points.
4. Aim for "good" (70+) or "excellent" (90+) — This avoids penalizing contributor intake health and signals that the repo is ready for Gittensor-driven contributor flow.

Reducing Noise#

Gittensory filters Gittensor-driven contributions so maintainers only see what matters. The default posture is quiet: no public output until you configure it.

Core Design: Low-Noise by Default#

The primary principle: Gittensory produces no public output for non-Gittensor PRs. The GitHub App is a listener, not a poster, until you explicitly configure it 3. Once installed, there are no public check runs, no comments, no labels — you are in control.

The Primary Noise Gate: Miner Detection#

Only confirmed official Gittensor miners receive public output 16. This is enforced by looking up the PR author against the official Gittensor API.

Miner detection caching:

• 5-minute TTL on successful lookups 68
• 1-minute TTL when the Gittensor API is unavailable 69
• If Gittensor API is unreachable: graceful skip — no false positives posted 70

Six Skip Conditions#

The decidePublicSurface() function enforces six skip conditions 71:

1. Surface off — both public surface and check runs are disabled in repo settings
2. Missing author — PR has no resolvable author login
3. Bot author — author is a bot account
4. Maintainer author — OWNER/MEMBER/COLLABORATOR, unless includeMaintainerAuthors=true
5. Miner detection unavailable — Gittensor API unreachable
6. Not official Gittensor miner — author not confirmed via the official Gittensor API

Audit Trail#

Every quiet skip is tracked via auditPrVisibilitySkip() with a skip reason 72:

• Skip reasons: bot_author, maintainer_author, not_official_gittensor_miner, miner_detection_unavailable
• Product usage metrics record the outcome as "skipped" — allows measuring noise reduction impact

What You DON'T See (No Public Output)#

Gittensory silently skips:

• PRs from bots — GitHub bot accounts and accounts ending in [bot] are skipped
• PRs from non-Gittensor contributors — no public output for authors who are not confirmed official Gittensor miners
• PRs from maintainers/owners — OWNER/MEMBER/COLLABORATOR authors are skipped unless you explicitly opt in via includeMaintainerAuthors=true
• PRs when Gittensor API is temporarily unavailable — graceful degradation, no false positives

What You DO See (Confirmed Miners Only)#

For confirmed Gittensor miners, you see:

• One sticky intelligence comment (updates in place via HTML marker, never duplicates)
• One configured label (default: "gittensor")
• Optional check run (only if enabled in repo settings)

No noise from non-Gittensor contributors. No duplicate comments. No bot spam.

Configurable Noise Controls#

The publicSurface setting 73 controls what public output appears:

• "off" — no public output at all
• "comment_only" — sticky intelligence comment only, no label
• "label_only" — label only, no comment
• "comment_and_label" — both comment and label

Command Authorization Filtering#

@gittensory commands are also noise-filtered 74:

• Only maintainers (OWNER/MEMBER/COLLABORATOR) or confirmed miner PR authors can invoke commands
• Non-maintainer, non-miner: silently skipped (no error noise)
• Bots: silently skipped

Queue-Level Prioritization#

Gittensory provides intelligent PR prioritization:

• analyzePRQueue() ranks open PRs by review action: review_now, needs_author, likely_duplicate, close_or_redirect, watch 75
• Maintainer noise report aggregates repo-wide queue pressure into a single noise score (0-100) with level (low/medium/high/critical) 42

This helps maintainers focus on what's ready for review, rather than scanning every open PR.

Forbidden-Words Sanitizer#

All public output passes through sanitizePublicComment() 44:

• Prevents wallet, hotkey, payout, farming, scoreability terms from leaking into GitHub threads
• Private scoring context stays session-gated in the API/control panel

What this means: Even if an internal scoring comment accidentally included a reward term, it would never reach the public GitHub thread.

Summary: Quiet by Default, Signal When It Matters#

The default is quiet. You see nothing for non-Gittensor PRs. For confirmed Gittensor miners, you see one sticky comment and one label — no more. No bot spam. No duplicate comments. No public reward or scoring language. Maintainers only see what matters.

Public-Safe PR Packets#

A public-safe PR packet is a structured document that helps contributors draft their pull request submissions with linked context, validation evidence, and next steps already organized 76. The "public-safe" designation means all private scoring terms have been removed, source code is never transmitted, and no financial or wallet language appears in the packet 1. For maintainers, packets represent an indirect quality improvement: contributors who use them arrive with better-structured PRs, fewer common omissions, and clearer justification for their changes.

What Is a PR Packet#

A PR packet is assembled by the buildPublicSafePrPacket() function, which takes local branch metadata—changed files, validation results, linked issues, base freshness status, and GitHub check state—and produces a markdown document with nine structured sections 77. The packet includes a title suggestion derived from the branch name or commit message, and all text is sanitized using isPublicSafeText() to remove forbidden terms including reward, score, wallet, hotkey, farming, payout, and local file paths 78.

Packets are metadata-only: source code never leaves the local environment 1. Contributors supply git metadata—branch name, changed file paths, line counts, commit messages, linked issue numbers, and local validation command results—but the packet generation process operates on structured metadata, not file contents.

Nine Sections in a Packet#

Every packet contains the following sections 77:

1. Summary — Placeholder text prompting the contributor to describe the user-visible problem or maintainer-facing improvement.
2. Linked Context — Lists issues the PR closes (e.g., "Closes #42") or explains why no issue is linked.
3. Branch Freshness — Reports base branch freshness status (fresh, stale, possibly_stale, unknown), staleness warnings, and validation evidence ("3 passed commands").
4. GitHub Status — Current PR state from cached GitHub data (approved, needs author, failing checks, pending review, no PR, unknown) with notes about review decisions and mergeable state.
5. Maintainer Focus — Guidance parsed from the maintainer focus manifest (if provided), including wanted/blocked path matches, preferred labels, linked-issue policy, test expectations, issue-discovery policy, and maintainer-supplied public notes. Omitted when no focus manifest is present.
6. Overlap/WIP Check — Collision signals from cached issue and PR metadata, including possible overlap risk level and related items (e.g., "PR #101, issue #42").
7. Changed Paths — Summary of modified files with change statistics (e.g., "src/api.ts (modified, +42/-18)").
8. Validation — Results of local validation commands with pass/fail status, durations, and summaries.
9. Next Steps — Public-safe actionable recommendations, including preflight findings, base freshness advice, and rerun conditions.

Additional Metadata#

Beyond the nine sections, the packet includes metadata fields for maintainers and contributors 79:

• titleSuggestion — Derived from branch name or commit message.
• markdown — Full rendered packet in markdown format.
• bodySections — Structured array of heading/lines pairs, enabling flexible rendering.
• reviewerNotes — Lane context, review burden, and role context (e.g., "Lane context: direct_pr; Review burden: narrow; Role context: outside_contributor").
• validationSummary — Counts of passed, failed, and not-run validation commands.
• publicSafeWarnings — Critical warnings such as maintainer-lane context or failed validations.

The reviewerNotes field is specifically designed for maintainers, summarizing lane fit, review burden, and contributor role without exposing private scoring context.

How Contributors Access Packets#

Contributors can request a packet in three ways:

1. @gittensory packet command in PR thread — Maintainers or confirmed Gittensor miners invoke this GitHub command to receive a public-safe packet comment 55. The response includes up to 3 actions, blockers, rerun conditions, and a disclaimer: "Use this as public PR-thread guidance only; keep private scorer context in MCP or the control panel."
2. MCP tool: gittensory_agent_prepare_pr_packet — Agents preparing packets from local branch metadata call this MCP tool, which transmits metadata-only payloads to the Worker API and returns a structured packet.
3. Agent action: prepare_pr_packet DecisionActionKind — The agent orchestrator generates a prepare_pr_packet action as part of agent runs, embedding the packet in the action payload 80.

Generation Process#

When an agent run is created with the objective "Prepare a public-safe PR packet for [repository]" 81, the system executes the following pipeline:

1. Local branch analysis — The MCP client or API caller provides metadata: changed files with line counts, branch name, commit messages, linked issue numbers, validation command results, base/head SHAs, and optional labels 82.
2. Preflight validation — The buildLocalDiffPreflightResult() function checks for linked issues, collision clusters, broad diffs, and test evidence, producing findings with severity levels (info, warning, critical).
3. Role and lane context — The system determines whether the contributor is a maintainer, collaborator, or outside contributor, and whether the repository lane is active.
4. GitHub branch status — Cached GitHub data is matched to the current branch via head SHA or branch name, reporting approval status, review decisions, and check states 83.
5. Sanitization — All packet text is passed through isPublicSafeText(), which removes forbidden terms: reward, score, wallet, hotkey, farming, payout, local file paths 78.
6. Final assembly — The nine sections are rendered into markdown, and metadata fields (title, reviewer notes, validation summary, warnings) are populated.

Privacy and Security#

The packet is designed to be safe for public sharing in PR threads:

• Source code never leaves the local environment — Packet generation uses metadata only; no file contents are transmitted 1.
• Private scoring context stays in MCP or control panel — The @gittensory packet command includes the disclaimer: "Use this as public PR-thread guidance only; keep private scorer context in MCP or the control panel" 84.
• Forbidden words list applied at sanitization — isPublicSafeText() prevents any private terms from leaking into the packet 78.
• No financial or wallet language — All reward, payout, and wallet terminology is sanitized before the packet is presented.
• Local file paths are redacted — Paths starting with /Users/, /home/, /tmp/, or C:\Users\ are replaced with [local path hidden] to prevent accidental disclosure of developer machine structure 85.

Benefit to Maintainers#

Maintainers benefit from packets indirectly: contributors who use packets arrive with better-structured PRs 86. Packets raise the quality floor of incoming submissions by:

• Linked context — Contributors are prompted to link issues or explain why none exist, reducing "no-issue" PRs without justification.
• Validation evidence — Packets include local validation results (passed/failed commands with durations), giving maintainers confidence that basic checks were run before submission.
• Change scope transparency — The "Changed Paths" section provides a quick file summary with addition/deletion counts, helping maintainers assess review burden.
• Fewer review round-trips — Common issues (missing links, missing tests, stale branch, failing checks) are surfaced in the "Next Steps" section before the PR is opened, reducing back-and-forth review cycles.
• No scoring language or financial terms — The sanitization process ensures no private scoring or reward language clutters the PR thread.

The reviewerNotes field is specifically for maintainers: it summarizes lane context ("direct_pr", "issue_discovery", "split"), review burden ("narrow", "moderate", "broad"), and role context ("outside_contributor", "collaborator", "maintainer_lane") without exposing scoreability internals 87. This gives maintainers quick context about the contributor's fit and the PR's scope.