@event4u/agent-config 14.14.0 → 14.15.0

package/src/scripts/release_drill.ts

@@ -122,6 +122,20 @@ interface WorldConfig {
      * 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;
 }
 
 /**
@@ -206,6 +220,7 @@ class FakeWorld {
         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 {
@@ -375,10 +390,68 @@ function _count(world: FakeWorld, needle: string): number {
 }
 
 const SCENARIOS: Record<string, Scenario> = {
+    'marker-refuses-before-commit': {
+        summary:
+            'step 3: a draft marker refuses BEFORE the release commit — no local release state, and therefore no remote state either',
+        config: { changelog_file: markedChangelogFixture(current_version()) },
+        expect_success: false,
+        verify: (w, err) => {
+            const f: string[] = [];
+            _expect(
+                (err ?? '').includes('release highlights are still the generator'),
+                `died for the wrong reason: ${err ?? '(no error)'}`,
+                f,
+            );
+            _expect(
+                !w.calls.some((c) => c.startsWith('git commit')),
+                'a release commit was made after the refusal',
+                f,
+            );
+            // RENAMED from `marker-refuses-before-branch-push` when
+            // `guard_release_curation` moved the refusal one step earlier.
+            // Every negative assertion below is UNCHANGED and still
+            // load-bearing — each is a remote side effect the 14.14.0 run
+            // actually produced: a pushed branch, an open PR, a check watch on
+            // a check that could not pass. They now hold more strongly, since
+            // the run stops before the commit rather than after it, and the
+            // no-commit assertion above is the property that is new.
+            //
+            // What this scenario no longer reaches, said plainly rather than
+            // left for a reader to infer: `guard_release_branch_push`. On the
+            // non-merged path it is now unreachable in ONE run, because a
+            // section marked at step 4 was already marked at step 3. It stays
+            // as defence-in-depth for a section that changes BETWEEN the two —
+            // a hand edit mid-run, or a resume over an altered changelog — and
+            // its own behaviour stays pinned by the unit tests in
+            // `tests/scripts/release_push_failure_masking.test.ts`, which is
+            // where that coverage moved to rather than being dropped.
+            _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: { changelog_file: markedChangelogFixture(current_version()) },
+        config: {
+            pr_already_merged: true,
+            changelog_file: markedChangelogFixture(current_version()),
+        },
         expect_success: false,
         verify: (w, err) => {
             const f: string[] = [];
@@ -403,6 +476,7 @@ const SCENARIOS: Record<string, Scenario> = {
         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()),
         },
@@ -431,6 +505,7 @@ const SCENARIOS: Record<string, Scenario> = {
         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()),

package/src/scripts/release_env.ts

@@ -303,6 +303,35 @@ function set_marketplace_version(p: string, version: string): void {
     fs.writeFileSync(p, jsonDumpsIndent(data, 2) + '\n', 'utf-8');
 }
 
+/**
+ * Mirror of Python `str.splitlines()` — split on CR/LF/CRLF and drop a single
+ * trailing empty element.
+ *
+ * Lives here rather than in `release.ts` because that file is 2000+ lines and
+ * every line above 1500 is charged by `check_source_size_budget`, while this
+ * module is a third of the cap. Behaviour unchanged; it is a pure text helper
+ * beside the other pure text helpers in this module.
+ *
+ * Known duplication, recorded rather than fixed here: `adoption_report.ts:106`
+ * and `readme_linter.ts:418` carry their own copies. Collapsing all three onto
+ * one definition touches three modules and is not this change's subject.
+ */
+function _splitlines(text: string): string[] {
+    if (text === '') {
+        return [];
+    }
+    const parts = text.split(/\r\n|\r|\n/);
+    if (parts.length > 0 && parts[parts.length - 1] === '') {
+        parts.pop();
+    }
+    return parts;
+}
+
+/** Mirror of Python `str.rstrip()` (trailing whitespace). */
+function _rstrip(text: string): string {
+    return text.replace(/\s+$/u, '');
+}
+
 export {
     ArgparseExit,
     commaGroup,
@@ -330,4 +359,6 @@ export {
     REPO_ROOT,
     REPO_SLUG,
     SystemExitError,
+    _rstrip,
+    _splitlines,
 };

package/src/scripts/release_publication.ts

@@ -16,7 +16,7 @@
  * import path changes.
  */
 import { spawnSync } from 'node:child_process';
-import { publication_blockers } from './_lib/release_highlights.js';
+import { DERIVED_MARKER, publication_blockers } from './_lib/release_highlights.js';
 import * as fs from 'node:fs';
 import process from 'node:process';
 
@@ -422,7 +422,131 @@ 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\`.`,
+    );
+}
+
+/**
+ * Ask for the curation BEFORE the pipeline commits anything — the fifth guard
+ * site, and the one that closes the gap the other four only narrowed.
+ *
+ * `guard_release_branch_push` already refuses before any REMOTE state exists,
+ * which is why 14.14.1 cost nothing but a re-run. What it cannot do is refuse
+ * before LOCAL state exists: by the time the push is attempted, step 2 has
+ * bumped six files and regenerated the derived trees and step 3 has committed
+ * all of it as `release: X.Y.Z`. The operator then edits prose on top of a
+ * commit that already claims to be the release and continues with `--resume`.
+ *
+ * The sentence this fixes is in that guard's own docstring: the 2026-09-01
+ * flip's risk register named *"the releaser edits prose before merge"* as the
+ * mitigation, and *"nothing in the pipeline asked, so nothing did"*. Refusing
+ * is not asking. This is the ask, placed where the answer is cheapest: the
+ * changelog section has just been written, nothing is committed, and the fix is
+ * an edit to a file already open in the working tree.
+ *
+ * It names the labels rather than only the marker, because the operator's next
+ * action is to rewrite specific lines and hunting for them in a 30-line section
+ * is the friction that made the refusal feel like a failure rather than a step.
+ *
+ * Deliberately silent when the section does not exist — same reasoning as the
+ * push guard: a missing section is the publication sites' refusal to make, not
+ * this one's.
+ *
+ * `prMerged` is a parameter rather than a check at the call site, and it is
+ * load-bearing in both directions. On the merged path steps 2 and 3 do not run,
+ * so there is no pre-commit moment to ask about; firing anyway PREEMPTS the
+ * step-8 and step-9 guards, whose whole subject is the merged section. That is
+ * measured, not anticipated — the unconditional form red three `release_drill`
+ * scenarios that exist to pin exactly those later refusals. It lives here
+ * rather than in an `if` at the call site because `release.ts` is 2000+ lines
+ * and every line above 1500 is charged by the growth ratchet, while this module
+ * is far below it.
+ */
+export function guard_release_curation(version: string, prMerged = false): void {
+    if (prMerged) {
+        return;
+    }
+    const section = extract_changelog_section(read_changelog_text(), version);
+    if (!section) {
+        return;
+    }
+    const blockers = publication_blockers(section.body, version, `\`release/${version}\``);
+    if (blockers.length === 0) {
+        return;
+    }
+    const marked = section.body
+        .split('\n')
+        .filter((l) => l.includes(DERIVED_MARKER))
+        .map((l) => `      ${l.trim()}`);
+    die(
+        `the ${version} release highlights are still the generator's draft ` +
+            `(${String(blockers.length)} blocker(s)):\n` +
+            blockers.map((b) => `    - ${b}`).join('\n') +
+            (marked.length > 0
+                ? `\n    Lines to rewrite in \`CHANGELOG.md\` under \`## [${version}]\`:\n` +
+                  marked.join('\n')
+                : '') +
+            '\n    Stopped BEFORE committing — no release commit, no branch on ' +
+            `${REMOTE}, no pull request, no tag. Curate the ` +
+            '`### Release highlights` head, then re-run `task release`.',
+    );
+}
+
 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);

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).