@event4u/agent-config 14.21.0 → 14.22.0

package/dist/agent-src/scripts/_cli_entry.ts

@@ -0,0 +1,51 @@
+/**
+ * "Was this module invoked as the command?" — one definition for the scripts
+ * under `agents/scripts` that both run directly and are imported by siblings.
+ *
+ * Five of them carried a byte-identical copy of this logic, and the copies were
+ * about to gain a sixth clause each. The interesting part is why the obvious
+ * one-liner is not enough:
+ *
+ *  - `--splitting` in `build:agent-src-delegate` can move a module body into a
+ *    shared chunk, where `import.meta.url` names the CHUNK. The URL comparison
+ *    then never matches and the command exits 0 having done nothing — measured
+ *    on `update_roadmap_progress` before this guard existed. Inside the bundle
+ *    the invoked file name is the reliable signal, so the delegate branch runs
+ *    first and a miss falls through rather than returning false.
+ *  - A symlinked invocation (`.augment/scripts` → `dist/agent-src/scripts`, or
+ *    macOS `/var` → `/private/var`) makes the raw URLs differ: `import.meta.url`
+ *    is the resolved real path while `argv[1]` keeps the symlink. Hence the
+ *    realpath comparison last.
+ *
+ * `moduleUrl` is the caller's own `import.meta.url` — it cannot be read from
+ * here, which is why it is a parameter rather than a lookup.
+ */
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+/** Defined only by the esbuild delegate builds; `undefined` under tsx and node. */
+declare const __AGENT_CONFIG_CLI_DELEGATE__: boolean | undefined;
+
+export function isCliEntry(moduleUrl: string, name: string): boolean {
+    const argv1 = process.argv[1];
+    if (argv1 === undefined) {
+        return false;
+    }
+    if (
+        typeof __AGENT_CONFIG_CLI_DELEGATE__ !== 'undefined' &&
+        __AGENT_CONFIG_CLI_DELEGATE__ &&
+        path.basename(argv1, '.js') === name
+    ) {
+        return true;
+    }
+    const argvPath = path.resolve(argv1);
+    if (moduleUrl === pathToFileURL(argvPath).href) {
+        return true;
+    }
+    try {
+        return fs.realpathSync(fileURLToPath(moduleUrl)) === fs.realpathSync(argvPath);
+    } catch {
+        return false;
+    }
+}

package/dist/agent-src/scripts/archive_completed_roadmaps.ts

@@ -56,11 +56,13 @@ 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, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 
 import { collect } from './update_roadmap_progress.js';
 import { guardedBaselineProblems, parseGuardedBaselines } from './guarded_baseline.js';
 
