@event4u/agent-config 14.13.0 → 14.14.0

package/src/scripts/release_drill.ts

@@ -31,11 +31,13 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
 
 import {
     _MERGE_UPDATE_ROUNDS,
+    _set_changelog_reader,
     _set_exec_override,
     execute,
     Plan,
     SystemExitError,
 } from './release.js';
+import { DERIVED_MARKER } from './_lib/release_highlights.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
@@ -92,6 +94,34 @@ interface WorldConfig {
      * removes.
      */
     changelog?: string;
+    /**
+     * Content the WORKING-TREE read returns — `read_changelog_text()`, used by
+     * step 5 (PR body) and step 8 (annotated-tag message).
+     *
+     * Added 2026-09-01 with the publication guard (roadmap § 3.1). `changelog`
+     * above only covers `git show <tag>:CHANGELOG.md`; the working tree was
+     * still the REAL file, whose `14.13.0` section carries four
+     * `_auto-derived, rewrite before merge:_` lines. A guard at the tag call
+     * site therefore refused every scenario for a reason unrelated to what the
+     * scenario tested — the same coupling `changelog` was introduced to
+     * remove, on the other read.
+     *
+     * Defaults to `defaultChangelogFixture(target)`, which is policy-valid by
+     * construction.
+     */
+    changelog_file?: string;
+    /**
+     * The tag already exists locally and was never pushed — the § 3.2 resume
+     * state, which reached `_push_tag` having read no changelog at all.
+     */
+    tag_created_unpushed?: boolean;
+    /**
+     * The tag is already on the remote, so step 8 skips entirely and step 9 —
+     * the GitHub Release body — is the FIRST irreversible transition the run
+     * reaches. The only state in which the Release guard can be exercised on
+     * its own, because a marker otherwise stops the run at step 8.
+     */
+    tag_already_remote?: boolean;
 }
 
 /**
@@ -122,6 +152,21 @@ export function defaultChangelogFixture(target: string): string {
     ].join('\n');
 }
 
+/**
+ * `defaultChangelogFixture` with one head line still carrying the generator's
+ * draft marker — the exact state five released sections shipped in.
+ *
+ * Built from `DERIVED_MARKER` rather than from a literal string: a fixture
+ * that hardcodes the marker text keeps passing after the marker is renamed,
+ * which is a guard policing a population of zero.
+ */
+export function markedChangelogFixture(target: string): string {
+    return defaultChangelogFixture(target).replace(
+        '- fixture entry for the release drill',
+        `### Release highlights\n\n- **Behaviour changes:** ${DERIVED_MARKER} rule/schema diffs in abc1234.\n\n- fixture entry for the release drill`,
+    );
+}
+
 /**
  * A scriptable stand-in for every git/gh/task command execute() issues.
  * Stateful where the real world is: checkouts move HEAD, `git tag` makes the
@@ -144,6 +189,8 @@ class FakeWorld {
     private merge_fails_hard: boolean;
     private checks_fail: boolean;
     private readonly changelog: string;
+    /** Working-tree content; see `WorldConfig.changelog_file`. */
+    readonly changelog_file: string;
 
     constructor(
         readonly branch: string,
@@ -152,6 +199,9 @@ class FakeWorld {
     ) {
         this.push_rejections = cfg.push_rejections ?? 0;
         this.changelog = cfg.changelog ?? defaultChangelogFixture(target);
+        this.changelog_file = cfg.changelog_file ?? defaultChangelogFixture(target);
+        this.tag_local = (cfg.tag_created_unpushed ?? false) || (cfg.tag_already_remote ?? false);
+        this.tag_remote = cfg.tag_already_remote ?? false;
         this.behind_probes = cfg.behind_probes ?? 0;
         this.merge_races_once = cfg.merge_races_once ?? false;
         this.merge_fails_hard = cfg.merge_fails_hard ?? false;
@@ -325,6 +375,95 @@ function _count(world: FakeWorld, needle: string): number {
 }
 
 const SCENARIOS: Record<string, Scenario> = {
+    'marker-refuses-before-tag': {
+        summary:
+            'step 8: a draft marker in the merged section refuses BEFORE the annotated tag is created',
+        config: { changelog_file: markedChangelogFixture(current_version()) },
+        expect_success: false,
+        verify: (w, err) => {
+            const f: string[] = [];
+            _expect(
+                (err ?? '').includes('refusing to publish the annotated tag'),
+                `died for the wrong reason: ${err ?? '(no error)'}`,
+                f,
+            );
+            // The load-bearing assertion, and it is about ORDER, not about the
+            // message: nothing irreversible may run after the refusal.
+            _expect(
+                !w.calls.some((c) => c.startsWith('git tag -a ')),
+                'an annotated tag was created after the refusal',
+                f,
+            );
+            _expect(!w.tag_local && !w.tag_remote, 'a tag exists after the refusal', f);
+            _expect(!w.release_created, 'a GitHub Release was created after the refusal', f);
+            return f;
+        },
+    },
+    'marker-refuses-resumed-tag-push': {
+        summary:
+            'step 8 (§ 3.2): a tag created but never pushed is NOT pushed when its section carries the marker',
+        config: {
+            tag_created_unpushed: true,
+            changelog_file: markedChangelogFixture(current_version()),
+        },
+        expect_success: false,
+        verify: (w, err) => {
+            const f: string[] = [];
+            _expect(
+                (err ?? '').includes('refusing to publish the tag push (resumed)'),
+                `died for the wrong reason: ${err ?? '(no error)'}`,
+                f,
+            );
+            // The recorded bypass: this path read no changelog at all, so the
+            // push was the FIRST thing that happened. It must now be the thing
+            // that does not happen.
+            _expect(!w.tag_remote, 'the tag was pushed after the refusal', f);
+            _expect(
+                !w.calls.includes(`git push origin ${w.target}`),
+                'a tag push ran after the refusal',
+                f,
+            );
+            _expect(!w.release_created, 'a GitHub Release was created after the refusal', f);
+            return f;
+        },
+    },
+    'marker-refuses-github-release': {
+        summary:
+            'step 9: with the tag already pushed, a marker in the TAGGED section refuses before the Release is created',
+        config: {
+            tag_already_remote: true,
+            changelog: markedChangelogFixture(current_version()),
+            changelog_file: markedChangelogFixture(current_version()),
+        },
+        expect_success: false,
+        verify: (w, err) => {
+            const f: string[] = [];
+            _expect(
+                (err ?? '').includes('refusing to publish the GitHub Release notes'),
+                `died for the wrong reason: ${err ?? '(no error)'}`,
+                f,
+            );
+            _expect(!w.release_created, 'the GitHub Release was created after the refusal', f);
+            _expect(
+                !w.calls.some((c) => c.startsWith(`gh release create ${w.target}`)),
+                'gh release create ran after the refusal',
+                f,
+            );
+            return f;
+        },
+    },
+    'clean-section-still-publishes': {
+        summary:
+            'the guard is scoped to a real defect: a policy-valid section tags and releases as before',
+        config: {},
+        expect_success: true,
+        verify: (w, _err) => {
+            const f: string[] = [];
+            _expect(w.tag_remote, 'tag never pushed', f);
+            _expect(w.release_created, 'GitHub Release never created', f);
+            return f;
+        },
+    },
     'happy-resume': {
         summary: 'resume with everything green runs checkout → checks → merge → tag → release',
         config: {},
@@ -472,6 +611,9 @@ function run_scenario(name: string): ScenarioOutcome {
         return true;
     };
     _set_exec_override((args) => world.exec(args));
+    // The working-tree read, faked for the same reason the command layer is.
+    // Without this the drill's step 8 reads the repository's real CHANGELOG.md.
+    _set_changelog_reader(() => world.changelog_file);
     try {
         execute(plan, { wait_for_checks: true, dry_run: false, resume: true });
     } catch (err) {
@@ -482,6 +624,7 @@ function run_scenario(name: string): ScenarioOutcome {
         }
     } finally {
         _set_exec_override(null);
+        _set_changelog_reader(null);
         process.stdout.write = orig_out;
         process.stderr.write = orig_err;
     }

package/src/scripts/release_env.ts

@@ -91,6 +91,39 @@ const PROJECT_TEMPLATE = path.join(
     'agent-project-settings.example.yml',
 );
 const CHANGELOG = path.join(REPO_ROOT, 'CHANGELOG.md');
+
+/**
+ * Overridable reader for the WORKING-TREE changelog.
+ *
+ * Mirrors `_set_exec_override` in `release_publication.ts`, and exists for the
+ * same reason: `execute()` reads `CHANGELOG.md` off disk at two points (the PR
+ * body and the annotated-tag message), and the release drill fakes commands
+ * but not the filesystem. Before this seam the drill's step 8 read the
+ * repository's REAL changelog — whose current section carries four
+ * `_auto-derived, rewrite before merge:_` lines at `14.13.0` — so a
+ * publication guard added at that call site refused every drill scenario for a
+ * reason that had nothing to do with what the scenario was testing.
+ *
+ * That is the failure mode the `WorldConfig.changelog` fixture already removed
+ * for `git show`, and the AI council of 2026-08-23 (2/2 convergent) chose a
+ * controlled fixture over a policy exemption when it removed it. This is the
+ * same choice applied to the other read: the drill supplies policy-valid
+ * content and exercises the real parsing and guarding path, rather than being
+ * exempted from it.
+ *
+ * `null` restores the real filesystem read. Test-only; nothing in production
+ * sets it.
+ */
+let _changelog_reader: ((file: string) => string) | null = null;
+
+function _set_changelog_reader(fn: ((file: string) => string) | null): void {
+    _changelog_reader = fn;
+}
+
+/** The working-tree changelog text, through the seam above. */
+function read_changelog_text(): string {
+    return _changelog_reader ? _changelog_reader(CHANGELOG) : fs.readFileSync(CHANGELOG, 'utf-8');
+}
 const MAIN_BRANCH = 'main';
 const REMOTE = 'origin';
 const REPO_SLUG = 'event4u-app/agent-config';
@@ -282,6 +315,8 @@ export {
     _cap_body,
     CHANGELOG,
     CalledProcessError,
+    _set_changelog_reader,
+    read_changelog_text,
     GH_PR_BODY_LIMIT,
     GH_RELEASE_NOTES_LIMIT,
     MAIN_BRANCH,

package/src/scripts/release_publication.ts

@@ -16,12 +16,14 @@
  * import path changes.
  */
 import { spawnSync } from 'node:child_process';
+import { publication_blockers } from './_lib/release_highlights.js';
 import * as fs from 'node:fs';
 import process from 'node:process';
 
 import { gh_argv_label, gh_retry } from './_lib/gh_transient.js';
 import {
     extract_changelog_section,
+    tag_message_from_section,
     pr_body_from_section,
 } from './_lib/release_material.js';
 
@@ -34,6 +36,7 @@ import {
     REPO_ROOT,
     SystemExitError,
     _cap_body,
+    read_changelog_text,
 } from './release_env.js';
 
 function die(msg: string, code = 2): never {
@@ -718,3 +721,84 @@ export {
     run,
     watch_pr_checks,
 };
+
+/**
+ * Refuse an irreversible publication whose section is not publishable.
+ *
+ * Called at the THREE call sites that publish, never inside a formatter:
+ * annotated-tag creation, the resumed push of a tag created but never pushed,
+ * and the GitHub Release body. A pure formatter has no notion of whether it is
+ * actually publishing, which is why an earlier attempt at that placement was
+ * refused; the call site does, and it is the one that can still stop.
+ *
+ * **The resumed push is the bypass worth naming.** The changelog is read only
+ * in the tag-CREATION branch, so a resume over a tag that was created but never
+ * pushed reached `_push_tag` having read nothing. A guard covering creation
+ * alone misses exactly that path, and pushing a tag is as irreversible as
+ * creating it.
+ *
+ * `die` throws before the command runs, so nothing irreversible fires after a
+ * refusal — an ordering asserted against the drill's recorded command list
+ * rather than by reading this comment.
+ *
+ * Lives here rather than in `release.ts` because that file is 2000+ lines and
+ * every line above 1500 is charged by the source-size growth ratchet, while
+ * this module is far below it and already owns `die`. Behaviour unchanged.
+ */
+export function _refuse_unpublishable(sectionBody: string, version: string, surface: string): void {
+    const blockers = publication_blockers(sectionBody, version);
+    if (blockers.length === 0) {
+        return;
+    }
+    die(
+        `refusing to publish the ${surface} for ${version} — ` +
+            `${String(blockers.length)} publication blocker(s):\n` +
+            blockers.map((b) => `    - ${b}`).join('\n'),
+    );
+}
+
+/**
+ * Read the section under release and refuse if it is not publishable.
+ *
+ * One helper for all three publish sites so the read, the missing-section
+ * refusal and the blocker refusal cannot drift apart between them — the
+ * resumed-push path drifted exactly that way before this existed, reaching
+ * `_push_tag` having read nothing.
+ */
+export function guard_publication(version: string, surface: string): void {
+    const section = extract_changelog_section(read_changelog_text(), version);
+    if (!section) {
+        die(
+            `CHANGELOG.md on ${MAIN_BRANCH} carries no section for ${version} — ` +
+                `refusing to publish the ${surface}`,
+        );
+        return;
+    }
+    _refuse_unpublishable(section.body, version, surface);
+}
+
+/**
+ * Derive the tag message from the MERGED changelog, refuse if unpublishable,
+ * create the annotated tag and push it.
+ *
+ * The three steps are one function because they are one irreversible act with
+ * one precondition, and splitting them across call sites is what let the
+ * resumed-push path reach `_push_tag` having read nothing. Sequencing is
+ * load-bearing (release-truth Phase 1, council 2026-08-03): merge FIRST, pull
+ * main, THEN derive the message — tagging before the merge reads a section that
+ * does not exist yet. The annotated tag replaces the previous lightweight one so
+ * tag metadata is a fourth surface carrying the same single-source content.
+ */
+export function create_and_push_annotated_tag(version: string): void {
+    const merged = extract_changelog_section(read_changelog_text(), version);
+    if (!merged) {
+        die(
+            `CHANGELOG.md on ${MAIN_BRANCH} carries no section for ${version} — ` +
+                'refusing to tag a release whose changelog entry is missing',
+        );
+        return;
+    }
+    _refuse_unpublishable(merged.body, version, 'annotated tag');
+    run(['git', 'tag', '-a', version, '-m', tag_message_from_section(merged.body, version)]);
+    _push_tag(version);
+}