fix upstream

Author: KSemenenko

.github/workflows/upstream-watch.yml

@@ -13,6 +13,9 @@ concurrency:
   group: upstream-watch
   cancel-in-progress: false
 
+env:
+  UPSTREAM_WATCH_STATE_FILE: .cache/upstream-watch/upstream-watch-state.json
+
 jobs:
   watch:
     runs-on: ubuntu-latest
@@ -26,22 +29,33 @@ jobs:
         with:
           python-version: "3.12"
 
+      - name: Restore upstream watch state cache
+        id: restore-upstream-watch-state
+        uses: actions/cache/restore@v4
+        with:
+          path: ${{ env.UPSTREAM_WATCH_STATE_FILE }}
+          key: upstream-watch-state-${{ github.repository_id }}-${{ github.ref_name }}-${{ github.run_id }}
+          restore-keys: |
+            upstream-watch-state-${{ github.repository_id }}-${{ github.ref_name }}-
+
+      - name: Seed upstream watch state
+        run: |
+          mkdir -p "$(dirname "${{ env.UPSTREAM_WATCH_STATE_FILE }}")"
+          if [ ! -f "${{ env.UPSTREAM_WATCH_STATE_FILE }}" ]; then
+            cp .github/upstream-watch-state.json "${{ env.UPSTREAM_WATCH_STATE_FILE }}"
+          fi
+
       - name: Validate upstream watch config
         run: python3 scripts/upstream_watch.py --validate-config
 
       - name: Run upstream watch
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: python3 scripts/upstream_watch.py
+        run: python3 scripts/upstream_watch.py --state "${{ env.UPSTREAM_WATCH_STATE_FILE }}"
 
-      - name: Commit updated watch state
-        run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git add .github/upstream-watch-state.json
-          if git diff --cached --quiet; then
-            echo "No state changes to commit."
-            exit 0
-          fi
-          git commit -m "chore: refresh upstream watch state"
-          git push
+      - name: Save upstream watch state cache
+        if: always()
+        uses: actions/cache/save@v4
+        with:
+          path: ${{ env.UPSTREAM_WATCH_STATE_FILE }}
+          key: upstream-watch-state-${{ github.repository_id }}-${{ github.ref_name }}-${{ github.run_id }}

AGENTS.md

@@ -476,15 +476,20 @@ When adding a documentation watch:
 - Watch stable, meaningful overview pages, not random transient pages.
 - Prefer official Microsoft Learn URLs that define platform or framework guidance.
 - Keep issue fan-out reviewable. Upstream-watch automation must track one open maintenance issue per library or skill group, not one permanently open issue per individual documentation page when those pages roll up to the same library refresh.
-- When another upstream change arrives for a library or skill group that already has an open upstream-watch issue, update that existing issue and append the new watch detail instead of creating another open issue.
+- When another upstream change arrives for a library or skill group that already has an open upstream-watch issue, carry the pending watch context forward into the replacement issue so the new issue starts with the full current upstream state.
 - Upstream-watch issue discovery must paginate across the full matching issue set before deciding whether an issue already exists. Do not assume the first page of GitHub issues is sufficient for deduplication or repair.
+- Upstream-watch automation must be issue-driven and must not create `catalog-v*` releases or any other user-facing release noise just because machine-maintained watch state changed.
+- Do not commit routine upstream-watch state refreshes to `main`. Persist automation state in a non-release-triggering channel so scheduled watch runs can open or rotate issues without manufacturing empty catalog releases.
+- When a new upstream event arrives for a library or skill group that already has an open upstream-watch issue, create a fresh issue for the new event and close the older open issue as superseded by the newer one.
 
 ## State File Rules
 
 [`.github/upstream-watch-state.json`](.github/upstream-watch-state.json) is machine-maintained state.
 
 Rules:
 
+- Treat the checked-in `.github/upstream-watch-state.json` file as a bootstrap baseline and local fallback, not as a daily-updated commit log on `main`.
+- Scheduled automation may restore and save runtime watch state outside tracked files, but it must not push routine state refresh commits to the default branch.
 - Do not hand-edit it unless there is a repository emergency.
 - To validate watch config structure without contacting upstream sources, run: