@event4u/agent-config 9.14.0 → 9.15.0

package/src/scripts/prepack-check.mjs

@@ -3,7 +3,7 @@
  * prepack-check.mjs — guard the published artifact.
  *
  * Runs during `npm pack` / `npm publish` AND as a dry-run on every PR
- * (Static Checks workflow). Two gates:
+ * (Static Checks workflow). Four gates:
  *
  *   1. Compiled-bin shape — the TS CLI binary exists, is executable, and
  *      carries the Node shebang before the tarball is built. Otherwise a
@@ -12,6 +12,11 @@
  *   2. Shipped-import completeness — every relative import reachable from
  *      the shipped `src/` trees resolves to a file the `files` whitelist
  *      actually ships (the 8.3.0 ERR_MODULE_NOT_FOUND class).
+ *   3. Lifecycle-target shape — every consumer-side lifecycle script points
+ *      at a target that exists and ships (the 9.8.0 dead-postinstall class).
+ *   4. Router-target shipping — every `routes_to` target in dist/router.json
+ *      resolves inside the shipped `files[]` set, so a `files[]` narrowing
+ *      cannot ship a dead router pointer.
  *
  * Folded from external council pass 2026-05-18 (Phase 1.3 acceptance).
  *
@@ -176,6 +181,40 @@ if (lifecycleErrors.length > 0) {
 }
 process.stderr.write('prepack-check: lifecycle script targets OK\n');
 
