---
name: upstream-scout
description: Scan every project related to one of our watchthelight-labs projects (or all of them) for what changed since the last run, find brand-new related projects, read the changes deeply enough to judge whether they matter to us, write them up in the public research repo, file user logs from labs issues, and credit and link new research in the matching labs repo's README. Trigger: /upstream-scout [target ...|all] [--quick] [--scheduled] [--since ISO], "scout upstream", "what's new in related repos", "check WhateverXe / NullMoth / mt76 for news". Also run by /legion-check (quick) and by the daily scheduled task.
---

Run these in order, without asking, and report briefly at the end (actionable items first). Same steps on Windows, macOS and a cloud run.

Where things are

• Project root (private project-legion): $LEGION_ROOT, else the first that exists of C:\Users\Hackintosh, ~/Hackintosh, ~/src/project-legion, ~/project-legion. It holds research/upstream/watchlist.json (what to follow, edit by hand), state.json (cursors), redaction-map.json (private, never published) and scripts/upstream/scan.py.
• Research repo (public): ~/src/research (clone watchthelight-labs/research if missing). Write-ups go to scout/<target>/<YYYY-MM-DD>.md, run reports to scout/reports/<YYYY-MM-DD>.md, logs to logs/ through tools/ingest.py.
• Labs checkouts: ~/src/<repo> (clone if missing). Commit as watchthelight <admin@watchthelight.org>, lowercase, no AI attribution, no em dashes.
• Targets and their labs repo, credit section and keywords: in the watchlist (xe, nvgfx, mt7925-wifi, mt7925-wifi-native, mt7925-bt, legion-efi, cpu-power, audio, i2c, ite-kbd, cbmr).

1. Prepare. git pull --rebase the project root, the research repo and every labs checkout you will touch (two machines and the GitHub Action push too). Targets: the arguments, else all. With --scheduled, drop a target whose last_run (scan.py status) is under 20 h old; if none are left, stop quietly.

2. Collect. python scripts/upstream/scan.py collect --target T ... [--quick] [--since ISO] --out <scratch>/deltas.json. --quick (from legion-check) means default branch only, no PRs, small discovery, and skip step 5. Read the deltas file, not the console.

3. Triage. Per target, drop noise: commits flagged noise, dependency bumps, CI, translations, README typo fixes, issues that only matched one generic keyword. Keep releases, commits whose title or keywords touch our hardware or our open problems, merged PRs with keyword hits, issues with keyword hits, every discovery candidate, and every labs issue with new comments from other people.

4. Read deeply. For each kept item:

   • Commits and releases: gh api repos/R/compare/<cursor-sha-or-tag>...<new> (or the commit / release body); read the diff of the files that matter, not just titles.
   • Discovery candidates: README, recent commits, licence, whether it runs on real hardware or is a stub.
   • Issues and threads: the full thread.

   Map each one against what is open on our side: open issues in the target's labs repo (gh issue list -R watchthelight-labs/<repo>), the tracker Issues sheet (python scripts/tracker.py show), open watchthelight loops for the project (search_memory). Answer for each: what changed, does it unblock, contradict or duplicate something of ours, can we use it (licence: anything marked no_code, and any ChefKiss code, is ideas only, never code), and how sure we are (High / Medium / Low / Unverified, as CLAUDE.md defines). With more than 5 kept items, spread the reading over parallel subagents (up to 8), each returning that structured answer.

5. Web sweep (skip with --quick). One subagent per target with changes or candidates, about 5 searches from the target's discovery.web list plus what step 4 raised, limited to the window: InsanelyMac, r/hackintosh, Dortania's bugtracker, GitHub discussions, forks with new commits. Same structured answer.

6. Classify every finding: noise, notable (worth knowing), actionable (we should do something: test, port, answer, change a claim), new project (a related repo we didn't know). File discovery verdicts: scan.py seen OWNER/REPO related|noise --target T --note "..."; add a related one to the target's related list in the watchlist with relation and credited: false until step 8 credits it.

7. Record.

   • Write-up per target with findings: scout/<target>/<date>.md in the research repo: what changed, why it matters to us (or doesn't), confidence, and a link for every claim (commit, release, issue, thread). No findings, no file.
   • Logs: for each labs issue in the deltas with new comments that carry code or attachments, python ~/src/research/tools/ingest.py --map <root>/research/upstream/redaction-map.json --issue <url> [--machine <vendor-model slug>]. Pick the slug from the issue's machine field (asus-tuf-gaming-b850-plus-wifi style) when the user has no machine in machines.json yet. A refused file stops that post: look, fix the redactor if it missed a pattern, never hand-edit around it.
   • Tracker: python scripts/tracker.py add-research "<topic>" "<claim>" --url <url> --source-type <GitHub commit|release|issue|forum> --confidence <...> --notes "upstream-scout <date>" for every notable or actionable finding.
   • Labs issues: when a finding bears on an open issue of ours, comment there (short, humanized, link to the source and the write-up).
   • watchthelight: one note per run, "Upstream scout : " (scope project:legion-hackintosh), type open_loop when anything is actionable, else fact; echo the receipt.

8. Credit (auto-publish, Bash's standing decision):

   • Every new project we learned from gets an entry in the target's credit section (credit.heading in the watchlist), in that section's style (table row or bullets line; follow the existing entries' wording and length). If the labs repo has no credit section yet, add ## Credits before ## Licence.
   • A credited project with a new capability that matters to us gets its entry updated (e.g. "internal eDP support since 0.4.0").
   • A README or docs claim the finding makes false gets corrected (status lines, "nobody has", "not possible").
   • Mirrors in also get the same change (NvGfx docs/XE.md; for XeGfx edits also git subtree pull --prefix gpu/xegfx https://github.com/watchthelight-labs/XeGfx.git main in the NvGfx xe checkout).
   • Before each push: python ~/.claude/skills/humanize/scripts/slop_lint.py <file> when it exists, else python <root>/scripts/upstream/lint_public.py <file>; zero hard hits. Then commit, push, and set credited: true in the watchlist.
   • Every public commit URL goes into the report.

9. Finish.

   • scan.py commit <deltas.json> (cursors move only now).
   • scan.py export-public ~/src/research/scout/watchlist.json, python ~/src/research/tools/index.py, python ~/src/research/tools/privacy_check.py --map <root>/research/upstream/redaction-map.json --fix (must end with 0 problems before any push).
   • Run report scout/reports/<date>.md: targets and windows, actionable first, then notable, new projects with verdicts, logs ingested, public edits (commit links), API calls and errors.
   • Commit and push the research repo and the project root (research/upstream/watchlist.json, state.json; never deltas/).
   • Report to Bash in a few lines: actionable items with links, then counts.

Rules

• Public text (credits, comments, write-ups, reports): clear and human, no em dashes, no hype; say what we learned and link it. Never publish an identity: logs only through ingest.py, and the privacy check passes before every research-repo push.
• Never run or build third-party code from a finding before an audit in research/repository-audits/ (CLAUDE.md).
• A finding is not a fact until it is reproduced; keep the confidence honest.
• If gh hits the rate limit, finish with what was collected, note it in the report, and do not move the cursors of targets that were not fully scanned (run scan.py commit on a deltas file trimmed to the finished targets).