docs(agents): document changelog/TODO fragment system in copilot-instructions

.github/copilot-instructions.md

@@ -1,7 +1,7 @@
 <!-- file: .github/copilot-instructions.md -->
-<!-- version: 2.4.0 -->
+<!-- version: 2.5.0 -->
 <!-- guid: 4d5e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a -->
-<!-- last-edited: 2026-06-13 -->
+<!-- last-edited: 2026-07-21 -->
 
 # github-common — Additional Context
 
@@ -27,3 +27,19 @@ Reusable GitHub Actions workflows, scripts, and multi-repo automation. Language:
 - `scripts/intelligent_sync_to_repos.py` — propagates changes to target repos; use `--dry-run` first
 - `scripts/workflow-debugger.py` — analyzes workflow failures; outputs to `workflow-debug-output/fix-tasks/`
 - All commits must use conventional commit format: `type(scope): description`
+
+## 📝 Changelog & TODO — Use the Fragment System (MANDATORY)
+
+**Do not hand-edit `CHANGELOG.md`, and do not add new tasks straight into the
+`TODO.md` inbox.** Both files are assembled from per-change fragments so that
+parallel PRs never collide on them.
+
+- **`CHANGELOG.md` is assembled, not hand-edited.** Add a fragment under
+  `changelog.d/` (run `scriv create`, or write the Markdown file by hand). The
+  fragments are folded into `CHANGELOG.md` at release time by `scriv`, and a CI
+  check (`changelog-check.yml`) requires one on each PR. See `changelog.d/README.md`.
+- **New `TODO.md` tasks are added via fragments.** Drop a Markdown fragment in
+  `todo.d/` (see `todo.d/README.md`) instead of editing the `## 📥 Inbox`
+  section. `scripts/assemble_todo.py` folds fragments in daily. This is
+  **add-only**: checking a task off or removing it is a normal direct edit of
+  `TODO.md`.

.github/guid-index.json

@@ -59,7 +59,7 @@
     "path": ".github/copilot-instructions.md",
     "guid": "4d5e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a",
     "title": "github-common \u2014 Additional Context",
-    "version": "2.4.0",
+    "version": "2.5.0",
     "header_path": ".github/copilot-instructions.md",
     "path_mismatch": false
   },
@@ -91,7 +91,7 @@
     "path": ".github/instructions/copilot-instructions.md",
     "guid": "4d5e6f7a-8b9c-0d1e-2f3a-4b5c6d7e8f9a",
     "title": "github-common \u2014 Additional Context",
-    "version": "2.4.0",
+    "version": "2.5.0",
     "header_path": ".github/copilot-instructions.md",
     "path_mismatch": true
   },
@@ -979,7 +979,7 @@
     "path": ".github/workflows/reusable-ci.yml",
     "guid": "reusable-ci-2025-09-24-core-workflow",
     "title": "Reusable CI Workflow",
-    "version": "1.13.0",
+    "version": "1.14.0",
     "header_path": ".github/workflows/reusable-ci.yml",
     "path_mismatch": false
   },

changelog.d/document-fragment-system-for-agents.md

@@ -0,0 +1,8 @@
+### Changed
+
+#### Document the changelog/TODO fragment system for AI agents
+
+`CLAUDE.md` and `.github/copilot-instructions.md` now instruct AI agents to use
+the `changelog.d/` and `todo.d/` fragment systems instead of editing
+`CHANGELOG.md` or the `TODO.md` inbox directly, preventing parallel-PR
+collisions on those files.