hex-audit 0.4.0

package/dist/skills/init-audit.md

@@ -0,0 +1,271 @@
+---
+description: "Initialize a Solidity audit project: deterministic analysis + protocol overview + system diagram + flow charts + spec conformance, all in one run"
+---
+
+# Skill: Initialize Audit
+
+**Recommended model:** Opus (this skill performs all reasoning-heavy pre-review work; switch to Opus before invoking)
+
+You are setting up a new Solidity audit project with Hex. This single skill replaces the old chain of `/init-audit` → `/generate-overview` → `/generate-diagram` → `/generate-flows` → `/check-spec-conformance`. By the time it finishes, every analysis page on the dashboard has data and every DEVIATES/PARTIAL spec item has been materialized as a Potential card on the issue board.
+
+## Prerequisites
+
+- The auditor has cloned or received the client project.
+- Node.js and npm are installed.
+- Hex CLI is installed (`npm install -g hex-audit`).
+
+## Phase 1 — Config + dependency safety
+
+### 1.1 Gather information
+
+Ask the auditor for:
+- **Project directory path** — where the client project lives (default: current directory).
+- **Scope** — glob or explicit list of files in audit scope (e.g., `src/core/**/*.sol`).
+- **Commit hash** — the specific commit being audited (default: HEAD).
+- **Chain** — target chain (default: ethereum).
+- **Documentation URL** — if available.
+
+### 1.2 Audit dependencies (BEFORE compiling)
+
+Build scripts and `npm install` hooks are a primary supply-chain attack vector. Check these **before** running `forge build`, `npm install`, or any compilation command:
+
+1. **`package.json` install hooks** — `preinstall`, `postinstall`, `prepare`, `prebuild`, `pretest` scripts that shell out, download from URLs, or touch files outside the project. Cross-reference with npmjs.com advisories.
+2. **Foundry `lib/` submodules** — inspect each `lib/*/foundry.toml` for `ffi = true`, broad `fs_permissions`, or `script` entries.
+3. **Root `foundry.toml`**:
+   - `ffi = true` → **HIGH RISK** (arbitrary system commands during build/test).
+   - `fs_permissions` broader than read-only on `./src` or `./out` → flag.
+   - Profile overrides differing from main profile → flag.
+4. **`remappings.txt`** — verify each target exists in `lib/`; flag shadowed paths, mismatched paths, or hijack vectors (a remap of `@openzeppelin/=lib/malicious-oz/`).
+5. **Suspicious files** — root-level `*.sh`, `*.py`, `Makefile` targets, `.github/` workflows.
+6. **Plaintext secrets** in `.env*` files (private keys, mnemonics, API keys). Do NOT log the values.
+7. **`.vscode/extensions.json`** — flag extension recommendations from unknown publishers.
+
+**If any build-time threats are found: STOP and warn before compilation.**
+
+After build safety passes, evaluate Solidity dependencies:
+- Identify well-known libs (OpenZeppelin, Solmate, Solady, PRBMath). Flag outdated versions with known advisories (OZ < 4.9.3, Solmate `SafeTransferLib` missing code-size check, etc.).
+- Flag typosquats (`@openzepplin` vs `@openzeppelin`).
+- Flag unused dependencies (in `lib/` or `node_modules/` but not imported by scope files).
+- Spot-check unknown packages for inline assembly, `selfdestruct`, `delegatecall` to hardcoded addresses.
+
+### 1.3 Initialize and analyze
+
+Run:
+```bash
+npx hex init --project "<path>" --scope "<scope>" --commit <hash> --chain <chain> --docs "<url>"
+npx hex analyze
+```
+
+`hex analyze` runs stats → deps → access → state → calls → patterns → constraints in parallel, then `surface` last. If a tool is missing (Slither, forge), the corresponding analysis is skipped — note the limitation and move on.
+
+## Phase 2 — Protocol overview
+
+Read from the output directory (`.hex/`):
+- `config.json` — project name, scope, chain, docs URL.
+- `stats.json` — contracts, nSLOC, ERCs, dependencies.
+- `deps.json` — contract relationships and clusters.
+
+Run `npx hex context` to load the full codebase. If `config.json.project.docs_url` is set, fetch and read the documentation.
+
+Write a 2–3 paragraph overview to `.hex/overview.md` covering:
+1. **What the protocol does** — purpose, target users, the problem it solves.
+2. **Core mechanism** — deposit/withdraw flows, token economics, governance model.
+3. **Key contracts and their roles** — entry points, state holders, libraries.
+4. **Notable design patterns** — upgradeability, access control, external dependencies, oracle usage.
+
+Write for an experienced Solidity auditor. Be precise and technical. Reference specific contract names and functions where relevant.
+
+**Do NOT:**
+- List findings or security concerns (this is purely descriptive).
+- Speculate about vulnerabilities.
+- Include code snippets.
+- Add disclaimers about AI limitations.
+
+**Format:**
+
+```markdown
+# Protocol Overview: [Name]
+
+[2-3 paragraphs]
+
+## Key Contracts
+
+| Contract | Type | nSLOC | Role |
+|----------|------|-------|------|
+| ... | ... | ... | ... |
+
+## External Dependencies
+- [Package] v[version] — used for [purpose]
+
+## Architecture Notes
+- [Notable design decisions, patterns, or concerns to keep in mind during review]
+```
+
+## Phase 3 — System diagram
+
+Read `.hex/overview.md`, `.hex/patterns.json` (for `UPGRADEABLE`, `CROSS_CHAIN`, `DELEGATECALL`, `protocol_hints`), `.hex/attack-surface.json` (entry-point classification, token interactions, external deps), `.hex/access-control.json` (roles + modifiers).
+
+Detect the protocol archetype from `patterns.json` (Vault / Lending / Bridge / Governance / AMM / Staking). Multiple may apply.
+
+Write a Mermaid `graph TD` diagram to `.hex/diagrams/diagram.mmd`. Constraints:
+
+- **Only in-scope contracts** (per `config.json.project.scope`). Out-of-scope contracts may appear as simplified nodes if in-scope contracts interact with them; otherwise omit.
+- Skip interfaces, abstract contracts, and pure libraries.
+- **Maximum ~15 nodes per diagram.** If the protocol is larger, split into multiple files (`diagram-core.mmd`, `diagram-governance.mmd`, etc.) grouped by purpose.
+- Prefix contract labels with a semantic symbol where applicable:
+  - 🏦 Vault / ERC-4626, 💰 Token, 🔮 Oracle, 🔒 Timelock/access control, 📦 Storage, ⚡ Flash loan, 🌉 Bridge.
+- Define a classDef palette at the bottom of every diagram:
+  ```
+  classDef core fill:#a5d8ff,stroke:#1971c2,color:#000
+  classDef user fill:#b2f2bb,stroke:#2f9e44,color:#000
+  classDef admin fill:#ff8787,stroke:#c92a2a,color:#000
+  classDef ext fill:#ffd8a8,stroke:#e8590c,color:#000
+  classDef proxy fill:#d0bfff,stroke:#7048e8,color:#000,stroke-dasharray:5 5
+  classDef storage fill:#ffec99,stroke:#f08c00,color:#000
+  ```
+- Apply class by role: core logic → `core`, user-facing → `user`, admin/governance → `admin`, external deps → `ext`, proxy/upgradeable → `proxy`, storage/registry → `storage`.
+- Edge labels: type the interaction — `-->|external call|`, `-.->|delegatecall|`, `==>|access-controlled|`, `-.->|reads|`.
+- Include a short overview header comment (`%% System architecture for <Project>`) and a visual legend at the bottom showing each classDef with one-line meaning.
+
+## Phase 4 — Flow charts
+
+Same context as Phase 3, plus `.hex/external-calls.json`.
+
+For each archetype, generate at minimum:
+- **Value Flow** — how tokens/ETH move (deposits, withdrawals, fees, swaps).
+- **Permission Flow** — who can do what; role grant/revoke; admin operations.
+
+Archetype-specific flows (only generate when the archetype is detected):
+- **Vault**: deposit/mint, withdraw/redeem, strategy allocation, fee collection.
+- **Lending**: borrow, repay, liquidation (health check → liquidation → seizure → bad debt).
+- **Governance**: proposal lifecycle (create → vote → queue → execute), delegation.
+- **Bridge**: send (lock/burn → relay → finality → mint/unlock), receive/verify.
+- **AMM/DEX**: swap, add liquidity, remove liquidity, fee accrual.
+- **Staking**: stake, unstake, claim, compound.
+- Add an **upgrade flow** if any upgradeable proxies are detected.
+
+Write each flow to `.hex/diagrams/flow-<name>.mmd` (e.g., `flow-deposit.mmd`). Constraints per flow:
+
+- **In-scope contracts only.** Out-of-scope contracts may appear as `ext` nodes when called by in-scope code.
+- **Max ~15 nodes per flow.** Split if larger.
+- Distinct shapes by semantic role:
+  - Stadium `id(["Label"])` — entry point, success outcome, or revert
+  - Rectangle `id["Label"]` — internal step or external call
+  - Cylinder `id[("Label")]` — state change / storage mutation
+  - Rhombus `id{"Label"}` — decision / validation
+- Use the same classDef palette as the diagram, plus `entry`, `state`, `decision`, `reject`, `success` variants per flow needs.
+- **Every decision diamond shows BOTH the success and the revert path** — don't omit failure branches.
+- Use plain-English labels (`"Burns user shares"`, not `"_burn(msg.sender, shares)"`).
+- Wrap each contract's nodes in a `subgraph` swim-lane.
+
+## Phase 5 — Spec conformance
+
+Read `.hex/config.json` (docs URL, scope, ERCs), `.hex/stats.json` (ERC/EIP usage), `.hex/attack-surface.json` (token interactions).
+
+Cross-reference four sources:
+
+**5.1 External documentation.** Fetch `config.json.project.docs_url`. Extract every behavioral claim ("users can deposit X and receive Y", "fees capped at 10%", "only admin can pause"). For each claim, find the implementing code and verify match.
+
+**5.2 NatSpec.** For every function with `@notice`/`@dev`/`@param`/`@return`:
+- Does the function actually do what `@notice` says?
+- Are `@param` constraints accurate?
+- Does it return what `@return` claims?
+- Pay extra attention to conditional NatSpec ("reverts if…", "only when…").
+
+**5.3 Interface conformance.** For every interface the contract implements (explicit `is IFoo` or implicit):
+- All interface functions implemented?
+- Behavioral semantics of each function respected?
+
+**5.4 ERC/EIP compliance.** For each ERC/EIP in `stats.json.erc_eip_usage`:
+- **Fetch the canonical spec** via WebFetch from `https://eips.ethereum.org/EIPS/eip-<number>`. If the fetch fails, note `"spec_fetched": false` and fall back to training knowledge.
+- Extract every MUST/SHOULD/MAY requirement into a checklist; verify each against the implementation.
+
+Known gotchas:
+- **ERC-20**: return values on transfer/approve, zero-amount transfers, approval race.
+- **ERC-4626**: rounding direction per spec, preview vs actual, max* return values.
+- **ERC-721**: safeTransferFrom callbacks.
+- **ERC-2612**: permit deadline, nonce handling, domain separator chain ID.
+
+**Weird token compat.** For every contract interacting with ERC-20 tokens (check `attack-surface.json.token_interactions`), classify handling of:
+- Fee-on-transfer (balance-diff accounting vs trusting transfer amount).
+- Rebasing (shares vs absolute balances; stale balance caches).
+- Blocklist (DoS via blocked recipient in batches/loops; liquidation/withdrawal block).
+- Double-entry-point legacy tokens (dedup on contract address).
+
+### Output format
+
+Write `.hex/spec-conformance.json`:
+
+```json
+{
+  "checked_at": "<ISO-8601>",
+  "sources_checked": { "external_docs": true, "natspec": true, "interfaces": true, "erc_eip": ["ERC-20", "ERC-4626"] },
+  "summary": { "total_checks": N, "conforms": N, "deviates": N, "partial": N, "unverifiable": N, "undocumented": N },
+  "items": [
+    {
+      "id": "SC-001",
+      "source": "erc_eip" | "natspec" | "interface" | "external_docs",
+      "spec_text": "Verbatim text or paraphrase of the requirement",
+      "spec_location": { "type": "eip", "number": 4626, "section": "Specification", "url": "https://eips.ethereum.org/EIPS/eip-4626" },
+      "status": "CONFORMS" | "DEVIATES" | "PARTIAL" | "UNVERIFIABLE" | "UNDOCUMENTED",
+      "finding": "Plain-English explanation of what the code does vs what the spec demands.",
+      "code_location": { "file": "src/Vault.sol", "line_start": 120, "line_end": 145 },
+      "severity_hint": "Low",
+      "confidence": "high"
+    }
+  ]
+}
+```
+
+Also write a human-readable `.hex/spec-conformance.md` rendering the same data grouped by status (DEVIATES first, CONFORMS last).
+
+## Phase 6 — Materialize conformance items onto the board
+
+For every item in `spec-conformance.json.items` with `status` of `DEVIATES` or `PARTIAL`, append a tracking entry to `.hex/tracking.json` (creating the file if missing). Schema:
+
+```json
+{
+  "id": "<spec-item-id, e.g. SC-001>",
+  "title": "<spec-item.finding's first sentence, truncated to ~80 chars>",
+  "severity": "<spec-item.severity_hint, default 'Info' if absent>",
+  "source": "conformance",
+  "status": "pending_validation",
+  "poc_status": "not_started",
+  "poc_file": null,
+  "duplicates": [],
+  "notes": "<spec source + spec_location URL — so the board card has provenance>"
+}
+```
+
+These appear on the dashboard's Issues board as Potential cards immediately. The auditor validates them later with `/validate-issue <id>`.
+
+**Idempotency:** if a tracking entry with the same id already exists, leave it alone (the auditor may have already edited/promoted it).
+
+## Phase 7 — Report and auto-launch the dashboard
+
+Summarize:
+- Files / contracts in scope, total nSLOC.
+- Number of external/public functions, state variables.
+- Number of conformance DEVIATES/PARTIAL items materialized to the board.
+- Any warnings or limitations (missing tools, failed coverage, etc.).
+
+Then launch the dashboard in the background so the auditor's browser opens automatically. Run this Bash command with `run_in_background: true` so the skill returns control to the auditor while Next.js keeps serving the dashboard:
+
+```bash
+npx hex dashboard
+```
+
+Print a one-line confirmation after starting it: `Dashboard starting at http://localhost:3000 (live-refreshing as .hex/ changes).`
+
+Do NOT run the command in the foreground — that would block this skill's return. The dashboard's auto-open already handles the browser; you just need to launch the process and return.
+
+## Outputs (recap)
+
+After this skill finishes, the following exist in `.hex/`:
+
+- `config.json`, `stats.json`, `deps.json`, `access-control.json`, `state-vars.json`, `external-calls.json`, `patterns.json`, `constraints.json`, `attack-surface.json`
+- `overview.md`
+- `diagrams/diagram.mmd` (+ split diagrams if needed)
+- `diagrams/flow-*.mmd`
+- `spec-conformance.json`, `spec-conformance.md`
+- `tracking.json` — populated with conformance DEVIATES/PARTIAL items as Potential issues

package/dist/skills/sync-issues.md

@@ -0,0 +1,266 @@
+---
+description: 'Two-way sync between local Hex findings and GitHub Issues — pulls teammate issues into the board (canonical), pushes verified findings out, runs inline dedup'
+---
+
+# Skill: Sync Issues
+
+**Recommended model:** Sonnet
+
+This skill is Hex's GitHub Issues integration. Hex never authenticates with GitHub — you authenticate once via `gh auth login` and this skill drives the `gh` CLI via bash. A single invocation runs both directions plus inline dedup.
+
+**Dedup direction note.** GitHub is the **source of truth**. When a teammate's pulled GitHub issue matches a local potential issue (same root cause, same contract/function), the **local** entry is marked Duplicate — not the GitHub one. The rationale is multi-auditor coordination: if a teammate already filed an issue, your in-progress local card is redundant. This is opposite of the auditagent dedup direction in `/ingest-aa-report`.
+
+## Context Assembly
+
+Read:
+- `<output_dir>/config.json` — needs `settings.github.repo` set.
+- `<output_dir>/findings.json` — local canonical findings.
+- `<output_dir>/tracking.json` — for status filtering on push (default: only `verified` is pushed).
+- `<output_dir>/external/github/findings.json` if it exists — last pulled state.
+- `<output_dir>/external/github/sync-status.json` for `last_synced_at`.
+
+Writes to:
+- `<output_dir>/findings.json` — updates `github.*` blocks on local findings.
+- `<output_dir>/external/github/findings.json` — teammate findings in `AiResultFile` shape.
+- `<output_dir>/external/github/sync-status.json` — counters + timestamp.
+- `<output_dir>/external/github/raw-issues.json` — debug cache of the gh JSON.
+- `<output_dir>/tracking.json` — teammate findings as new entries; local entries flipped to `duplicate` on match.
+- `<output_dir>/comparison.json` — appended with `match_signals` for each dedup hit.
+
+## Phase 0 — Preflight
+
+**0a. `gh` installed and authenticated?** Run `gh auth status`. If non-zero exit, print:
+
+```
+gh CLI is not authenticated. Run `gh auth login` once on this machine, then re-run /sync-issues.
+```
+
+…and stop. Hex never stores GitHub credentials.
+
+If `gh` itself is missing: instruct install from `https://cli.github.com/` then `gh auth login`.
+
+**0b. Resolve `settings.github.repo`.** If missing, use **AskUserQuestion**: "Which GitHub repo should this audit sync to? (e.g. `nethermind/audit-vaultx`)". Validate it has an `owner/repo` shape. Persist back to `config.json`.
+
+**0c. Permission check.** Run `gh repo view <repo> --json viewerPermission`. If `READ` or null, **AskUserQuestion**: "Read-only access to <repo>. Push will fail. Continue with pull-only? (yes/no)". Track `push_enabled`.
+
+## Phase 1 — Pull
+
+**1a. Fetch issues.**
+
+```bash
+gh issue list --repo <repo> --label "hex" --state all --limit 1000 \
+  --json number,title,body,labels,state,author,createdAt,updatedAt,url
+```
+
+Save raw JSON to `external/github/raw-issues.json`.
+
+For each issue whose `updatedAt` is newer than the prior `last_synced_at`, fetch comments:
+
+```bash
+gh issue view <number> --repo <repo> --json comments
+```
+
+(First sync: fetch for everything.)
+
+**1b. Classify each issue.**
+
+Find the round-trip footer in the body: regex `<!--\s*hex-finding-id:\s*(F\d+|AA-\d+|SC-\d+)\s*-->`. Then:
+
+- **Footer present, ID matches a local `findings.json` entry** → known local finding. Update its `github` block in place:
+  ```json
+  {
+    "issue_number": <num>,
+    "issue_url": "<url>",
+    "state": "open|closed",
+    "last_synced_at": "<now>",
+    "sync_status": "in_sync",
+    "comments": [{ "author": "<login>", "body": "<text>", "created_at": "<iso>", "url": "<url>" }]
+  }
+  ```
+
+- **Footer present, no matching local finding** → an issue we previously pushed that's since been deleted locally. Append a tracking entry restoring the link (status `pending_validation`, source `manual`, notes pointing at the URL). Do not touch `findings.json` — the body may have been edited remotely.
+
+- **No footer** → teammate finding. Two writes:
+  1. Add to the in-memory `external/github/findings.json` AiResultFile (`tool: "github"`, severity parsed from `severity:*` labels, default Medium):
+     ```json
+     {
+       "id": "github-<issue_number>",
+       "tool": "github",
+       "title": "<issue title>",
+       "severity": "Critical|High|Medium|Low|Info",
+       "description": "<body without footer>",
+       "affected_code": [<best-effort file refs extracted from body>],
+       "confidence": "medium",
+       "category": "<from label if present>",
+       "raw_category": "github-issue"
+     }
+     ```
+  2. Add to `tracking.json`:
+     ```json
+     {
+       "id": "github-<issue_number>",
+       "title": "<title>",
+       "severity": "<severity>",
+       "source": "github",
+       "status": "pending_validation",
+       "poc_status": "not_started",
+       "poc_file": null,
+       "duplicates": [],
+       "notes": "issue=<url> author=<author>"
+     }
+     ```
+
+Write `external/github/findings.json` atomically after the pass.
+
+## Phase 2 — Inline dedup (GitHub-canonical)
+
+For each **new github entry** added in Phase 1 step 1b's third branch, run a semantic comparison against every **existing** non-github tracking entry. Match signals:
+
+| Signal | Compare |
+|---|---|
+| **contract** (boolean) | Affected contract name match? |
+| **function** (boolean) | Affected function name match? |
+| **root_cause** (`same` / `overlapping` / `different`) | Technical mechanism |
+| **attack_vector** (`same` / `overlapping` / `different`) | What an attacker actually does |
+
+A match requires at least one of:
+- `root_cause = same` AND `function = true`, or
+- `root_cause = same` AND `contract = true` AND `attack_vector = same`, or
+- `root_cause = overlapping` AND `function = true` AND `attack_vector = same`.
+
+**On match (GitHub is canonical):**
+
+- Flip the **local** matching entry to `status: "duplicate"`, set `duplicate_of: "github-<issue_number>"` on it.
+- The github entry stays `pending_validation` (it's the canonical the team is working from).
+- Append to `comparison.json` under `duplicates`:
+  ```json
+  {
+    "ai_finding": "<local-entry-id>",
+    "matches": "github-<issue_number>",
+    "confidence": "high|medium|low",
+    "match_signals": { "contract": true, "function": true, "root_cause": "same", "attack_vector": "same" },
+    "reasoning": "<one short sentence>"
+  }
+  ```
+  (The schema field is named `ai_finding` for historical reasons but is repurposed here as "the local duplicate.")
+
+Persist updated `tracking.json` and `comparison.json` after the dedup pass.
+
+## Phase 3 — Push
+
+Skip if `push_enabled = false`.
+
+**3a. Candidates.** From `findings.json`, select each finding whose tracking entry has `status` in `settings.github.publish_status` (default `["verified"]`). Skip findings already marked `status: "duplicate"` (no point publishing a known duplicate).
+
+Within candidates:
+- Has `github.issue_number` → update via `gh issue edit`.
+- No `github.issue_number` → create via `gh issue create`.
+
+**3b. Render the body** (write to a temp file, then `--body-file`):
+
+```markdown
+**Severity:** <Severity>
+
+<finding.description>
+
+### Affected code
+
+<for each finding.root_cause.locations[]>
+**`<location.file>`**
+
+```solidity
+<location.snippet>
+```
+</for>
+
+### Recommendation
+
+<finding.recommendation>
+
+---
+
+*Synced from Hex audit `<config.project.name>` at commit `<config.project.commit>`.*
+
+<!-- hex-finding-id: <finding.id> -->
+```
+
+The footer is the round-trip identity key — never omit.
+
+**3c. Labels.**
+
+```
+<default_labels...> severity:<lowercased> source:<finding.source or 'manual'> status:<tracking.status>
+```
+
+Apply via repeated `--label` flags.
+
+**3d. Create or update.**
+
+Create:
+```bash
+gh issue create --repo <repo> --title "[<Severity>] <title>" --body-file <tmp> \
+  --label "hex" --label "audit" --label "severity:..." --label "source:..." --label "status:..."
+```
+
+Parse the returned URL to extract the issue number; update the local finding's `github` block.
+
+Update existing:
+```bash
+gh issue edit <num> --repo <repo> --title "[<Severity>] <title>" --body-file <tmp> \
+  --add-label "severity:..." --add-label "status:..."
+```
+
+Do NOT `--remove-label` — teammates may have added labels we shouldn't strip.
+
+If push fails for any single finding: capture stderr, set its `github.sync_status` to `conflict`, append a one-line error, continue with the next finding. Never abort the whole sync on one failure.
+
+**3e. Persist** `findings.json` once after all pushes, atomically.
+
+## Phase 4 — Status report
+
+Write `external/github/sync-status.json`:
+
+```json
+{
+  "repo": "<repo>",
+  "last_synced_at": "<now>",
+  "pushed": <new-created>,
+  "updated": <existing-updated>,
+  "pulled": <total-issues-seen>,
+  "teammate_findings": <count-of-footer-less>,
+  "duplicates_detected": <local-entries-flipped-to-duplicate>,
+  "errors": [<one-line-per-error>]
+}
+```
+
+Print:
+
+```
+GitHub sync complete (<repo>)
+  ↑ Pushed N new, updated M
+  ↓ Pulled K issues — J teammate findings, L matched local
+  ⇄ Dedup flipped D local entries to Duplicate (GitHub is canonical)
+<if errors:>
+  Errors:
+    - <error 1>
+```
+
+## Conflict resolution defaults
+
+- **Body content** — local wins on push. Reviewer edits inside `### Affected code` will be overwritten on re-push. Reviewer comments are never touched.
+- **State (open/closed)** — remote wins. Updates the local finding's `github.state`. Surface in the dashboard so the auditor can decide whether to also reject the finding.
+- **Comments** — pull-only. Hex never posts.
+
+## Error handling
+
+- Per-issue errors are isolated — log to `errors[]`, continue.
+- Rate limit (403 with "rate limit" in output): print "Rate-limited — sync resumes after <ISO time>." Stop the current phase.
+- Network failures: print the gh error and stop the current phase. Already-completed phases stay persisted.
+
+## What this skill does NOT do
+
+- Does not authenticate (use `gh auth login` once).
+- Does not post comments (auditors discuss inside GitHub).
+- Does not create labels (manual one-time setup; `gh issue create` errors if a label is missing).
+- Does not delete remote issues.
+- Does not push `rejected`, `unverified`, or `duplicate` findings.