@event4u/agent-config 14.13.0 → 14.14.1

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,48 @@ 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;
+    /**
+     * The release PR is ALREADY merged when the run starts — the real
+     * resume-after-merge state, in which steps 1 through 7 skip and step 8 is
+     * the first step that does work.
+     *
+     * Added 2026-09-02 with `guard_release_branch_push`. Before that guard, a
+     * marker scenario could start from scratch and still reach step 8, because
+     * nothing between the changelog write and the tag looked at the section.
+     * The push guard now stops such a run at step 4 — correctly, and that is
+     * the point of it — which makes this knob the only way left to exercise
+     * the tag and Release guards on their own. It is not a bypass: the state
+     * it fakes is one every resumed release actually passes through.
+     */
+    pr_already_merged?: boolean;
 }
 
 /**
@@ -122,6 +166,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 +203,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,10 +213,14 @@ 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;
         this.checks_fail = cfg.checks_fail ?? false;
+        this.pr_merged = cfg.pr_already_merged ?? false;
     }
 
     exec(args: readonly string[]): ExecResult {
@@ -325,6 +390,136 @@ function _count(world: FakeWorld, needle: string): number {
 }
 
 const SCENARIOS: Record<string, Scenario> = {
+    'marker-refuses-before-branch-push': {
+        summary:
+            'step 4: a draft marker refuses the branch push — the first remote state — so no PR is ever opened',
+        config: { changelog_file: markedChangelogFixture(current_version()) },
+        expect_success: false,
+        verify: (w, err) => {
+            const f: string[] = [];
+            _expect(
+                (err ?? '').includes(`refusing to push ${w.branch}`),
+                `died for the wrong reason: ${err ?? '(no error)'}`,
+                f,
+            );
+            // The load-bearing assertions are about what did NOT happen. Each
+            // one is a remote side effect the 14.14.0 run actually produced
+            // before this guard existed: a pushed branch, an open PR, and a
+            // check watch on a check that could not pass.
+            _expect(
+                !w.calls.includes(`git push -u origin ${w.branch}`),
+                'the branch was pushed after the refusal',
+                f,
+            );
+            _expect(
+                !w.calls.some((c) => c.startsWith('gh pr create')),
+                'a pull request was opened after the refusal',
+                f,
+            );
+            _expect(
+                !w.calls.some((c) => c.includes('--watch')),
+                'CI was waited on 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-before-tag': {
+        summary:
+            'step 8: a draft marker in the merged section refuses BEFORE the annotated tag is created',
+        config: {
+            pr_already_merged: true,
+            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: {
+            pr_already_merged: true,
+            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: {
+            pr_already_merged: true,
+            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 +667,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 +680,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 {
@@ -419,7 +422,65 @@ export function _is_non_fast_forward(stderr: string, stdout: string): boolean {
     return /(non-fast-forward|fetch first|behind its remote counterpart)/i.test(text);
 }
 
+/**
+ * Refuse the FIRST remote state of a release whose section is not publishable.
+ *
+ * The fourth guard site, and the one the other three structurally cannot cover.
+ * They sit at the irreversible transitions — annotated tag, resumed tag push,
+ * GitHub Release body — and every one of them is DOWNSTREAM of `gh pr create`
+ * and of `gh pr checks --watch`. `check_release_highlights` refuses the same
+ * section from the other side, on the release PR, so a run whose head is still
+ * the generator's draft pushed a branch, opened a PR, burned CI, waited on a
+ * check that could not pass, and died there — leaving a half-open release to
+ * clean up by hand.
+ *
+ * That is not a hypothetical: it is PR #1812 (14.14.0, 2026-09-02), and the
+ * 2026-09-01 flip's own risk register pre-registered it as Risk 1 — *"the flip
+ * reds the next release PR on its first run"*. Its stated mitigation was that
+ * the releaser edits prose before merge; nothing in the pipeline asked, so
+ * nothing did.
+ *
+ * The branch push is the first thing in the pipeline that leaves the machine,
+ * so a refusal here costs one local edit and no remote state at all: no branch
+ * on the remote, no pull request, no CI minutes, no tag. It sits at the push
+ * CALL SITE rather than in a formatter for the reason the publication guards
+ * already state — a formatter has no notion of whether it is publishing, and
+ * the call site is the one that can still stop. Deriving the version from
+ * `release/X.Y.Z` mirrors what `release-validation.yml` already does with
+ * `head_ref`.
+ *
+ * Two states pass unguarded, deliberately: a branch that is not
+ * `release/X.Y.Z` (nothing about a release to read), and a version with no
+ * changelog section (the missing-section refusal belongs to the publication
+ * sites, which need a section to publish; refusing here would break every
+ * non-release push through this helper).
+ */
+export function guard_release_branch_push(branch: string): void {
+    const prefix = 'release/';
+    if (!branch.startsWith(prefix)) {
+        return;
+    }
+    const version = branch.slice(prefix.length);
+    const section = extract_changelog_section(read_changelog_text(), version);
+    if (!section) {
+        return;
+    }
+    const blockers = publication_blockers(section.body, version, `\`${branch}\``);
+    if (blockers.length === 0) {
+        return;
+    }
+    die(
+        `refusing to push ${branch} — the ${version} changelog section is not publishable ` +
+            `(${String(blockers.length)} blocker(s)):\n` +
+            blockers.map((b) => `    - ${b}`).join('\n') +
+            `\n    Nothing has left this machine: no branch on ${REMOTE}, no pull request, no tag.\n` +
+            '    Curate the `### Release highlights` head in CHANGELOG.md under ' +
+            `\`## [${version}]\`, then re-run \`task release -- --resume\`.`,
+    );
+}
+
 function push_release_branch(branch: string): void {
+    guard_release_branch_push(branch);
     const first = run(['git', 'push', '-u', REMOTE, branch], { check: false, capture: true });
     if (first.returncode === 0) {
         process.stdout.write(first.stdout);
@@ -718,3 +779,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);
+}

package/src/scripts/roadmap_context.ts

@@ -49,6 +49,7 @@ import { fileURLToPath } from 'node:url';
 import { gitEnv } from './_lib/git_env.js';
 import { read_live_records, register_dir } from './_lib/session_register.js';
 import { other_worktree_branches_detailed } from './sessions_cli.js';
+import { recordContextObservation } from './_lib/context_observation.js';
 
 /** One open pull request, with the file set it changes. */
 export interface PullRequestInfo {
@@ -746,6 +747,20 @@ export function main(argv: string[] = process.argv.slice(2)): number {
         roadmap: at('--roadmap'),
         ...(ownedFile !== null ? { ownedPaths: readOwnedPathsFile(ownedFile) } : {}),
     });
+    // `road-to-wired-instruments` 2.1 — this probe is the only thing in the tree
+    // that can OBSERVE the world (it costs a `gh` call), so it records what it
+    // saw where a Stop-path concern can read it without spawning anything. The
+    // continuation ladder's premise rung is the consumer; the resume checkpoint
+    // is the other.
+    //
+    // Only a LIVE reading is recorded. Offline, `contextFingerprint` still
+    // returns a digest — over a null base and an empty PR list — and that digest
+    // is a statement about the network, not about the repository. Recording it
+    // would make every offline probe look like a moved premise, which is a false
+    // halt manufactured out of a dropped connection.
+    if (ctx.network === 'live') {
+        recordContextObservation(root, ctx.roadmap ?? '', ctx.fingerprint);
+    }
     if (argv.includes('--fingerprint')) {
         // Just the digest, for the loop's phase-boundary comparison and for the
         // resume checkpoint's `context_fingerprint` (§ 5.6 — same value).