@event4u/agent-config 16.2.0 → 16.4.0

package/src/scripts/bench_touched_file_quality.ts

@@ -0,0 +1,238 @@
+#!/usr/bin/env node
+/**
+ * bench_touched_file_quality — what the shadow quality pass costs at stop.
+ *
+ * `road-to-touched-files-that-pass-their-own-tools` 1.4: record the `shadow`
+ * variant's p95 over a five-file TypeScript fixture BEFORE any default moves.
+ * Risk 1 of that roadmap is that a quality pass makes stop the slowest hook in
+ * the chain, and 2.3 defers the `shadow → warn` flip to the owner. Neither
+ * decision should be taken on an estimate.
+ *
+ * CORRECTED FROM REPRODUCTION — the step's premise was wrong, and the
+ * correction is why this is a file rather than a patch.
+ *
+ * The step reads "the per-concern bench already measures `verify-before-complete`
+ * at default". It does not. `bench_hook_latency.perConcernRows` is fed by
+ * `blockingConcerns()`, which filters `hook_manifest.yaml` to
+ * `severity: blocking`; `verify-before-complete` is declared `severity: advisory`
+ * (manifest line ~122), so it has never had a per-concern row and there was no
+ * `default` reading to add a `shadow` variant beside. Adding the concern to that
+ * filter would have changed what "blocking" means in a report whose consumer
+ * (step 3.3 of the kernel-plumbing roadmap) derives per-concern TIMEOUTS from it
+ * — a timeout for an advisory concern is a different decision, and smuggling it
+ * in through a measurement would have been the wrong place to take it.
+ *
+ * So this measures the pass directly, which is also the number the two open
+ * decisions actually need: the slot p95 in `docs/hook-latency.json` is dominated
+ * by spawn + bundle load, and what 1.4 asks about is the DELTA the pass adds.
+ *
+ * METHOD, pinned so the number reproduces:
+ *   - A throwaway consumer-shaped project: `package.json` declaring `typescript`
+ *     and `eslint`, five TypeScript files, a flat ESLint config, `git init`, and
+ *     a `minimal-safe-diff.json` naming all five as this turn's touched files.
+ *   - `node_modules` is SYMLINKED to this repository's, so `npx eslint` resolves
+ *     a real, installed linter and runs offline. The measurement is therefore of
+ *     a real tool over real files, not of a stub.
+ *   - N iterations (default 20, `--runs N`) of `collectTouchedFileQuality` — the
+ *     exact function the stop path calls — measured with `performance.now()`.
+ *     That covers the recorder read, `git status`, `resolve_toolchain`, and every
+ *     spawn the plan produced.
+ *   - The `off` baseline is measured too, by the same loop with the pass skipped,
+ *     so the row reports a DELTA rather than an absolute whose floor is unknown.
+ *
+ * WHAT THE NUMBER IS NOT. It is one machine's reading, and the dominant term is
+ * whichever tools the fixture's resolver happens to emit — a consumer whose
+ * toolchain resolves `phpstan` over a large tree will measure something else
+ * entirely. It bounds the decision for THIS shape; it is not a budget.
+ *
+ * Exit codes: 0 measured · 2 the fixture could not be built.
+ */
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { collectTouchedFileQuality } from './before_complete_hook.js';
+
+const REPO_ROOT = path.resolve(path.dirname(path.resolve(fileURLToPath(import.meta.url))), '..', '..');
+
+/** Files in the fixture. Five, per the step. */
+export const FIXTURE_FILE_COUNT = 5;
+
+const SESSION = 'bench-touched-file-quality';
+
+export function percentile(samples: readonly number[], p: number): number {
+    if (samples.length === 0) return 0;
+    const sorted = [...samples].sort((a, b) => a - b);
+    const idx = Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1);
+    return sorted[Math.max(0, idx)] as number;
+}
+
+/**
+ * Build the throwaway consumer project and return its root.
+ *
+ * Deliberately NOT inside the repository: a fixture under `src/` or `agents/`
+ * would be picked up by the tree's own gates, and one that `git init`s inside an
+ * existing worktree would report the repository's status rather than its own.
+ */
+export function buildFixture(): string {
+    const root = fs.mkdtempSync(path.join(os.tmpdir(), 'tfq-bench-'));
+
+    fs.writeFileSync(
+        path.join(root, 'package.json'),
+        JSON.stringify(
+            { name: 'tfq-bench-fixture', private: true, devDependencies: { typescript: '*', eslint: '*' } },
+            null,
+            2,
+        ),
+        'utf-8',
+    );
+    // A flat config with no rules: eslint still parses every file, which is the
+    // cost being measured, without a rule set that would make the number a
+    // statement about this repository's lint configuration.
+    fs.writeFileSync(path.join(root, 'eslint.config.mjs'), 'export default [];\n', 'utf-8');
+
+    for (let i = 0; i < FIXTURE_FILE_COUNT; i += 1) {
+        fs.writeFileSync(
+            path.join(root, `mod${String(i)}.ts`),
+            `export interface Row${String(i)} { id: number; name: string }\n` +
+                `export function build${String(i)}(n: number): Row${String(i)}[] {\n` +
+                `    return Array.from({ length: n }, (_, j) => ({ id: j, name: 'r' + String(j) }));\n` +
+                `}\n`,
+            'utf-8',
+        );
+    }
+
+    try {
+        fs.symlinkSync(path.join(REPO_ROOT, 'node_modules'), path.join(root, 'node_modules'), 'dir');
+    } catch {
+        // Left absent on a platform that refuses the link: `npx eslint` then
+        // resolves to nothing and the pass records `skipped: absent`, which the
+        // report states rather than hides.
+    }
+
+    spawnSync('git', ['init', '-q'], { cwd: root });
+
+    fs.mkdirSync(path.join(root, 'agents', 'state'), { recursive: true });
+    fs.writeFileSync(
+        path.join(root, 'agents', 'state', 'minimal-safe-diff.json'),
+        JSON.stringify({
+            session_id: SESSION,
+            files_touched_this_turn: Array.from(
+                { length: FIXTURE_FILE_COUNT },
+                (_, i) => `mod${String(i)}.ts`,
+            ),
+        }),
+        'utf-8',
+    );
+
+    return root;
+}
+
+export interface BenchRow {
+    readonly concern: string;
+    readonly mode: 'off' | 'shadow';
+    readonly runs: number;
+    readonly p50_ms: number;
+    readonly p95_ms: number;
+    readonly max_ms: number;
+    /** What the pass actually did, so a row of zeros is never mistaken for speed. */
+    readonly commands: readonly string[];
+    readonly skipped: readonly string[];
+}
+
+export function measure(root: string, iterations: number): { off: BenchRow; shadow: BenchRow } {
+    const offSamples: number[] = [];
+    const shadowSamples: number[] = [];
+    let commands: string[] = [];
+    let skipped: string[] = [];
+
+    // One warm-up outside the samples: the first `npx` resolution pays a cost no
+    // subsequent stop pays, and reporting it inside the p95 would describe a
+    // session's first stop as if it were every stop.
+    collectTouchedFileQuality(root, SESSION);
+
+    for (let i = 0; i < iterations; i += 1) {
+        const t0 = performance.now();
+        const result = collectTouchedFileQuality(root, SESSION);
+        shadowSamples.push(performance.now() - t0);
+        if (i === 0 && result !== null) {
+            commands = result.runs.filter((r) => r.skipped === null).map((r) => r.command);
+            skipped = result.runs
+                .filter((r) => r.skipped !== null)
+                .map((r) => `${r.source_command} → ${String(r.skipped)}`);
+        }
+
+        // `off` is not "the same loop with a flag" — on the off path the stop
+        // handler never reaches this function at all, so the baseline is the
+        // empty interval, measured to keep the harness's own overhead visible.
+        const t1 = performance.now();
+        offSamples.push(performance.now() - t1);
+    }
+
+    const row = (mode: 'off' | 'shadow', xs: number[]): BenchRow => ({
+        concern: 'verify-before-complete',
+        mode,
+        runs: xs.length,
+        p50_ms: Math.round(percentile(xs, 50) * 1000) / 1000,
+        p95_ms: Math.round(percentile(xs, 95) * 1000) / 1000,
+        max_ms: Math.round(Math.max(...xs, 0) * 1000) / 1000,
+        commands: mode === 'shadow' ? commands : [],
+        skipped: mode === 'shadow' ? skipped : [],
+    });
+
+    return { off: row('off', offSamples), shadow: row('shadow', shadowSamples) };
+}
+
+export function render(rows: { off: BenchRow; shadow: BenchRow }): string {
+    const line = (r: BenchRow): string =>
+        `| ${r.concern} | ${r.mode} | ${String(r.runs)} | ${r.p50_ms.toFixed(3)} | ` +
+        `${r.p95_ms.toFixed(3)} | ${r.max_ms.toFixed(3)} |`;
+    const out: string[] = [
+        '',
+        `fixture: ${String(FIXTURE_FILE_COUNT)} TypeScript files, consumer-shaped project`,
+        '',
+        '| concern | mode | runs | p50_ms | p95_ms | max_ms |',
+        '|---|---|---|---|---|---|',
+        line(rows.off),
+        line(rows.shadow),
+        '',
+        `delta p95 (shadow − off): ${(rows.shadow.p95_ms - rows.off.p95_ms).toFixed(3)} ms`,
+        '',
+        `commands executed: ${rows.shadow.commands.length === 0 ? '(none)' : rows.shadow.commands.join(' · ')}`,
+        `skipped: ${rows.shadow.skipped.length === 0 ? '(none)' : rows.shadow.skipped.join(' · ')}`,
+        '',
+    ];
+    return out.join('\n');
+}
+
+export function main(argv: readonly string[]): number {
+    const runsIdx = argv.indexOf('--runs');
+    const parsed = runsIdx === -1 ? NaN : Number(argv[runsIdx + 1]);
+    const iterations = Number.isFinite(parsed) && parsed > 0 ? Math.trunc(parsed) : 20;
+    const asJson = argv.includes('--json');
+
+    let root: string;
+    try {
+        root = buildFixture();
+    } catch (err) {
+        process.stderr.write(`bench_touched_file_quality: could not build the fixture — ${String(err)}\n`);
+        return 2;
+    }
+
+    const rows = measure(root, iterations);
+    process.stdout.write(asJson ? `${JSON.stringify(rows, null, 2)}\n` : render(rows));
+
+    try {
+        fs.rmSync(root, { recursive: true, force: true });
+    } catch {
+        // A leftover temp directory is not a failed measurement.
+    }
+    return 0;
+}
+
+const _entry = process.argv[1];
+if (_entry !== undefined && path.resolve(_entry) === path.resolve(fileURLToPath(import.meta.url))) {
+    process.exit(main(process.argv.slice(2)));
+}

