From 286ddbf6f8c43efbb295d33d717bb9cb213421b4 Mon Sep 17 00:00:00 2001
From: TzuHsuan <96853116+TzuH-Hsu@users.noreply.github.com>
Date: Wed, 16 Sep 2026 13:35:27 +0800
Subject: [PATCH] feat: issue labeler logic moves to scripts/issue-labeler.js
 with a durable test
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The labeler was the one workflow carrying logic — ~150 lines of JS inline
in the YAML, testable only by extracting it by hand. The logic is now a
plain Node module with pure functions and one run() entry point; the
workflow checks out the default branch (pinned checkout, no credentials)
and calls it in two lines. labels.yml is read from the checkout instead
of the API. scripts/issue-labeler.test.js pins the behaviour (12 cases,
node built-ins only) and runs from make check; in CI a missing node
fails, locally it skips loudly. Hygiene rule 1 and AGENTS.md name the
shape; ADR-0008 records it; check-label-forms.sh follows the constants
to the script.

Closes #49

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 .github/CODEOWNERS                            |   1 +
 .github/workflows/issue-labeler.yml           | 229 ++----------------
 AGENTS.md                                     |   4 +-
 CONTRIBUTING.md                               |   1 +
 Makefile                                      |   1 +
 ...DR-0008-event-workflow-logic-in-scripts.md |  30 +++
 docs/adr/README.md                            |   1 +
 docs/template/architecture.md                 |   7 +-
 docs/template/design-principles.md            |   2 +-
 docs/template/upgrading.md                    |   2 +-
 scripts/check-issue-labeler.sh                |  29 +++
 scripts/check-label-forms.sh                  |  45 +++-
 scripts/issue-labeler.js                      | 216 +++++++++++++++++
 scripts/issue-labeler.test.js                 | 160 ++++++++++++
 skills/github-actions-hygiene/SKILL.md        |   5 +-
 15 files changed, 508 insertions(+), 225 deletions(-)
 create mode 100644 docs/adr/ADR-0008-event-workflow-logic-in-scripts.md
 create mode 100755 scripts/check-issue-labeler.sh
 create mode 100644 scripts/issue-labeler.js
 create mode 100644 scripts/issue-labeler.test.js

diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS
index 618c7cc..4c67522 100644
--- a/.github/CODEOWNERS
+++ b/.github/CODEOWNERS
@@ -23,6 +23,7 @@
 
 # Example: Require infrastructure ownership
 # /scripts/bootstrap.sh                    @infra-owner
+# /scripts/issue-labeler.js                @infra-owner
 
 # Example: Solo dev auto-request
 # *                                        @your-username
diff --git a/.github/workflows/issue-labeler.yml b/.github/workflows/issue-labeler.yml
index e22d8c4..b053984 100644
--- a/.github/workflows/issue-labeler.yml
+++ b/.github/workflows/issue-labeler.yml
@@ -1,18 +1,21 @@
 name: Issue labeler
 
-# Syncs priority:*, area:* and the four type:* SUBTYPE labels from
-# the issue form fields on open/edit. The issue body is untrusted input — it is
-# only ever read inside the actions/github-script JS sandbox
-# (context.payload.issue.body), never interpolated into a shell `run:` step.
+# Syncs priority:*, area:* and the four type:* SUBTYPE labels from the issue
+# form fields on open/edit. The logic lives in scripts/issue-labeler.js
+# (ADR-0008); this file only checks out the default branch and calls it, so
+# it carries no adopter values and can be replaced whole on upgrade. The
+# script is tested by `make check` (scripts/check-issue-labeler.sh).
 #
-# "the four type:* subtype labels", not "type:*": the type: namespace also
-# carries labels no form produces, so this workflow owns an exact list rather
-# than a prefix. See FORM_MANAGED_TYPES below.
+# The issue body is untrusted input — it is only ever read inside the
+# actions/github-script JS sandbox (context.payload.issue.body), never
+# interpolated into a shell `run:` step, and every label the script adds is
+# validated against an allowlist the body cannot influence.
 #
-# area:* is the family adopters are told to rename, so its allowlist is not
-# written here: it is read from .github/labels.yml on the default branch at
-# run time (see loadAllowedAreas below). This file carries no adopter values
-# and can be replaced whole on upgrade.
+# Why a checkout on an issue event: the script and .github/labels.yml (the
+# run-time source of the area:* allowlist) live in the repository. On `issues`
+# events GITHUB_SHA is the head of the default branch, so this checks out
+# exactly the code and label declarations that were merged — never a PR
+# branch's copy.
 
 on:
   issues:
@@ -34,203 +37,17 @@ jobs:
     timeout-minutes: 5
     permissions:
       issues: write
-      contents: read # getContent on .github/labels.yml
+      contents: read # checkout of the default branch
     steps:
+      - name: Check out the default branch
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 1
+
       - name: Sync form-managed labels
         uses: actions/github-script@3a2844b7e9c422d3c10d287c895573f7108da1b3 # v9.0.0
         with:
           script: |
