From 431e27d822d53dd6515618f7782da9f23de7e09d Mon Sep 17 00:00:00 2001
From: John Osumi <931193+sumitake@users.noreply.github.com>
Date: Thu, 24 Sep 2026 20:45:30 -0700
Subject: [PATCH] docs: correct stale comments left over from prior refactors

- build-changelog.py: the module-level DESIGN comment still described
  the old positional-insertion strategy (insert BETWEEN [Unreleased]
  and the first ### heading). The compiler has used boundary-marker
  replacement (FRAGMENT_BLOCK_START/END) for a while now, and the
  function's own docstring already documents that correctly - only
  the top-of-file comment was stale.
- build_skills.py: PACKAGES_FIELD_RE only matches the inline bracket
  form (`packages: [a, b]`); the comment claiming block-list support
  was never accurate for this regex. Also drop --package's help text
  reference to an "_active filter" that resolve_packages() no longer
  has (there is now exactly one supported package).
- 2026-07-12 license plan doc: fix a script-name typo
  (build_changelog.py -> build-changelog.py) in a verification
  command block.

No behavior change: build_skills.py --check and the build-changelog
unit tests (24 tests) pass identically before and after.
---
 .../plans/2026-07-12-agent-collab-v3.1.0-license.md   |  2 +-
 scripts/build-changelog.py                            | 11 ++++++-----
 scripts/build_skills.py                               |  6 +++---
 3 files changed, 10 insertions(+), 9 deletions(-)

diff --git a/docs/superpowers/plans/2026-07-12-agent-collab-v3.1.0-license.md b/docs/superpowers/plans/2026-07-12-agent-collab-v3.1.0-license.md
index a574e0ac..037bff3a 100644
--- a/docs/superpowers/plans/2026-07-12-agent-collab-v3.1.0-license.md
+++ b/docs/superpowers/plans/2026-07-12-agent-collab-v3.1.0-license.md
@@ -492,7 +492,7 @@ Run:
 ```bash
 python3 scripts/test_check_release_consistency.py
 python3 scripts/check_release_consistency.py
-python3 scripts/build_changelog.py --dry-run
+python3 scripts/build-changelog.py --dry-run
 ```
 
 Expected: all commands PASS and dry-run displays the v3.1.0 fragment without modifying `CHANGELOG.md`.
diff --git a/scripts/build-changelog.py b/scripts/build-changelog.py
index 028f3add..29904d60 100644
--- a/scripts/build-changelog.py
+++ b/scripts/build-changelog.py
@@ -32,11 +32,12 @@
     reverse order puts the most recently landed change nearest the top of
     ``[Unreleased]`` — matching Keep a Changelog's most-recent-on-top
     convention instead of burying it at the bottom of the section.
-  * The compiler inserts fragments BETWEEN the ``## [Unreleased]`` line and
-    the first ``###`` sub-heading (or end of section if no sub-headings).
-    Existing inline entries under ``## [Unreleased]`` are PRESERVED below the
-    inserted fragment block. This lets historical entries continue to live in
-    CHANGELOG.md while new entries land via fragments going forward.
+  * The compiler replaces the auto-generated block delimited by the
+    ``<!-- changelog-fragments ... -->`` markers under ``## [Unreleased]``
+    (or inserts that block immediately after the header if the markers are
+    absent). Existing inline entries outside the markers are PRESERVED. This
+    lets historical entries continue to live in CHANGELOG.md while new entries
+    land via fragments going forward.
 
 LIMITATIONS
   * Does NOT migrate existing inline entries. That's deliberate per the M1
diff --git a/scripts/build_skills.py b/scripts/build_skills.py
index f325aaa0..ff66256a 100644
--- a/scripts/build_skills.py
+++ b/scripts/build_skills.py
@@ -116,8 +116,8 @@
 PLACEHOLDER_RE = re.compile(r"\{\{\s*([a-z][a-z0-9_]*)\s*\}\}")
 # Matches the opening ``---`` frontmatter block of a spec.
 FRONTMATTER_RE = re.compile(r"^---\n(.*?)\n---\n", re.DOTALL)
-# Matches a ``packages:`` list field inside frontmatter YAML (simple inline or
-# block list; we use a lightweight regex rather than a YAML parser to keep the
+# Matches a ``packages:`` list field inside frontmatter YAML (inline bracket
+# form only; we use a lightweight regex rather than a YAML parser to keep the
 # build stdlib-only).  Captures the value portion after "packages:".
 PACKAGES_FIELD_RE = re.compile(
     r"^packages:\s*\[([^\]]*)\]", re.MULTILINE
@@ -345,7 +345,7 @@ def main() -> int:
     )
     parser.add_argument(
         "--package", default=None,
-        help="generate only for the named package (skip the _active filter)",
+        help="generate only for the named package",
     )
     parser.add_argument(
         "--spec", default=None,