package/src/scripts/check_agent_artifact_location.ts

@@ -78,6 +78,23 @@ const SKIP_DIRS: ReadonlySet<string> = new Set([
 
 /** Frontmatter keys that only a roadmap carries in this tree. */
 const FM_ROADMAP_RE = /^complexity:[ \t]*(lightweight|structural)[ \t]*$/m;
+/**
+ * Anchored at the absolute start of the string — `^` with no `m` flag — on
+ * purpose: this is a FRONTMATTER fence, which by the project's own convention
+ * only means something at byte offset 0 of the file. A `---` fence that
+ * begins three lines in is not frontmatter, it is a horizontal rule or a
+ * quoted example, so loosening this to `m` would create false positives of
+ * its own.
+ *
+ * The R2 review-input roadmap snapshots used to depend on that strictness as an
+ * INCIDENTAL exemption: their two-line HTML-comment header, written for a
+ * different gate, pushed this fence off offset 0. They are now exempt by path —
+ * see `isReviewInputRoadmapSnapshot` — so neither the header nor this regex's
+ * anchoring decides their fate any more.
+ *
+ * Tested in `check_agent_artifact_location.test.ts`
+ * (describe: "review-input snapshot convention").
+ */
 const FM_RE = /^---\n([\s\S]*?)\n---/;
 const PHASE_RE = /^##[ \t]+Phase[ \t]/m;
 const CHECKBOX_RE = /^[ \t]*- \[[ x~-]\][ \t]/m;
@@ -144,6 +161,24 @@ function walkMarkdown(root: string): string[] {
     return out.sort();
 }
 
+/**
+ * The one declared exemption: an R2 review-input roadmap snapshot.
+ *
+ * `dispatch_r2_reviewer.ts` writes a verbatim roadmap copy to exactly this
+ * shape, and a file in it is non-authoritative evidence whoever wrote it —
+ * nothing reads it back as a roadmap. Decided by path, not by a marker an
+ * author could type anywhere (authority-routing roadmap 5.1, `## Decisions`):
+ * measured 2026-10-07, every roadmap-shaped file outside the root was one of
+ * these snapshots, so the path names the whole population and nothing else.
+ * Takes the repository-relative POSIX path the walker produces; the walker
+ * never follows a symlink, so a link cannot manufacture an exempt path.
+ */
+const REVIEW_INPUT_SNAPSHOT_PATH_RE = /^agents\/evidence\/(?:[^/]+\/)*[^/.][^/]*\.review-input\/roadmap\.md$/;
+
+export function isReviewInputRoadmapSnapshot(rel: string): boolean {
+    return REVIEW_INPUT_SNAPSHOT_PATH_RE.test(rel) && !rel.split('/').some((s) => s === '..' || s === '.');
+}
+
 /** `true` when `child` is at or below `root`. */
 function isUnder(child: string, root: string): boolean {
     const rel = path.relative(root, child);
@@ -156,6 +191,7 @@ export function scan(root: string): ScanResult {
     const findings: Finding[] = [];
     for (const f of files) {
         if (isUnder(f, roadmapRoot)) continue;
+        if (isReviewInputRoadmapSnapshot(path.relative(root, f).split(path.sep).join('/'))) continue;
         // Cheap name pre-filter first — the SHARED definition, imported, so the
         // roadmap corpus and this guard cannot drift apart.
         if (!isRoadmapCandidate(f)) continue;

package/src/scripts/check_branch_freshness.ts

@@ -46,7 +46,9 @@
  * branch AS THE SERVER REPORTS IT (`ls-remote --symref`), then the local
  * `origin/HEAD`, then `main`. Every message names the base AND where it came
  * from, because "I checked main because that is the PR's base" and "I checked
- * main because I could not ask" must never print the same.
+ * main because I could not ask" must never print the same. An explicit
+ * `--base` given a blank value exits 2: an unset variable is not a request for
+ * the PR's base.
  *
  * The server symref matters for the same reason `remoteHead` exists: the local
  * `refs/remotes/origin/HEAD` is written at clone time and never refreshed, so
@@ -67,6 +69,9 @@ import { fileURLToPath } from "node:url";
 
 import { runGateCli, runSelfTest, type SelfTestCase } from "./_lib/gate_self_test.js";
 import { workspaceIdentity } from "./_lib/git_common_dir.js";
+import { describeRefusal, isRefusal, type GitConventionReading } from "./_lib/git_convention.js";
+import { baseValueError, parseBaseRef } from "./_lib/git_base_ref.js";
+import { makeTargetDeps, parseExactHeadSha, readCommittedConvention } from "./_lib/git_convention_carrier.js";
 import { reportScanned } from "./_lib/scan_scope.js";
 
 // ledger-exempt: single remote-ref probe — the entire scope is ONE ls-remote answer (0 or 1 refs) resolved to one aggregate ancestor verdict, and every empty path already publishes its reason via reportScanned allowEmpty; there is no per-target collection to account.
@@ -125,6 +130,8 @@ export type BaseSource =
 export interface BaseResolution {
   readonly base: string;
   readonly source: BaseSource;
+  /** The remote `base` is a branch on; absent means origin. */
+  readonly remote?: string;
   readonly pr?: number;
   /** Present iff an open PR against a different base could not be ruled out. */
   readonly unverified?: string;
@@ -270,6 +277,19 @@ export function explicitBase(argv: readonly string[]): string | null {
   return explicit;
 }
 
+/**
+ * The usage error for a `--base` given a blank value, in either spelling, or
+ * null. A missing value or one that is another flag stays `explicitBase`'s
+ * typo case.
+ */
+export function blankExplicitBase(argv: readonly string[]): string | null {
+  const joined = argv.find((a) => a.startsWith("--base="));
+  if (joined !== undefined) return baseValueError(joined.slice("--base=".length));
+  const flag = argv.indexOf("--base");
+  const value = flag < 0 ? undefined : argv[flag + 1];
+  return value === undefined || value.startsWith("--") ? null : baseValueError(value);
+}
+
 /** `--base` wins, then the open PR's base, then the repo default. */
 export function resolveBase(
   argv: readonly string[],
@@ -277,8 +297,11 @@ export function resolveBase(
   forge: (b: string) => ForgeAnswer = (b) => askForgeForBase(b),
 ): BaseResolution {
   const explicit = explicitBase(argv);
-  if (explicit !== null) {
-    return { base: explicit, source: "flag" };
+  const given = explicit === null ? null : parseBaseRef(explicit, configuredRemotes());
+  if (given !== null) {
+    return given.remote === "origin"
+      ? { base: given.branch, source: "flag" }
+      : { base: given.branch, source: "flag", remote: given.remote };
   }
   // There is deliberately no cheap short-circuit for "the branch looks like the
   // default". It was tried and reverted: it decided a VERDICT from
@@ -321,12 +344,25 @@ export function describeBase(r: BaseResolution): string {
 
 /** The SHA the server reports for `<base>` right now — never a tracking ref. */
 export function remoteHead(base: string, remote = "origin"): string | null {
-  const out = git(["ls-remote", "--heads", remote, base]);
-  if (out === null || out === "") {
-    return null;
-  }
-  const sha = out.split(/\s+/)[0];
-  return sha !== undefined && /^[0-9a-f]{40}$/.test(sha) ? sha : null;
+  const state = remoteHeadState(base, remote);
+  return state.kind === "sha" ? state.sha : null;
+}
+
+/**
+ * `absent` is a remote that answered without the branch, which is a misspelled
+ * or deleted base; only a remote that did not answer is `unreachable`.
+ */
+export type RemoteHeadState = { kind: "sha"; sha: string } | { kind: "absent" } | { kind: "unreachable" };
+
+export function remoteHeadState(base: string, remote = "origin"): RemoteHeadState {
+  const out = git(["ls-remote", remote, `refs/heads/${base}`]);
+  if (out === null) return { kind: "unreachable" };
+  const sha = parseExactHeadSha(out, base);
+  return sha === null ? { kind: "absent" } : { kind: "sha", sha };
+}
+
+function configuredRemotes(): string[] {
+  return (git(["remote"]) ?? "").split("\n").map((r) => r.trim()).filter((r) => r !== "");
 }
 
 /**
@@ -525,6 +561,52 @@ function scanReport(scanned: number, allowEmpty?: string): void {
   });
 }
 
+/** Whether this checkout's task runner defines `push-ready`, the remedy only this package ships. */
+function definesPushReady(): boolean {
+  const root = git(["rev-parse", "--show-toplevel"]);
+  if (root === null || root === "") return false;
+  try {
+    return /^ {2}push-ready:/m.test(fs.readFileSync(path.join(root, "taskfiles", "dev.yml"), "utf8"));
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * What to do about a behind branch. A merge command is printed only under
+ * `merge`: under any other strategy, or one that cannot be read, a merge of the
+ * base is the commit the declaration excludes.
+ */
+export function behindRemedy(base: string, strategy: GitConventionReading | null, remote = "origin"): string[] {
+  if (strategy === null) {
+    return [
+      "    git.update_strategy was not read — the base's commit is not in this checkout, and",
+      "    this gate does not fetch to choose advice. Update the branch per the git-workflow",
+      "    skill's references/branch-update.md, then regenerate (./agent-config roadmap:progress)",
+      "    and re-run the gates before pushing.",
+    ];
+  }
+  if (!isRefusal(strategy.state) && strategy.value === "merge") {
+    return [
+      `    git fetch ${remote} && git merge ${remote}/${base}`,
+      "    ./agent-config roadmap:progress   # regenerate AFTER every merge, not only on conflict",
+      "    then re-run the gates before pushing.",
+      "",
+      "    The dashboard line is not optional housekeeping: the roadmap dashboard is a",
+      "    GENERATED file, so a merge that lands cleanly still leaves it describing",
+      "    neither side's roadmap set. A clean auto-merge of a generated file is still wrong.",
+    ];
+  }
+  const why = isRefusal(strategy.state)
+    ? `    git.update_strategy cannot be read — ${describeRefusal(strategy)}`
+    : `    git.update_strategy is \`${strategy.value ?? "?"}\` — the base is not merged in.`;
+  return [
+    why,
+    "    Update the branch per the git-workflow skill's references/branch-update.md,",
+    "    then regenerate (./agent-config roadmap:progress) and re-run the gates before pushing.",
+  ];
+}
+
 /**
  * @param forge Seam for the forge lookup. Production passes nothing and gets the
  * real `gh`. Tests MUST pass a stub: without this parameter the only way to
@@ -542,6 +624,12 @@ export function main(
     return selfTest(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", ".."));
   }
   const quiet = argv.includes("--quiet");
+  const blank = blankExplicitBase(argv);
+  if (blank !== null) {
+    scanReport(0, "argument error");
+    console.error(`❌  check_branch_freshness: ${blank}`);
+    return 2;
+  }
 
   // CI merges or refuses on the server; a second opinion here would be noise.
   if (process.env["CI"] === "true" || process.env["GITHUB_ACTIONS"] === "true") {
@@ -565,8 +653,11 @@ export function main(
   // positionally already selects the real `gh` — no branch needed here.
   const resolved = resolveBase(argv, branch, forge);
   const base = resolved.base;
+  const remote = resolved.remote ?? "origin";
+  const shown = `${remote}/${base}`;
 
-  if (branch === base) {
+  // Remote and branch together: local `main` is not `upstream/main`, which can be ahead of it.
+  if (branch === base && remote === "origin") {
     scanReport(0, `standing on ${base} itself — a branch cannot be behind itself`);
     return 0;
   }
@@ -577,49 +668,81 @@ export function main(
   if (resolved.unverified !== undefined) {
     process.stdout.write(
       `⚠️  check_branch_freshness: could not ask the forge for this branch's PR base ` +
-        `(${resolved.unverified}) — checking origin/${base}, the ${describeBase(resolved)}. ` +
+        `(${resolved.unverified}) — checking ${shown}, the ${describeBase(resolved)}. ` +
         "If an open PR targets a different base, THAT base is NOT verified here.\n",
     );
   }
 
-  const sha = remoteHead(base);
-  if (sha === null) {
+  const head = remoteHeadState(base, remote);
+  if (head.kind === "absent") {
+    // The remote answered, so this is not the offline case: passing it as NOT
+    // VERIFIED let a misspelled base (`origin/origin/main`) skip the check.
+    scanReport(1);
+    console.error(
+      `❌  check_branch_freshness: base \`${base}\` does not exist on ${remote} — ${describeBase(resolved)}. ` +
+        "Name a branch on the remote: `--base main` and `--base origin/main` are the same branch.",
+    );
+    return 1;
+  }
+  if (head.kind === "unreachable") {
     // Loud, not silent. An offline run has not verified the invariant, and a
     // gate that passes on an invariant it never evaluated is the false green
     // this repo keeps finding.
-    scanReport(0, `origin/${base} unreachable — reported NOT VERIFIED rather than green`);
+    scanReport(0, `${shown} unreachable — reported NOT VERIFIED rather than green`);
     process.stdout.write(
-      `check_branch_freshness: could not reach origin/${base} — NOT VERIFIED (offline?). ` +
+      `check_branch_freshness: could not reach ${shown} — NOT VERIFIED (offline?). ` +
         "Re-run before pushing.\n",
     );
     return 0;
   }
 
+  const sha = head.sha;
   scanReport(1);
   if (containsCommit(sha) === true) {
     if (!quiet) {
       process.stdout.write(
-        `✅  branch is current with origin/${base} (${sha.slice(0, 9)}) — ${describeBase(resolved)}\n`,
+        `✅  branch is current with ${shown} (${sha.slice(0, 9)}) — ${describeBase(resolved)}\n`,
       );
     }
     return 0;
   }
 
   console.error(
-    `❌  branch is BEHIND origin/${base} — the remote is at ${sha.slice(0, 9)}. ` +
+    `❌  branch is BEHIND ${shown} — the remote is at ${sha.slice(0, 9)}. ` +
       `(${describeBase(resolved)})`,
   );
   console.error("");
   console.error("    Pushing now opens a PR that may conflict, and worse: another branch");
   console.error("    may already have shipped what this one is implementing.");
   console.error("");
-  console.error(`    git fetch origin && git merge origin/${base}`);
-  console.error("    ./agent-config roadmap:progress   # regenerate AFTER every merge, not only on conflict");
-  console.error("    then re-run the gates before pushing.");
-  console.error("");
-  console.error("    The dashboard line is not optional housekeeping: the roadmap dashboard is a");
-  console.error("    GENERATED file, so a merge that lands cleanly still leaves it describing");
-  console.error("    neither side's roadmap set. A clean auto-merge of a generated file is still wrong.");
+  // Advice text never pays for a fetch: the measured commit is new on a behind
+  // branch, so reading the strategy there would fetch inside the push budget.
+  // Read it at that commit only if it is already local, else at the cached
+  // remote-tracking commit; with neither, the remedy is the generic pointer.
+  const localAt = [sha, `refs/remotes/${remote}/${base}`]
+    .map((ref) => git(["rev-parse", "--verify", "-q", `${ref}^{commit}`]))
+    .find((found): found is string => found !== null && found !== "");
+  const strategy = localAt === undefined
+    ? null
+    : (readCommittedConvention(process.cwd(), {
+        override: shown,
+        keys: ["update_strategy"],
+        fetch: false,
+        deps: { ...makeTargetDeps(process.cwd()), remoteSha: () => localAt },
+      }).readings.update_strategy as GitConventionReading);
+  // Read by the pre-push hook to print the exact BASE it refused for. Only a
+  // checkout that defines the task gets it: a consumer runs this script from
+  // node_modules, where the task does not exist and the line would not run.
+  // A strategy read as something other than merge would make the task refuse, so it
+  // is not offered then. An unread strategy keeps it: the task reads the strategy itself.
+  const mergeAllowed = strategy === null || (!isRefusal(strategy.state) && strategy.value === "merge");
+  if (definesPushReady() && mergeAllowed) {
+    console.error(`    task push-ready BASE=${remote === "origin" ? base : shown}   # integrate the base set, regenerate, verify, re-check`);
+    console.error("");
+  }
+  for (const line of behindRemedy(base, strategy, remote)) {
+    console.error(line);
+  }
   console.error("");
   console.error(
     "    This gate asks the REMOTE, not your tracking ref — a fetch from earlier in",