-            // Parses the GitHub issue-form markdown body (### <Label> headings)
-            // and syncs the form-managed labels to match. Only ever touches
-            // priority:*, area:* and the four type:* subtypes listed
-            // in FORM_MANAGED_TYPES — every other label on the issue is left
-            // alone, including any type:* label OUTSIDE that list (a coarse
-            // type:bug/type:feature, or an adopter's own). The four form-owned
-            // subtypes are still removed when the form no longer selects them;
-            // that is the point of the sync.
-            const body = context.payload.issue.body || '';
-
-            // Split the body into sections keyed by "### <Heading>".
-            function parseSections(text) {
-              const lines = text.split(/\r?\n/);
-              const sections = {};
-              let current = null;
-              for (const line of lines) {
-                const heading = line.match(/^###\s+(.+?)\s*$/);
-                if (heading) {
-                  current = heading[1].trim();
-                  sections[current] = [];
-                  continue;
-                }
-                if (current) {
-                  sections[current].push(line);
-                }
-              }
-              return sections;
-            }
-
-            const sections = parseSections(body);
-
-            function sectionText(name) {
-              const raw = sections[name];
-              if (!raw) return '';
-              return raw.join('\n').trim();
-            }
-
-            // Dropdown answers render as a plain text line under the heading.
-            // Missing/optional answers render as "_No response_".
-            function dropdownPrefix(name) {
-              const text = sectionText(name);
-              if (!text || text === '_No response_') return null;
-              const firstLine = text.split(/\r?\n/)[0].trim().toLowerCase();
-              return firstLine;
-            }
-
-            // Allowlists — the issue body is untrusted input, so every label
-            // this script adds must be validated against a list the body cannot
-            // influence, never derived from body text alone (addLabels
-            // auto-creates unknown labels, so an unconstrained regex match
-            // would let a crafted body mint arbitrary labels). Priorities and
-            // subtypes are fixed constants; area:* is read from labels.yml
-            // (below), which only a merged PR can change.
-            const ALLOWED_PRIORITIES = ['p0', 'p1', 'p2', 'p3'];
-            // Deliberately NOT read from labels.yml: a repo running the
-            // coarse-Type label fallback (ADR-0006) declares type:bug and
-            // type:feature there, and a crafted "### Subtype" line must not be
-            // able to mint a coarse Type on a Task. scripts/check-label-forms.sh
-            // keeps this list and task.yml's dropdown equal.
-            const ALLOWED_SUBTYPES = ['chore', 'ops', 'docs', 'security'];
-            // The exact type:* labels this workflow owns. Deliberately NOT
-            // `label.startsWith('type:')`: only task.yml has a Subtype dropdown,
-            // so on a bug report or feature request `desired` never holds a
-            // type:* label — and a prefix match would put every hand-applied
-            // type:* label into `toRemove` and strip it on the next body edit.
-            const FORM_MANAGED_TYPES = ALLOWED_SUBTYPES.map((s) => `type:${s}`);
-
-            // area:* allowlist = every `- name: area:...` entry in
-            // .github/labels.yml on the DEFAULT branch. The default branch, not
-            // the event ref, so a PR branch's copy cannot widen the list. The
-            // parse mirrors parse_labels_yml in scripts/bootstrap.sh: an entry
-            // is a `- name:` line, and a commented-out entry starts with # and
-            // never matches. A read failure THROWS — an empty allowlist is not
-            // a safe default, because `desired` would then hold no area:* and
-            // every area label already on the issue would land in toRemove.
-            async function loadAllowedAreas() {
-              const ref = context.payload.repository.default_branch;
-              const { data } = await github.rest.repos.getContent({
-                owner: context.repo.owner,
-                repo: context.repo.repo,
-                path: '.github/labels.yml',
-                ref,
-              });
-              if (!data || data.type !== 'file' || typeof data.content !== 'string') {
-                throw new Error(`.github/labels.yml is not a readable file on ${ref}`);
-              }
-              const yml = Buffer.from(data.content, 'base64').toString('utf8');
-              const areas = [];
-              for (const line of yml.split(/\r?\n/)) {
-                // Same reading as parse_labels_yml: the name is everything after
-                // `name:` with surrounding whitespace trimmed — no quote or
-                // comment stripping, so area:c# and area:team's survive intact
-                // and a quoted or inline-commented entry is wrong here exactly
-                // as it is wrong for bootstrap (labels.yml's header rules both out).
-                const m = line.match(/^\s*-\s*name:\s*(area:\S.*?)\s*$/);
-                if (m) areas.push(m[1]);
-              }
-              if (areas.length === 0) {
-                core.warning(`no area:* entries in .github/labels.yml on ${ref} — Area checkboxes will apply nothing`);
-              }
-              return areas;
-            }
-            const ALLOWED_AREAS = await loadAllowedAreas();
-
-            const desired = new Set();
-
-            // Option text is "<value> — <description>". Rather than guessing
-            // where the value ends, match the text against the allowed values:
-            // the longest allowed value the text starts with, followed by the
-            // end of the text or a dash (—, – or -) with whitespace on both
-            // sides. A value may therefore contain spaces or a spaced dash, as
-            // GitHub label names can; the allowlist alone decides, and there
-            // is no second regex spelling out the same values
-            // (scripts/check-label-forms.sh keeps the forms and labels.yml on
-            // this convention).
-            function matchAllowed(text, allowed) {
-              const candidates = [...allowed].sort((a, b) => b.length - a.length);
-              for (const name of candidates) {
-                if (text === name) return name;
-                if (text.startsWith(name) && /^\s+[—–-]\s+/.test(text.slice(name.length))) return name;
-              }
-              return null;
-            }
-
-            // ### Priority -> priority:pX (dropdown, e.g. "p0 — Critical, drop everything")
-            const priorityLine = dropdownPrefix('Priority');
-            if (priorityLine) {
-              const value = matchAllowed(priorityLine, ALLOWED_PRIORITIES);
-              if (value) desired.add(`priority:${value}`);
-            }
-
-            // ### Subtype -> type:X (task form only; dropdown, e.g. "chore — Maintenance")
-            const subtypeLine = dropdownPrefix('Subtype');
-            if (subtypeLine) {
-              const value = matchAllowed(subtypeLine, ALLOWED_SUBTYPES);
-              if (value) desired.add(`type:${value}`);
-            }
-
-            // ### Area -> area:* (checkboxes, e.g. "- [x] area:docs — Documentation and guides")
-            const areaText = sectionText('Area');
-            if (areaText) {
-              const checkedLines = areaText.split(/\r?\n/).filter((line) => /^-\s*\[[xX]\]/.test(line));
-              for (const line of checkedLines) {
-                // "- [x] area:<name> — <description>": same rule as the
-                // dropdowns; the allowlist decides, not a character class.
-                const value = matchAllowed(line.replace(/^-\s*\[[xX]\]\s*/, '').trim(), ALLOWED_AREAS);
-                if (value) desired.add(value);
-              }
-            }
-
-            // Only these labels are form-managed; every other label is left
-            // untouched. area: stays a prefix match on purpose — that is what
-            // cleans up a stale area:old label after an adopter renames their
-            // area taxonomy in .github/labels.yml.
-            function isFormManaged(label) {
-              return (
-                label.startsWith('priority:') ||
-                FORM_MANAGED_TYPES.includes(label) ||
-                label.startsWith('area:')
-              );
-            }
-
-            const { owner, repo } = context.repo;
-            const issue_number = context.payload.issue.number;
-
-            const currentLabels = (context.payload.issue.labels || []).map((l) => l.name);
-            const currentManaged = currentLabels.filter(isFormManaged);
-
-            const toAdd = [...desired].filter((label) => !currentLabels.includes(label));
-            // On 'edited', drop previously form-managed labels the user un-selected.
-            // On 'opened' this is a no-op (nothing managed exists yet).
-            const toRemove = currentManaged.filter((label) => !desired.has(label));
-
-            if (toAdd.length > 0) {
-              await github.rest.issues.addLabels({
-                owner,
-                repo,
-                issue_number,
-                labels: toAdd,
-              });
-            }
-
-            for (const label of toRemove) {
-              await github.rest.issues.removeLabel({
-                owner,
-                repo,
-                issue_number,
-                name: label,
-              });
-            }
-
-            core.info(`Desired: ${[...desired].join(', ') || '(none)'}`);
-            core.info(`Added: ${toAdd.join(', ') || '(none)'}`);
-            core.info(`Removed: ${toRemove.join(', ') || '(none)'}`);
+            const { run } = require(`${process.env.GITHUB_WORKSPACE}/scripts/issue-labeler.js`);
+            await run({ github, context, core });
diff --git a/AGENTS.md b/AGENTS.md
index 4f7d73b..64d54b0 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -16,7 +16,7 @@ Agent-specific entry files (`CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructi
 
 ## Build and validation
 
-The Makefile is the only executable contract in this repository. CI calls make targets; customize the Makefile, never the workflows. The single exception is runner selection, which GitHub resolves before any make target exists to be called: set the `RUNNER_LABELS` repository variable instead of editing `runs-on` (see `docs/setup/runners.md`).
+The Makefile is the only executable contract in this repository. CI calls make targets; customize the Makefile, never the workflows. Two exceptions, neither of which puts adopter values in the YAML: runner selection, which GitHub resolves before any make target exists to be called — set the `RUNNER_LABELS` repository variable instead of editing `runs-on` (see `docs/setup/runners.md`); and event handlers that need the token and payload, whose logic lives in `scripts/*.js` behind a thin `github-script` caller and is tested by `make check` (the issue labeler; ADR-0008).
 
 | Level | Name | Command | When required |
 | --- | --- | --- | --- |
@@ -39,7 +39,7 @@ The Makefile is the only executable contract in this repository. CI calls make t
 | `skills/` | Reusable knowledge modules (one directory per skill, `SKILL.md` inside) |
 | `docs/adr/` | Architecture Decision Records |
 | `docs/setup/` | Bootstrap and GitHub configuration guides |
-| `scripts/` | Bootstrap and self-consistency check scripts |
+| `scripts/` | Bootstrap, self-consistency checks, and the event-handler logic workflows call (`issue-labeler.js`; ADR-0008) |
 | `Makefile` | Canonical target contract (validation ladder entry points) |
 
 ## Workflow
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 79e0cf5..8b11560 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -20,6 +20,7 @@ Install the lint tools used by `make lint-docs`:
 | Tool | Install |
 | --- | --- |
 | markdownlint-cli2 | `npm install -g markdownlint-cli2` |
+| node (any LTS) | `brew install node` — runs `scripts/issue-labeler.test.js` in `make check` |
 | yamllint | `brew install yamllint` (or `pip install yamllint`) |
 | lychee | `brew install lychee` |
 | actionlint | `brew install actionlint` |
diff --git a/Makefile b/Makefile
index 96ee8da..bc21fae 100644
--- a/Makefile
+++ b/Makefile
@@ -45,6 +45,7 @@ check: ## Run repo self-consistency scripts (skips scripts not yet added)
 	@if [ -x scripts/check-local-md.sh ]; then scripts/check-local-md.sh; else echo "skip: scripts/check-local-md.sh not present yet"; fi
 	@if [ -x scripts/check-license-marker.sh ]; then scripts/check-license-marker.sh; else echo "skip: scripts/check-license-marker.sh not present yet"; fi
 	@if [ -x scripts/check-label-forms.sh ]; then scripts/check-label-forms.sh; else echo "skip: scripts/check-label-forms.sh not present yet"; fi
+	@if [ -x scripts/check-issue-labeler.sh ]; then scripts/check-issue-labeler.sh; else echo "skip: scripts/check-issue-labeler.sh not present yet"; fi
 
 lint: lint-docs lint-actions lint-secrets check ## L0 - aggregate all lint/consistency checks
 
diff --git a/docs/adr/ADR-0008-event-workflow-logic-in-scripts.md b/docs/adr/ADR-0008-event-workflow-logic-in-scripts.md
new file mode 100644
index 0000000..f5550aa
--- /dev/null
+++ b/docs/adr/ADR-0008-event-workflow-logic-in-scripts.md
@@ -0,0 +1,30 @@
+# ADR-0008: Event-driven workflow logic lives in `scripts/`, behind a thin `github-script` caller
+
+- **Status**: Accepted
+- **Date**: 2026-09-16
+- **Issue**: #49
+
+## Context
+
+`AGENTS.md` and `skills/github-actions-hygiene` rule 1 say workflows call `make` targets and never contain logic. The issue labeler was always the exception: an event handler that needs the `GITHUB_TOKEN` and the `issues` payload, which no `make` target can own, so ~150 lines of JavaScript lived inline in `.github/workflows/issue-labeler.yml`. The exception was undocumented, and the only way to test the script was to extract it from the YAML by hand — which is exactly how #48 was validated. A repository whose rule is "the template obeys its own rules" cannot leave its one stateful workflow untestable and unnamed.
+
+## Decision
+
+1. **The logic moves to `scripts/issue-labeler.js`**, a plain Node module with pure functions (`parseSections`, `matchAllowed`, `parseAllowedAreas`, `computeChanges`) and one I/O entry point (`run({github, context, core})`). The workflow checks out the default branch (`actions/checkout`, pinned, `persist-credentials: false`, `fetch-depth: 1`) and its `github-script` step is two lines: `require` the module, `await run(...)`.
+2. **`labels.yml` is read from the checkout, not the API.** On `issues` events `GITHUB_SHA` is the head of the default branch, so the checkout holds exactly the merged declarations — the same trust boundary the API read had, without the extra request.
+3. **The script is tested by `make check`** (`scripts/check-issue-labeler.sh` → `node --test scripts/issue-labeler.test.js`, node built-ins only). A missing `node` fails with an install hint, the way every other tool `make` needs does — never a green skip (validation-ladder rule 7).
+4. **Rule 1 names the shape.** Event-driven workflows that genuinely need the token and payload keep their logic in `scripts/*.js`, called through `github-script` after a checkout; the workflow stays a thin caller and carries no adopter values.
+
+## Consequences
+
+- The labeler is readable in one file and has a durable test; a change to its matching rules is a normal PR with a failing test first.
+- The workflow file stays replaceable whole on upgrade — the property adopters already rely on — but now travels with `scripts/issue-labeler.js`; `docs/template/upgrading.md` says so.
+- One more pinned action to keep bumped (Dependabot covers it) and a checkout on every issue event (a few seconds).
+- `node` becomes a dependency of `make check`; CI already has it for markdownlint.
+- The logic is now protected by whatever protects `scripts/` on the default branch, not by GitHub's rule that tokens without the `workflows` scope cannot write under `.github/workflows/`. The blast radius is unchanged (the job holds `issues: write` and nothing else), and `main` already requires a PR plus green `ci`; adopters who want a review barrier add `/scripts/issue-labeler.js` and `/.github/workflows/` to `.github/CODEOWNERS` (the commented example there shows the line) and set `require_code_owner_review` in the ruleset.
+
+## Alternatives considered
+
+- **Record the exception and keep the script inline.** Rejected: it leaves the only stateful workflow untestable, and the next change to it repeats the extract-by-hand validation.
+- **Keep reading `labels.yml` through the API and skip the checkout.** Rejected: the checkout is needed for the script anyway, and a second copy of the same data by a second route is a second thing to keep consistent.
+- **A `make labeler` target invoked from a `run:` step.** Rejected: the payload would have to reach the shell through the environment, and the token through `gh` — more surface, no gain over `github-script`'s sandbox.
diff --git a/docs/adr/README.md b/docs/adr/README.md
index cf70038..8c57bed 100644
--- a/docs/adr/README.md
+++ b/docs/adr/README.md
@@ -29,3 +29,4 @@ Routine choices (a library patch bump, a wording tweak) do not get ADRs. When in
 | [ADR-0005](ADR-0005-runner-selection-variable.md) | Runner selection is an adopter variable, not a workflow edit | Accepted |
 | [ADR-0006](ADR-0006-coarse-type-fallback.md) | Coarse Type on accounts without native issue types | Accepted |
 | [ADR-0007](ADR-0007-retire-agent-labels.md) | Retire the `agent-ok` / `by-agent` label mechanism | Accepted |
+| [ADR-0008](ADR-0008-event-workflow-logic-in-scripts.md) | Event-driven workflow logic lives in `scripts/`, behind a thin `github-script` caller | Accepted |
diff --git a/docs/template/architecture.md b/docs/template/architecture.md
index 6dc7f3d..ff87f7a 100644
--- a/docs/template/architecture.md
+++ b/docs/template/architecture.md
@@ -12,18 +12,19 @@ Why each piece of this repository exists, and what it costs to keep. A component
 | `CLAUDE.md`, `GEMINI.md`, `.github/copilot-instructions.md` | Per-agent entry points (≤10 lines each) | Near zero — pointers only |
 | `skills/` (15 modules) | On-demand knowledge for humans + agents | Content reviews; consistency enforced by `scripts/check-skills.sh` |
 | `.github/PROJECT_FIELDS.md` | Metadata single-home authority map | Update only when taxonomy changes (rare, ADR-worthy) |
-| `.github/labels.yml` | Labels as code; bootstrap re-run = sync; carries the commented-out coarse-Type fallback (ADR-0006) | Edit alongside label changes; `FORM_MANAGED_TYPES` in `issue-labeler.yml` must match, and the commented block must stay commented |
+| `.github/labels.yml` | Labels as code; bootstrap re-run = sync; carries the commented-out coarse-Type fallback (ADR-0006) | Edit alongside label changes; `FORM_MANAGED_TYPES` in `scripts/issue-labeler.js` must match (`scripts/check-label-forms.sh` enforces), and the commented block must stay commented |
 | `.github/ISSUE_TEMPLATE/` (3 forms) | Set native types; feed the labeler | Area/Priority/Subtype options must match `labels.yml` — `scripts/check-label-forms.sh` fails `make check` until they do |
 | `.github/PULL_REQUEST_TEMPLATE.md` | Validation ladder + RISK convention at point of use | Near zero |
 | `.github/workflows/ci.yml` | L0 gate; installs tools via `make ci-tools`, runs `make ci-pr`. The only required status check — see its header before touching `on:` or `runs-on:` | SHA-pin bumps via Dependabot |
-| `.github/workflows/issue-labeler.yml` | Form selections → labels (single-home preserving); `area:*` allowlist read from `labels.yml` at run time | `ALLOWED_PRIORITIES` / `ALLOWED_SUBTYPES` must match the forms — checked by `scripts/check-label-forms.sh` |
+| `.github/workflows/issue-labeler.yml` | Thin caller: checkout + `require('scripts/issue-labeler.js')` (ADR-0008) | Two action SHA pins via Dependabot; no adopter values |
+| `scripts/issue-labeler.js` (+ `.test.js`) | Form selections → labels (single-home preserving); `area:*` allowlist read from the checked-out `labels.yml` | `ALLOWED_PRIORITIES` / `ALLOWED_SUBTYPES` must match the forms — checked by `scripts/check-label-forms.sh`; behaviour pinned by `scripts/issue-labeler.test.js` via `make check` |
 | `.github/workflows/maintenance.yml` | Weekly drift detectors: external link check + CI tool version check | Near zero |
 | `.github/workflows/release-please.yml` + configs | Human-gated release automation (ADR-0002) | Action SHA bumps; `initial-version` pins adopters' first release and is inert afterwards |
 | `.github/rulesets/main-branch.json` | Importable branch protection (PR + green `ci` required) | Near zero |
 | `LICENSE` | The template's own licence (MIT); bootstrap phase 9 replaces it with the adopter's choice and moves upstream attribution to `NOTICE` | Near zero — the holder line is asserted against `bootstrap.sh`'s constants by `scripts/check-license-marker.sh` |
 | `Makefile` | The only executable contract; adopter customization point | Grows with adopter stack, not with the template |
 | `scripts/bootstrap.sh` | Applies everything a template can't ship as files; idempotent sync | Highest-cost component — E2E-verified each release (below) |
-| `scripts/check-*.sh` | Self-consistency: skills index, local-md hygiene, licence marker, label values repeated in forms and the labeler | Near zero |
+| `scripts/check-*.sh` | Self-consistency: skills index, local-md hygiene, licence marker, label values repeated in forms and the labeler, the labeler's own tests | Near zero |
 | `scripts/install-ci-tools.sh` | Checksum-verified CI tool installs; single home for all five tool version pins, shared by `ci.yml` and `maintenance.yml` via `make ci-tools`; bounds `RUNNER_LABELS` to linux x86_64 | Hand-bump a pin when the drift check flags it |
 | `scripts/check-tool-versions.sh` | Diffs those pins against upstream weekly and fails on drift — Dependabot cannot see them, so nothing else would | Near zero; add a row when a tool is added |
 | `docs/adr/` | Decision records; the "why" layer | Grows slowly by trigger criteria |
diff --git a/docs/template/design-principles.md b/docs/template/design-principles.md
index 548ab83..5e85535 100644
--- a/docs/template/design-principles.md
+++ b/docs/template/design-principles.md
@@ -8,7 +8,7 @@ These principles decided every file in this repository. When proposing a change
 2. **GitHub-native before third-party.** Native issue types, native sub-issues, native rulesets, Projects v2. A third-party tool must clear a high bar: solve something GitHub genuinely cannot.
 3. **Every file justifies its maintenance cost.** If a file stops earning its keep, it gets deleted. The [architecture ledger](architecture.md) records what each piece is for.
 4. **One home per fact.** Metadata (ADR-0003), documentation (`skills/docs-hygiene/`), configuration — duplicate homes always drift.
-5. **Logic in the Makefile, not workflows.** Adopters customize `make` targets; workflow YAML stays untouched and upgradable.
+5. **Logic in the Makefile, not workflows.** Adopters customize `make` targets; workflow YAML stays untouched and upgradable. The one shape the Makefile cannot hold — an event handler that needs the token and the payload — lives in `scripts/` behind a two-line caller (ADR-0008), which keeps the YAML just as untouched.
 6. **The template obeys its own rules.** Its CI is the CI it ships; its issues use its own forms; its releases use its own flow. Dogfooding is the drift detector.
 7. **AI agents are first-class, humans stay in control.** Agents share the same issue, PR, and validation contract as humans and load the same skills; humans decide what agents work on and gate merges, releases, and destructive operations.
 8. **Ratchets over cleanup.** Label budgets, workflow-count budgets, handoff caps — prevention mechanisms, because every failure mode this template guards against is cheap to prevent and expensive to undo (see `skills/anti-patterns/`).
diff --git a/docs/template/upgrading.md b/docs/template/upgrading.md
index e06280e..1ab3a25 100644
--- a/docs/template/upgrading.md
+++ b/docs/template/upgrading.md
@@ -15,7 +15,7 @@ Repositories created from a template share no git history with it, so updates ar
    git diff HEAD template/vX.Y.Z -- .github/ skills/ Makefile scripts/
    ```
 
-3. Cherry-pick what you want by path. Good candidates: `skills/`, `.github/workflows/`, `scripts/check-*.sh` (rarely customized locally). Careful candidates: `Makefile` (your `test` target lives there), `.github/labels.yml` (your renamed `area:*` labels), `AGENTS.md` (your conventions).
+3. Cherry-pick what you want by path. Good candidates: `skills/`, `.github/workflows/` (the labeler workflow only calls code that lives elsewhere — take it together with `scripts/issue-labeler.js`, `scripts/issue-labeler.test.js`, `scripts/check-issue-labeler.sh`, `scripts/check-label-forms.sh` and the two `check:` lines in the Makefile; `make check` tells you if the set is incomplete), `scripts/check-*.sh` (rarely customized locally). Careful candidates: `Makefile` (your `test` target lives there), `.github/labels.yml` (your renamed `area:*` labels), `AGENTS.md` (your conventions).
 4. Apply as a normal PR through your own CI. Never bulk-overwrite customized files.
 5. Re-run `scripts/bootstrap.sh` if the update changed `labels.yml` or the ruleset — it syncs GitHub-side state to the files.
 
diff --git a/scripts/check-issue-labeler.sh b/scripts/check-issue-labeler.sh
new file mode 100755
index 0000000..e502bd3
--- /dev/null
+++ b/scripts/check-issue-labeler.sh
@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+# check-issue-labeler.sh — runs the issue labeler's tests.
+#
+# The labeler's logic lives in scripts/issue-labeler.js (ADR-0008); the
+# workflow only calls it. scripts/issue-labeler.test.js exercises the pure
+# functions and the run() entry point with stubbed GitHub clients, under
+# plain node with no dependencies.
+#
+# node is a dependency of `make check` for this one script, like
+# markdownlint-cli2 is for lint-docs; a missing node fails with an install
+# hint the way the Makefile's other tool checks do — never a green skip.
+#
+# Exit status: 0 if the tests pass, 1 otherwise.
+
+set -euo pipefail
+
+cd "$(dirname "$0")/.."
+
+command -v node >/dev/null 2>&1 || { echo "install: node (e.g. brew install node) — needed for scripts/issue-labeler.test.js"; exit 1; }
+
+if node --test --test-reporter=dot scripts/issue-labeler.test.js; then
+  echo ""
+  echo "OK: scripts/issue-labeler.test.js passed"
+  echo "Summary: labeler tests passed"
+  exit 0
+fi
+echo "FAIL: scripts/issue-labeler.test.js failed — rerun with: node --test scripts/issue-labeler.test.js"
+echo "Summary: labeler tests FAILED"
+exit 1
diff --git a/scripts/check-label-forms.sh b/scripts/check-label-forms.sh
index 2127131..bd1e592 100755
--- a/scripts/check-label-forms.sh
+++ b/scripts/check-label-forms.sh
@@ -3,7 +3,7 @@
 # must still match it.
 #
 # .github/labels.yml is the taxonomy's single home (skills/labels-and-taxonomy
-# rule 1), but three issue forms and the labeler workflow repeat some of its
+# rule 1), but three issue forms and the labeler source repeat some of its
 # values as static text, and nothing else notices when they drift: the form
 # still renders, the labeler still exits green, and ticking a box that names a
 # label the repo no longer has applies nothing. A downstream adopter renamed
@@ -36,7 +36,7 @@
 # dash (see h. for what older labelers can and cannot read). An option that
 # resolves to no declared name is reported as `?<option text>`.
 #
-#   j. while the labeler workflow exists, each managed field it reads must keep
+#   j. while a labeler exists, each managed field it reads must keep
 #      the heading it reads — `label: Priority`, `label: Subtype`,
 #      `label: Area` — because the issue body carries headings, not field
 #      ids; renaming one blinds the labeler while ids and options still match.
@@ -57,10 +57,12 @@
 #      every set comparison and be ignored at run time (newer labelers match
 #      the leading token and let the allowlist decide).
 #
-# Usage: scripts/check-label-forms.sh [labels-yml] [forms-dir] [labeler-yml]
-#   Defaults: .github/labels.yml .github/ISSUE_TEMPLATE
-#             .github/workflows/issue-labeler.yml
-#   The overrides exist so the parser can be exercised against fixtures.
+# Usage: scripts/check-label-forms.sh [labels-yml] [forms-dir] [labeler-source]
+#   Defaults: .github/labels.yml .github/ISSUE_TEMPLATE, and for the labeler
+#   source scripts/issue-labeler.js when it exists (the logic lives there
+#   since ADR-0008), else .github/workflows/issue-labeler.yml (older copies
+#   carry the script inline). The overrides exist so the parser can be
+#   exercised against fixtures.
 #
 # Exit status: 0 if every check passes, 1 otherwise.
 
@@ -70,7 +72,23 @@ cd "$(dirname "$0")/.."
 
 LABELS_FILE="${1:-.github/labels.yml}"
 FORMS_DIR="${2:-.github/ISSUE_TEMPLATE}"
-LABELER_FILE="${3:-.github/workflows/issue-labeler.yml}"
+LABELER_FILE="${3:-}"
+WORKFLOW_FILE=.github/workflows/issue-labeler.yml
+mixed_generations=0
+if [ -z "$LABELER_FILE" ]; then
+  if [ -f scripts/issue-labeler.js ]; then
+    LABELER_FILE=scripts/issue-labeler.js
+    # The script exists, but is the workflow the thin caller that runs it? An
+    # adopter who took scripts/ and kept an inline workflow is still running
+    # the inline copy — validate that, and say the set is torn.
+    if [ -f "$WORKFLOW_FILE" ] && grep -qE 'const ALLOWED_' "$WORKFLOW_FILE"; then
+      LABELER_FILE="$WORKFLOW_FILE"
+      mixed_generations=1
+    fi
+  else
+    LABELER_FILE="$WORKFLOW_FILE"
+  fi
+fi
 
 FALLBACK_TYPES="type:bug type:feature"
 
@@ -88,7 +106,7 @@ ok() {
 }
 
 # Every `- name:` entry in labels.yml, one per line. The same reading as
-# parse_labels_yml in scripts/bootstrap.sh and the labeler workflow: the name
+# parse_labels_yml in scripts/bootstrap.sh and the labeler: the name
 # is the rest of the line, trimmed — no quote or comment stripping, so a
 # quoted or inline-commented entry surfaces here as a mismatch, exactly as it
 # would misbehave in bootstrap. Whole-line comments never match.
@@ -272,7 +290,7 @@ for path in "$FORMS_DIR"/*.yml "$FORMS_DIR"/*.yaml; do
     fi
   fi
   # --- j: the headings the labeler reads (only while there is a labeler)
-  [ -f "$LABELER_FILE" ] || continue
+  [ -f "$LABELER_FILE" ] || [ -f .github/workflows/issue-labeler.yml ] || continue
   for pair in "area:Area" "priority:Priority" "subtype:Subtype"; do
     fid="${pair%%:*}"; want="${pair#*:}"
     has_field "$path" "$fid" || continue
@@ -289,8 +307,15 @@ if [ "$forms_seen" -eq 0 ]; then
 fi
 
 # --- c/d: labeler constants
+if [ "$mixed_generations" -eq 1 ]; then
+  fail "$WORKFLOW_FILE still carries the labeler inline while scripts/issue-labeler.js also exists — the running labeler is the inline one; take the workflow and the script together (docs/template/upgrading.md)"
+fi
 if [ ! -f "$LABELER_FILE" ]; then
   echo "SKIP: $LABELER_FILE not present"
+elif case "$LABELER_FILE" in *.yml|*.yaml) true ;; *) false ;; esac && grep -qF 'issue-labeler.js' "$LABELER_FILE" && grep -qF 'require(' "$LABELER_FILE"; then
+  # The workflow is the thin caller shape (ADR-0008) but the script it
+  # requires is not here: the labeler would fail on every issue event.
+  fail "$LABELER_FILE requires scripts/issue-labeler.js, which is missing — take the workflow and the script together (docs/template/upgrading.md)"
 else
   lab_prio="$(labeler_list "$LABELER_FILE" ALLOWED_PRIORITIES | with_prefix 'priority:')"
   compare "labeler ALLOWED_PRIORITIES matches the priority:* set in $LABELS_FILE" "$priorities" "$lab_prio" \
@@ -304,7 +329,7 @@ else
     lab_areas="$(labeler_list "$LABELER_FILE" ALLOWED_AREAS | with_prefix '')"
     compare "labeler ALLOWED_AREAS matches the area:* set in $LABELS_FILE" "$areas" "$lab_areas" \
       "fix: edit the ALLOWED_AREAS constant in $LABELER_FILE — or take the labeler that reads labels.yml at run time (github-project-os #45)"
-  elif grep -qF "path: '.github/labels.yml'" "$LABELER_FILE" && grep -qE 'ALLOWED_AREAS = await ' "$LABELER_FILE"; then
+  elif grep -qF 'labels.yml' "$LABELER_FILE" && grep -qE 'loadAllowedAreas|readAllowedAreas' "$LABELER_FILE"; then
     ok "labeler reads area:* from $LABELS_FILE at run time (no ALLOWED_AREAS constant to drift)"
   else
     fail "labeler neither declares ALLOWED_AREAS nor loads it from .github/labels.yml — every Area selection would be ignored, or the script would throw"
diff --git a/scripts/issue-labeler.js b/scripts/issue-labeler.js
new file mode 100644
index 0000000..5d1cf0e
--- /dev/null
+++ b/scripts/issue-labeler.js
@@ -0,0 +1,216 @@
+'use strict';
+// issue-labeler.js — the logic behind .github/workflows/issue-labeler.yml.
+//
+// The workflow is a thin caller: after checking out the default branch it
+// runs `require('<workspace>/scripts/issue-labeler.js').run({github, context,
+// core})` inside actions/github-script. Everything that decides anything is
+// here, so it can be read in one place and exercised by
+// scripts/issue-labeler.test.js under plain node — no GitHub involved
+// (ADR-0008).
+//
+// What it does: parse the GitHub issue-form markdown body (### <Label>
+// headings) and sync the form-managed labels to match. Only ever touches
+// priority:*, area:* and the four type:* subtypes in FORM_MANAGED_TYPES —
+// every other label on the issue is left alone, including any type:* label
+// OUTSIDE that list (a coarse type:bug/type:feature, or an adopter's own).
+// The four form-owned subtypes are still removed when the form no longer
+// selects them; that is the point of the sync.
+//
+// The issue body is untrusted input. It is only ever read as data here —
+// never interpolated into a shell — and every label this script adds is
+// validated against a list the body cannot influence.
+
+const fs = require('fs');
+const path = require('path');
+
+// Allowlists. Priorities and subtypes are fixed constants; area:* is read
+// from .github/labels.yml (below), which only a merged PR can change.
+const ALLOWED_PRIORITIES = ['p0', 'p1', 'p2', 'p3'];
+// Deliberately NOT read from labels.yml: a repo running the coarse-Type
+// label fallback (ADR-0006) declares type:bug and type:feature there, and a
+// crafted "### Subtype" line must not be able to mint a coarse Type on a
+// Task. scripts/check-label-forms.sh keeps this list and task.yml's dropdown
+// equal.
+const ALLOWED_SUBTYPES = ['chore', 'ops', 'docs', 'security'];
+// The exact type:* labels this script owns. Deliberately NOT
+// `label.startsWith('type:')`: only task.yml has a Subtype dropdown, so on a
+// bug report or feature request `desired` never holds a type:* label — and a
+// prefix match would put every hand-applied type:* label into `toRemove` and
+// strip it on the next body edit.
+const FORM_MANAGED_TYPES = ALLOWED_SUBTYPES.map((s) => `type:${s}`);
+
+const LABELS_YML = path.join('.github', 'labels.yml');
+
+// area:* allowlist = every `- name: area:...` entry in labels.yml. The parse
+// mirrors parse_labels_yml in scripts/bootstrap.sh: an entry is a `- name:`
+// line, the name is the rest of the line trimmed — no quote or comment
+// stripping, so area:c# and area:team's survive intact and a quoted or
+// inline-commented entry is wrong here exactly as it is wrong for bootstrap
+// (labels.yml's header rules both out). A commented-out entry starts with #
+// and never matches.
+function parseAllowedAreas(ymlText) {
+  const areas = [];
+  for (const line of String(ymlText).split(/\r?\n/)) {
+    const m = line.match(/^\s*-\s*name:\s*(area:\S.*?)\s*$/);
+    if (m) areas.push(m[1]);
+  }
+  return areas;
+}
+
+// Reads labels.yml from the checked-out default branch. A read failure
+// THROWS — an empty allowlist is not a safe default, because `desired` would
+// then hold no area:* and every area label already on the issue would land in
+// toRemove.
+function readAllowedAreas(repoRoot) {
+  const file = path.join(repoRoot, LABELS_YML);
+  let text;
+  try {
+    text = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    throw new Error(`cannot read ${file}: ${err.message} — refusing to run with an empty area:* allowlist`);
+  }
+  return parseAllowedAreas(text);
+}
+
+// Split the body into sections keyed by "### <Heading>".
+function parseSections(text) {
+  const lines = String(text || '').split(/\r?\n/);
+  const sections = {};
+  let current = null;
+  for (const line of lines) {
+    // Linear, not `(.+?)\s*$`: the lazy form backtracks quadratically on a
+    // heading line padded with tens of thousands of spaces (~2 s at the
+    // 65,536-char body cap). The `s` flag keeps a stray CR or U+2028 inside
+    // the heading matching as it did before; the heading is trimmed either way.
+    const heading = line.match(/^###\s(.+)$/s);
+    if (heading) {
+      current = heading[1].trim();
+      sections[current] = [];
+      continue;
+    }
+    if (current) sections[current].push(line);
+  }
+  return sections;
+}
+
+// Option text is "<value> — <description>". Rather than guessing where the
+// value ends, match the text against the allowed values: the longest allowed
+// value the text starts with, followed by the end of the text or a dash
+// (—, – or -) with whitespace on both sides. A value may therefore contain
+// spaces or a spaced dash, as GitHub label names can; the allowlist alone
+// decides, and there is no second regex spelling out the same values
+// (scripts/check-label-forms.sh keeps the forms and labels.yml on this
+// convention).
+function matchAllowed(text, allowed) {
+  const candidates = [...allowed].sort((a, b) => b.length - a.length);
+  for (const name of candidates) {
+    if (text === name) return name;
+    if (text.startsWith(name) && /^\s+[—–-]\s+/.test(text.slice(name.length))) return name;
+  }
+  return null;
+}
+
+// Pure: given the body, the issue's current labels and the area allowlist,
+// return what the labels should be and the delta to get there.
+function computeChanges({ body, currentLabels, allowedAreas }) {
+  const sections = parseSections(body);
+
+  function sectionText(name) {
+    const raw = sections[name];
+    return raw ? raw.join('\n').trim() : '';
+  }
+  // Dropdown answers render as a plain text line under the heading.
+  // Missing/optional answers render as "_No response_".
+  function dropdownPrefix(name) {
+    const text = sectionText(name);
+    if (!text || text === '_No response_') return null;
+    return text.split(/\r?\n/)[0].trim().toLowerCase();
+  }
+
+  const desired = new Set();
+
+  // ### Priority -> priority:pX (dropdown, e.g. "p0 — Critical, drop everything")
+  const priorityLine = dropdownPrefix('Priority');
+  if (priorityLine) {
+    const value = matchAllowed(priorityLine, ALLOWED_PRIORITIES);
+    if (value) desired.add(`priority:${value}`);
+  }
+
+  // ### Subtype -> type:X (task form only; dropdown, e.g. "chore — Maintenance")
+  const subtypeLine = dropdownPrefix('Subtype');
+  if (subtypeLine) {
+    const value = matchAllowed(subtypeLine, ALLOWED_SUBTYPES);
+    if (value) desired.add(`type:${value}`);
+  }
+
+  // ### Area -> area:* (checkboxes, e.g. "- [x] area:docs — Documentation and guides")
+  const areaText = sectionText('Area');
+  if (areaText) {
+    const checkedLines = areaText.split(/\r?\n/).filter((line) => /^-\s*\[[xX]\]/.test(line));
+    for (const line of checkedLines) {
+      const value = matchAllowed(line.replace(/^-\s*\[[xX]\]\s*/, '').trim(), allowedAreas);
+      if (value) desired.add(value);
+    }
+  }
+
+  // Only these labels are form-managed; every other label is left untouched.
+  // area: stays a prefix match on purpose — that is what cleans up a stale
+  // area:old label after an adopter renames their area taxonomy in labels.yml.
+  function isFormManaged(label) {
+    return (
+      label.startsWith('priority:') ||
+      FORM_MANAGED_TYPES.includes(label) ||
+      label.startsWith('area:')
+    );
+  }
+
+  const current = currentLabels || [];
+  const currentManaged = current.filter(isFormManaged);
+  const toAdd = [...desired].filter((label) => !current.includes(label));
+  // On 'edited', drop previously form-managed labels the user un-selected.
+  // On 'opened' this is a no-op (nothing managed exists yet).
+  const toRemove = currentManaged.filter((label) => !desired.has(label));
+  return { desired: [...desired], toAdd, toRemove };
+}
+
+// Entry point for actions/github-script.
+async function run({ github, context, core, repoRoot }) {
+  const root = repoRoot || process.env.GITHUB_WORKSPACE || process.cwd();
+  const allowedAreas = readAllowedAreas(root);
+  if (allowedAreas.length === 0) {
+    core.warning(`no area:* entries in ${LABELS_YML} — Area checkboxes will apply nothing`);
+  }
+
+  const issue = context.payload.issue;
+  const { desired, toAdd, toRemove } = computeChanges({
+    body: issue.body || '',
+    currentLabels: (issue.labels || []).map((l) => l.name),
+    allowedAreas,
+  });
+
+  const { owner, repo } = context.repo;
+  const issue_number = issue.number;
+  if (toAdd.length > 0) {
+    await github.rest.issues.addLabels({ owner, repo, issue_number, labels: toAdd });
+  }
+  for (const label of toRemove) {
+    await github.rest.issues.removeLabel({ owner, repo, issue_number, name: label });
+  }
+
+  core.info(`Desired: ${desired.join(', ') || '(none)'}`);
+  core.info(`Added: ${toAdd.join(', ') || '(none)'}`);
+  core.info(`Removed: ${toRemove.join(', ') || '(none)'}`);
+  return { desired, toAdd, toRemove };
+}
+
+module.exports = {
+  run,
+  computeChanges,
+  parseSections,
+  parseAllowedAreas,
+  readAllowedAreas,
+  matchAllowed,
+  ALLOWED_PRIORITIES,
+  ALLOWED_SUBTYPES,
+  FORM_MANAGED_TYPES,
+};
diff --git a/scripts/issue-labeler.test.js b/scripts/issue-labeler.test.js
new file mode 100644
index 0000000..e863c17
--- /dev/null
+++ b/scripts/issue-labeler.test.js
@@ -0,0 +1,160 @@
+'use strict';
+// issue-labeler.test.js — exercises scripts/issue-labeler.js under plain node.
+// Run by scripts/check-issue-labeler.sh from `make check`. No dependencies:
+// node:test + node:assert only. Fixtures are inline; the last group also runs
+// the real .github/labels.yml of the repository this file lives in.
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const labeler = require('./issue-labeler.js');
+
+const YML = `
+labels:
+  - name: type:chore
+  - name: area:a-architecture
+    color: 111111
+  - name: area:wp_1
+  # - name: area:commented
+  - name: "area:quoted"
+  - name: area:c#
+  - name: area:team's
+  - name: area:pm
+  - name: area:customer success
+  - name: area:customer - success
+  - name: area:ci
+  - name: area:ci-tools
+  - name: priority:p0
+`;
+const AREAS = labeler.parseAllowedAreas(YML);
+
+function changes(body, currentLabels = [], allowedAreas = AREAS) {
+  return labeler.computeChanges({ body, currentLabels, allowedAreas });
+}
+
+test('parseAllowedAreas: only `- name: area:` lines, commented and quoted excluded, punctuation kept', () => {
+  assert.deepEqual(AREAS, [
+    'area:a-architecture', 'area:wp_1', 'area:c#', "area:team's", 'area:pm',
+    'area:customer success', 'area:customer - success', 'area:ci', 'area:ci-tools',
+  ]);
+});
+
+test('parseSections: headings become keys, text is kept per section', () => {
+  const s = labeler.parseSections('### A\n\nx\n\n### B\n\n- [x] y');
+  assert.deepEqual(Object.keys(s), ['A', 'B']);
+  assert.equal(s.B.join('\n').trim(), '- [x] y');
+});
+
+test('parseSections: stray line terminators inside a heading line still parse (parity with the inline original)', () => {
+  assert.deepEqual(Object.keys(labeler.parseSections('### Area\r\n- [x] x')), ['Area']);
+  assert.deepEqual(Object.keys(labeler.parseSections('### Area \r')), ['Area']);
+  assert.deepEqual(Object.keys(labeler.parseSections('### Area\u2028')), ['Area']);
+  assert.deepEqual(Object.keys(labeler.parseSections('###\tPriority')), ['Priority']);
+  assert.deepEqual(Object.keys(labeler.parseSections('###Priority')), []);
+});
+
+test('parseSections: a heading line padded to the body cap parses in linear time', () => {
+  const t0 = process.hrtime.bigint();
+  const s = labeler.parseSections('### a' + ' '.repeat(65530) + 'b');
+  const ms = Number(process.hrtime.bigint() - t0) / 1e6;
+  assert.deepEqual(Object.keys(s), ['a' + ' '.repeat(65530) + 'b']);
+  assert.ok(ms < 200, `took ${ms} ms`);
+});
+
+test('matchAllowed: longest allowed value first, then end-of-text or a spaced dash', () => {
+  assert.equal(labeler.matchAllowed('area:ci — CI', ['area:ci', 'area:ci-tools']), 'area:ci');
+  assert.equal(labeler.matchAllowed('area:ci-tools — t', ['area:ci', 'area:ci-tools']), 'area:ci-tools');
+  assert.equal(labeler.matchAllowed('area:customer - success — CS', AREAS), 'area:customer - success');
+  assert.equal(labeler.matchAllowed('area:pm tools — undeclared', AREAS), null);
+  assert.equal(labeler.matchAllowed('area:pm - hyphen', AREAS), 'area:pm');
+  assert.equal(labeler.matchAllowed('area:pm', AREAS), 'area:pm');
+});
+
+test('opened: ticked boxes with digits/underscore/punctuation apply; unticked, commented and undeclared do not', () => {
+  const r = changes([
+    '### Area', '',
+    '- [x] area:wp_1 — x', '- [x] area:commented — y', '- [ ] area:pm — z',
+    '- [x] area:quoted — q', '- [x] area:c# — sharp', "- [x] area:team's — t", '- [x] area:evil — nope', '',
+    '### Priority', '', 'p0 — Critical',
+  ].join('\n'));
+  assert.deepEqual(r.toAdd, ['priority:p0', 'area:wp_1', 'area:c#', "area:team's"]);
+  assert.deepEqual(r.toRemove, []);
+});
+
+test('edited: the old area is removed, the new one added, hand-applied type:bug untouched', () => {
+  const r = changes('### Area\n\n- [x] area:pm — z\n\n### Priority\n\np0 — Critical',
+    ['area:wp_1', 'type:bug', 'priority:p0']);
+  assert.deepEqual(r.toAdd, ['area:pm']);
+  assert.deepEqual(r.toRemove, ['area:wp_1']);
+});
+
+test('dropdowns: case folded, allowlist decides, no second regex', () => {
+  const ok = changes('### Priority\n\nP1 — Blocking\n\n### Subtype\n\nDocs — Documentation');
+  assert.deepEqual(ok.toAdd, ['priority:p1', 'type:docs']);
+  const bad = changes('### Priority\n\np9 — nope\n\n### Subtype\n\nbug — spoof');
+  assert.deepEqual(bad.toAdd, []);
+  const none = changes('### Priority\n\n_No response_');
+  assert.deepEqual(none.toAdd, []);
+});
+
+test('a body without the sections strips form-managed labels but never type:bug/type:feature or unknown families', () => {
+  const r = changes('just prose', ['priority:p2', 'area:pm', 'type:docs', 'type:bug', 'type:feature', 'wontfix']);
+  assert.deepEqual(r.toRemove, ['priority:p2', 'area:pm', 'type:docs']);
+});
+
+test('stale area label outside the allowlist is still cleaned up (area: is a prefix match for removal)', () => {
+  const r = changes('### Area\n\n- [x] area:pm — z', ['area:old']);
+  assert.deepEqual(r.toAdd, ['area:pm']);
+  assert.deepEqual(r.toRemove, ['area:old']);
+});
+
+test('run: adds then removes via the API stub, logs the three lines', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'labeler-'));
+  fs.mkdirSync(path.join(dir, '.github'));
+  fs.writeFileSync(path.join(dir, '.github', 'labels.yml'), YML);
+  const calls = [];
+  const github = { rest: { issues: {
+    addLabels: async (a) => calls.push(['add', a.labels]),
+    removeLabel: async (a) => calls.push(['remove', a.name]),
+  } } };
+  const context = { repo: { owner: 'o', repo: 'r' }, payload: { issue: {
+    number: 7, body: '### Area\n\n- [x] area:pm — z', labels: [{ name: 'area:wp_1' }, { name: 'type:bug' }],
+  } } };
+  const logs = [];
+  const core = { info: (m) => logs.push(m), warning: (m) => logs.push('WARN ' + m) };
+  const r = await labeler.run({ github, context, core, repoRoot: dir });
+  assert.deepEqual(r, { desired: ['area:pm'], toAdd: ['area:pm'], toRemove: ['area:wp_1'] });
+  assert.deepEqual(calls, [['add', ['area:pm']], ['remove', 'area:wp_1']]);
+  assert.deepEqual(logs, ['Desired: area:pm', 'Added: area:pm', 'Removed: area:wp_1']);
+});
+
+test('run: an unreadable labels.yml throws before any API call', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'labeler-'));
+  const calls = [];
+  const github = { rest: { issues: {
+    addLabels: async () => calls.push('add'), removeLabel: async () => calls.push('remove'),
+  } } };
+  const context = { repo: { owner: 'o', repo: 'r' }, payload: { issue: { number: 1, body: '### Area\n\n- [x] area:pm — z', labels: [{ name: 'area:pm' }] } } };
+  await assert.rejects(() => labeler.run({ github, context, core: { info() {}, warning() {} }, repoRoot: dir }), /cannot read .*labels\.yml/);
+  assert.deepEqual(calls, []);
+});
+
+test('run: an empty area set warns and applies nothing for Area', async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'labeler-'));
+  fs.mkdirSync(path.join(dir, '.github'));
+  fs.writeFileSync(path.join(dir, '.github', 'labels.yml'), 'labels:\n  - name: priority:p0\n');
+  const warnings = [];
+  const github = { rest: { issues: { addLabels: async () => {}, removeLabel: async () => {} } } };
+  const context = { repo: { owner: 'o', repo: 'r' }, payload: { issue: { number: 1, body: '### Area\n\n- [x] area:pm — z', labels: [] } } };
+  const r = await labeler.run({ github, context, core: { info() {}, warning: (m) => warnings.push(m) }, repoRoot: dir });
+  assert.deepEqual(r.toAdd, []);
+  assert.equal(warnings.length, 1);
+});
+
+test("this repository's labels.yml: the shipped starter set behaves as before", () => {
+  const areas = labeler.readAllowedAreas(path.join(__dirname, '..'));
+  assert.ok(areas.includes('area:ci'));
+  const r = changes('### Area\n\n- [x] area:ci — CI workflows and automation\n- [x] area:nope — n', [], areas);
+  assert.deepEqual(r.toAdd, ['area:ci']);
+});
diff --git a/skills/github-actions-hygiene/SKILL.md b/skills/github-actions-hygiene/SKILL.md
index 400d7d6..acae8b7 100644
--- a/skills/github-actions-hygiene/SKILL.md
+++ b/skills/github-actions-hygiene/SKILL.md
@@ -12,7 +12,7 @@ Workflows are the highest-privilege, least-reviewed code in most repositories 
 
 ## Rules
 
