Fix upstream watch grouping and refresh AI skills

.github/upstream-watch.ai.json

@@ -665,7 +665,7 @@
     },
     {
       "id": "agent-framework-docs-tutorials-workflows-workflow-builder-with-factories",
-      "source": "https://raw.githubusercontent.com/MicrosoftDocs/semantic-kernel-docs/main/agent-framework/tutorials/workflows/workflow-builder-with-factories.md",
+      "source": "https://learn.microsoft.com/agent-framework/workflows/workflows",
       "skills": [
         "dotnet-microsoft-agent-framework"
       ]
@@ -1078,7 +1078,7 @@
     },
     {
       "id": "agent-framework-docs-user-guide-workflows-shared-states",
-      "source": "https://raw.githubusercontent.com/MicrosoftDocs/semantic-kernel-docs/main/agent-framework/user-guide/workflows/shared-states.md",
+      "source": "https://learn.microsoft.com/agent-framework/workflows/state",
       "skills": [
         "dotnet-microsoft-agent-framework"
       ]

AGENTS.md

@@ -462,6 +462,9 @@ 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.
+- 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.
 
 ## State File Rules
 

CONTRIBUTING.md

@@ -402,6 +402,7 @@ For normal config entries, every watch entry must define:
 
 The watcher derives `kind`, `id`, `name`, source coordinates, and default `notes`.
 You can still override those fields explicitly, but do it only when the default output would be unclear.
+Issues are deduplicated at the library or skill-group level, so related documentation pages should normally roll up into one open upstream issue instead of one issue per page.
 
 For project-specific libraries, the `skills` list must point to the dedicated project skill.
 Do not use umbrella skills such as `dotnet`, `dotnet-architecture`, or `dotnet-orleans` as placeholders for a concrete library watch.

README.md

@@ -336,6 +336,7 @@ Those files are the human-maintained source of truth for:
 - GitHub release streams that should trigger skill review
 - documentation pages that should trigger skill review
 - which `dotnet-*` skills are affected by each upstream change
+- how multiple page-level watches roll up into one open upstream issue per library or skill group
 
 Each named shard file has exactly two lists:
 
@@ -350,7 +351,7 @@ flowchart LR
   B --> C["Run dry-run and sync-state-only once"]
   C --> D["Scheduled upstream-watch.yml runs upstream_watch.py daily"]
   D --> E["GitHub release or documentation change is detected"]
-  E --> F["Automation opens or updates an upstream issue"]
+  E --> F["Automation opens or updates one grouped upstream issue per library or skill set"]
   F --> G["A human or agent updates skills/ and docs"]
   G --> H["Changes merge to main"]
   H --> I["04:00 UTC release pipeline publishes catalog, site, and tool"]