opentensor · sam0x17 · Apr 24, 2026 · Apr 24, 2026 · Apr 24, 2026 · Apr 24, 2026
diff --git a/.agents/skills/auditor/SKILL.md b/.agents/skills/auditor/SKILL.md
@@ -0,0 +1,66 @@
+---
+name: auditor
+description: Run the domain-focused Auditor persona on the local working tree's diff against a base branch. May build/test if needed for confirmation. Outputs a verdict, optional suggested-changes patch, and (if relevant) a proposed PR description. Use after the Skeptic has cleared the branch, or directly when the user trusts their own code and wants the domain review.
+---
+
+# Auditor — local mode
+
+You are running the Auditor persona locally against the user's working tree. The Skeptic has either already passed (or the user is running you directly because they wrote the code themselves and trust intent). Your output goes to the terminal, not GitHub.
+
+## Step 1 — Determine the diff
+
+Same detection as the Skeptic skill:
+1. PR base via `gh pr view --json baseRefName` if a PR exists.
+2. Default to `devnet-ready`.
+3. Override via skill argument: `/auditor main`.
+
+Compute the diff:
+
+```bash
+git fetch origin "$BASE" --quiet
+git diff --merge-base "origin/$BASE"...HEAD
+```
+
+If the diff is empty, report "No changes vs $BASE" and exit.
+
+## Step 2 — Run the persona
+
+Load and follow:
+- `.github/ai-review/common.md`
+- `.github/ai-review/auditor.md`
+
+**Local-mode adaptations:**
+
+- **PR description handling**: if a PR exists, follow the persona's auto-fill / discrepancy-comment logic but do NOT actually call `gh pr edit`. Instead, write the proposed description to `.auditor-pr-description.md` and tell the user. If no PR exists, generate a draft description and write it to the same file — the user will use it when they open the PR.
+- **Auto-fix CI failures**: you MAY run `./scripts/fix_rust.sh` against the working tree if lints / formatting are off, but DO NOT commit. Leave changes in the working tree for the user to review.
+- **Spec version bump**: if the diff touches `runtime/` or `pallets/` and `spec_version` in `runtime/src/lib.rs` was not bumped, do NOT modify the file. Instead, surface this as a finding the user must address.
+- **Build/test escalation**: same rules as the workflow — only build/test when a finding requires runtime confirmation. Use `cargo test -p <pallet> <test>` for targeted tests rather than the full workspace.
+- **Duplicate-work check**: if a PR exists, run the same `gh pr list` check the persona file describes. If no PR exists, skip this step (no duplicates to check yet).
+
+## Step 3 — Output
+
+```
+============================================================
+  AUDITOR VERDICT: 👍 | 👎
+============================================================
+
+Gittensor: KNOWN | LIKELY | UNKNOWN
+Spec version: <bumped | NOT BUMPED — required>
+Auto-fix: <ran fix_rust.sh, modified N files | not needed>
+
+Description: <see .auditor-pr-description.md | already adequate>
+Duplicates: <none | PR #N is the better candidate>
+
+Findings:
+  [SEVERITY] Title
+    file:line — description
+
+Suggested new files:
+  path/to/new_test.rs (see .auditor-suggestions.patch)
+
+Conclusion: <one or two sentences>
+```
+
+Write any suggested code changes to `.auditor-suggestions.patch` (apply with `git apply`). Write any proposed new files into the patch as well, as added-file diffs. Write the proposed PR description (if generated) to `.auditor-pr-description.md`.
+
+Do NOT post anything to GitHub. Do NOT commit. Do NOT push.
diff --git a/.agents/skills/skeptic/SKILL.md b/.agents/skills/skeptic/SKILL.md
@@ -0,0 +1,59 @@
+---
+name: skeptic
+description: Run the security-focused Skeptic persona on the local working tree's diff against a base branch. Static analysis only — does not build, test, or execute anything from the diff. Outputs a verdict comment and a suggested-changes patch file. Use when the user wants to security-review a branch before pushing.
+---
+
+# Skeptic — local mode
+
+You are running the Skeptic persona locally against the user's working tree. There is no PR yet (or the PR exists but the user wants a fast iteration before pushing). Your output goes to the terminal, not GitHub.
+
+## Step 1 — Determine the diff
+
+Detect the base branch in this order:
+1. If `gh pr view --json baseRefName` succeeds in the current branch's PR, use that.
+2. Else, default to `devnet-ready` (the policy base for new PRs).
+3. Allow override: if the user invoked the skill with an argument like `/skeptic main`, use that.
+
+Compute the diff:
+
+```bash
+git fetch origin "$BASE" --quiet
+git diff --merge-base "origin/$BASE"...HEAD
+```
+
+If the diff is empty, report "No changes vs $BASE" and exit.
+
+## Step 2 — Run the persona
+
+Load and follow the instructions in:
+- `.github/ai-review/common.md`
+- `.github/ai-review/skeptic.md`
+
+**Constraints inherited from the persona file:**
+- **Do NOT** run `cargo`, `npm`, `make`, `docker`, or any build/test command. Read-only analysis only.
+- You **may** use `gh`, `git log`, `git show`, `git diff`, `grep`, `rg`, and read files.
+
+For the contributor signal step, if `gh pr view` reveals an existing PR, query the author's history. Otherwise (no PR yet), use the local commit author identity from `git log --format='%an <%ae>'` and skip the GitHub-API queries — note in the output that the contributor-signal check was limited because no PR exists yet.
+
+## Step 3 — Output
+
+Print to stdout in the same format the persona file specifies, but adapted for terminal:
+
+```
+============================================================
+  SKEPTIC VERDICT: [SAFE | VULNERABLE | MALICIOUS]
+============================================================
+
+Contributor scrutiny: <tier>
+Branch: <head> -> <base>
+
+Findings:
+  [SEVERITY] Title
+    file:line — description
+
+Conclusion: <one sentence>
+```
+
+If you have suggested changes (suggestion-block content from the persona output), additionally write them to `.skeptic-suggestions.patch` in unified diff format that the user can apply with `git apply .skeptic-suggestions.patch`. Print the patch path at the end of your output. If no suggestions, do not create the file.
+
+Do NOT post anything to GitHub. Do NOT modify any files in the working tree (other than writing the suggestions patch).
diff --git a/.claude/skills/auditor/SKILL.md b/.claude/skills/auditor/SKILL.md
@@ -0,0 +1,66 @@
+---
+name: auditor
+description: Run the domain-focused Auditor persona on the local working tree's diff against a base branch. May build/test if needed for confirmation. Outputs a verdict, optional suggested-changes patch, and (if relevant) a proposed PR description. Use after the Skeptic has cleared the branch, or directly when the user trusts their own code and wants the domain review.
+---
+
+# Auditor — local mode
+
+You are running the Auditor persona locally against the user's working tree. The Skeptic has either already passed (or the user is running you directly because they wrote the code themselves and trust intent). Your output goes to the terminal, not GitHub.
+
+## Step 1 — Determine the diff
+
+Same detection as the Skeptic skill:
+1. PR base via `gh pr view --json baseRefName` if a PR exists.
+2. Default to `devnet-ready`.
+3. Override via skill argument: `/auditor main`.
+
+Compute the diff:
+
+```bash
+git fetch origin "$BASE" --quiet
+git diff --merge-base "origin/$BASE"...HEAD
+```
+
+If the diff is empty, report "No changes vs $BASE" and exit.
+
+## Step 2 — Run the persona
+
+Load and follow:
+- `.github/ai-review/common.md`
+- `.github/ai-review/auditor.md`
+
+**Local-mode adaptations:**
+
+- **PR description handling**: if a PR exists, follow the persona's auto-fill / discrepancy-comment logic but do NOT actually call `gh pr edit`. Instead, write the proposed description to `.auditor-pr-description.md` and tell the user. If no PR exists, generate a draft description and write it to the same file — the user will use it when they open the PR.
+- **Auto-fix CI failures**: you MAY run `./scripts/fix_rust.sh` against the working tree if lints / formatting are off, but DO NOT commit. Leave changes in the working tree for the user to review.
+- **Spec version bump**: if the diff touches `runtime/` or `pallets/` and `spec_version` in `runtime/src/lib.rs` was not bumped, do NOT modify the file. Instead, surface this as a finding the user must address.
+- **Build/test escalation**: same rules as the workflow — only build/test when a finding requires runtime confirmation. Use `cargo test -p <pallet> <test>` for targeted tests rather than the full workspace.
+- **Duplicate-work check**: if a PR exists, run the same `gh pr list` check the persona file describes. If no PR exists, skip this step (no duplicates to check yet).
+
+## Step 3 — Output
+
+```
+============================================================
+  AUDITOR VERDICT: 👍 | 👎
+============================================================
+
+Gittensor: KNOWN | LIKELY | UNKNOWN
+Spec version: <bumped | NOT BUMPED — required>
+Auto-fix: <ran fix_rust.sh, modified N files | not needed>
+
+Description: <see .auditor-pr-description.md | already adequate>
+Duplicates: <none | PR #N is the better candidate>
+
+Findings:
+  [SEVERITY] Title
+    file:line — description
+
+Suggested new files:
+  path/to/new_test.rs (see .auditor-suggestions.patch)
+
+Conclusion: <one or two sentences>
+```
+
+Write any suggested code changes to `.auditor-suggestions.patch` (apply with `git apply`). Write any proposed new files into the patch as well, as added-file diffs. Write the proposed PR description (if generated) to `.auditor-pr-description.md`.
+
+Do NOT post anything to GitHub. Do NOT commit. Do NOT push.
diff --git a/.claude/skills/skeptic/SKILL.md b/.claude/skills/skeptic/SKILL.md
@@ -0,0 +1,59 @@
+---
+name: skeptic
+description: Run the security-focused Skeptic persona on the local working tree's diff against a base branch. Static analysis only — does not build, test, or execute anything from the diff. Outputs a verdict comment and a suggested-changes patch file. Use when the user wants to security-review a branch before pushing.
+---
+
+# Skeptic — local mode
+
+You are running the Skeptic persona locally against the user's working tree. There is no PR yet (or the PR exists but the user wants a fast iteration before pushing). Your output goes to the terminal, not GitHub.
+
+## Step 1 — Determine the diff
+
+Detect the base branch in this order:
+1. If `gh pr view --json baseRefName` succeeds in the current branch's PR, use that.
+2. Else, default to `devnet-ready` (the policy base for new PRs).
+3. Allow override: if the user invoked the skill with an argument like `/skeptic main`, use that.
+
+Compute the diff:
+
+```bash
+git fetch origin "$BASE" --quiet
+git diff --merge-base "origin/$BASE"...HEAD
+```
+
+If the diff is empty, report "No changes vs $BASE" and exit.
+
+## Step 2 — Run the persona
+
+Load and follow the instructions in:
+- `.github/ai-review/common.md`
+- `.github/ai-review/skeptic.md`
+
+**Constraints inherited from the persona file:**
+- **Do NOT** run `cargo`, `npm`, `make`, `docker`, or any build/test command. Read-only analysis only.
+- You **may** use `gh`, `git log`, `git show`, `git diff`, `grep`, `rg`, and read files.
+
+For the contributor signal step, if `gh pr view` reveals an existing PR, query the author's history. Otherwise (no PR yet), use the local commit author identity from `git log --format='%an <%ae>'` and skip the GitHub-API queries — note in the output that the contributor-signal check was limited because no PR exists yet.
+
+## Step 3 — Output
+
+Print to stdout in the same format the persona file specifies, but adapted for terminal:
+
+```
+============================================================
+  SKEPTIC VERDICT: [SAFE | VULNERABLE | MALICIOUS]
+============================================================
+
+Contributor scrutiny: <tier>
+Branch: <head> -> <base>
+
+Findings:
+  [SEVERITY] Title
+    file:line — description
+
+Conclusion: <one sentence>
+```
+
+If you have suggested changes (suggestion-block content from the persona output), additionally write them to `.skeptic-suggestions.patch` in unified diff format that the user can apply with `git apply .skeptic-suggestions.patch`. Print the patch path at the end of your output. If no suggestions, do not create the file.
+
+Do NOT post anything to GitHub. Do NOT modify any files in the working tree (other than writing the suggestions patch).
diff --git a/.github/ai-review/README.md b/.github/ai-review/README.md
@@ -0,0 +1,121 @@
+# AI Review — Operational Notes
+
+This directory contains the persona prompts and supporting scripts for the
+two-persona AI PR review driven by [`ai-review.yml`](../workflows/ai-review.yml).
+
+## Files
+
+| File | Purpose |
+| --- | --- |
+| `common.md` | Shared review context (repo topology, branch policy, output discipline) |
+| `skeptic.md` | Skeptic persona: security review, static-only, no network or build |
+| `auditor.md` | Auditor persona: domain review after Skeptic clears |
+| `prefetch.sh` | Pre-fetches all GitHub context into `/tmp/ai-review-context/` so Codex doesn't need tokens or network |
+| `gittensor-accounts.txt` | Nucleus-curated supplement to the on-chain Gittensor index |
+| `known-gittensor-accounts.json` | Auto-maintained on-chain index |
+| `index_gittensor.py` | Indexer that walks the SN74 `issues-v0` contract to build the index |
+
+## Required repo secrets
+
+| Secret | Used by | Required |
+| --- | --- | --- |
+| `OPENAI_API_KEY` | Codex (skeptic + auditor) | **Yes** |
+
+## Optional — GitHub App for narrow-scope tokens
+
+If left unconfigured, the workflow uses the default `GITHUB_TOKEN`. To narrow
+the blast radius of any token leak, configure a dedicated GitHub App and the
+workflow will automatically use its token instead.
+
+### Setup
+
+1. Create a GitHub App under the `opentensor` org:
+   - Settings → Developer settings → GitHub Apps → New GitHub App.
+   - Webhook: not needed; disable.
+   - Repository permissions:
+     - **Pull requests**: Read & Write (for comments + body edits)
+     - **Contents**: Read & Write (for auditor auto-fix commits)
+     - **Issues**: Read & Write (for sticky issue comments)
+     - **Metadata**: Read
+   - User permissions: none.
+   - "Where can this GitHub App be installed?": Only on this account.
+2. Install the App on the `opentensor/subtensor` repo (only).
+3. From the App settings page, generate a private key (`.pem` file).
+4. In repo Settings → Secrets and variables → Actions:
+   - Variables tab: add `AI_REVIEW_APP_ID` = the App's numeric ID.
+   - Secrets tab: add `AI_REVIEW_APP_PRIVATE_KEY` = the contents of the `.pem`.
+
+The workflow detects `AI_REVIEW_APP_ID` and mints a short-lived installation
+token via [`actions/create-github-app-token`](https://github.com/actions/create-github-app-token).
+Token lifetime is 1 hour; permissions are exactly what the App grants and
+nothing more. The token is masked in logs and is never passed to Codex.
+
+## Security model
+
+| Trust boundary | Mechanism |
+| --- | --- |
+| Persona prompts can be modified by PR | Loaded from base branch via `git show origin/$BASE:...` into `/tmp/ai-review-trusted/`; PR-side copies are never loaded |
+| Codex prompt-injection might call `gh` | Codex runs with no `GH_TOKEN` and no `OPENAI_API_KEY` in env; prefetch step holds tokens, post-comment step holds tokens; Codex only reads files |
+| Malicious `build.rs` in PR-added dep | Same env-stripping above means cargo subprocesses inherit no tokens; `drop-sudo` strategy removes sudo from the runner |
+| Upstream Gittensor compromise | Indexer workflow installs gittensor pinned to commit SHA, runs in a job with `contents: read` only; a separate job with `contents: write` publishes the resulting JSON via PR — never executing third-party code |
+| `OPENAI_API_KEY` leakage from Codex | Held only in the proxy's process memory (codex-action handles this), shielded by `drop-sudo` |
+
+## Updating pinned action versions
+
+Every third-party action used in the AI-review workflows is pinned to an
+immutable commit SHA (with the major-version tag in a trailing comment), e.g.
+`openai/codex-action@e0fdf01220eb9a88167c4898839d273e3f2609d1 # v1`. Mutable
+tags like `@v1` would let an upstream maintainer (or compromised account)
+silently swap in attacker-controlled code that runs with our OpenAI key and
+GitHub App credentials.
+
+To update a pinned action:
+
+```bash
+# Look up the current SHA for the desired ref
+gh api repos/<owner>/<repo>/git/refs/tags/<ref> --jq '.object.sha'
+```
+
+Open a PR that updates the SHA and the trailing version comment. The skeptic
+will re-evaluate the change.
+
+## Fork PR handling
+
+Repository secrets (`OPENAI_API_KEY`, `AI_REVIEW_APP_PRIVATE_KEY`) are not
+exposed to `pull_request` events from forks, and the default token is read-
+only, so the Codex steps cannot run on a fork auto-trigger.
+
+The persona jobs do still run on fork PRs — they fail-fast in the very first
+"Fork PR advisory" step with a clear error message directing maintainers to
+invoke the workflow manually. This is intentional: a skipped required check
+is treated by GitHub Branch Protection as satisfied, which would silently
+bypass the security gate for exactly the contributor class that needs it most
+(fork PRs from untrusted authors). Failing the check instead keeps the gate
+red until a maintainer explicitly clears it.
+
+**To AI-review a fork PR:** a nucleus member dispatches the workflow with
+the PR number. `workflow_dispatch` runs in base context with secrets
+available, performs the real review, and the required checks turn green.
+
+```bash
+gh workflow run ai-review.yml --repo opentensor/subtensor -f pr_number=<N>
+```
+
+## Required-checks setup
+
+After the first successful run, add these to branch protection on `devnet-ready`
+(and other protected branches) under Settings → Branches → Branch protection rules:
+
+- `ai-review / skeptic`
+- `ai-review / auditor`
+
+## Index refresh
+
+Manual trigger:
+
+```bash
+gh workflow run ai-review-index-gittensor.yml --repo opentensor/subtensor
+```
+
+Daily cron is already configured (06:17 UTC). The indexer opens a PR with any
+new entries; nucleus reviews and merges.