+// ---------------------------------------------------------------------------
+// Router-pointer shipping guard (gate 4): every `routes_to` target in
+// dist/router.json must resolve to a file that exists AND is inside the
+// shipped `files[]` set. A `files[]` narrowing that drops a routed target was
+// caught once by a working gate; this makes that catch structural rather than
+// incidental, and moves it to pack time on the causing PR
+// (road-to-gates-that-can-fail Phase 4). The kind→path table is single-sourced
+// from ./router_target_paths.mjs, shared with
+// cmd_conformance.ts::routeTargetPaths — two copies could disagree about where
+// a pointer lives, which is the packaging↔runtime gap this closes.
+//
+// PREPACK_ROUTER_JSON points the gate at a different index (repo-relative or
+// absolute) — used by tests/scripts/prepack_router_targets.test.ts and by the
+// planted-target proof, so dist/router.json itself is never mutated.
+// ---------------------------------------------------------------------------
+import { checkRouterTargetsShipped } from './prepack_router_targets.mjs';
+
+const routerRel = env.PREPACK_ROUTER_JSON ?? 'dist/router.json';
+const routerResult = checkRouterTargetsShipped({
+    routerPath: resolve(routerRel),
+    isShipped,
+    exists: (relPath) => existsSync(resolve(relPath)),
+    readFile: (p) => readFileSync(p, 'utf8'),
+});
+if (routerResult.errors.length > 0) {
+    for (const e of routerResult.errors) {
+        process.stderr.write(`prepack-check: ${e}\n`);
+    }
+    die(`${routerResult.errors.length} router target(s) do not resolve inside the shipped set.`);
+}
+process.stderr.write(
+    `prepack-check: router targets OK (${routerResult.scanned} routes_to target(s) in ${routerRel})\n`,
+);
+
 // Optional: invoked with --verbose dumps the size for tarball-budget bookkeeping.
 if (argv.includes('--verbose')) {
     process.stderr.write(`prepack-check: size=${st.size} bytes\n`);

package/src/scripts/prepack_router_targets.d.mts

@@ -0,0 +1,7 @@
+/** Type declarations for prepack_router_targets.mjs (prepack gate 4). */
+export declare function checkRouterTargetsShipped(opts: {
+    routerPath: string;
+    isShipped: (relPath: string) => boolean;
+    exists: (relPath: string) => boolean;
+    readFile: (absPath: string) => string;
+}): { errors: string[]; scanned: number };

package/src/scripts/prepack_router_targets.mjs

@@ -0,0 +1,93 @@
+/**
+ * prepack_router_targets.mjs — pure core of prepack gate 4.
+ *
+ * Every `routes_to` target in `dist/router.json` must resolve to a file that
+ * (a) exists and (b) is inside the `files[]` whitelist. A pointer that
+ * resolves in the dev tree but is not in the tarball is dead the moment a
+ * consumer installs it — `agent-config conformance`'s `router-pointers` check
+ * then fails on the consumer's machine, for a defect introduced here.
+ *
+ * The kind→path table is NOT defined here: it is imported from
+ * `router_target_paths.mjs`, which `cmd_conformance.ts::routeTargetPaths` also
+ * consumes. One table, two readers — see that file's header for why.
+ *
+ * Extracted from `prepack-check.mjs` for the same reason
+ * `prepack_lifecycle_check.mjs` was: the entry script has top-level side
+ * effects and `process.exit`, so it cannot be imported by a test.
+ * road-to-gates-that-can-fail Phase 4.
+ */
+import { routeTargetPathsPosix } from './router_target_paths.mjs';
+
+/**
+ * @typedef {object} RouterTargetOptions
+ * @property {string} routerPath        Absolute path to the router index.
+ * @property {(relPath: string) => boolean} isShipped  `files[]` membership test.
+ * @property {(relPath: string) => boolean} exists     Existence test, repo-relative.
+ * @property {(absPath: string) => string} readFile    Reader for `routerPath`.
+ */
+
+/**
+ * @param {RouterTargetOptions} opts
+ * @returns {{ errors: string[], scanned: number }}
+ */
+export function checkRouterTargetsShipped(opts) {
+    const { routerPath, isShipped, exists, readFile } = opts;
+    const errors = [];
+    let scanned = 0;
+
+    let router;
+    try {
+        router = JSON.parse(readFile(routerPath));
+    } catch (e) {
+        return {
+            errors: [`router index ${routerPath} unreadable or not JSON: ${e.message}`],
+            scanned: 0,
+        };
+    }
+
+    for (const tier of ['tier_1', 'tier_2']) {
+        for (const entry of router[tier] ?? []) {
+            const ruleId = String(entry?.id ?? '<unnamed rule>');
+            for (const raw of entry?.routes_to ?? []) {
+                const target = String(raw);
+                scanned += 1;
+                const candidates = routeTargetPathsPosix(target);
+                if (candidates.length === 0) {
+                    errors.push(
+                        `${tier}:${ruleId} routes_to ${JSON.stringify(target)} — unparseable ` +
+                            'target or unknown kind (router_target_paths.mjs has no template ' +
+                            'for it), so nothing can be verified as shipped',
+                    );
+                    continue;
+                }
+                const present = candidates.filter((rel) => exists(rel));
+                if (present.length === 0) {
+                    errors.push(
+                        `${tier}:${ruleId} routes_to '${target}' → none of ` +
+                            `[${candidates.join(', ')}] exists in the tree`,
+                    );
+                    continue;
+                }
+                if (!present.some((rel) => isShipped(rel))) {
+                    errors.push(
+                        `${tier}:${ruleId} routes_to '${target}' → ${present[0]} exists but is ` +
+                            'NOT in the package.json `files` whitelist — the pointer would ' +
+                            'ship dead and fail `agent-config conformance` on the consumer',
+                    );
+                }
+            }
+        }
+    }
+
+    // Zero-scope is a failure (Phase 1 of the same roadmap): a router index
+    // that yields no targets means the shape changed under the gate, not that
+    // the package is clean.
+    if (errors.length === 0 && scanned === 0) {
+        errors.push(
+            `scanned 0 routes_to target(s) in ${routerPath} — the scan scope is dead or the ` +
+                'router schema moved; this gate cannot report clean on nothing',
+        );
+    }
+
+    return { errors, scanned };
+}

package/src/scripts/print_required_checks.ts

@@ -61,28 +61,75 @@ const DOCS_ONLY_ALLOWED_TOP: ReadonlySet<string> = new Set([
     'llms.txt',
 ]);
 
+// Check names below are the strings GitHub actually REPORTS, verified against
+// `gh pr checks 1108` on 2026-08-02 (road-to-renewal-foundation Phase 1).
+//
+// They previously named a matrix that had drifted into fiction — `Consistency`,
+// `Skill Lint`, `Tests / install-tests`, `Tests / node-tests`,
+// `Public Install Smoke / smoke`, `Migration Dry-Run`,
+// `Release Validation / release-shape`, `Release Guard (post-tag)` and, most
+// clearly, `Tests / python-tests`, which cannot exist at all: the Python→TS
+// migration completed and `no-python-in-src.yml` now enforces its absence. A
+// preview tool that prints names no check will ever report is worse than no
+// preview — it reads as a verified list.
+//
+// Matrix families are printed as ONE line with the axis spelled out rather than
+// as N pinned contexts. Shard counts and runner labels are part of the reported
+// name, so pinning them here would re-create the same drift on the next matrix
+// change — the exact failure this reconciliation removed.
 const FEATURE_CHECKS = [
-    'Consistency',
-    'Smoke Contracts',
-    'Skill Lint',
-    'Tests / install-tests',
-    'Tests / install-aux-tests',
-    'Tests / python-tests',
-    'Tests / node-tests',
-    'Public Install Smoke / smoke',
+    'Sync + Generate Tools Consistency',
+    'Smoke — kernel',
+    'Smoke — router',
+    'Smoke — schema',
+    'Smoke — skills',
+    'skill-lint',
+    'Static Checks (ESLint · typecheck · prepack)',
+    'Install Script Tests (matrix: {ubuntu,macos}-latest × shard 1-4/4)',
+    'Install Aux Tests (matrix: {ubuntu,macos}-latest)',
+    'Node Tests (matrix: {ubuntu,macos}-latest × shard 1-4/4)',
+    'Golden Tests (matrix: {ubuntu,macos}-latest)',
+    'Workspace Tests (matrix: {ubuntu,macos}-latest)',
+    'Public Install Smoke (matrix: {ubuntu,macos,windows}-latest × node {20,22})',
+    'Rule backstops',
+    'no-python-in-src',
+    'lint commit subjects',
 ] as const;
 
 const RELEASE_CHECKS = [
-    'Consistency',
-    'Smoke Contracts',
-    'Migration Dry-Run',
-    'Release Validation / release-shape',
-    'Release Validation / changelog-entry',
-    'Release Validation / version-consistency',
-    'Release Guard (post-tag)',
+    'Sync + Generate Tools Consistency',
+    'Smoke — kernel',
+    'Smoke — router',
+    'Smoke — schema',
+    'Smoke — skills',
+    'Release-PR shape detector',
+    'CHANGELOG entry exists for head version',
+    'package.json / marketplace.json / pack manifests agree',
+    'Release install E2E (pack → install → upgrade → boot)',
+    'npm audit (runtime deps, high+)',
+    'skill-lint-strict',
 ] as const;
 
-const DOCS_ONLY_CHECKS = ['Consistency', 'Smoke Contracts'] as const;
+const DOCS_ONLY_CHECKS = [
+    'Sync + Generate Tools Consistency',
+    'Smoke — kernel',
+    'Smoke — router',
+    'Smoke — schema',
+    'Smoke — skills',
+] as const;
+
+/**
+ * The checks that mechanically BLOCK a merge, per the repository ruleset
+ * `main protection` (id 17749383). Everything else above runs and is visible
+ * on the PR but does not gate the merge button.
+ *
+ * Deliberately a constant, not an API read: this script is contractually
+ * offline ("never invokes `gh`, never touches the network"). Re-verify with
+ * `gh api repos/event4u-app/agent-config/rulesets/17749383` when the ruleset
+ * changes — `docs/contracts/branch-protection-policy.md` § Change discipline
+ * owns that procedure.
+ */
+const ENFORCED_CHECKS = ['Sync + Generate Tools Consistency'] as const;
 
 /** `git rev-parse --abbrev-ref HEAD`, mirroring `_git(check=True)`. */
 function current_branch(): string {
@@ -161,12 +208,19 @@ function print_set(shape_label: Shape, files: string[]): void {
         'docs-only': DOCS_ONLY_CHECKS,
     };
     const checks = table[shape_label];
+    const enforced: ReadonlySet<string> = new Set(ENFORCED_CHECKS);
     process.stdout.write(`PR shape: ${shape_label}  (${files.length} file(s) in diff)\n`);
-    process.stdout.write(`Required checks (${checks.length}):\n`);
+    process.stdout.write(`Checks this PR will face (${checks.length}):\n`);
     for (const name of checks) {
-        process.stdout.write(`  - ${name}\n`);
+        // `!` marks the checks that actually block the merge button; the rest
+        // run and are visible but are advisory at the branch-protection layer.
+        process.stdout.write(`  ${enforced.has(name) ? '!' : '-'} ${name}\n`);
     }
     process.stdout.write('\n');
+    process.stdout.write(
+        `! = blocks merge (${ENFORCED_CHECKS.length} of ${checks.length}); ` +
+            '- = runs, visible, advisory\n',
+    );
     process.stdout.write(
         'Contract: docs/contracts/branch-protection-policy.md ' +
             '(per-PR-shape matrix)\n',

package/src/scripts/profile_staleness_hook.ts

@@ -37,6 +37,9 @@ import {
   LOCAL_PROJECT_SUBDIR,
 } from "./_lib/agent_settings.js";
 import { readHookStdin } from "./hooks/hook_stdin.js";
+import { probeRanToday, stampProbeRun } from "./hooks/probe_throttle.js";
+
+const THROTTLE_CONCERN = "profile-staleness";
 
 // --- inlined session_profiles.stale_notice slice (unported dep) ----------
 
@@ -143,6 +146,15 @@ export function main(argv?: string[]): number {
   _readStdinIfNotTty();
 
   const root = rootArg !== null ? rootArg : _project_root();
+
+  // Daily throttle (road-to-hook-latency-repair): the overlay does not
+  // change within a day more often than a session ends — one attempt per
+  // local calendar day is enough. Skipped probe re-runs tomorrow.
+  if (probeRanToday(root, THROTTLE_CONCERN)) {
+    return 0;
+  }
+  stampProbeRun(root, THROTTLE_CONCERN);
+
   let notice: string | null;
   try {
     notice = _stale_notice(root);

package/src/scripts/record_evaluator_measurements.mjs

@@ -0,0 +1,105 @@
+#!/usr/bin/env node
+/**
+ * record_evaluator_measurements.mjs — write the committed measurement record.
+ *
+ * `cli_help_command_count` drifted 74 → 80 against a value frozen at 79 with
+ * nobody seeing it, because the only place the real number existed was a
+ * transient CI log. The fix (road-to-gates-that-can-fail Phase 5; council route
+ * 2026-08-02) is a COMMITTED artifact: the nightly writes the measurement set
+ * here, and `check_evaluator_budgets --recorded` compares a later fresh run
+ * against it — a contradiction warns on `main` and fails on `release/*`. The
+ * review surface that already exists carries the signal; no notification
+ * channel a single maintainer would mute.
+ *
+ * Lives under `agents/evidence/` (the repo's committed-evidence tree), NOT
+ * under `src/config/` which ships: this is maintainer evidence with nightly
+ * churn, not consumer runtime config, and keeping it out of the tarball also
+ * keeps `evaluator-budgets.json` — the policy — reviewable on its own.
+ *
+ * Sorted keys + 4-space indent + trailing newline: a moved number must be a
+ * one-line diff, or the artifact is not reviewable.
+ *
+ * Usage:
+ *   node src/scripts/record_evaluator_measurements.mjs \
+ *     --measurements <file.json> [--out <file.json>]
+ *     [--sha <git sha>] [--run-url <url>] [--conditions <text>]
+ */
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { argv, exit, stdout } from 'node:process';
+
+/** Default (repo-relative) home of the record. */
+export const RECORD_REL = 'agents/evidence/metrics/evaluator-measurements.json';
+
+const RECORD_COMMENT =
+    'Written by src/scripts/record_evaluator_measurements.mjs, invoked from ' +
+    'src/scripts/evaluator_umbrella.sh when UMBRELLA_RECORD=1 (the nightly). ' +
+    'check_evaluator_budgets.ts --recorded compares a fresh measurement set against ' +
+    'this file; a contradiction on a DETERMINISTIC metric warns on main and fails on ' +
+    'release. Do not hand-edit — refresh it from a real run.';
+
+/**
+ * Build the record document. Pure — the caller owns the filesystem.
+ *
+ * @param {Record<string, unknown>} measurements
+ * @param {{ recordedAt?: string, sha?: string, runUrl?: string, conditions?: string }} [meta]
+ */
+export function buildRecord(measurements, meta = {}) {
+    const sorted = {};
+    for (const key of Object.keys(measurements).sort()) {
+        sorted[key] = measurements[key];
+    }
+    return {
+        schema_version: 1,
+        _comment: RECORD_COMMENT,
+        recorded_at: meta.recordedAt ?? new Date().toISOString(),
+        git_sha: meta.sha || null,
+        run_url: meta.runUrl || null,
+        conditions: meta.conditions || null,
+        measurements: sorted,
+    };
+}
+
+/** Canonical serialization — stable so an unchanged run produces no diff. */
+export function serializeRecord(doc) {
+    return `${JSON.stringify(doc, null, 4)}\n`;
+}
+
+function argValue(args, flag) {
+    const i = args.indexOf(flag);
+    return i >= 0 ? args[i + 1] : undefined;
+}
+
+export function main(args = argv.slice(2)) {
+    const measurementsPath = argValue(args, '--measurements');
+    if (measurementsPath === undefined) {
+        process.stderr.write(
+            'usage: record_evaluator_measurements --measurements <file.json> ' +
+                '[--out <file.json>] [--sha <sha>] [--run-url <url>] [--conditions <text>]\n',
+        );
+        return 2;
+    }
+    const out = resolve(argValue(args, '--out') ?? RECORD_REL);
+    let measurements;
+    try {
+        measurements = JSON.parse(readFileSync(resolve(measurementsPath), 'utf8'));
+    } catch (e) {
+        process.stderr.write(`record_evaluator_measurements: ${e.message}\n`);
+        return 2;
+    }
+    const doc = buildRecord(measurements, {
+        sha: argValue(args, '--sha'),
+        runUrl: argValue(args, '--run-url'),
+        conditions: argValue(args, '--conditions'),
+    });
+    mkdirSync(dirname(out), { recursive: true });
+    writeFileSync(out, serializeRecord(doc));
+    stdout.write(
+        `recorded ${Object.keys(doc.measurements).length} measurement(s) → ${out}\n`,
+    );
+    return 0;
+}
+
+if (process.argv[1] !== undefined && resolve(process.argv[1]).endsWith('record_evaluator_measurements.mjs')) {
+    exit(main());
+}

package/src/scripts/recruit_preflight.sh

@@ -107,7 +107,7 @@ fi
 #    exists. /tmp/agent-config-ci-start.txt is written by _ci-start
 #    at the start of every 'task ci' run; /tmp/agent-config-ci-end.txt
 #    by _ci-end on success. Pre-flight passes when both exist AND
-#    end > start AND no .agent-src.uncondensed file is newer than end.
+#    end > start AND no src/ file is newer than end.
 START_MARKER="/tmp/agent-config-ci-start.txt"
 END_MARKER="/tmp/agent-config-ci-end.txt"
 if [ ! -f "$START_MARKER" ] || [ ! -f "$END_MARKER" ]; then

package/src/scripts/release.ts

@@ -169,6 +169,8 @@ class CalledProcessError extends Error {
 // _lib/ and install.ts's REPO_ROOT computation).
 const REPO_ROOT = path.resolve(path.dirname(_HERE), '..', '..');
 const PACKAGE_JSON = path.join(REPO_ROOT, 'package.json');
+// Bumped alongside package.json — see set_lockfile_version for why.
+const PACKAGE_LOCK_JSON = path.join(REPO_ROOT, 'package-lock.json');
 const MARKETPLACE_JSON = path.join(REPO_ROOT, '.claude-plugin', 'marketplace.json');
 // Source-of-truth project-settings template. Carries an `agent_config_version`
 // pin that check_template_pin_drift requires to equal package.json.version. We
@@ -562,6 +564,65 @@ function git(args: readonly string[], opts: { capture?: boolean } = {}): string
     return capture ? r.stdout.trim() : '';
 }
 
+/**
+ * One name per failing check, from `gh pr checks --json name,bucket` output.
+ *
+ * Pure over the JSON text so the shape is testable without gh. Returns []
+ * when the payload is unparseable or nothing sits in the `fail` bucket —
+ * the caller then falls back to the raw watch output alone.
+ */
+export function _failed_check_names(jsonText: string): string[] {
+    let parsed: unknown;
+    try {
+        parsed = JSON.parse(jsonText);
+    } catch {
+        return [];
+    }
+    if (!Array.isArray(parsed)) {
+        return [];
+    }
+    const names: string[] = [];
+    for (const entry of parsed) {
+        if (typeof entry !== 'object' || entry === null) {
+            continue;
+        }
+        const e = entry as Record<string, unknown>;
+        if (e['bucket'] === 'fail' && typeof e['name'] === 'string') {
+            names.push(e['name']);
+        }
+    }
+    return names;
+}
+
+/**
+ * Remediation lines for a set of failing check names.
+ *
+ * The watch table scrolls failures out of view on a busy PR, so the operator
+ * repeatedly saw only `pass`/`skipping` rows plus "PR checks failed" — the
+ * 9.14.0 failure mode, twice. Name the red checks explicitly and, for the
+ * shape detector, say where the fix belongs (main, never the release branch).
+ */
+export function _failed_checks_report(names: readonly string[]): string {
+    if (names.length === 0) {
+        return '';
+    }
+    const lines: string[] = ['', 'Failing check(s):'];
+    for (const name of names) {
+        lines.push(`  ❌ ${name}`);
+    }
+    if (names.includes('Release-PR shape detector')) {
+        lines.push(
+            '',
+            'Release-PR shape: a release PR may only contain the version-bump',
+            'allowlist. Land the out-of-shape files on main via their own PR, then',
+            'merge main into the release branch — their release-PR diff becomes',
+            'empty (docs/contracts/release-pr-gating.md § Mid-release fixes).',
+        );
+    }
+    lines.push('', 'After fixing, resume with: task release -- --resume --yes', '');
+    return lines.join('\n');
+}
+
 /**
  * Watch PR checks and tolerate the 'no checks' case.
  *
@@ -606,6 +667,15 @@ function watch_pr_checks(): void {
     if (output) {
         process.stderr.write(output + '\n');
     }
+    const summary = spawnSync('gh', ['pr', 'checks', '--json', 'name,bucket'], {
+        cwd: REPO_ROOT,
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    const report = _failed_checks_report(_failed_check_names(summary.stdout ?? ''));
+    if (report) {
+        process.stderr.write(report + '\n');
+    }
     die(`PR checks failed (exit ${returncode})`);
 }
 
@@ -1064,6 +1134,34 @@ function set_package_version(p: string, version: string): void {
     fs.writeFileSync(p, jsonDumpsIndent(data, 4) + '\n', 'utf-8');
 }
 
+/**
+ * Update BOTH version fields npm keeps in a lockfile — the top-level one and
+ * the root package entry (`packages[""]`).
+ *
+ * The bump previously touched package.json and left the lock behind, so every
+ * release shipped a `main` whose two files disagreed and every subsequent
+ * local `npm install` produced a spurious modification (measured 2026-08-02:
+ * package.json 9.13.0 vs package-lock.json 9.12.0). Rewriting the two fields
+ * rather than shelling out to `npm install --package-lock-only` keeps the bump
+ * offline and cannot re-resolve a dependency mid-release.
+ * road-to-gates-that-can-fail Phase 5.
+ */
+function set_lockfile_version(p: string, version: string): void {
+    if (!fs.existsSync(p)) {
+        return;
+    }
+    const data = JSON.parse(fs.readFileSync(p, 'utf-8')) as Record<string, unknown>;
+    data['version'] = version;
+    const packages = data['packages'];
+    if (typeof packages === 'object' && packages !== null && !Array.isArray(packages)) {
+        const root = (packages as Record<string, unknown>)[''];
+        if (typeof root === 'object' && root !== null && !Array.isArray(root)) {
+            (root as Record<string, unknown>)['version'] = version;
+        }
+    }
+    fs.writeFileSync(p, jsonDumpsIndent(data, 4) + '\n', 'utf-8');
+}
+
 /** Update `metadata.version`; preserve 2-space indentation + UTF-8. */
 function set_marketplace_version(p: string, version: string): void {
     const data = JSON.parse(fs.readFileSync(p, 'utf-8')) as Record<string, unknown>;
@@ -1442,8 +1540,13 @@ function execute(
         if (resume && current_pkg === plan.target) {
             _step(2, total, `Files already at ${plan.target} — skip bump`);
         } else {
-            _step(2, total, 'Bump package.json + marketplace.json + template pin, prepend CHANGELOG');
+            _step(
+                2,
+                total,
+                'Bump package.json + package-lock.json + marketplace.json + template pin, prepend CHANGELOG',
+            );
             set_package_version(PACKAGE_JSON, plan.target);
+            set_lockfile_version(PACKAGE_LOCK_JSON, plan.target);
             set_marketplace_version(MARKETPLACE_JSON, plan.target);
             set_template_pin(PROJECT_TEMPLATE, plan.target);
             prepend_changelog(CHANGELOG, plan.changelog_entry);
@@ -2135,6 +2238,7 @@ export {
     _cap_body,
     prepend_changelog,
     set_package_version,
+    set_lockfile_version,
     set_marketplace_version,
     set_template_pin,
     resolve_bump,

package/src/scripts/router_target_paths.d.mts

@@ -0,0 +1,4 @@
+/** Type declarations for router_target_paths.mjs (the shared kind→path table). */
+export declare const ROUTE_TARGET_TEMPLATES: Readonly<Record<string, readonly string[]>>;
+export declare function parseRouteTarget(target: string): { kind: string; id: string } | null;
+export declare function routeTargetPathsPosix(target: string): string[];

package/src/scripts/router_target_paths.mjs

@@ -0,0 +1,69 @@
+/**
+ * router_target_paths.mjs — the ONE kind→path table for `dist/router.json`
+ * `routes_to` targets.
+ *
+ * Two consumers read it and they must not disagree:
+ *   * `src/scripts/_cli/cmd_conformance.ts::routeTargetPaths` — resolves a
+ *     pointer against the INSTALLED package tree at runtime.
+ *   * `src/scripts/prepack-check.mjs` gate 4 — asserts the same pointer lands
+ *     inside the `files[]` whitelist BEFORE the tarball is built.
+ *
+ * A copied table would let one side ship a target the other cannot see, which
+ * is exactly the packaging↔runtime gap the pack gate exists to close
+ * (road-to-gates-that-can-fail Phase 4). Plain `.mjs` because `prepack-check`
+ * runs as raw Node during the npm lifecycle and cannot load TypeScript; the
+ * TS side reads the sibling `router_target_paths.d.mts` declarations. Same
+ * shape as `prepack_lifecycle_check.mjs`.
+ *
+ * Templates are POSIX-relative with a single `{id}` placeholder. Callers that
+ * need platform separators split on `/` and `path.join` the segments.
+ */
+
+/**
+ * Candidate homes per target kind, in resolution order — the FIRST existing
+ * candidate wins.
+ *
+ * `contract:` has two legitimate homes in the shipped tree: the public
+ * contract pages under `docs/contracts/` (per the rule-router contract) and
+ * the agent-facing contract contexts under
+ * `dist/agent-src/contexts/contracts/` (e.g. artifact-engagement-flow).
+ */
+export const ROUTE_TARGET_TEMPLATES = Object.freeze({
+    skill: Object.freeze(['dist/agent-src/skills/{id}/SKILL.md']),
+    command: Object.freeze(['dist/agent-src/commands/{id}.md']),
+    guideline: Object.freeze(['docs/guidelines/{id}.md']),
+    contract: Object.freeze([
+        'docs/contracts/{id}.md',
+        'dist/agent-src/contexts/contracts/{id}.md',
+    ]),
+});
+
+/**
+ * Split a `<kind>:<id>` target. Returns `null` for a malformed target (no
+ * colon, empty kind, empty id, or an unknown kind).
+ *
+ * @param {string} target
+ * @returns {{ kind: string, id: string } | null}
+ */
+export function parseRouteTarget(target) {
+    const sep = target.indexOf(':');
+    if (sep <= 0) return null;
+    const kind = target.slice(0, sep);
+    const id = target.slice(sep + 1);
+    if (!id) return null;
+    if (!Object.prototype.hasOwnProperty.call(ROUTE_TARGET_TEMPLATES, kind)) return null;
+    return { kind, id };
+}
+
+/**
+ * POSIX package-relative candidate paths for one `routes_to` target.
+ * Empty array = the target is unparseable or its kind is unknown.
+ *
+ * @param {string} target
+ * @returns {string[]}
+ */
+export function routeTargetPathsPosix(target) {
+    const parsed = parseRouteTarget(target);
+    if (parsed === null) return [];
+    return ROUTE_TARGET_TEMPLATES[parsed.kind].map((tpl) => tpl.replace('{id}', parsed.id));
+}