+import { isCliEntry } from './_cli_entry.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 interface CompletedProcess {
@@ -638,6 +640,16 @@ function _regen_dashboard(root: string, dry_run: boolean): void {
     if (dry_run) {
         return;
     }
+    // Inside `dist/cli-delegate/` the twin sits next to us as a precompiled
+    // bundle, and plain `node` runs it — the tsx walk below would otherwise
+    // reach `npx tsx`, which resolves against the CONSUMER's npm config and
+    // hard-fails on a mismatched `engines`/`devEngines` pin (the very class
+    // ADR-204 removed from the dispatcher and left standing here).
+    const bundledTwin = path.join(path.dirname(_HERE), 'update_roadmap_progress.js');
+    if (_isFile(bundledTwin)) {
+        spawnSync(process.execPath, [bundledTwin], { cwd: root, encoding: 'utf-8' });
+        return;
+    }
     const script = path.join(path.dirname(_HERE), 'update_roadmap_progress.ts');
     // Python: `_run([sys.executable, str(script)], root)`; the twin spawns the
     // dashboard generator twin through the same `tsx` runtime, cwd=root.
@@ -800,28 +812,7 @@ function main(argv?: readonly string[]): number {
     return 0;
 }
 
-function _isCliEntry(): boolean {
-    if (process.argv[1] === undefined) {
-        return false;
-    }
-    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
-    if (import.meta.url === argvUrl) {
-        return true;
-    }
-    // A symlinked invocation (e.g. via `.augment/scripts` → `dist/agent-src/scripts`,
-    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
-    // import.meta.url is the resolved real path while argv[1] keeps the symlink
-    // path. Compare realpaths so the entry guard still fires (without this the
-    // archival sweep silently no-ops when run through the symlink).
-    try {
-        const here = fs.realpathSync(fileURLToPath(import.meta.url));
-        const argv = fs.realpathSync(path.resolve(process.argv[1]));
-        return here === argv;
-    } catch {
-        return false;
-    }
-}
-if (_isCliEntry() || process.argv[1] === _HERE) {
+if (isCliEntry(import.meta.url, 'archive_completed_roadmaps')) {
     try {
         process.exitCode = main();
     } catch (exc) {

package/dist/agent-src/scripts/roadmap_gates.ts

@@ -65,7 +65,7 @@
  */
 
 import * as path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import * as fs from 'node:fs';
 import { spawnSync } from 'node:child_process';
 
@@ -80,6 +80,8 @@ import { execute } from './gate_execute.js';
 import { listPending } from '../templates/scripts/work_engine/hooks/builtin/staged_confirmation_store.js';
 import type { StagedAction } from '../templates/scripts/work_engine/hooks/builtin/staged_confirmation.js';
 
+import { isCliEntry } from './_cli_entry.js';
+
 const _HERE = fileURLToPath(import.meta.url);
 
 /** Hard wrap for the rendered body — keeps output readable in a narrow pane. */
@@ -928,26 +930,8 @@ function main(argv?: readonly string[]): number {
     return 0;
 }
 
-function _isCliEntry(): boolean {
-    if (process.argv[1] === undefined) {
-        return false;
-    }
-    const argvPath = path.resolve(process.argv[1]);
-    if (import.meta.url === pathToFileURL(argvPath).href) {
-        return true;
-    }
-    // A symlinked invocation (`.augment/scripts` → `dist/agent-src/scripts`, or
-    // macOS /var → /private/var) makes the raw URLs differ: import.meta.url is
-    // the resolved real path while argv[1] keeps the symlink. Compare realpaths
-    // so the entry guard still fires through the projection.
-    try {
-        return fs.realpathSync(_HERE) === fs.realpathSync(argvPath);
-    } catch {
-        return false;
-    }
-}
 
-if (_isCliEntry()) {
+if (isCliEntry(import.meta.url, 'roadmap_gates')) {
     process.exitCode = main();
 }
 

package/dist/agent-src/scripts/roadmap_set_step.ts

@@ -30,7 +30,9 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import process from 'node:process';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
+
+import { isCliEntry } from './_cli_entry.js';
 
 const _HERE = fileURLToPath(import.meta.url);
 
@@ -246,8 +248,9 @@ export function main(argv: string[] = process.argv.slice(2)): number {
     }
 }
 
+
 /* c8 ignore start */
-if (process.argv[1] !== undefined && pathToFileURL(path.resolve(process.argv[1])).href === pathToFileURL(_HERE).href) {
+if (isCliEntry(import.meta.url, 'roadmap_set_step')) {
     process.exit(main());
 }
 /* c8 ignore stop */

package/dist/agent-src/scripts/stubs_due.ts

@@ -42,7 +42,9 @@
  */
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
+
+import { isCliEntry } from './_cli_entry.js';
 
 const STUB_DIR = path.join('agents', 'roadmaps', 'stubs');
 
@@ -459,24 +461,8 @@ export function main(argv: readonly string[] = process.argv.slice(2)): number {
     return 0;
 }
 
-function _isCliEntry(): boolean {
-    if (process.argv[1] === undefined) {
-        return false;
-    }
-    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
-    if (import.meta.url === argvUrl) {
-        return true;
-    }
-    try {
-        const here = fs.realpathSync(fileURLToPath(import.meta.url));
-        const argv = fs.realpathSync(path.resolve(process.argv[1]));
-        return here === argv;
-    } catch {
-        return false;
-    }
-}
 
-if (_isCliEntry() || process.argv[1] === _HERE) {
+if (isCliEntry(import.meta.url, 'stubs_due')) {
     process.exitCode = main();
 }
 

package/dist/agent-src/scripts/update_roadmap_progress.ts

@@ -62,7 +62,7 @@ import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
+import { fileURLToPath } from 'node:url';
 import { run_archival_sweep } from './archival_sweep.js';
 import {
     evaluateDashboardOnDisk,
@@ -72,6 +72,8 @@ import {
 } from './dashboard_mode.js';
 import type * as YamlModule from 'yaml';
 import { headerFragment as stubHeaderFragment } from './stubs_due.js';
+
+import { isCliEntry } from './_cli_entry.js';
 import { reportGuardedBaselines } from './guarded_baseline.js'; // third step state; contract lives there
 
 const _HERE = fileURLToPath(import.meta.url);
@@ -96,7 +98,9 @@ const EXCLUDE_DIRS: ReadonlySet<string> = new Set(['archive', 'skipped', 'stubs'
 
 // FRONTMATTER_RE = re.compile(r"\A---\n(.*?)\n---\s*\n", re.DOTALL)
 const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---[ \t\n\r\f\v]*\n/;
-const UNSCHEDULED_VALUES: ReadonlySet<string> = new Set(['draft', 'carrier']);
+// A set of one since ADR-262 deleted `status: carrier`; the shape stays so a
+// future unscheduled value is one entry rather than a control-flow change.
+const UNSCHEDULED_VALUES: ReadonlySet<string> = new Set(['draft']);
 
 const MERGE_GATED_RE = /merge-gated/i;
 // PR_NUM_RE = re.compile(r"pr\s*[=#:]?\s*#?\s*(\d+)", re.IGNORECASE)
@@ -1438,28 +1442,7 @@ function main(argv?: readonly string[]): number {
     return guarded.problems > 0 ? 1 : 0;
 }
 
-function _isCliEntry(): boolean {
-    if (process.argv[1] === undefined) {
-        return false;
-    }
-    const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
-    if (import.meta.url === argvUrl) {
-        return true;
-    }
-    // A symlinked invocation (e.g. via `.augment/scripts` → `dist/agent-src/scripts`,
-    // or macOS /var → /private/var temp dirs) makes the raw URLs differ:
-    // import.meta.url is the resolved real path while argv[1] keeps the symlink
-    // path. Compare realpaths so the entry guard still fires (without this the
-    // dashboard regen silently no-ops when run through the symlink).
-    try {
-        const here = fs.realpathSync(fileURLToPath(import.meta.url));
-        const argv = fs.realpathSync(path.resolve(process.argv[1]));
-        return here === argv;
-    } catch {
-        return false;
-    }
-}
-if (_isCliEntry() || process.argv[1] === _HERE) {
+if (isCliEntry(import.meta.url, 'update_roadmap_progress')) {
     try {
         process.exitCode = main();
     } catch (exc) {

package/dist/agent-src/skills/code-intelligence/SKILL.md

@@ -182,6 +182,28 @@ consumer-shipped SCIP index. Literal-string probes are reported as a separate
 cannot answer them at all, which is where grep stays necessary rather than a
 defect in the engine.
 
+## Staleness delivery — which hosts get it for free, and which do not
+
+Migrated verbatim from `external-code-graph-interop` so the obligation stays in
+the rule and the per-host delivery detail is paid only on activation.
+
+On a host with a verified `pre_tool_use` contract, the `code-graph-context`
+concern supplies this for free: once per session, on the first search or
+code read, it delivers the graph's state as structured `additionalContext` —
+`code-graph: fresh` or `code-graph: N commit(s) behind`. It is silent when no
+graph exists, so hearing nothing is not evidence that the graph is fresh.
+
+**On every other host that carrier does not exist**, and this section is the
+delivery: run `agent-config code-graph detect --format json` before trusting a
+relationship answer, and say which state you got. Which hosts those are is
+`agent-config hooks:status` — resolved from the platform table, never guessed
+from the host's name.
+
+Either way the disposition is the same: `behind:N` → `agent-config code-graph
+refresh` first, or use grep and say so. This is a freshness obligation, not an
+ordering claim; the rule's query-first ordering still governs which source to
+reach for.
+
 ## Do NOT
 
 - Do NOT rebuild a **fresh** consumer-shipped index — query it (interop
@@ -199,3 +221,6 @@ defect in the engine.
   discipline; the graph is one evidence source, still confirmed against the real
   code when load-bearing.
 - `agent-config code-graph` — the CLI surface over the engine (build / query / detect / affected).
+- [`discovery_graph`](../../scripts/discovery_graph.ts) — this suite's OWN
+  artifact relation-graph (`affected`/`explain`). The external code-graph is the
+  *source-code* analogue; keep the two apart when answering.

package/dist/agent-src/skills/roadmap-writing/SKILL.md

@@ -224,6 +224,23 @@ procedure when [`roadmap-management`](../roadmap-management/SKILL.md)
 spawns a follow-up). Bare `[~]` / `[-]` is allowed; annotated is
 preferred.
 
+#### A prohibition-shaped step closes with `[x]`
+
+A step whose content is a **prohibition** (*"Do not build the enforcement"*) has
+no artifact to point at. `[~]` invents receiver work nobody owes, `[-]` mislabels
+restraint as cancellation, `[ ]` makes an honoured bounded obligation
+unarchivable. It closes with **`[x]`** — the obligation was discharged, and `[x]`
+never required that something was created. Its `verify:` must name every
+implementation, registration and semantically-equivalent surface (a structural
+check, not one literal grep, which misses aliases and generated code); **fail if
+an expected search root is missing**, checked BEFORE the absence check, because a
+glob over a vanished directory returns nothing and reads as success; scope the
+claim to the branch diff — *"this change introduced no enforcement"*, never the
+unprovable *"enforcement exists nowhere"*; and be re-run at archival. Not for a
+prohibition meant to hold indefinitely — that belongs in a rule, test or linter,
+because a closed step stops watching. Council convention, 2026-09-08 (2 seats,
+convergent); falsified if tooling defines `[x]` as requiring a positive mutation.
+
 ### 7. Follow-up roadmaps spawn from deferred items — frontmatter shape
 
 When a parent roadmap closes with `[~]` items, the

package/dist/agent-src/templates/agent-settings.md

@@ -629,7 +629,6 @@ the canonical narrative lives in
 | `hooks.injection_scan.enabled` | `true`, `false` | `false` | PostToolUse prompt-injection scanner: scans tool output for injection signatures and warns in context (exit 2) — never blocks. |
 | `hooks.rtk_wrap.enabled` | `true`, `false` | `false` | PreToolUse RTK-wrap nudge: when `rtk` is on PATH, warns (exit 2, never blocks) to re-run a verbose CLI command wrapped with rtk. |
 | `hooks.design_slop.enabled` | `true`, `false` | `false` | PreToolUse anti-slop nudge: runs the `lint_design_slop` registry against about-to-be-written UI content and warns (exit 2, never blocks) on P0/P1 aesthetic tells. |
-| `hooks.code_graph.enabled` | `true`, `false` | `false` | PreToolUse code-graph nudge (deprecated — honest null 2026-07-28): when a code-graph index exists, warns once per session to query the graph before grep. Requires manually installing the ABI-locked parser pair. |
 | `pipelines.skill_improvement` | `true`, `false` | `true` | When `true`: propose learning capture after meaningful tasks. When `false`: silent. Included in every profile except `custom`. |
 | `roadmap.skip_pre_run_gate` | `true`, `false` | `true` | When `true` (default): `/roadmap:process-step\|phase\|full` skips the interactive pre-run summary and starts the loop immediately — the resolved roadmap, cadence, and council are surfaced inline so an unwanted pick can still be aborted. When `false`: the loop shows the pre-run summary with numbered options (Go / Different roadmap / Different scope / Toggle council / Abort) and waits. The gate is always shown — regardless of this flag — when the roadmap is ambiguous (multiple active, none named) or a scope / cadence conflict has no sensible default. |
 | `roadmap.quality_cadence` | `end_of_roadmap`, `per_phase`, `per_step` | `end_of_roadmap` | When `/roadmap:process-step|phase|full` runs the project's quality pipeline — only relevant when `quality.local_auto_run` is `true`; when it is `false` (the default) local pipeline runs are suppressed at every cadence and remote CI is the gate. Default skips per-step / per-phase runs and gates only the final archival. `per_phase` runs once after every phase; `per_step` is the legacy verbose mode. Step checkboxes and the dashboard are always updated regardless. |

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: "14.21.0"
+agent_config_version: "14.22.0"
 
 # --- Project identity ---
 project:

package/dist/cli-delegate/_cli_entry.js

@@ -0,0 +1,8 @@
+import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);
+import {
+  isCliEntry
+} from "./chunk-5EK5WQN6.js";
+import "./chunk-JO25G5H7.js";
+export {
+  isCliEntry
+};

package/dist/cli-delegate/_lib/pin_resolver.js

@@ -0,0 +1,170 @@
+import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);
+
+// src/scripts/_lib/pin_resolver.ts
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+var PACKAGE_NAME = "@event4u/agent-config";
+var PIN_KEY = "agent_config_version";
+var NO_REEXEC_ENV = "AGENT_CONFIG_NO_PIN_REEXEC";
+var REEXEC_DEPTH_ENV = "AGENT_CONFIG_PIN_REEXEC_DEPTH";
+function _normalize(version) {
+  return version.trim().replace(/^v+/, "");
+}
+async function read_pin(cwd, options = {}) {
+  let settings;
+  try {
+    let loader = options.settings_loader;
+    if (loader === void 0) {
+      const specifier = "./agent_settings";
+      const mod = await import(specifier);
+      if (typeof mod.load_agent_settings !== "function") {
+        return null;
+      }
+      loader = mod.load_agent_settings;
+    }
+    settings = await loader({ cwd });
+  } catch {
+    return null;
+  }
+  const raw = settings[PIN_KEY];
+  if (typeof raw !== "string") {
+    return null;
+  }
+  const pin = raw.trim();
+  return pin || null;
+}
+function should_reexec(pin, installed, options = {}) {
+  const env = options.env ?? process.env;
+  if (env[NO_REEXEC_ENV] === "1") {
+    return false;
+  }
+  if (env[REEXEC_DEPTH_ENV] === "1") {
+    return false;
+  }
+  if (!pin) {
+    return false;
+  }
+  if (!installed) {
+    return false;
+  }
+  return _normalize(pin) !== _normalize(installed);
+}
+function build_reexec_argv(pin, argv) {
+  return ["npx", "--yes", `${PACKAGE_NAME}@${_normalize(pin)}`, ...argv];
+}
+function _which(cmd) {
+  const path_var = process.env.PATH ?? "";
+  const exts = process.platform === "win32" ? (process.env.PATHEXT ?? ".COM;.EXE;.BAT;.CMD").split(";") : [""];
+  for (const dir of path_var.split(path.delimiter)) {
+    if (!dir) {
+      continue;
+    }
+    for (const ext of exts) {
+      const candidate = path.join(dir, cmd + ext.toLowerCase());
+      try {
+        const st = fs.statSync(candidate);
+        if (st.isFile()) {
+          if (process.platform !== "win32") {
+            fs.accessSync(candidate, fs.constants.X_OK);
+          }
+          return candidate;
+        }
+      } catch {
+      }
+    }
+  }
+  return null;
+}
+function _exec_runner(npx, argv, env) {
+  const result = spawnSync(npx, argv.slice(1), {
+    env,
+    stdio: "inherit"
+  });
+  process.exit(result.status ?? 1);
+}
+async function maybe_reexec(installed, options = {}) {
+  const cwd = options.cwd ?? process.cwd();
+  const argv = options.argv ?? process.argv.slice(1);
+  const env = options.env ?? process.env;
+  const pin_reader = options.pin_reader ?? ((c) => read_pin(c));
+  const which = options.which ?? _which;
+  const pin = await pin_reader(cwd);
+  if (!should_reexec(pin, installed, { env })) {
+    return null;
+  }
+  if (pin == null) {
+    throw new Error("maybe_reexec: pin narrowed to null after should_reexec");
+  }
+  const npx = which("npx");
+  if (!npx) {
+    return null;
+  }
+  const new_argv = build_reexec_argv(pin, argv.length > 0 ? argv.slice(1) : []);
+  const child_env = { ...env };
+  child_env[REEXEC_DEPTH_ENV] = "1";
+  const runner = options.runner ?? null;
+  if (runner === null) {
+    return _exec_runner(npx, new_argv, child_env);
+  }
+  return runner(npx, new_argv, child_env);
+}
+function _parse_cli(argv) {
+  let cwd = process.cwd();
+  let installed = "";
+  let forward = [];
+  let i = 0;
+  while (i < argv.length) {
+    const token = argv[i];
+    if (token === "--cwd" && i + 1 < argv.length) {
+      cwd = argv[i + 1];
+      i += 2;
+    } else if (token === "--installed" && i + 1 < argv.length) {
+      installed = argv[i + 1];
+      i += 2;
+    } else if (token === "--") {
+      forward = argv.slice(i + 1);
+      break;
+    } else {
+      i += 1;
+    }
+  }
+  return { cwd, installed, forward };
+}
+function _isCliEntry() {
+  if (process.argv[1] === void 0) {
+    return false;
+  }
+  if (true) {
+    if (path.basename(process.argv[1], ".js") === "pin_resolver") {
+      return true;
+    }
+  }
+  const argvUrl = pathToFileURL(path.resolve(process.argv[1])).href;
+  if (import.meta.url === argvUrl) {
+    return true;
+  }
+  try {
+    const here = fs.realpathSync(fileURLToPath(import.meta.url));
+    const argv = fs.realpathSync(path.resolve(process.argv[1]));
+    return here === argv;
+  } catch {
+    return false;
+  }
+}
+if (_isCliEntry()) {
+  const { cwd, installed, forward } = _parse_cli(process.argv.slice(2));
+  const child_argv = ["agent-config", ...forward];
+  await maybe_reexec(installed, { cwd, argv: child_argv });
+}
+export {
+  NO_REEXEC_ENV,
+  PACKAGE_NAME,
+  PIN_KEY,
+  REEXEC_DEPTH_ENV,
+  build_reexec_argv,
+  maybe_reexec,
+  read_pin,
+  should_reexec
+};

package/dist/cli-delegate/archival_sweep.js

@@ -0,0 +1,8 @@
+import { createRequire as __acCreateRequire } from 'node:module'; const require = globalThis.require ?? __acCreateRequire(import.meta.url);
+import {
+  run_archival_sweep
+} from "./chunk-YWVXLR44.js";
+import "./chunk-JO25G5H7.js";
+export {
+  run_archival_sweep
+};