From 85d56e01c069dba457b775300987d180e5f21cd5 Mon Sep 17 00:00:00 2001
From: Johnathan Falk <johnathan.falk@gmail.com>
Date: Tue, 21 Jul 2026 12:05:12 -0400
Subject: [PATCH] docs(agents): document changelog/TODO fragment system in
 copilot-instructions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The changelog.d/ and todo.d/ fragment systems were documented in CLAUDE.md but
not in .github/copilot-instructions.md — the detailed file CLAUDE.md points
agents to. Add a "Use the Fragment System" section so agents that follow the
pointer find the rule: use changelog.d/ and todo.d/ fragments instead of editing
CHANGELOG.md / the TODO.md inbox directly.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013vU67T2LJDCbYTBs9ZFAf2
---
 .github/copilot-instructions.md               | 20 +++++++++++++++++--
 .github/guid-index.json                       |  6 +++---
 .../document-fragment-system-for-agents.md    |  8 ++++++++
 3 files changed, 29 insertions(+), 5 deletions(-)
 create mode 100644 changelog.d/document-fragment-system-for-agents.md

diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index 6e9a2c68..5d9cd3da 100644
--- a/.github/copilot-instructions.md
+++ b/.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`.
diff --git a/.github/guid-index.json b/.github/guid-index.json
index 51d86721..0e185eb9 100644
--- a/.github/guid-index.json
+++ b/.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
   },
diff --git a/changelog.d/document-fragment-system-for-agents.md b/changelog.d/document-fragment-system-for-agents.md
new file mode 100644
index 00000000..84ac9c8f
--- /dev/null
+++ b/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.