-1. **Workflows call `make` targets; they never contain logic.** All branching, tool installation flags, and conditionals belong in the `Makefile`. A workflow step should read as `run: make lint`, not a shell script with real decisions in it. Adopters customize the Makefile — never the workflow YAML — to change what runs. The one thing the Makefile cannot own is `runs-on`, which GitHub resolves before any make target exists; expose it as a repository variable (`RUNNER_LABELS` here) so *where* a job runs stays configurable without forking the file.
+1. **Workflows call `make` targets; they never contain logic.** All branching, tool installation flags, and conditionals belong in the `Makefile`. A workflow step should read as `run: make lint`, not a shell script with real decisions in it. Adopters customize the Makefile — never the workflow YAML — to change what runs. Two things the Makefile cannot own: `runs-on`, which GitHub resolves before any make target exists — expose it as a repository variable (`RUNNER_LABELS` here) so *where* a job runs stays configurable without forking the file; and event handlers that need the token and the event payload (the issue labeler) — their logic lives in `scripts/*.js`, tested by `make check`, and the workflow is a two-line `actions/github-script` caller after a pinned checkout (ADR-0008). Neither shape puts adopter values in the YAML.
 2. **Least privilege by default.** Set `permissions: contents: read` at the workflow (top) level; escalate only inside the specific job that needs more, and only to the exact scope needed (e.g. `pull-requests: write` on a labeler job, not on the whole workflow).
 3. **Pin every third-party action to a full commit SHA**, with the human-readable version as a trailing comment — never a floating tag like `@v4`:
 
@@ -84,7 +84,8 @@ verify_checksum() {
 ## Related
 
 - `` `.github/workflows/ci.yml` `` — reference implementation of pinned actions, top-level `permissions: read`, concurrency group, `timeout-minutes`, and `persist-credentials: false`; also carries the header warning explaining why its `on:` block must never gain a path filter (the `ci` job is the only required status check)
-- `Makefile` — where all workflow logic actually lives (`lint`, `test`, `verify`, `ci-pr`, `ci-tools`)
+- `Makefile` — where workflow logic lives (`lint`, `test`, `verify`, `ci-pr`, `ci-tools`), except the event handler in `scripts/issue-labeler.js` (rule 1, ADR-0008)
+- `` `scripts/issue-labeler.js` `` / `` `scripts/check-issue-labeler.sh` `` — the one event handler and the `make check` step that tests it
 - `` `scripts/install-ci-tools.sh` `` — checksum-verified tool installs and the single home for all five CI tool version pins, shared by `ci.yml` and `maintenance.yml`
 - `` `scripts/check-tool-versions.sh` `` — rule 10's watcher: diffs those pins against upstream weekly and fails on drift
 - `AGENTS.md` — "The Makefile is the only executable contract in this repository"