feat(upstream): add commit-level triage and weekly watch for forks (#305) (#320)

Forks tracking this template face a weekly "which of these commits do I
actually care about?" question. check_upstream_updates.py answers it at the
file level (version stamps); this adds the commit-level half.

tools/upstream_triage.py walks the commits a fork is behind and splits them
into "worth reviewing" and "probably skip". Work already ported drops off on
its own via git patch-id, commits touching only files the fork removed are set
aside, and SHAs in .github/upstream-wontport.txt stay hidden. It reports and
nothing more - ready-to-run cherry-pick lines, but no merge, push, or PR,
since on a fork "applies cleanly" is not "correct".

.github/workflows/upstream-watch.yml runs it weekly into one rolling issue. It
no-ops on the upstream template (guarded, and pinned by a test) and uses only
the built-in GITHUB_TOKEN, so it can never write outside its own fork. The two
tools point at each other in their output; README, SETUP 8, and CHANGELOG
introduce them together. Tests cover patch-id matching, relevance filtering,
the won't-port list, and the workflow guard - all offline.

Co-authored-by: Angelina Lok <angelina@chattermill.io>
Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>

.github/upstream-wontport.txt

@@ -0,0 +1,12 @@
+# Upstream commits this fork has consciously decided never to port.
+# tools/upstream_triage.py skips anything listed here so it stops re-surfacing
+# in the weekly Upstream watch report. One SHA per line (short or full); text
+# after # is a note.
+#
+# Only for commits you've reviewed and rejected on purpose. Commits you DO
+# port drop off automatically once cherry-picked (patch-id match), so they
+# never need an entry here. Likewise commits that only touch files your fork
+# removed are auto-skipped - you don't need to list those either.
+#
+# This ships empty on the template. Populate it in your own fork, e.g.:
+#   cffacfd   # Danish demo portals - my fork removed them on purpose

.github/workflows/upstream-watch.yml

@@ -0,0 +1,85 @@
+# Weekly upstream triage. Reports only - it NEVER merges, pushes, or edits code.
+#
+# It fetches the upstream template, runs tools/upstream_triage.py to sort the
+# commits this fork lacks into "worth reviewing" vs "probably skip" (dropping
+# cherry-picks already applied and changes that only touch files this fork
+# removed), and writes the result into a single rolling issue. You read it and
+# port anything worth porting by hand.
+#
+# The report/act boundary is deliberate and load-bearing: the report stops at
+# ready-to-run cherry-pick lines and never opens a draft PR or merges. On a
+# fork "applies cleanly" is not "correct" - a commit for portals the fork
+# dropped can cherry-pick fine and still be wrong, and that silent-wrong case
+# is worse than a conflict. Merges stay a human decision, the same posture
+# /apply keeps (it drafts, never submits). Keep it that way.
+#
+# This is the commit-level companion to tools/check_upstream_updates.py, which
+# tracks personalized-file version stamps. Two tools, two questions.
+#
+# Runs only on forks (guarded below), so the upstream template never triggers
+# it against itself - GitHub also leaves inherited workflows disabled on a fork
+# until the owner enables Actions, so the guard is a second fence, not the only
+# one. Token is the built-in GITHUB_TOKEN, scoped to reading contents and
+# writing issues in this repo only: the digest can never be written outside the
+# fork.
+
+name: Upstream watch
+
+on:
+  schedule:
+    - cron: "0 8 * * 1" # 08:00 UTC every Monday
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  triage:
+    name: Triage upstream commits
+    # No-op on the upstream template itself. Pinned by
+    # tests/test_upstream_triage.py so a template clone never runs it by surprise.
+    if: github.repository != 'MadsLorentzen/ai-job-search'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+
+      - name: Fetch upstream template
+        run: |
+          git remote add upstream https://github.com/MadsLorentzen/ai-job-search.git 2>/dev/null || true
+          git fetch --quiet upstream master
+
+      - name: Build triage report
+        run: |
+          {
+            echo "_Last checked: $(date -u '+%Y-%m-%d %H:%M UTC') · [run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})_"
+            echo
+            python tools/upstream_triage.py --remote upstream --branch master
+          } > report.md
+          cat report.md
+
+      - name: Open or update the rolling issue
+        env:
+          # Built-in token is scoped to this repo only, so the digest can never
+          # be written outside the fork.
+          GH_TOKEN: ${{ github.token }}
+          # Pin to this fork. Without it, the `upstream` git remote added above
+          # makes gh's remote resolution target the base repo, so the digest
+          # would land on upstream's tracker instead of the fork's.
+          GH_REPO: ${{ github.repository }}
+        run: |
+          title="Upstream sync watch"
+          existing=$(gh issue list --state open --search "in:title \"$title\"" \
+            --json number,title --jq ".[] | select(.title==\"$title\") | .number" | head -n1)
+          if [ -n "$existing" ]; then
+            gh issue edit "$existing" --body-file report.md
+            echo "Updated issue #$existing"
+          else
+            gh issue create --title "$title" --body-file report.md
+            echo "Created a new rolling issue"
+          fi