@event4u/agent-config 9.14.0 → 9.16.0

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.
  *
@@ -573,13 +634,16 @@ function git(args: readonly string[], opts: { capture?: boolean } = {}): string
  * A short grace period gives GitHub time to register workflow runs on a
  * freshly-pushed branch.
  */
-function watch_pr_checks(): void {
+function watch_pr_checks(branch: string): void {
     // time.sleep(5) — blocking grace period. Never reached on any test path.
     const until = Date.now() + 5000;
     while (Date.now() < until) {
         // busy-wait stand-in for time.sleep(5) without an event-loop yield.
     }
-    const proc = spawnSync('gh', ['pr', 'checks', '--watch'], {
+    // The branch is passed explicitly — `gh` inferring the PR from HEAD
+    // resolved to `main` mid-run once (2026-08-03, 9.16.0 resume) and the
+    // whole release died on "no pull requests found for branch main".
+    const proc = spawnSync('gh', ['pr', 'checks', branch, '--watch'], {
         cwd: REPO_ROOT,
         encoding: 'utf-8',
         stdio: ['ignore', 'pipe', 'pipe'],
@@ -606,9 +670,117 @@ function watch_pr_checks(): void {
     if (output) {
         process.stderr.write(output + '\n');
     }
+    const summary = spawnSync('gh', ['pr', 'checks', branch, '--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})`);
 }
 
+/**
+ * Push the release branch, integrating a remote that moved under us.
+ *
+ * A GitHub-side "Update branch" click (or a concurrent resume run) advances
+ * `origin/<branch>` while the local ref stays behind; a bare `git push` is
+ * then rejected with "fetch first" and the whole release run dies (measured
+ * 2026-08-03, 9.15.0). Same-branch commits are never ours to drop, so the
+ * recovery is merge-and-retry, never force-push.
+ */
+function push_release_branch(branch: string): void {
+    const first = run(['git', 'push', '-u', REMOTE, branch], { check: false });
+    if (first.returncode === 0) {
+        return;
+    }
+    process.stdout.write(`↻  ${REMOTE}/${branch} moved — integrating and retrying push\n`);
+    run(['git', 'fetch', REMOTE, branch]);
+    run(['git', 'merge', '--no-edit', `${REMOTE}/${branch}`]);
+    run(['git', 'push', '-u', REMOTE, branch]);
+}
+
+/** mergeStateStatus of the branch's PR ('' when the probe fails). */
+function _pr_merge_state(branch: string): string {
+    const r = run(
+        ['gh', 'pr', 'view', branch, '--json', 'mergeStateStatus', '--jq', '.mergeStateStatus'],
+        {
+            check: false,
+            capture: true,
+        },
+    );
+    return r.returncode === 0 ? r.stdout.trim() : '';
+}
+
+/**
+ * Bound on update-and-retry rounds in merge_release_pr. Three is deliberate:
+ * main receiving unrelated merges three times inside one checks-wait window
+ * means the queue is hot and a human should decide, not a loop.
+ */
+const _MERGE_UPDATE_ROUNDS = 3;
+
+/**
+ * Merge the release PR, absorbing a moving base branch.
+ *
+ * Branch protection requires the head to be up to date with `main`, and
+ * `main` moves constantly (dependabot, unrelated merges) — so between the
+ * checks-wait and the merge the PR routinely flips to BEHIND and a bare
+ * `gh pr merge` dies with "the head branch is not up to date with the base
+ * branch" (measured 2026-08-03, 9.16.0). Recovery is mechanical and safe by
+ * construction: merging `origin/main` into `release/X.Y.Z` makes the fix
+ * files identical on both sides, so the release-PR diff stays inside the
+ * version-bump allowlist (docs/contracts/release-pr-gating.md § Mid-release
+ * fixes) — do it here instead of aborting the run.
+ */
+function merge_release_pr(branch: string, wait_for_checks: boolean): void {
+    if (git(['rev-parse', '--abbrev-ref', 'HEAD'], { capture: true }) !== branch) {
+        run(['git', 'checkout', branch]);
+    }
+    for (let round = 0; round <= _MERGE_UPDATE_ROUNDS; round++) {
+        if (_pr_merge_state(branch) !== 'BEHIND') {
+            const merged = run(['gh', 'pr', 'merge', branch, '--merge', '--delete-branch'], {
+                check: false,
+            });
+            if (merged.returncode === 0) {
+                return;
+            }
+            if (_pr_merge_state(branch) !== 'BEHIND') {
+                // Not the moving-base failure — surface it unchanged.
+                throw new CalledProcessError(merged.returncode, [
+                    'gh',
+                    'pr',
+                    'merge',
+                    branch,
+                    '--merge',
+                    '--delete-branch',
+                ]);
+            }
+            // BEHIND appeared between the probe and the merge — fall through
+            // to the update below.
+        }
+        if (round === _MERGE_UPDATE_ROUNDS) {
+            break;
+        }
+        process.stdout.write(
+            `↻  head behind ${MAIN_BRANCH} (update round ${round + 1}/${_MERGE_UPDATE_ROUNDS}) — ` +
+                `merging ${REMOTE}/${MAIN_BRANCH} into ${branch} and re-running checks\n`,
+        );
+        run(['git', 'fetch', REMOTE, MAIN_BRANCH]);
+        run(['git', 'merge', '--no-edit', `${REMOTE}/${MAIN_BRANCH}`]);
+        push_release_branch(branch);
+        if (wait_for_checks) {
+            watch_pr_checks(branch);
+        }
+    }
+    die(
+        `release PR is still behind ${MAIN_BRANCH} after ${_MERGE_UPDATE_ROUNDS} update round(s) — ` +
+            `${MAIN_BRANCH} is moving faster than the checks complete. ` +
+            'Re-run when the queue quiets down: task release -- --resume --yes',
+    );
+}
+
 function have(bin: string): boolean {
     const res = spawnSync('which', [bin], { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
     if (res.error) {
@@ -1064,6 +1236,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 +1642,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);
@@ -1493,9 +1698,10 @@ function execute(
         _step(4, total, 'PR already merged — skip push');
     } else {
         // `git push -u` is naturally idempotent — it prints "Everything
-        // up-to-date" when remote already matches. No probe needed.
+        // up-to-date" when remote already matches. push_release_branch
+        // additionally absorbs a remote that moved under us.
         _step(4, total, `Push ${branch} to ${REMOTE}`);
-        run(['git', 'push', '-u', REMOTE, branch]);
+        push_release_branch(branch);
     }
 
     // ─── 5. PR ──────────────────────────────────────────────────────────────
@@ -1534,7 +1740,7 @@ function execute(
         _step(6, total, 'PR already merged — skip checks wait');
     } else if (wait_for_checks) {
         _step(6, total, 'Wait for PR checks');
-        watch_pr_checks();
+        watch_pr_checks(branch);
     } else {
         _step(6, total, 'Skip waiting for checks (--no-wait)');
     }
@@ -1544,7 +1750,7 @@ function execute(
         _step(7, total, `PR #${pr_info!['number']} already merged — skip`);
     } else {
         _step(7, total, 'Merge pull request (merge commit) and delete branch');
-        run(['gh', 'pr', 'merge', '--merge', '--delete-branch']);
+        merge_release_pr(branch, wait_for_checks);
     }
 
     // ─── 8. tag main + push tag ─────────────────────────────────────────────
@@ -2135,6 +2341,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));
+}

package/src/scripts/router_telemetry.ts

@@ -183,6 +183,57 @@ function _fnmatch(name: string, pat: string): boolean {
 // ── Trigger matching ─────────────────────────────────────────────────────
 
 /** Apply one trigger to a prompt + context; return True on match. */
+/** Unicode word character — letters, digits, underscore (incl. umlauts). */
+const _WORD_CHAR = /[\p{L}\p{N}_]/u;
+
+function _isWordChar(c: string | undefined): boolean {
+  return c !== undefined && _WORD_CHAR.test(c);
+}
+
+/**
+ * Word-boundary-anchored keyword match (road-to-tested-routing Phase 3).
+ *
+ * A `keyword` occurrence counts only when its word-character edges sit on
+ * word boundaries: `ac` no longer fires inside "black", `plan` no longer
+ * fires inside "planet". Two deliberate reliefs:
+ *
+ * - An edge that is itself a NON-word character (e.g. `__()`, `/image:`,
+ *   `trans(`, an emoji) carries no boundary requirement on that side —
+ *   punctuation-shaped keywords keep their exact substring semantics.
+ * - The right boundary accepts one optional plural `s` ("icons", "options",
+ *   "secrets" still fire their singular keyword). Richer inflection (German
+ *   verb endings: "implementiere", "committen") is a DOCUMENTED accepted
+ *   recall cost of anchoring — the matrices carry standalone-token phrasings
+ *   for those languages instead.
+ *
+ * `phrase` deliberately stays unanchored substring; since this change the
+ * two trigger kinds genuinely differ.
+ */
+export function keyword_matches_anchored(prompt_lower: string, kw_lower: string): boolean {
+  if (kw_lower === "") {
+    return false;
+  }
+  const needLeft = _isWordChar(kw_lower[0]);
+  const needRight = _isWordChar(kw_lower[kw_lower.length - 1]);
+  let idx = prompt_lower.indexOf(kw_lower);
+  while (idx !== -1) {
+    const leftOk = !needLeft || !_isWordChar(prompt_lower[idx - 1]);
+    let rightOk = true;
+    if (needRight) {
+      let end = idx + kw_lower.length;
+      if (prompt_lower[end] === "s") {
+        end += 1; // optional plural `s`
+      }
+      rightOk = !_isWordChar(prompt_lower[end]);
+    }
+    if (leftOk && rightOk) {
+      return true;
+    }
+    idx = prompt_lower.indexOf(kw_lower, idx + 1);
+  }
+  return false;
+}
+
 export function trigger_matches(
   trigger: Trigger,
   prompt: string,
@@ -191,7 +242,7 @@ export function trigger_matches(
 ): boolean {
   const prompt_lower = prompt.toLowerCase();
   if ("keyword" in trigger) {
-    return prompt_lower.includes(String(trigger["keyword"]).toLowerCase());
+    return keyword_matches_anchored(prompt_lower, String(trigger["keyword"]).toLowerCase());
   }
   if ("phrase" in trigger) {
     return prompt_lower.includes(String(trigger["phrase"]).toLowerCase());