@event4u/agent-config 9.18.0 → 9.18.1

package/.claude-plugin/marketplace.json

@@ -6,7 +6,7 @@
   },
   "metadata": {
     "description": "Bootstrap shim for the event4u agent-config suite. This plugin ships ONLY the dispatcher hooks plus one install-pointer skill — ALL content (skills, rules, commands) is installed via `npx -y @event4u/agent-config init`, which writes the file projection AND registers the same hooks in ~/.claude/settings.json. DEPRECATED as a content channel; kept so the marketplace listing stays discoverable and existing installs keep working hooks.",
-    "version": "9.18.0",
+    "version": "9.18.1",
     "keywords": [
       "agent-config",
       "skills",

package/CHANGELOG.md

@@ -82,6 +82,29 @@ Entry-shape contract: [`docs/contracts/CHANGELOG-conventions.md`](docs/contracts
 
 ### Fixed
 
+- **Every release PR was red on its first run — the generator and the
+  highlight gate contradicted each other.** `release.ts` wrote `_none_` into
+  all five curated-head fields; `check_release_highlights` (added 2026-08-03)
+  fails a `_none_` the release span contradicts. Because every release of this
+  package touches `src/rules/` or `src/scripts/schemas/`, "Behaviour changes"
+  is *always* substantiated, so the gate reliably red-flagged the generator's
+  own default — 9.17.0 (run 30871194277) and 9.18.0 (run 30909511315) both
+  failed on that one step, and each release had to be unblocked by hand.
+  - The span → category classifier now lives once, in
+    `src/scripts/_lib/release_highlights.ts`, and is shared by the generator
+    and the gate; the two duplicated label lists are gone with it.
+  - `release.ts` **pre-fills** each substantiated label with the deriving
+    reason plus its citing SHAs (capped at 6, remainder stated, never silently
+    truncated). `_none_` is now a fallback for labels the span does not
+    substantiate, not a blanket default — so the tool no longer asserts five
+    things it never checked.
+  - The gate keeps full teeth for the failure it was actually built for: a
+    **human** editing a substantiated line back down to `_none_`, which is what
+    produced the false 9.13.0 and 9.14.0 heads. An unrewritten auto-derived
+    line is advisory (a prose gap, not a false claim) and never blocks.
+  - Derivation is best-effort in the generator: a git failure degrades to the
+    `_none_` skeleton with a warning instead of aborting a release.
+
 - **`/team delegate` double gate is now enforced in code, not only in prose**
   (team mode stays default-off; closing `road-to-team-mode`). The gate on the
   only write-access wrapper existed as agent-followed instructions in the
@@ -271,6 +294,37 @@ Entry-shape contract: [`docs/contracts/CHANGELOG-conventions.md`](docs/contracts
 > that forces a new era split (`# Era: 9.19.x`, etc.) — see
 > [`docs/contracts/CHANGELOG-conventions.md § Era splits`](docs/contracts/CHANGELOG-conventions.md).
 
+## [9.18.1](https://github.com/event4u-app/agent-config/compare/9.18.0...9.18.1) (2026-08-04)
+
+### Release highlights
+
+<!-- Curated head: fill before merge, keep it under 10 lines, and leave `_none_` where it is genuinely the answer. The generated log below is unchanged. -->
+- **Behaviour changes:** the release generator pre-fills the curated head from the release span instead of writing `_none_` into all five fields (8fe60e9, 2f23d6b) — `_none_` now means "the span substantiates nothing", so a reader can trust it; review-gate scope classification changed, with IaC and extensionless build files counting as code and a findings row required to be exactly six cells (6c5f0f5).
+- **Default changes + migration:** _none_
+- **Security and correctness:** two more fail-open routes in the review-gate fence parser are closed — an unterminated fence no longer swallows the rest of a findings artefact (55dc01d) and a bare fence never delimits a region (9937ad9, the fourth such route); both previously let a truncated artefact read as clean.
+- **Honest nulls:** the honest-null recorded against 6c6fc15a9 in the 9.18.0 notes was **false** — the real binding review is restored (d56c0be), so treat that 9.18.0 line as withdrawn. Rounds 6 to 8 of the R2 review closed 7 findings and deferred 10, with 0 critical or high (7a0f7b3, 39f071f, 70bb89f).
+- **Known limitations:** the head pre-fill matches an `honest-null` literal anywhere in a commit body, so a commit *about* the mechanism gets cited as one — it did here, for 2f23d6b, and a human dropped it. The derived line is a draft, never a claim; the gate blocks only a `_none_` the span contradicts and never judges a filled field.
+
+### Bug Fixes
+
+* **release:** derive the head in --dry-run too, so the preview matches ([2f23d6b](https://github.com/event4u-app/agent-config/commit/2f23d6bb963577af5741951962b48e556e5a3e97))
+* **release:** stop the generator writing a `_none_` the gate rejects ([8fe60e9](https://github.com/event4u-app/agent-config/commit/8fe60e9aba5192c07f8e33bc6ce1747a77e82922))
+* **gates:** a bare fence never delimits a region — close the fourth fail-open route ([9937ad9](https://github.com/event4u-app/agent-config/commit/9937ad9b75f60bffd4ad42f2a830589bd4be7e5c))
+* **gates:** an unterminated fence must not swallow the rest of a findings artefact ([55dc01d](https://github.com/event4u-app/agent-config/commit/55dc01d1fd3c8dbf44dd04fa7b3f41e3f4bc39bb))
+* **gates:** IaC and extensionless build files are code; a row is exactly six cells ([6c5f0f5](https://github.com/event4u-app/agent-config/commit/6c5f0f5999b8a421cf765269a8da8b780465dc98))
+
+### Documentation
+
+* **review:** close round 8 — 1 fixed, 4 deferred, 0 critical ([70bb89f](https://github.com/event4u-app/agent-config/commit/70bb89f2820f4c5a5a26cd25f5db2daa53b08e5e))
+* **review:** close round 7 — 2 fixed, 3 deferred, 0 critical/high ([39f071f](https://github.com/event4u-app/agent-config/commit/39f071fad58dc2c5cb9e6ec87e8e37b79085db2f))
+* **gates:** in-place re-binding is the normal fix-pass path (2.1/2.5/2.7) ([1f7d140](https://github.com/event4u-app/agent-config/commit/1f7d1404c4bc63e87d4b46f91d52f81f2ae51f7b))
+* **review:** round-7 R2 findings — 2 medium, 3 low, 0 critical/high ([2bd3eda](https://github.com/event4u-app/agent-config/commit/2bd3edad82ff69700f62c4d16c93f38a484e5e08))
+* **review:** close round 6 — 4 fixed, 3 deferred, 0 critical/high ([7a0f7b3](https://github.com/event4u-app/agent-config/commit/7a0f7b33aed30921f2404ae1955a8e5aa76dde9b))
+* **gates:** two claims corrected to match the code (round-6 lows) ([0f5d43a](https://github.com/event4u-app/agent-config/commit/0f5d43a17be245b034287b0f486839fb156f8b86))
+* **review:** restore the real binding review — 6c6fc15a9's honest-null was false ([d56c0be](https://github.com/event4u-app/agent-config/commit/d56c0be63f6782183737ab50256401ab52a1f38f))
+
+Tests: 10963 (+19 since 9.18.0)
+
 ## [9.18.0](https://github.com/event4u-app/agent-config/compare/9.17.0...9.18.0) (2026-08-04)
 
 ### Release highlights

package/dist/agent-src/templates/agents/agent-project-settings.example.yml

@@ -39,7 +39,7 @@ schema_version: 1
 # CI guard: a release bump of `package.json` must update this value
 # in lockstep — see scripts/check_template_pin_drift.ts (road-to-
 # portable-runtime-and-update-check P3.3).
-agent_config_version: "9.18.0"
+agent_config_version: "9.18.1"
 
 # --- Project identity ---
 project:

package/dist/discovery/deprecation-report.md

@@ -1,6 +1,6 @@
 # Discovery — Deprecation Report
 
-- Generated: `2026-08-04T14:13:41Z`
+- Generated: `2026-08-04T15:34:05Z`
 - Deprecated artefacts: **0**
 
 _None. Tree is clean._

package/dist/discovery/discovery-manifest.json

@@ -14402,7 +14402,7 @@
       "reason": "scaffold template for ticket-bundle tickets (ADR-101); carries no runtime frontmatter — emit-tickets fills it in per ticket"
     }
   ],
-  "generated_at": "2026-08-04T14:13:41Z",
+  "generated_at": "2026-08-04T15:34:05Z",
   "packs": [
     {
       "artefact_count": 117,

package/dist/discovery/discovery-manifest.json.sha256

@@ -1 +1 @@
-4a7dadd2d33fe1127bfd31cb3bdf58c83d3609c17b740e06e8666569b760cf65  discovery-manifest.json
+9221573649a81d2b695576370a341ecdcd2d64ba0246a685d3caaf4582a78ca8  discovery-manifest.json

package/dist/discovery/discovery-manifest.summary.md

@@ -1,6 +1,6 @@
 # Discovery Manifest — Summary
 
-- Generated: `2026-08-04T14:13:41Z`
+- Generated: `2026-08-04T15:34:05Z`
 - Scanner: `c24312e116f8`
 - Artefacts: **594**
 - Unassigned: **0**

package/dist/discovery/orphan-report.md

@@ -1,6 +1,6 @@
 # Discovery — Orphan Report
 
-- Generated: `2026-08-04T14:13:41Z`
+- Generated: `2026-08-04T15:34:05Z`
 - Orphan artefacts: **0**
 
 > An orphan is an artefact whose declared pack has no other members.

package/dist/discovery/packs.json

@@ -1,6 +1,6 @@
 {
   "checksum": "sha256:d766f7f17140ce6b648e68821c9403c0bf478609a1ea925e85501c5994002a05",
-  "generated_at": "2026-08-04T14:13:41Z",
+  "generated_at": "2026-08-04T15:34:05Z",
   "packs": [
     {
       "always_on": false,

package/dist/discovery/trust-report.md

@@ -1,6 +1,6 @@
 # Discovery — Trust Report
 
-- Generated: `2026-08-04T14:13:41Z`
+- Generated: `2026-08-04T15:34:05Z`
 - Workspaces tracked: **10**
 - Human-review-required artefacts: **3**
 

package/dist/discovery/workspaces.json

@@ -1,6 +1,6 @@
 {
   "checksum": "sha256:d766f7f17140ce6b648e68821c9403c0bf478609a1ea925e85501c5994002a05",
-  "generated_at": "2026-08-04T14:13:41Z",
+  "generated_at": "2026-08-04T15:34:05Z",
   "scanner_version": "c24312e116f8",
   "workspaces": [
     {

package/dist/mcp/registry-manifest.json

@@ -9,7 +9,7 @@
     "homepage": "https://event4u-app.github.io/agent-config",
     "name": "@event4u/agent-config",
     "repository": "https://github.com/event4u-app/agent-config",
-    "version": "9.18.0"
+    "version": "9.18.1"
   },
   "registries": [
     {

package/dist/mcp/server.json

@@ -9,12 +9,12 @@
       "transport": {
         "type": "stdio"
       },
-      "version": "9.18.0"
+      "version": "9.18.1"
     }
   ],
   "repository": {
     "source": "github",
     "url": "https://github.com/event4u-app/agent-config"
   },
-  "version": "9.18.0"
+  "version": "9.18.1"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@event4u/agent-config",
     "mcpName": "io.github.event4u-app/agent-config",
-    "version": "9.18.0",
+    "version": "9.18.1",
     "description": "Governed skills, rules and commands for AI coding tools (Claude Code, Cursor, Windsurf, Copilot) — every claim machine-checked, including \"zero runtime daemon\".",
     "license": "MIT",
     "private": false,

package/src/config/gate-coverage.yml

@@ -329,8 +329,12 @@ gates:
       Gate R2 (docs/contracts/plan-review-gates.md § 2). HONEST LIMIT, stated
       because a floor that cannot fail is exactly the false green this file
       exists to prevent: scanned = artefacts inspected + 1 for the diff
-      evaluation, so it is >= 1 by construction and `min_scanned: 1` can never
-      trip. NOTHING ELSE TRIPS EITHER DURING THE ADVISORY WINDOW. The argv above
+      evaluation, so on any run that REACHES the count `min_scanned: 1` cannot
+      trip. It is not unreachable in principle — a moved reviews root exits
+      before the inventory and reports `scanned: 0`, which the guard does read —
+      but that path is the dead-scope violation below, so the floor never adds
+      anything the assertion does not already catch.
+      NOTHING TRIPS AT ALL DURING THE ADVISORY WINDOW. The argv above
       mirrors the CI invocation, and under `--advisory` every violation kind —
       dead-scan-scope included — is printed as a warning and the exit code is 0.
       So for the duration of the Stage-A window this entry proves only that the

package/src/scripts/_lib/release_highlights.ts

@@ -0,0 +1,279 @@
+/**
+ * Shared release-highlight classifier — one definition of the curated head's
+ * labels and of the span → category derivation.
+ *
+ * Used by BOTH sides on purpose:
+ *
+ * - the generator (`release.ts`) pre-fills the curated head with what it can
+ *   substantiate from the span;
+ * - the gate (`check_release_highlights.ts`) blocks a `_none_` the span
+ *   contradicts.
+ *
+ * Why shared instead of duplicated. Before this module the generator emitted
+ * `_none_` for all five fields while the gate rejected exactly that default
+ * the moment the span carried evidence. Every release of this package touches
+ * `src/rules/` or `src/scripts/schemas/`, so "Behaviour changes" is always
+ * substantiated and every release PR was red on its FIRST run by construction
+ * — 9.17.0 (run 30871194277) and 9.18.0 (run 30909511315) both hit it, on the
+ * same step, for the same reason.
+ *
+ * This is not a weaker gate. The generator no longer manufactures a claim it
+ * cannot support, and the gate keeps full teeth for the failure it was built
+ * for: a human editing a substantiated line back down to `_none_`, which is
+ * exactly what produced the false 9.13.0 and 9.14.0 heads. Machine-written
+ * `_none_` was never that failure; it was noise standing in front of it.
+ */
+import { spawnSync } from 'node:child_process';
+
+/** The five curated labels, in the order an operator reads them. */
+export const HEAD_LABELS: readonly string[] = [
+    'Behaviour changes',
+    'Default changes + migration',
+    'Security and correctness',
+    'Honest nulls',
+    'Known limitations',
+];
+
+export const HEAD_NONE = '_none_';
+
+/**
+ * Prefix marking a head line the generator derived rather than a human wrote.
+ *
+ * Machine-checkable so the gate can warn when one survives to merge, and
+ * readable so the line still says something true to anyone who ships it
+ * unedited. It is not a placeholder token: the line it introduces carries real
+ * evidence (the reason plus the citing SHAs), so nothing here is
+ * wrong-if-shipped — only unpolished-if-unedited.
+ */
+export const DERIVED_MARKER = '_auto-derived, rewrite before merge:_';
+
+/** Cap on cited SHAs per line, so a wide release cannot unbound the head. */
+export const DERIVED_SHA_CAP = 6;
+
+export interface SpanCommit {
+    sha: string;
+    subject: string;
+    body: string;
+    /** `A` / `M` / `D` / `R…` status per touched path. */
+    files: ReadonlyArray<{ status: string; path: string }>;
+    breaking: boolean;
+}
+
+/** One derived hit: the commit that substantiates a label. */
+export interface CategoryHit {
+    sha: string;
+    /** Rendered detail — the subject, plus a removed-surface note when any. */
+    text: string;
+}
+
+/** Public artefact trees whose deletions count as removed public surface. */
+const _PUBLIC_SURFACE_PREFIXES = [
+    'src/skills/',
+    'src/rules/',
+    'src/agent-src/commands/',
+    'src/domains/',
+];
+
+const _RULE_OR_SCHEMA_PREFIXES = ['src/rules/', 'src/scripts/schemas/'];
+
+/**
+ * Why a label fired, in generator-facing prose. Keyed by label; a label absent
+ * here is never derived (`Known limitations` is pure prose, not checkable).
+ */
+const _DERIVED_REASON: Readonly<Record<string, string>> = {
+    'Behaviour changes': 'rule/schema diffs, breaking commits or removed public surface',
+    'Default changes + migration': 'commits naming a default, migration or migrate',
+    'Security and correctness': 'security-scoped commits',
+    'Honest nulls': 'commits carrying an honest-null marker',
+};
+
+/**
+ * Derive evidence per curated label from the span. Rules per label:
+ *
+ * - Security and correctness: conventional scope matching /secur/i, or the
+ *   whole word "security" in the subject.
+ * - Behaviour changes: breaking (`!` / BREAKING CHANGE) commits, diffs
+ *   touching `src/rules/` or `src/scripts/schemas/`, and deletions under the
+ *   public artefact trees (removed public surface).
+ * - Default changes + migration: subject carrying the whole word "default",
+ *   "migration", or "migrate".
+ * - Honest nulls: subject or body carrying an "honest null" marker.
+ * - Known limitations: never derived — pure prose, not gate-checkable.
+ *
+ * Derivation is deliberately conservative: a false red makes every release
+ * annoying, a miss only returns the head to the pre-gate state.
+ */
+export function derive_category_hits(
+    commits: readonly SpanCommit[],
+): Record<string, CategoryHit[]> {
+    const out: Record<string, CategoryHit[]> = {};
+    for (const label of HEAD_LABELS) {
+        out[label] = [];
+    }
+    for (const c of commits) {
+        const scopeMatch = /^\w+\(([^)]*)\)!?:/u.exec(c.subject);
+        const scope = scopeMatch ? scopeMatch[1]! : '';
+        if (/secur/iu.test(scope) || /\bsecurity\b/iu.test(c.subject)) {
+            out['Security and correctness']!.push({ sha: c.sha, text: c.subject });
+        }
+        const removedPublic = c.files.filter(
+            (f) =>
+                f.status.startsWith('D') &&
+                _PUBLIC_SURFACE_PREFIXES.some((p) => f.path.startsWith(p)),
+        );
+        const ruleOrSchema = c.files.some((f) =>
+            _RULE_OR_SCHEMA_PREFIXES.some((p) => f.path.startsWith(p)),
+        );
+        if (c.breaking || ruleOrSchema || removedPublic.length > 0) {
+            const text =
+                removedPublic.length > 0
+                    ? `${c.subject} (removes ${removedPublic.map((f) => f.path).join(', ')})`
+                    : c.subject;
+            out['Behaviour changes']!.push({ sha: c.sha, text });
+        }
+        if (/\b(default|migration|migrate)\b/iu.test(c.subject)) {
+            out['Default changes + migration']!.push({ sha: c.sha, text: c.subject });
+        }
+        if (/honest[ -]null/iu.test(`${c.subject}\n${c.body}`)) {
+            out['Honest nulls']!.push({ sha: c.sha, text: c.subject });
+        }
+    }
+    return out;
+}
+
+/**
+ * String-rendered evidence per label (`<sha7> <detail>`), the shape the gate
+ * reports to a human. Derived from the structured hits so the two can never
+ * disagree.
+ */
+export function derive_categories(commits: readonly SpanCommit[]): Record<string, string[]> {
+    const hits = derive_category_hits(commits);
+    const out: Record<string, string[]> = {};
+    for (const label of HEAD_LABELS) {
+        out[label] = (hits[label] ?? []).map((h) => `${h.sha.slice(0, 7)} ${h.text}`);
+    }
+    return out;
+}
+
+/**
+ * Pre-fill values for the curated head, one line per SUBSTANTIATED label.
+ *
+ * A label with no evidence is omitted, so the caller's `_none_` default still
+ * applies where `_none_` is the true answer. One line per label keeps the
+ * rendered head inside its cap; SHA citations are capped at `DERIVED_SHA_CAP`
+ * with an explicit remainder count rather than a silent truncation.
+ */
+export function render_derived_head_values(
+    hits: Readonly<Record<string, readonly CategoryHit[]>>,
+): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (const label of HEAD_LABELS) {
+        const reason = _DERIVED_REASON[label];
+        const ev = hits[label] ?? [];
+        if (!reason || ev.length === 0) {
+            continue;
+        }
+        const shas = ev.map((h) => h.sha.slice(0, 7));
+        const shown = shas.slice(0, DERIVED_SHA_CAP);
+        const remainder = shas.length - shown.length;
+        const more = remainder > 0 ? ` +${remainder} more` : '';
+        out[label] = `${DERIVED_MARKER} ${reason} in ${shown.join(', ')}${more}.`;
+    }
+    return out;
+}
+
+/** Labels whose curated value is still the generator's unedited draft. */
+export function stale_draft_labels(
+    curated: Readonly<Record<string, string>>,
+): string[] {
+    return HEAD_LABELS.filter((l) => (curated[l] ?? '').includes(DERIVED_MARKER));
+}
+
+// ─── git span collection ────────────────────────────────────────────────────
+
+const _RECORD = '\u001e';
+const _FIELD = '\u001f';
+
+export function parse_git_log(raw: string): SpanCommit[] {
+    const commits: SpanCommit[] = [];
+    for (const record of raw.split(_RECORD)) {
+        if (!record.trim()) {
+            continue;
+        }
+        const [head, ...restLines] = record.split('\n');
+        const parts = (head ?? '').split(_FIELD);
+        if (parts.length < 3) {
+            continue;
+        }
+        const sha = parts[0]!.trim();
+        const subject = parts[1]!;
+        const bodyParts: string[] = [parts.slice(2).join(_FIELD)];
+        const files: Array<{ status: string; path: string }> = [];
+        for (const line of restLines) {
+            const m = /^([A-Z]\d*)\t(.+)$/u.exec(line);
+            if (m) {
+                // Renames carry two paths; the last tab field is the new path,
+                // the first the old — record both so a rename out of a public
+                // tree still counts its origin path.
+                const segs = m[2]!.split('\t');
+                for (const p of segs) {
+                    files.push({ status: m[1]!, path: p });
+                }
+            } else {
+                // %b is multi-line — everything that is not a name-status
+                // line is body continuation (honest-null markers live there).
+                bodyParts.push(line);
+            }
+        }
+        const body = bodyParts.join('\n');
+        commits.push({
+            sha,
+            subject,
+            body,
+            files,
+            breaking: /^\w+(\([^)]*\))?!:/u.test(subject) || /BREAKING CHANGE/u.test(body),
+        });
+    }
+    return commits;
+}
+
+/** `git log` arguments for a span, shared so both callers read one format. */
+export function span_log_args(from: string | null, to: string): string[] {
+    return [
+        'log',
+        from ? `${from}..${to}` : to,
+        '--no-merges',
+        '--name-status',
+        '--format=%x1e%H%x1f%s%x1f%b',
+    ];
+}
+
+/**
+ * Collect the span. Throws on git failure so a caller can decide whether the
+ * derivation is load-bearing (the gate) or best-effort (the generator).
+ */
+export function collect_span_commits(from: string | null, to: string, cwd: string): SpanCommit[] {
+    const r = spawnSync('git', span_log_args(from, to), {
+        encoding: 'utf-8',
+        cwd,
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (r.status !== 0) {
+        throw new Error(`git ${span_log_args(from, to).join(' ')} failed: ${r.stderr}`);
+    }
+    return parse_git_log(r.stdout);
+}
+
+/** Latest reachable release tag before `ref`, or null when there is none. */
+export function previous_release_tag(ref: string, cwd: string): string | null {
+    const r = spawnSync(
+        'git',
+        ['describe', '--tags', '--abbrev=0', '--match', '[0-9]*.[0-9]*.[0-9]*', `${ref}^`],
+        { encoding: 'utf-8', cwd },
+    );
+    if (r.status !== 0) {
+        return null;
+    }
+    const tag = r.stdout.trim();
+    return tag === '' ? null : tag;
+}

package/src/scripts/check_completion_review.ts

@@ -18,10 +18,15 @@
  *     with the required Reason/Ref content;
  *   - every table-shaped row parses into the six §2.2 cells (`malformed-row`) —
  *     a short row is never silently dropped, or an `open` finding would pass;
+ *   - ``` fences resolve (`unbalanced-fence`) — only a LABELLED, properly-closed
+ *     fence hides content, so no arrangement of bare fences can swallow a row,
+ *     for the same reason;
  *   - severity rows are sorted descending (critical > high > medium > low);
  *   - findings-before-fixes ancestry: the commit that FIRST added the
  *     artifact is an ancestor of every referenced fix commit (§2.5 — the
- *     first-add commit is what counts, so backdating is detected too).
+ *     first-add commit is what counts, so backdating is detected too; it is the
+ *     earliest add of the PATH, so the guarantee covers the artefact's FIRST
+ *     round, and per-round ordering stays convention — §2.5 names that limit).
  *
  * The review binds to the review-SCOPE HASH, never to a commit sha. That
  * definition is owned by `dispatch_r2_reviewer.ts` and imported here so the
@@ -114,6 +119,16 @@ export interface ParsedArtifact {
      * defect class.
      */
     malformedRows: string[];
+    /**
+     * 1-based lines of every stray ``` fence, ascending (§2.2).
+     *
+     * A stray is a BARE ``` (which never delimits a region) or a labelled opener
+     * that is never closed. All of them are reported as one `unbalanced-fence`
+     * violation naming every line — a single number could only ever name the
+     * last. Stray fences skip nothing: the lines around them are parsed, because
+     * no fence arrangement may swallow an `open` row (see {@link scanFences}).
+     */
+    strayFenceLines: number[];
     /** The §5 context manifest, when present and parseable. */
     manifest: ParsedManifest | null;
 }
@@ -181,8 +196,46 @@ const CODE_EXTENSIONS = new Set([
     'erl',
     'dart',
     'r',
+    // Infrastructure-as-code and build definitions. Production behaviour lives
+    // here as much as in application code — this suite ships terraform /
+    // terragrunt / aws-infrastructure skills and an engineering-safety-floor
+    // that treats these files as prod surfaces, so omitting them let an
+    // IaC-only completion claim "no code surface" and take the skip path.
+    'tf',
+    'tfvars',
+    'hcl',
+    'gradle',
+    'cmake',
+    'proto',
+    'bicep',
 ]);
 
+/**
+ * Extensionless build / infra files. `isCodePath` decides by extension, so a
+ * `Dockerfile` or `Makefile` (no dot) fell through to "not code" — the same
+ * hole as a missing extension, one step further along.
+ */
+const CODE_BASENAMES = new Set([
+    'dockerfile',
+    'containerfile',
+    'makefile',
+    'jenkinsfile',
+    'vagrantfile',
+    'procfile',
+    'brewfile',
+    'rakefile',
+    'gemfile',
+    'justfile',
+]);
+
+/**
+ * Tails that turn a {@link CODE_BASENAMES} stem into generated or prose state
+ * rather than code — `Gemfile.lock`, `Makefile.md`. Kept narrow on purpose: an
+ * unknown tail (`Dockerfile.prod`) stays code, so the classification errs broad
+ * exactly as contract §2.4 promises.
+ */
+const GENERATED_TAILS = new Set(['lock', 'md', 'txt', 'json', 'yml', 'yaml', 'bak', 'orig']);
+
 /**
  * Template extensions whose *inner* extension decides. `foo.blade.php` is
  * already caught by `php`; `foo.html.twig` / `foo.j2` are not, so they are
@@ -216,6 +269,18 @@ export function isCodePath(p: string): boolean {
     if (CODE_SUFFIXES.some((s) => base.endsWith(s))) {
         return true;
     }
+    // Extensionless build/infra files (Dockerfile, Makefile, …) plus their
+    // environment variants (`Dockerfile.prod`, `Makefile.local`). A generated
+    // sibling that merely shares the stem is NOT code — `Gemfile.lock` is
+    // dependency state, the same class as the `composer.json` this function
+    // already excludes.
+    const stem = base.includes('.') ? base.slice(0, base.indexOf('.')) : base;
+    if (CODE_BASENAMES.has(stem)) {
+        const tail = base.slice(stem.length + 1);
+        if (tail === '' || !GENERATED_TAILS.has(tail)) {
+            return true;
+        }
+    }
     const dot = base.lastIndexOf('.');
     if (dot <= 0) {
         return false;
@@ -301,6 +366,91 @@ function splitTableRow(line: string): string[] {
 }
 
 const FENCE_RE = /^\s*```/;
+/** A ```-prefixed line split into its backtick run and its info string. */
+const FENCE_PARTS_RE = /^\s*(`{3,})(.*)$/;
+
+export interface FenceScan {
+    /** 0-based indices of lines inside a LABELLED, properly-closed fence — the only lines to skip. */
+    fenced: Set<number>;
+    /**
+     * 1-based line numbers of every stray ``` fence, ascending.
+     *
+     * A stray is a bare ``` that opens nothing (no region is ever delimited by
+     * one) or a labelled opener that is never closed. Empty = fences are sound.
+     */
+    strays: number[];
+}
+
+/** Backtick-run length and info string of a fence line, or null if not a fence. */
+function fenceParts(line: string): { ticks: number; info: string } | null {
+    const m = FENCE_PARTS_RE.exec(line);
+    return m ? { ticks: (m[1] as string).length, info: (m[2] as string).trim() } : null;
+}
+
+/**
+ * Which lines are fenced — and which ``` fences are stray?
+ *
+ * Fenced regions exist for ONE reason: an *illustrative* template row (the §2.2
+ * `| # | Severity | …` example a doc-ish artefact quotes) must not be read as a
+ * live finding. Nothing else justifies making a line invisible, so the
+ * delimiter has to be something no author produces by accident.
+ *
+ * Two earlier shapes both failed OPEN, and they are the same defect:
+ *   - a single `inFence` toggle made every line after an ODD ```-count invisible;
+ *   - POSITIONAL pairing then detected parity but never MIS-pairing — two
+ *     unpaired inner openers (two `~~~`-wrapped illustrations, each holding one
+ *     stray ``` — exactly what `markdown-safe-codeblocks` produces, since the
+ *     outer `~~~` is not a fence to this grammar) paired with EACH OTHER and
+ *     swallowed every line between them, `unterminatedAt` staying `null`.
+ * In both, one earlier well-formed row kept `rows.length > 0`, so the
+ * neither-table-nor-honest-null fallback also stayed quiet and an unreviewed
+ * `open` row PASSED — the same fail-open the §2.2 `malformed-row` rule closes by
+ * a different route. Patching parity, then pairing, then the next arrangement is
+ * a losing game, so the discriminator is fixed instead of the arithmetic:
+ *
+ *   A region is skipped ONLY when it is a properly-closed pair whose OPENING
+ *   fence carries an info string (```` ```markdown ````). A BARE ``` never
+ *   delimits a region: it is recorded as a stray, the lines around it are parsed
+ *   as ordinary content, and the artefact is reported `unbalanced-fence`.
+ *
+ * So no arrangement of bare fences can hide a row — a swallowed `open` finding
+ * needs a deliberate label, which is the authoring act that means "illustration".
+ * Closing follows CommonMark (bare, and at least as many backticks as the
+ * opener), which also makes a ```` ````-wrapped ``` block nest correctly. An
+ * unterminated labelled opener skips nothing either and is itself a stray.
+ */
+export function scanFences(lines: readonly string[]): FenceScan {
+    const fenced = new Set<number>();
+    const strays: number[] = [];
+    let open: { at: number; ticks: number } | null = null;
+    for (let i = 0; i < lines.length; i++) {
+        const parts = fenceParts(lines[i] as string);
+        if (!parts) {
+            continue;
+        }
+        if (open !== null) {
+            // CommonMark closer: bare, and at least as long as the opener.
+            // Anything else is content inside the open region.
+            if (parts.info === '' && parts.ticks >= open.ticks) {
+                for (let j = open.at + 1; j < i; j++) {
+                    fenced.add(j);
+                }
+                open = null;
+            }
+            continue;
+        }
+        if (parts.info === '') {
+            strays.push(i + 1);
+            continue;
+        }
+        open = { at: i, ticks: parts.ticks };
+    }
+    if (open !== null) {
+        strays.push(open.at + 1);
+    }
+    strays.sort((a, b) => a - b);
+    return { fenced, strays };
+}
 
 export function parseArtifact(text: string): ParsedArtifact {
     const out: ParsedArtifact = {
@@ -311,18 +461,20 @@ export function parseArtifact(text: string): ParsedArtifact {
         rows: [],
         malformedLines: [],
         malformedRows: [],
+        strayFenceLines: [],
         manifest: parseManifest(text),
     };
     const lines = text.split(/\r?\n/);
-    let inFence = false;
+    const fences = scanFences(lines);
+    out.strayFenceLines = fences.strays;
     for (let i = 0; i < lines.length; i++) {
         const raw = lines[i] as string;
         const lineno = i + 1;
-        if (FENCE_RE.test(raw)) {
-            inFence = !inFence;
-            continue;
-        }
-        if (inFence) {
+        // A fence marker line carries no grammar of its own, and a line inside a
+        // LABELLED closed fence is illustrative content. A stray fence (bare, or
+        // an unclosed opener) skips nothing (see scanFences) — the lines around
+        // it are parsed, and the artefact is reported.
+        if (FENCE_RE.test(raw) || fences.fenced.has(i)) {
             continue;
         }
         const trimmed = raw.trim();
@@ -371,7 +523,12 @@ export function parseArtifact(text: string): ParsedArtifact {
             if (first === '#' || second === 'severity') {
                 continue; // header row
             }
-            if (cells.length >= 6) {
+            // EXACTLY six, per contract §2.2 — not `>= 6`. An over-long row is
+            // as malformed as a short one and the surplus is usually the tell:
+            // an unescaped `|` inside a cell (the shape §2.2 requires escaping)
+            // splits one cell into two and shifts Status/Reason-Ref rightwards,
+            // so accepting it silently reads the wrong cell as the status.
+            if (cells.length === 6) {
                 out.rows.push({
                     index: cells[0] ?? '',
                     severity: (cells[1] ?? '').toLowerCase(),
@@ -390,7 +547,7 @@ export function parseArtifact(text: string): ParsedArtifact {
                 // §2.2 template ends in exactly that empty cell. Gate R1 already
                 // reports this class — same name, `malformed_row`.
                 out.malformedRows.push(
-                    `line ${lineno}: findings row has ${String(cells.length)} cell(s), expected 6 ` +
+                    `line ${lineno}: findings row has ${String(cells.length)} cell(s), expected exactly 6 ` +
                         '(`| # | Severity | File:Line | Finding | Status | Reason/Ref |` — the trailing ' +
                         'Reason/Ref cell is required even when empty)',
                 );
@@ -605,6 +762,24 @@ function evaluate(input: EvalInput): Violation[] {
         for (const detail of art.malformedRows) {
             violations.push({ kind: 'malformed-row', file, detail });
         }
+        // §2.2: stray ``` fences — a BARE fence (which delimits nothing) or a
+        // labelled opener left unclosed. The parser swallows no line around them
+        // (so an `open` row still blocks), but an artefact whose fences do not
+        // resolve is malformed in its own right — the reader cannot tell
+        // illustrative content from live rows. ONE violation naming EVERY stray:
+        // a single line number could only ever name the last one.
+        if (art.strayFenceLines.length > 0) {
+            const at = art.strayFenceLines.map((n) => `line ${String(n)}`).join(', ');
+            violations.push({
+                kind: 'unbalanced-fence',
+                file,
+                detail:
+                    `${at}: stray \`\`\` fence — a bare fence delimits no region, and a labelled fence must ` +
+                    'be closed. An artefact whose ``` fences do not resolve is malformed (contract §2.2). ' +
+                    'Label the opener (```markdown) and close it, or inline-escape an illustrative ```; ' +
+                    'the lines around a stray fence are still parsed, so any finding row there is validated too.',
+            });
+        }
     }
 
     for (const { file, art } of relevant) {
@@ -757,6 +932,13 @@ function checkFindingsBeforeFixes(repo: string, artifactAbs: string, rows: reado
     // Earliest add commit: `git log --diff-filter=A` lists newest-first, so the
     // LAST line is the first commit that ever added the file (backdating via a
     // later amend does not move it).
+    //
+    // Scope of the guarantee, per contract §2.5: this resolves the earliest add
+    // of the PATH, not of the current round's artefact — a re-bound (or renamed
+    // and re-added) `<slug>.findings.md` keeps round 1's add. So the check proves
+    // "the review file existed before the fixes of its FIRST round", and
+    // per-round ordering stays agent-carried convention. Deliberate, and named
+    // as a limit in the contract rather than implied away.
     const logRes = gitTry(repo, ['log', '--diff-filter=A', '--format=%H', '--', rel]);
     const addLines = logRes.stdout
         .split('\n')

package/src/scripts/check_release_highlights.ts

@@ -11,8 +11,14 @@
  * commit types + rule/schema diffs, honest-null markers, removed public
  * surface) and FAILS when a populated generated category meets a `_none_`
  * curated field. It blocks the contradiction only — a human still writes the
- * prose; nothing here auto-formulates highlights, and a filled field is
- * never judged for quality.
+ * prose, and a filled field is never judged for quality.
+ *
+ * The classifier lives in `_lib/release_highlights.ts` and is shared with the
+ * generator, which now pre-fills each substantiated label instead of writing
+ * `_none_` everywhere. That removes the guaranteed first-run red (9.17.0,
+ * 9.18.0) without blunting this gate: a machine-written `_none_` was never the
+ * failure it was built for — a HUMAN writing one was (9.13.0, 9.14.0), and that
+ * still fails here. An unrewritten derived line warns; it never blocks.
  *
  * Derivation is deliberately conservative (documented per-label below):
  * a false red makes every release annoying; a miss only returns the head to
@@ -25,96 +31,41 @@
  * `--from` defaults to the latest reachable release tag before `--to`
  * (default HEAD). Exit codes: 0 plausible · 1 contradiction · 2 usage error.
  */
-import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
+import {
+    HEAD_LABELS,
+    HEAD_NONE,
+    type SpanCommit,
+    collect_span_commits,
+    derive_categories,
+    parse_git_log,
+    previous_release_tag,
+    stale_draft_labels,
+} from './_lib/release_highlights.js';
 import { extract_changelog_section } from './_lib/release_material.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 
-// The five curated labels, mirrored from release.ts RELEASE_HEAD_SECTIONS
-// (kept literal here so this checker has no import edge into the release
-// pipeline it audits; the unit tests pin the two lists against each other).
-export const HEAD_LABELS: readonly string[] = [
-    'Behaviour changes',
-    'Default changes + migration',
-    'Security and correctness',
-    'Honest nulls',
-    'Known limitations',
-];
-
-export const HEAD_NONE = '_none_';
-
-export interface SpanCommit {
-    sha: string;
-    subject: string;
-    body: string;
-    /** `A` / `M` / `D` / `R…` status per touched path. */
-    files: ReadonlyArray<{ status: string; path: string }>;
-    breaking: boolean;
-}
-
-/** Public artefact trees whose deletions count as removed public surface. */
-const _PUBLIC_SURFACE_PREFIXES = [
-    'src/skills/',
-    'src/rules/',
-    'src/agent-src/commands/',
-    'src/domains/',
-];
-
-const _RULE_OR_SCHEMA_PREFIXES = ['src/rules/', 'src/scripts/schemas/'];
-
-/**
- * Derive evidence per curated label from the span. Rules per label:
- *
- * - Security and correctness: conventional scope matching /secur/i, or the
- *   whole word "security" in the subject.
- * - Behaviour changes: breaking (`!` / BREAKING CHANGE) commits, diffs
- *   touching `src/rules/` or `src/scripts/schemas/`, and deletions under the
- *   public artefact trees (removed public surface).
- * - Default changes + migration: subject carrying the whole word "default",
- *   "migration", or "migrate".
- * - Honest nulls: subject or body carrying an "honest null" marker.
- * - Known limitations: never derived — pure prose, not gate-checkable.
- */
-export function derive_categories(commits: readonly SpanCommit[]): Record<string, string[]> {
-    const out: Record<string, string[]> = {};
-    for (const label of HEAD_LABELS) {
-        out[label] = [];
-    }
-    const evidence = (c: SpanCommit): string => `${c.sha.slice(0, 7)} ${c.subject}`;
-    for (const c of commits) {
-        const scopeMatch = /^\w+\(([^)]*)\)!?:/u.exec(c.subject);
-        const scope = scopeMatch ? scopeMatch[1]! : '';
-        if (/secur/iu.test(scope) || /\bsecurity\b/iu.test(c.subject)) {
-            out['Security and correctness']!.push(evidence(c));
-        }
-        const removedPublic = c.files.filter(
-            (f) => f.status.startsWith('D') && _PUBLIC_SURFACE_PREFIXES.some((p) => f.path.startsWith(p)),
-        );
-        const ruleOrSchema = c.files.some((f) =>
-            _RULE_OR_SCHEMA_PREFIXES.some((p) => f.path.startsWith(p)),
-        );
-        if (c.breaking || ruleOrSchema || removedPublic.length > 0) {
-            const detail =
-                removedPublic.length > 0
-                    ? `${evidence(c)} (removes ${removedPublic.map((f) => f.path).join(', ')})`
-                    : evidence(c);
-            out['Behaviour changes']!.push(detail);
-        }
-        if (/\b(default|migration|migrate)\b/iu.test(c.subject)) {
-            out['Default changes + migration']!.push(evidence(c));
-        }
-        if (/honest[ -]null/iu.test(`${c.subject}\n${c.body}`)) {
-            out['Honest nulls']!.push(evidence(c));
-        }
-    }
-    return out;
-}
+// Labels and derivation live in `_lib/release_highlights.ts` — ONE definition
+// shared with the generator that pre-fills the head. They used to be duplicated
+// here to keep the checker independent of the release pipeline, and that
+// independence is what produced the defect this gate now guards against from
+// the other side: the generator wrote `_none_` into every field while this
+// checker rejected exactly that, so every release PR was red on its first run.
+// Sharing the classifier does not blunt the gate — it still blocks the failure
+// it was built for, a human editing a substantiated line back to `_none_`.
+export {
+    HEAD_LABELS,
+    HEAD_NONE,
+    derive_categories,
+    parse_git_log as _parse_git_log,
+    type SpanCommit,
+};
 
 /**
  * Parse the curated head from a changelog section body. Returns null when
@@ -162,74 +113,6 @@ export function highlight_contradictions(
     return out;
 }
 
-// ─── git span collection (CLI only — the core above is pure) ────────────────
-
-const _RECORD = '\u001e';
-const _FIELD = '\u001f';
-
-export function _parse_git_log(raw: string): SpanCommit[] {
-    const commits: SpanCommit[] = [];
-    for (const record of raw.split(_RECORD)) {
-        if (!record.trim()) {
-            continue;
-        }
-        const [head, ...restLines] = record.split('\n');
-        const parts = (head ?? '').split(_FIELD);
-        if (parts.length < 3) {
-            continue;
-        }
-        const sha = parts[0]!.trim();
-        const subject = parts[1]!;
-        const bodyParts: string[] = [parts.slice(2).join(_FIELD)];
-        const files: Array<{ status: string; path: string }> = [];
-        for (const line of restLines) {
-            const m = /^([A-Z]\d*)\t(.+)$/u.exec(line);
-            if (m) {
-                // Renames carry two paths; the last tab field is the new path,
-                // the first the old — record both so a rename out of a public
-                // tree still counts its origin path.
-                const segs = m[2]!.split('\t');
-                for (const p of segs) {
-                    files.push({ status: m[1]!, path: p });
-                }
-            } else {
-                // %b is multi-line — everything that is not a name-status
-                // line is body continuation (honest-null markers live there).
-                bodyParts.push(line);
-            }
-        }
-        const body = bodyParts.join('\n');
-        commits.push({
-            sha,
-            subject,
-            body,
-            files,
-            breaking: /^\w+(\([^)]*\))?!:/u.test(subject) || /BREAKING CHANGE/u.test(body),
-        });
-    }
-    return commits;
-}
-
-function _git(args: string[]): string {
-    const r = spawnSync('git', args, { encoding: 'utf-8', cwd: REPO_ROOT, maxBuffer: 64 * 1024 * 1024 });
-    if (r.status !== 0) {
-        process.stderr.write(`git ${args.join(' ')} failed: ${r.stderr}\n`);
-        process.exit(2);
-    }
-    return r.stdout;
-}
-
-function _collect_span(from: string, to: string): SpanCommit[] {
-    const raw = _git([
-        'log',
-        `${from}..${to}`,
-        '--no-merges',
-        '--name-status',
-        '--format=%x1e%H%x1f%s%x1f%b',
-    ]);
-    return _parse_git_log(raw);
-}
-
 function main(argv: readonly string[]): number {
     let version: string | null = null;
     let from: string | null = null;
@@ -251,7 +134,13 @@ function main(argv: readonly string[]): number {
         return 2;
     }
     if (!from) {
-        from = _git(['describe', '--tags', '--abbrev=0', '--match', '[0-9]*.[0-9]*.[0-9]*', `${to}^`]).trim();
+        from = previous_release_tag(to, REPO_ROOT);
+        if (!from) {
+            process.stderr.write(
+                `no release tag reachable before ${to} — pass --from explicitly\n`,
+            );
+            return 2;
+        }
     }
     const section = extract_changelog_section(fs.readFileSync(changelogPath, 'utf-8'), version);
     if (!section) {
@@ -263,7 +152,26 @@ function main(argv: readonly string[]): number {
         process.stdout.write(`ℹ️  no curated head in the ${version} section — nothing to check\n`);
         return 0;
     }
-    const derived = derive_categories(_collect_span(from, to));
+    let span: SpanCommit[];
+    try {
+        span = collect_span_commits(from, to, REPO_ROOT);
+    } catch (err) {
+        process.stderr.write(`${(err as Error).message}\n`);
+        return 2;
+    }
+    // A generator-derived line that nobody rewrote is a prose gap, never a
+    // contradiction: the line's evidence is true, it is just unpolished. Warn
+    // so the omission is visible, and keep the exit code owned solely by the
+    // `_none_` check — a warning that reds the build is the guaranteed-red
+    // failure mode this whole change exists to remove.
+    const drafts = stale_draft_labels(curated);
+    if (drafts.length > 0) {
+        process.stdout.write(
+            `⚠️  auto-derived head line(s) not yet rewritten for ${version}: ` +
+                `${drafts.join(', ')} — advisory, not blocking.\n`,
+        );
+    }
+    const derived = derive_categories(span);
     const contradictions = highlight_contradictions(curated, derived);
     if (contradictions.length === 0) {
         process.stdout.write(`✅  curated head plausible for ${version} (span ${from}..${to})\n`);

package/src/scripts/dispatch_r2_reviewer.ts

@@ -437,11 +437,12 @@ const CI_BRANCH_ENV_KEYS = ['GITHUB_HEAD_REF', 'GITHUB_REF_NAME'] as const;
  * uses it to decide whether a leftover artifact in the reviews directory is
  * THIS branch's (and may therefore produce violations) or a foreign one.
  *
- * The CI environment is consulted FIRST because on a `pull_request` checkout
- * `HEAD` is a detached synthetic merge commit: `rev-parse --abbrev-ref HEAD`
- * yields `HEAD`, the slug degrades to `detached-<sha>`, and no artefact can
- * ever be "own" — which inverts contract §2.6 on the layer the contract calls
- * authoritative (an own malformed artefact would be reported as
+ * Resolution order is **git first, CI environment as the fallback** — see the
+ * reason inline below. The env fallback exists because on a `pull_request`
+ * checkout `HEAD` is a detached synthetic merge commit: `rev-parse --abbrev-ref
+ * HEAD` yields `HEAD`, the slug would degrade to `detached-<sha>`, and no
+ * artefact could ever be "own" — inverting contract §2.6 on the layer the
+ * contract calls authoritative (an own malformed artefact would report
  * `missing-artifact` instead of the root-cause `bad-marker`, and `stale-review`
  * would never fire in CI). A `HEAD` / `detached-*` env value carries no branch
  * identity either and is ignored.

package/src/scripts/release.ts

@@ -118,6 +118,12 @@ import {
     perform_split,
     plan_split,
 } from './_lib/changelog_eras.js';
+import {
+    HEAD_LABELS,
+    collect_span_commits,
+    derive_category_hits,
+    render_derived_head_values,
+} from './_lib/release_highlights.js';
 import {
     extract_changelog_section,
     pr_body_from_section,
@@ -383,13 +389,7 @@ const SECTIONS: ReadonlyArray<readonly [string, string | null, readonly string[]
  * so the package does not end up with two competing definitions of a curated
  * head.
  */
-const RELEASE_HEAD_SECTIONS: ReadonlyArray<string> = [
-    'Behaviour changes',
-    'Default changes + migration',
-    'Security and correctness',
-    'Honest nulls',
-    'Known limitations',
-];
+const RELEASE_HEAD_SECTIONS: ReadonlyArray<string> = HEAD_LABELS;
 
 /**
  * Cap on the head, in rendered lines.
@@ -402,16 +402,44 @@ const RELEASE_HEAD_SECTIONS: ReadonlyArray<string> = [
 export const RELEASE_HEAD_CAP_LINES = 10;
 
 /**
- * The default value of every head line.
+ * The fallback value of a head line the span does not substantiate.
+ *
+ * `_none_` and not a placeholder token: where nothing was derived it is the
+ * **true** answer, and a release that genuinely changed no defaults should say
+ * so rather than carry an unfilled marker.
  *
- * `_none_` and not a placeholder token: for most releases it is the **true**
- * answer, and a release that genuinely changed no defaults should say so
- * rather than carry an unfilled marker. That also keeps the skeleton free of
- * the placeholder prose `output-discipline` bans — there is nothing here that
- * is wrong-if-shipped, only something that is uninformative-if-unedited.
+ * It is a fallback and no longer a blanket default. Writing `_none_` into
+ * every field made the generator assert five things it had not checked, and
+ * `check_release_highlights` rejected exactly that assertion the moment the
+ * span contradicted it — which for this package is every release, because every
+ * release touches `src/rules/` or `src/scripts/schemas/`. Substantiated labels
+ * are now pre-filled from the span (`_derive_head_prefill`), so the tool states
+ * only what it can support and `_none_` means what it says.
  */
 const HEAD_DEFAULT = '_none_';
 
+/**
+ * Pre-fill values for the curated head from the release span.
+ *
+ * Best-effort by design, same stance as the test-trend footer: a git failure
+ * degrades to the `_none_` skeleton rather than blocking a release. The gate
+ * that reads the result runs later, on the branch head, and derives from the
+ * same shared classifier — so a degraded run surfaces as the gate's ordinary
+ * "fill the head" message instead of a crash mid-release.
+ */
+function _derive_head_prefill(prev: string | null): Record<string, string> {
+    try {
+        const span = collect_span_commits(prev, 'HEAD', REPO_ROOT);
+        return render_derived_head_values(derive_category_hits(span));
+    } catch (err) {
+        process.stderr.write(
+            `warning: could not derive release-head highlights (${(err as Error).message}); ` +
+                'the head ships as the `_none_` skeleton\n',
+        );
+        return {};
+    }
+}
+
 /**
  * Render the curated head. Emitted by the generator on every release so it
  * cannot be forgotten; edited by the maintainer before merge.
@@ -2344,8 +2372,14 @@ function main(argv: readonly string[] | null = null): number {
     // (~15s+), which `--dry-run exits 0 without needing …` contracts (and
     // the release test) assume never runs. Real releases compute it.
     const test_trend_line = args.dry_run ? null : _render_test_trend_line(prev);
+    // Derived unconditionally, dry-run included: it is one `git log` (~25 ms),
+    // not the trend line's full vitest collection. Skipping it on `--dry-run`
+    // made the preview print the `_none_` skeleton while the real run wrote
+    // pre-filled lines — a preview that contradicts its own output, which is
+    // the exact class of surface disagreement this pre-fill exists to end.
     const [full, body] = render_changelog_entry(target, prev, commits, today, {
         test_trend_line,
+        head: _derive_head_prefill(prev),
     });
 
     // Era-split planning — gate on the POST-release view (2026-07-07 fix).