@acme-skunkworks/agent-skills 1.0.0 → 1.1.0

package/README.md

@@ -16,7 +16,6 @@ npx skills add https://github.com/acme-skunkworks/agent-skills --skill <name> --
 
 ```
 .
-├── .changeset/              # pending changesets + config
 ├── .claude/commands/
 │   └── send-it.md           # all-in-one finisher (stopgap until the send-it skill ships)
 ├── .github/
@@ -24,10 +23,12 @@ npx skills add https://github.com/acme-skunkworks/agent-skills --skill <name> --
 │   │   └── load-repo-config/ # infrastructure/repo-config.yaml → step outputs
 │   └── workflows/
 │       ├── release.yml       # publish-only: build → npm (OIDC) → GitHub Packages (dormant)
-│       └── validate.yml      # PR gate: build & lint, changelog validation, infra tests
+│       └── validate.yml      # PR gate: build & lint, changelog validation, PR-title lint, infra tests
 ├── .husky/                  # git hooks (block main pushes; lint-staged; strip Claude trailer)
 ├── architecture/            # ADRs (sequentially numbered, immutable)
-├── changelog/               # dated per-change release-note entries (companion to CHANGELOG.md)
+├── changelog/               # dated per-change release-note entries (the repo's only changelog)
+├── release-please-config.json      # release-please packages config (single root package)
+├── .release-please-manifest.json   # release-please version manifest
 ├── infrastructure/
 │   ├── repo-config.yaml      # non-secret CI/release knobs
 │   ├── scripts/              # changelog .ts helpers + ensure-*.sh tool bootstraps
@@ -49,4 +50,4 @@ ADRs land under `architecture/` as `NNNN-<slug>.md`. ADR-0001 — the foundation
 
 ## Contributing
 
-See [CLAUDE.md](./CLAUDE.md) for the conventions (Conventional Commits, draft PRs, Changesets per behavioural change).
+See [CLAUDE.md](./CLAUDE.md) for the conventions (Conventional Commits, draft PRs, release-please versioning driven by the PR title).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@acme-skunkworks/agent-skills",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "private": false,
   "description": "Shared agent skills (Claude Code, Cursor) distributed as skills.sh-compatible bundles.",
   "keywords": [
@@ -28,20 +28,17 @@
   ],
   "scripts": {
     "changelog:finalise": "tsx infrastructure/scripts/finalise-changelog.ts",
-    "changeset": "changeset",
-    "changeset:version": "changeset version && pnpm changelog:finalise",
     "lint:sh": "bash -c 'if command -v shellcheck >/dev/null 2>&1; then shellcheck scripts/*.sh infrastructure/scripts/*.sh .husky/pre-commit .husky/pre-push .husky/commit-msg; elif [ \"$(uname -s)\" = \"Darwin\" ]; then echo \"⚠️  shellcheck not installed — skipping. Install: brew install shellcheck\"; else echo \"⚠️  shellcheck not installed — skipping. Install: apt-get install shellcheck\"; fi'",
     "lint:workflows": "actionlint",
     "lint:yaml": "yamllint .",
     "prepare": "husky",
-    "release": "changeset publish",
     "release:manual": "npm publish --access public --provenance=false",
     "release:manual:dry": "npm publish --access public --provenance=false --dry-run",
     "test": "vitest run",
     "test:sh": "bash -c 'if command -v bats >/dev/null 2>&1; then bats infrastructure/tests/*.bats; elif [ \"$(uname -s)\" = \"Darwin\" ]; then echo \"⚠️  bats not installed — skipping. Install: brew install bats-core\"; else echo \"⚠️  bats not installed — skipping. Install: apt-get install bats\"; fi'",
     "test:watch": "vitest",
     "validate:changelog": "tsx infrastructure/scripts/validate-changelog.ts",
-    "version": "changeset version"
+    "validate:skills": "tsx infrastructure/scripts/validate-skills.ts"
   },
   "lint-staged": {
     "**/*.sh": [
@@ -58,7 +55,6 @@
     ]
   },
   "devDependencies": {
-    "@changesets/cli": "^2.31.0",
     "@types/node": "^25.6.0",
     "gray-matter": "^4.0.3",
     "husky": "^9.1.7",

package/skills/changelog/README.md

@@ -0,0 +1,59 @@
+# changelog
+
+Author, refresh, or repair the changelog entry for the current branch under
+`changelog/YYYYMMDD-HHMMSS-<slug>.md` — derive metadata, write the frontmatter and
+grouped body, run the deterministic enrichment scripts, and validate against the
+changelog contract.
+
+## Install
+
+From any consumer repo:
+
+```bash
+npx skills add https://github.com/acme-skunkworks/agent-skills --skill changelog --agent claude-code --agent cursor --copy
+```
+
+`--copy` writes real files so the bundle is portable. Don't use `-g` / `--global`
+— the installation should live in the consumer repo.
+
+## Configure
+
+The shipped [`config.json`](config.json) carries **ACME Skunkworks defaults** —
+update them for your organisation on install, or issue-ID detection and Linear
+links will be wrong. A neutral [`config.example.json`](config.example.json) ships
+alongside it as a template — copy it over `config.json` or edit `config.json`
+directly.
+
+| Key | Meaning | Default |
+| --- | --- | --- |
+| `issueKeys` | Team-key prefixes used to recognise issue IDs in the branch and body. Keep legacy keys so old branches still match. | `["ASW", "AKW", "SKW"]` |
+| `linearWorkspaceSlug` | Linear workspace slug for issue links (`https://linear.app/<slug>/issue/<id>`). | `"goose-and-hobbes"` |
+| `baseBranch` | Trunk the branch diff is taken against (`origin/<baseBranch>`); `BASE_REF` env overrides per-run. | `"main"` |
+
+## Requirements
+
+- **Node.js ≥22** for the bundled scripts. They use **only Node built-ins** — no
+  `npm install`, no build step.
+- The **`git` CLI** for branch and diff analysis.
+- **pnpm** *only* for the optional `preflight-changelog-ci.mjs` step (Node/lockfile
+  CI-parity). Skip that step if your repo doesn't use pnpm.
+
+## What it does
+
+Detects the branch's existing entry (idempotent update-vs-create), derives the
+metadata from git and the diff, writes the frontmatter + grouped/categorised body,
+runs the enrichment scripts (`set-affected-packages.mjs`, `add-links.mjs`), and
+validates with `validate-changelog.mjs`. `created_at` is set once and never
+overwritten; `stats` and the post-merge fields are left blank for the release step.
+
+Run standalone via `/changelog` (writes/validates, leaves the entry **uncommitted**)
+or as the changelog step inside a ship flow. See [`SKILL.md`](SKILL.md) for the
+six-step process and [`references/changelog-contract.md`](references/changelog-contract.md)
+for the full frontmatter schema and field-ownership rules.
+
+## Scripts and tests
+
+The bundled scripts are the **zero-dependency `.mjs`** set (Node built-ins only),
+deliberately chosen so the bundle is drop-in with no tooling. Their **unit tests
+are maintained in the [`agent-skills`](https://github.com/acme-skunkworks/agent-skills)
+repo**, not bundled into the skill — see that repo's test suite for coverage.

package/skills/changelog/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: changelog
+description: >-
+  Author, refresh, or repair the changelog entry for the current branch — derive
+  metadata, write the frontmatter and grouped body, run the deterministic
+  enrichment scripts, and validate against the changelog contract. Use when asked
+  to write or update a changelog entry, refresh an entry after new commits, or as
+  the changelog step inside a ship/PR flow. Detects an existing entry for the
+  branch (idempotent update-vs-create), keeps `created_at` sacred, leaves
+  post-merge fields to the release step, and validates with a zero-dependency
+  Node script.
+license: MIT
+compatibility: >-
+  Requires Node.js ≥22 for the bundled scripts (no npm dependencies — Node
+  built-ins only) and the `git` CLI for branch/diff analysis. The optional
+  `preflight-changelog-ci.mjs` step assumes the consumer repo uses pnpm with a
+  committed lockfile; skip it if yours does not.
+metadata:
+  version: 0.1.1
+allowed-tools: Write, Read, Edit, Glob, Grep, Bash(git:*), Bash(node:*), Bash(pnpm:*)
+---
+
+# changelog
+
+Generate or update the changelog entry for the current branch under
+`changelog/YYYYMMDD-HHMMSS-<slug>.md`: derive its metadata from git and the diff,
+write the frontmatter and a grouped, categorised body, run the deterministic
+enrichment scripts, then validate the result.
+
+This skill is the single source of truth for **what a valid changelog entry is**
+— the frontmatter schema, the field-ownership boundaries, idempotent
+update-vs-create, and the validation gate. The same contract is enforced
+downstream by a consumer repo's CI and relied on by a release-orchestrator that
+finalises the post-merge fields, so the authoring rules live here once.
+
+It is invoked two ways:
+
+- **Standalone** (`/changelog`) — author, refresh, or repair this branch's entry
+  and leave it **uncommitted** in the working tree for review. No commit, push,
+  or PR.
+- **Inside a ship flow** (e.g. a `/send-it`) — the changelog step that runs
+  before push; the ship flow **commits** the entry, pushes, and opens the PR.
+
+## Configuration
+
+Three knobs live in [`config.json`](config.json) beside this file; the bundled
+scripts read it automatically. Edit your copied `config.json` to match the
+consuming repo (a neutral [`config.example.json`](config.example.json) ships as a
+template):
+
+| Key | Meaning | Default |
+| --- | --- | --- |
+| `issueKeys` | Team-key prefixes used to recognise issue IDs in the branch and body. The issue-ID regex is built from these; keep legacy keys so old branches still match. | `["ASW", "AKW", "SKW"]` |
+| `linearWorkspaceSlug` | Linear workspace slug used to build issue links (`https://linear.app/<slug>/issue/<id>`). | `"goose-and-hobbes"` |
+| `baseBranch` | The trunk the branch diff is taken against (`origin/<baseBranch>`). Overridable per-run via the `BASE_REF` env var. | `"main"` |
+
+All bundled scripts use only Node built-ins — no `npm install`, no build step.
+They operate on the **consumer repo's root `changelog/` directory** (run them
+from the repo root).
+
+## Running it
+
+### Step 1 — Detect an existing entry (idempotency)
+
+Grep `changelog/` for a file whose frontmatter contains `branch: "<current-branch>"`.
+If exactly one matches, you are in **update mode**: preserve its `created_at` and
+filename, rewrite the rest. Otherwise you are in **create mode**.
+
+### Step 2 — Analyse the branch
+
+- `git log origin/<base>..HEAD --pretty=full` — full commit list including bodies
+  and trailers.
+- `git diff origin/<base>...HEAD --name-only` — changed files, for grouping the
+  body by package.
+
+`<base>` is `config.json`'s `baseBranch` (default `main`). Fetch it first
+(`git fetch origin <base>`) so the diff is accurate — skip the fetch if the
+caller already did it (e.g. a ship flow fetches in its preflight step).
+
+### Step 3 — Derive metadata
+
+| Field          | How to derive                                                                                                                                          |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `issues`       | Match the issue-ID regex (built from `issueKeys`) against the branch name (upper-cased) and against commit subjects/bodies. Deduplicate.               |
+| `author`       | `git config user.email`.                                                                                                                               |
+| `co_authors`   | Parse `Co-authored-by: Name <email>` trailers across all branch commits. Store the email or `Name <email>` form. Empty array if none.                  |
+| `category`     | Infer from commit subjects and diff: `feature`, `fix`, `chore`, `docs`, `refactor`, `perf`. If ambiguous, ask the user to confirm.                     |
+| `breaking`     | Infer from `BREAKING CHANGE:` trailers, `!` in conventional-commit subjects, or removal of public surfaces. If unclear, ask the user. Default `false`. |
+| `release_note` | One-sentence user-facing summary distinct from `title`. Optional — leave blank if the change has no public-facing impact (chore, internal refactor).   |
+
+**Field ownership** — what this skill authors vs. what it must leave alone is the
+crux of the contract; see [`references/changelog-contract.md`](references/changelog-contract.md)
+for the full rules. In short:
+
+- **Authored here:** `title`, `release_note`, `category`, `breaking`, `issues`,
+  `co_authors`, `author`, and `affected_packages` (written by the enrichment
+  script in Step 5, not hand-edited).
+- **`created_at` is sacred** — set once on create (UTC time of first run); on
+  update, preserve it verbatim.
+- **Never authored here:** `stats` (`files_changed`, `loc_added`, `loc_removed`)
+  and the post-merge fields `merged_at` / `commit` / `merge_strategy`. A release
+  step finalises them from canonical GitHub PR data after merge. Emit them as
+  blank placeholders on create; leave existing values untouched on update.
+- `pr` is back-filled by the ship flow once the PR exists (not here when
+  standalone).
+
+The skill **emits the derived `issues` array** as a handoff — a ship flow reuses
+it for the PR body and any Linear writeback (e.g. via a `linear-sync` skill).
+
+### Step 4 — Generate the body
+
+Group bullets by package, categorised under `## Added` / `## Changed` / `## Fixed`.
+Only include headings that have entries. For multi-package changes use
+`**<pkg-name>:**` subheaders.
+
+If `breaking: true`, the body MUST start with a `## Breaking` section describing
+the change and the migration path.
+
+### Step 5 — Write or update the file
+
+**Filename:** `changelog/YYYYMMDD-HHMMSS-<slug>.md`, where the timestamp is
+`created_at` (UTC time of first run) and the slug derives from `title` (lowercase,
+non-alphanumerics → `-`, collapse repeats, ~60-char cap on a word boundary).
+
+**Always quote timestamp strings** in YAML (`created_at: "2026-04-26T13:24:00Z"`).
+Unquoted ISO timestamps parse as Date objects and gain `.000Z` millis on the
+enrichment round-trip; quoting keeps them lossless.
+
+**On update:** preserve `created_at` and the filename; rewrite `title`,
+`release_note`, `category`, `breaking`, `co_authors`, `issues`, and the body;
+leave `merged_at` / `commit` / `merge_strategy` / `stats` alone; update `pr` only
+if it was blank and a PR now exists.
+
+Use the frontmatter field order shown in
+[`references/changelog-contract.md`](references/changelog-contract.md), emitting
+`affected_packages: []` as a placeholder — the script fills it in place.
+
+Then run the two deterministic enrichment scripts from the consumer repo root
+(both idempotent; they match the entry by its `branch:` frontmatter and leave the
+post-merge fields blank):
+
+```bash
+node skills/changelog/scripts/set-affected-packages.mjs   # writes affected_packages from the branch diff
+node skills/changelog/scripts/add-links.mjs               # rewrites bare issue IDs in the body to Linear URLs
+```
+
+Adjust the path prefix if you installed the skill to a different location.
+
+### Step 6 — Validate against the contract
+
+This is the gate:
+
+```bash
+node scripts/preflight-changelog-ci.mjs   # optional: checks Node vs engines/.nvmrc, then pnpm install --frozen-lockfile
+node scripts/validate-changelog.mjs       # validates frontmatter schema, filename format, field types, ISO timestamps, Breaking section, issue IDs
+```
+
+`preflight-changelog-ci.mjs` is optional and pnpm-specific — skip it if the
+consumer repo doesn't use pnpm. On failure, stop and fix the entry before
+continuing — do not hand a malformed entry to the ship flow.
+
+## Standalone vs inside a ship flow
+
+- **Standalone (`/changelog`)** runs Steps 1–6 and then **reports**, leaving the
+  entry **uncommitted** in the working tree for the user to review and commit. It
+  never pushes or opens a PR.
+- **Inside a ship flow** the same steps run before push; the ship flow then
+  commits the entry (`docs(changelog): <title>`), pushes, and opens or updates the
+  PR, back-filling `pr:` once the PR number is known.
+
+## Implementation
+
+The enrichment and validation scripts live under [`scripts/`](scripts/) in this
+bundle and run on plain Node (no npm dependencies, no build step):
+
+- `scripts/set-affected-packages.mjs` — writes `affected_packages` from the branch diff.
+- `scripts/add-links.mjs` — rewrites bare issue IDs in the body to Linear URLs.
+- `scripts/preflight-changelog-ci.mjs` — optional Node/lockfile CI-parity check (pnpm).
+- `scripts/validate-changelog.mjs` — validates the entry against the contract.
+
+They share helpers under `scripts/lib/` (`changelog.mjs`, `derive-packages.mjs`,
+`frontmatter.mjs`, `config.mjs`). The post-merge finalisation of `stats` /
+`merged_at` / `commit` / `merge_strategy` is owned by the release-orchestrator and
+is **not** invoked here.
+
+> **Note for adopters:** unit tests for these scripts are maintained in the
+> `agent-skills` repo (not bundled into the skill). See the skill's README.

package/skills/changelog/config.example.json

@@ -0,0 +1,5 @@
+{
+  "issueKeys": ["ABC", "XYZ"],
+  "linearWorkspaceSlug": "your-workspace-slug",
+  "baseBranch": "main"
+}

package/skills/changelog/config.json

@@ -0,0 +1,5 @@
+{
+  "issueKeys": ["ASW", "AKW", "SKW", "SK"],
+  "linearWorkspaceSlug": "goose-and-hobbes",
+  "baseBranch": "main"
+}

package/skills/changelog/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@acme-skunkworks/skill-changelog",
+  "version": "0.1.1",
+  "private": true,
+  "description": "Agent skill: author, refresh, or repair the per-branch changelog entry — derive metadata, write the frontmatter and grouped body, run the deterministic enrichment scripts, and validate against the changelog contract.",
+  "keywords": [
+    "agent-skill",
+    "claude-code",
+    "cursor",
+    "changelog",
+    "release-notes",
+    "changesets"
+  ],
+  "homepage": "https://github.com/acme-skunkworks/agent-skills/tree/main/skills/changelog#readme",
+  "bugs": {
+    "url": "https://github.com/acme-skunkworks/agent-skills/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/acme-skunkworks/agent-skills.git",
+    "directory": "skills/changelog"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Rob Easthope",
+    "url": "https://github.com/RobEasthope"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

package/skills/changelog/references/changelog-contract.md

@@ -0,0 +1,121 @@
+# Changelog entry contract
+
+The full frontmatter schema and field-ownership rules the `changelog` skill
+enforces. The bundled `scripts/validate-changelog.mjs` is the executable form of
+this contract.
+
+## Frontmatter schema
+
+Preserve this field order. Emit `affected_packages: []` as a placeholder — the
+enrichment script fills it in place.
+
+```yaml
+---
+title: "Concise summary"
+release_note: "One-sentence user-facing summary"
+created_at: "2026-04-26T13:24:00Z"
+merged_at:
+branch: "<current-branch>"
+pr:
+commit:
+merge_strategy:
+author: "you@example.com"
+co_authors: []
+category: feature
+breaking: false
+issues: ["ASW-123"]
+affected_packages: []
+stats:
+  files_changed:
+  loc_added:
+  loc_removed:
+---
+```
+
+## Required fields
+
+`validate-changelog.mjs` requires: `title`, `created_at`, `branch`, `author`,
+`category`, `breaking`, `co_authors`, and a `stats` object. Other fields are
+validated **by type when present** but may be blank placeholders until enrichment.
+
+## Field types and rules
+
+| Field | Rule |
+| ----- | ---- |
+| `title` | Non-empty string. |
+| `release_note` | String or `null`/blank when present. |
+| `created_at` | ISO 8601 UTC with `Z` suffix, quoted. **Set once; never overwritten.** |
+| `merged_at` | ISO 8601 UTC with `Z` suffix when set; blank until release. |
+| `branch` | Non-empty string — the stable lookup key for enrichment. |
+| `pr` | Integer when set; blank until the PR exists. |
+| `commit` | 7-char hex SHA when set; blank until merge. |
+| `merge_strategy` | One of `merge`, `rebase`, `squash`; blank until merge. |
+| `author` | Non-empty string (an email). |
+| `co_authors` | Array of strings (`[]` when none). |
+| `category` | One of `feature`, `fix`, `chore`, `docs`, `refactor`, `perf`. |
+| `breaking` | Boolean. If `true`, the body MUST contain a `## Breaking` section. |
+| `issues` | Array of strings, each matching `[A-Z]{2,}-\d+`. |
+| `affected_packages` | Array of strings (`[]` when unpopulated). |
+| `stats.{files_changed,loc_added,loc_removed}` | Non-negative integers when set; blank until release. |
+
+The filename must match `YYYYMMDD-HHMMSS-<slug>.md` (slug `[a-z0-9-]+`), and the
+body must contain at least one of `## Breaking` / `## Added` / `## Changed` /
+`## Fixed`.
+
+## Field ownership boundaries
+
+Four owners, never overlapping:
+
+1. **The author (this skill).** `title`, `release_note`, `category`, `breaking`,
+   `issues`, `co_authors`, `author`. Re-derived on every run.
+2. **The enrichment scripts (deterministic, pre-merge).** `affected_packages` —
+   `set-affected-packages.mjs` always overwrites it from the latest branch diff,
+   so it tracks added commits. `add-links.mjs` rewrites bare issue IDs in the body
+   to Linear links.
+3. **The release-orchestrator (post-merge, privileged).** `merged_at`, `commit`,
+   `merge_strategy`, and authoritative `stats`, plus the published `version` where
+   a consumer adds one. Emit these as blank placeholders; never hand-edit them —
+   so an in-flight PR never shows numbers that drift as commits land.
+4. **The ship flow (`/send-it`).** `pr` — back-filled when the PR is opened; left
+   blank by the author and untouched by enrichment until then.
+
+`branch` is set by the author at create time and is the stable lookup key for
+enrichment.
+
+`created_at` is **sacred**: set once at create time, preserved verbatim on every
+update. The release step refuses to finalise an entry without it.
+
+## Body structure
+
+```markdown
+## Breaking <!-- only when breaking: true -->
+
+- Description and migration steps
+
+## Added
+
+- Description
+
+## Changed
+
+- ...
+
+## Fixed
+
+- ...
+```
+
+Only include `Added` / `Changed` / `Fixed` headings that have entries.
+
+## Notes for adopters
+
+- **Single-package repos** can drop `affected_packages` from the schema (there is
+  only one package) and skip `set-affected-packages.mjs`. The validator treats
+  `affected_packages` as optional-when-present, so leaving it out is fine — but
+  if you keep `validate-changelog.mjs` as shipped, it still requires `branch`,
+  `author`, `co_authors`, and `stats`.
+- **Adding a `version` field.** A single-versioned package may add `version` to
+  record the release each entry shipped in; that is owned by the release step,
+  alongside the other post-merge fields.
+- The `issueKeys`, `linearWorkspaceSlug`, and `baseBranch` knobs in `config.json`
+  are the only repo-specific inputs; everything else in the contract is generic.

package/skills/changelog/scripts/add-links.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+import { loadConfig } from "./lib/config.mjs";
+import { readdirSync, readFileSync, writeFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const CHANGELOG_DIR = "changelog";
+const { linearWorkspaceSlug: WORKSPACE, issueKeys: TEAM_KEYS } = loadConfig();
+
+/**
+ * Escape regex metacharacters so a configured key such as `C++` or `MY.KEY`
+ * can't throw at construction or silently widen the match.
+ * @param {string} s
+ */
+function escapeRegex(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// `null` when no issue keys are configured: an empty alternation would match the
+// empty string before every `-<digits>` and inject bogus links (e.g. `-2`).
+const ISSUE_RE =
+  TEAM_KEYS.length > 0
+    ? new RegExp(`\\b(?:${TEAM_KEYS.map(escapeRegex).join("|")})-\\d+\\b`, "g")
+    : null;
+const FENCE_RE = /```[\s\S]*?```/g;
+const INLINE_CODE_RE = /`[^`]*`/g;
+const ALREADY_LINKED_RE = /\[[^\]]*\]\([^)]*\)/g;
+
+function buildUrl(id) {
+  return `https://linear.app/${WORKSPACE}/issue/${id}`;
+}
+
+function rewriteBody(body) {
+  if (!ISSUE_RE) {
+    return body;
+  }
+
+  // Mask fenced/inline code and existing links so issue-like text inside them
+  // isn't linkified. Tokens are delimited with NUL bytes, which cannot occur in
+  // a UTF-8 text file, so a token can never collide with real prose on restore
+  // (the previous bare `FENCE0`/`INLINE1`/`LINK2` tokens could).
+  const masks = [];
+  const mask = (m) => {
+    masks.push(m);
+    return `\x00CR_MASK_${masks.length - 1}\x00`;
+  };
+
+  const masked = body
+    .replace(FENCE_RE, mask)
+    .replace(INLINE_CODE_RE, mask)
+    .replace(ALREADY_LINKED_RE, mask)
+    .replace(ISSUE_RE, (id) => `[${id}](${buildUrl(id)})`);
+
+  return masked.replace(/\x00CR_MASK_(\d+)\x00/g, (_, i) => masks[Number(i)]);
+}
+
+function splitFrontmatter(raw) {
+  // Match the opening/closing `---` fences with either LF or CRLF endings so a
+  // file authored on Windows isn't treated as having no frontmatter (which
+  // would let `rewriteBody` rewrite the frontmatter region too).
+  const match = raw.match(/^---\r?\n[\s\S]*?\r?\n---\r?\n/);
+  if (!match) {
+    return { fm: "", body: raw };
+  }
+
+  return { fm: match[0], body: raw.slice(match[0].length) };
+}
+
+let stat;
+try {
+  stat = statSync(CHANGELOG_DIR);
+} catch {
+  console.error(`changelog directory not found: ${CHANGELOG_DIR}`);
+  process.exit(2);
+}
+
+if (!stat.isDirectory()) {
+  console.error(`${CHANGELOG_DIR} is not a directory`);
+  process.exit(2);
+}
+
+const files = readdirSync(CHANGELOG_DIR)
+  .filter((n) => n.endsWith(".md") && n !== "README.md")
+  .map((n) => join(CHANGELOG_DIR, n));
+
+let touched = 0;
+for (const file of files) {
+  const raw = readFileSync(file, "utf8");
+  const { fm, body } = splitFrontmatter(raw);
+  const next = rewriteBody(body);
+  if (next !== body) {
+    writeFileSync(file, fm + next);
+    touched++;
+    console.log(`rewrote: ${file}`);
+  }
+}
+
+console.log(`Linear link rewriting complete. ${touched} file(s) updated.`);

package/skills/changelog/scripts/lib/changelog.mjs

@@ -0,0 +1,46 @@
+// Shared helpers for locating changelog entries on disk.
+//
+// `findEntryByBranch` is the one entry-lookup rule the enrichment scripts share,
+// so the rule can't drift between callers — the same reasoning that produced
+// derive-packages.mjs.
+
+import { parseFrontmatter } from "./frontmatter.mjs";
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const DEFAULT_CHANGELOG_DIR = "changelog";
+
+/**
+ * Find the changelog entry whose frontmatter `branch:` equals `branch`.
+ * @param {string} branch the branch name to match against the `branch:` field
+ * @param {string} [changelogDir] directory to scan (default: "changelog")
+ * @returns {string|null} the matching entry's path, or null if none matches
+ */
+export function findEntryByBranch(
+  branch,
+  changelogDir = DEFAULT_CHANGELOG_DIR,
+) {
+  let names;
+  try {
+    names = readdirSync(changelogDir);
+  } catch (err) {
+    // A repo with no `changelog/` directory yet means "no entry found", not a
+    // crash — callers (e.g. set-affected-packages.mjs) already handle null.
+    if (err.code === "ENOENT") {
+      return null;
+    }
+    throw err;
+  }
+
+  const files = names
+    .filter((n) => n.endsWith(".md") && n !== "README.md")
+    .map((n) => join(changelogDir, n));
+  for (const entryPath of files) {
+    const { data } = parseFrontmatter(readFileSync(entryPath, "utf8"));
+    if (data?.branch === branch) {
+      return entryPath;
+    }
+  }
+
+  return null;
+}