@event4u/agent-config 9.11.0 → 9.12.0

package/src/scripts/_lib/global_deploy_inventory.ts

@@ -254,6 +254,13 @@ function json_string_ascii(s: string): string {
   return out;
 }
 
+/**
+ * Predicate over a SOURCE file path — `true` = the file arrives in the install.
+ * Identical shape to `PlanSource.fileFilter` (`src/install/plan.ts`), so the
+ * plan path and the deploy path can share one predicate instance.
+ */
+export type FileFilter = (srcFile: string) => boolean;
+
 /**
  * Anchor-relative paths the deploy of `src` → `<anchor>/<dest_rel>` maintains
  * — written OR skipped-as-identical.
@@ -262,8 +269,20 @@ function json_string_ascii(s: string): string {
  * symlinked files resolve to file entries, symlinked subdirectories are walked
  * through their resolved targets. `dest_rel` may be empty (`""`) for plan
  * entries that deploy into the anchor root.
+ *
+ * `file_filter` MUST be the same predicate the copy was given. This set is what
+ * the reaper treats as "should exist"; a file the copy skipped but this set
+ * still lists is never reaped, and a file this set omits while the copy wrote it
+ * is deleted on the next deploy. Passing the filter to one and not the other is
+ * the failure mode the rule-scoping work exists to avoid — see
+ * `install._deploy_global_content`, which derives one filter and hands it to
+ * both.
  */
-export function expected_deploy_files(src: string, dest_rel: string): Set<string> {
+export function expected_deploy_files(
+  src: string,
+  dest_rel: string,
+  file_filter: FileFilter | null = null,
+): Set<string> {
   const out = new Set<string>();
   let src_stat: fs.Stats;
   try {
@@ -273,6 +292,9 @@ export function expected_deploy_files(src: string, dest_rel: string): Set<string
     return out;
   }
   if (!src_stat.isDirectory()) {
+    if (file_filter !== null && !file_filter(src)) {
+      return out;
+    }
     out.add(as_posix(dest_rel));
     return out;
   }
@@ -298,6 +320,12 @@ export function expected_deploy_files(src: string, dest_rel: string): Set<string
         _walk(fs.realpathSync(entry), rel);
         continue;
       }
+      // The predicate sees the SOURCE path, never `rel`: the rule-scope
+      // predicate reads the file's own frontmatter tags, so a dest-relative
+      // path would not resolve. Same contract as the copy twin.
+      if (file_filter !== null && !file_filter(entry)) {
+        continue;
+      }
       out.add(as_posix(rel));
     }
   };
@@ -554,7 +582,15 @@ function prune_empty_dirs(prune_candidates: Set<string>, anchor_resolved: string
 }
 
 /** `anchor in node.parents` — is `anchor` a strict ancestor of `node`? */
-function is_ancestor(anchor: string, node: string): boolean {
+/**
+ * Is `node` strictly inside `anchor`? Pure path arithmetic, no I/O — callers
+ * pass already-resolved (realpath'd) paths when symlink escape matters.
+ *
+ * Exported for `install._copy_dir_dereferencing_symlinks`, which must reject a
+ * symlink whose target leaves the package root. One definition rather than a
+ * second copy of the `path.relative` idiom.
+ */
+export function is_ancestor(anchor: string, node: string): boolean {
   const rel = path.relative(anchor, node);
   return rel !== "" && !rel.startsWith("..") && !path.isAbsolute(rel);
 }

package/src/scripts/check_installer_import_purity.ts

@@ -0,0 +1,295 @@
+#!/usr/bin/env tsx
+/**
+ * Guard against a maintainer-only CLI being bundled into the consumer installer.
+ *
+ * ## The incident this exists to prevent (road-to-consistent-rule-scoping, 2026-07-31)
+ *
+ * `src/install/rule_scope.ts` imported the rule-scoping predicate from
+ * `src/scripts/condense.ts` — deliberately, so install semantics could not drift
+ * from projection semantics. Correct intent. But `condense.ts` is maintainer CLI
+ * tooling that ends in a module-level self-invoke:
+ *
+ *     const isMain = _isCliEntry();
+ *     if (isMain) { process.exit(main()); }
+ *
+ * `_isCliEntry()` compares `import.meta.url` against `process.argv[1]`. That is
+ * right for a file run directly — and wrong once esbuild BUNDLES the module,
+ * because `import.meta.url` then resolves to the BUNDLE's own URL, which *is*
+ * `argv[1]` when a consumer runs `node dist/install/install.mjs`. The guard
+ * fired inside the installer, `condense.main()` ran, found no maintainer source
+ * tree in a consumer checkout, printed "No source directory found" and called
+ * `process.exit(1)` — killing the install AFTER the payload had already synced.
+ *
+ * All four `smoke-public-install` legs went red. Nothing caught it earlier:
+ * `prepack-check` verifies that imports resolve to SHIPPED paths (they did),
+ * the bundle-freshness gate only byte-diffs the rebuilt output, and the
+ * behavioural smoke test only runs post-push in its own workflow.
+ *
+ * ## What this checks
+ *
+ * The transitive relative-import closure of the installer bundle entry must
+ * contain NO module-level `process.exit(` outside the entry itself.
+ *
+ * "Module-level" is decided structurally, not textually: the AST walk descends
+ * through top-level statements and nested blocks/ifs/try but STOPS at any
+ * function, method, class, arrow or accessor body. So
+ * `function main() { process.exit(1) }` is fine — it only runs when called —
+ * while `if (isMain) { process.exit(main()) }` is not, because importing the
+ * module runs it.
+ *
+ * The entry module is exempt: it IS the CLI, and its own exit is the point.
+ *
+ * ## Why this shape and not the alternatives
+ *
+ * - **Not a string scan of the built bundle.** That reports a mystery literal
+ *   with no cause. This reports the import CHAIN
+ *   (`install.ts → rule_scope.ts → condense.ts`), which is the actionable fact.
+ * - **Not "forbid importing condense.ts".** A denylist of one file rots the
+ *   moment a second CLI module grows an entry guard. The hazard is the
+ *   module-level exit, so that is what is detected.
+ * - **Runs on SOURCE, so it needs no build.** It fails in `task ci` before a
+ *   push instead of on four CI legs after one.
+ *
+ * Exit 0 clean, 1 on any finding. No network, no build, no spend.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import ts from 'typescript';
+
+const _HERE = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(_HERE, '..', '..');
+
+/**
+ * Bundle entry points that ship to consumers as a single file.
+ *
+ * Keep in sync with the `build:*bundle` scripts in package.json. Each entry is
+ * exempt from the check for its own module-level exit — it is the CLI.
+ */
+const BUNDLE_ENTRIES: readonly string[] = [
+    'src/scripts/install.ts', // → dist/install/install.mjs (build:install-bundle)
+];
+
+interface Finding {
+    /** The offending module, repo-relative POSIX. */
+    readonly module: string;
+    /** 1-indexed line of the offending call. */
+    readonly line: number;
+    /** How the entry reaches it, entry first. */
+    readonly chain: readonly string[];
+}
+
+function toPosix(p: string): string {
+    return p.split(path.sep).join('/');
+}
+
+function relToRepo(abs: string, root: string = REPO_ROOT): string {
+    return toPosix(path.relative(root, abs));
+}
+
+/**
+ * Resolve a relative import specifier to a source file on disk.
+ *
+ * The codebase imports with `.js` extensions (NodeNext) while the sources are
+ * `.ts`, so try the TypeScript twin first, then the literal path, then an
+ * `index` file. Returns `null` for anything unresolvable — a bare package
+ * specifier, a type-only path that no longer exists, or a `.json` asset.
+ */
+function resolveImport(fromFile: string, specifier: string): string | null {
+    if (!specifier.startsWith('.')) return null;
+    const base = path.resolve(path.dirname(fromFile), specifier);
+    const candidates = [
+        base.replace(/\.js$/, '.ts'),
+        base.replace(/\.js$/, '.tsx'),
+        base,
+        `${base}.ts`,
+        path.join(base, 'index.ts'),
+    ];
+    for (const c of candidates) {
+        try {
+            if (fs.statSync(c).isFile()) return c;
+        } catch {
+            // next candidate
+        }
+    }
+    return null;
+}
+
+/** Relative import specifiers declared by `source`, in source order. */
+function importSpecifiers(source: ts.SourceFile): string[] {
+    const out: string[] = [];
+    const visit = (node: ts.Node): void => {
+        if (
+            (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&
+            node.moduleSpecifier !== undefined &&
+            ts.isStringLiteral(node.moduleSpecifier)
+        ) {
+            out.push(node.moduleSpecifier.text);
+        } else if (
+            ts.isCallExpression(node) &&
+            node.expression.kind === ts.SyntaxKind.ImportKeyword &&
+            node.arguments.length > 0 &&
+            ts.isStringLiteral(node.arguments[0] as ts.Node)
+        ) {
+            // A dynamic import() is still bundled by esbuild unless code-split,
+            // so it carries the same hazard as a static one.
+            out.push((node.arguments[0] as ts.StringLiteral).text);
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(source, visit);
+    return out;
+}
+
+/** True for nodes whose body only runs when called — the walk stops here. */
+function isDeferredScope(node: ts.Node): boolean {
+    return (
+        ts.isFunctionDeclaration(node) ||
+        ts.isFunctionExpression(node) ||
+        ts.isArrowFunction(node) ||
+        ts.isMethodDeclaration(node) ||
+        ts.isConstructorDeclaration(node) ||
+        ts.isGetAccessorDeclaration(node) ||
+        ts.isSetAccessorDeclaration(node) ||
+        ts.isClassDeclaration(node) ||
+        ts.isClassExpression(node)
+    );
+}
+
+/** Is `node` a `process.exit(...)` call? */
+function isProcessExitCall(node: ts.Node): boolean {
+    if (!ts.isCallExpression(node)) return false;
+    const callee = node.expression;
+    if (!ts.isPropertyAccessExpression(callee)) return false;
+    return (
+        ts.isIdentifier(callee.expression) &&
+        callee.expression.text === 'process' &&
+        callee.name.text === 'exit'
+    );
+}
+
+/**
+ * 1-indexed lines of every `process.exit(` that executes at MODULE LOAD.
+ *
+ * Descends through statement-level structure (blocks, if/else, try/catch/finally,
+ * loops, labels) and stops at any deferred scope, so a call inside a function is
+ * not reported while one inside a top-level `if` is.
+ */
+function moduleLevelExitLines(source: ts.SourceFile): number[] {
+    const lines: number[] = [];
+    const visit = (node: ts.Node): void => {
+        if (isDeferredScope(node)) return;
+        if (isProcessExitCall(node)) {
+            lines.push(source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1);
+        }
+        ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(source, visit);
+    return lines;
+}
+
+function parse(file: string): ts.SourceFile | null {
+    let text: string;
+    try {
+        text = fs.readFileSync(file, 'utf-8');
+    } catch {
+        return null;
+    }
+    return ts.createSourceFile(file, text, ts.ScriptTarget.ESNext, true);
+}
+
+/**
+ * Walk one entry's closure; return every module-level exit found below it.
+ *
+ * `root` defaults to the repo; tests pass a fixture tree so the chain-reporting
+ * itself is covered, not only the per-file detector.
+ */
+function auditEntry(entryRel: string, root: string = REPO_ROOT): Finding[] {
+    const entryAbs = path.join(root, entryRel);
+    if (!fs.existsSync(entryAbs)) {
+        process.stderr.write(
+            `check-installer-import-purity: entry ${entryRel} does not exist — ` +
+                'update BUNDLE_ENTRIES\n',
+        );
+        process.exitCode = 1;
+        return [];
+    }
+    const findings: Finding[] = [];
+    const seen = new Set<string>([entryAbs]);
+    // BFS so the reported chain is a shortest path — the least confusing one.
+    const queue: Array<{ file: string; chain: string[] }> = [
+        { file: entryAbs, chain: [entryRel] },
+    ];
+    while (queue.length > 0) {
+        const { file, chain } = queue.shift() as { file: string; chain: string[] };
+        const source = parse(file);
+        if (source === null) continue;
+
+        // The entry is the CLI; its own module-level exit is intended.
+        if (file !== entryAbs) {
+            for (const line of moduleLevelExitLines(source)) {
+                findings.push({ module: relToRepo(file, root), line, chain });
+            }
+        }
+
+        for (const spec of importSpecifiers(source)) {
+            const target = resolveImport(file, spec);
+            if (target === null || seen.has(target)) continue;
+            seen.add(target);
+            queue.push({ file: target, chain: [...chain, relToRepo(target, root)] });
+        }
+    }
+    return findings;
+}
+
+function main(): number {
+    const all: Finding[] = [];
+    for (const entry of BUNDLE_ENTRIES) {
+        all.push(...auditEntry(entry));
+    }
+    if (all.length === 0) {
+        process.stdout.write(
+            `✅  installer import purity: ${BUNDLE_ENTRIES.length} bundle entr` +
+                `${BUNDLE_ENTRIES.length === 1 ? 'y' : 'ies'} reach no module-level ` +
+                'process.exit()\n',
+        );
+        return 0;
+    }
+    process.stdout.write('❌  installer import purity — module-level process.exit() reachable:\n');
+    for (const f of all) {
+        process.stdout.write(`\n    ${f.module}:${f.line}\n`);
+        process.stdout.write(`      reached via: ${f.chain.join(' → ')}\n`);
+    }
+    process.stdout.write(
+        '\n  Why this fails the build: esbuild bundles the whole closure into\n' +
+            '  dist/install/install.mjs. A module-level process.exit() then runs when a\n' +
+            '  CONSUMER loads the installer — and a CLI entry guard comparing\n' +
+            '  import.meta.url to process.argv[1] evaluates TRUE inside a bundle, because\n' +
+            '  the bundle IS argv[1].\n\n' +
+            '  Fix: move the code the installer actually needs into a module with no CLI\n' +
+            '  entry and no top-level exit, and let the CLI re-export it. Do NOT relax\n' +
+            '  this gate — the failure it prevents kills a consumer install after the\n' +
+            '  payload has already been written.\n',
+    );
+    return 1;
+}
+
+const _isCliEntry = (): boolean => {
+    if (process.argv[1] === undefined) return false;
+    try {
+        return (
+            fs.realpathSync(fileURLToPath(import.meta.url)) ===
+            fs.realpathSync(path.resolve(process.argv[1]))
+        );
+    } catch {
+        return false;
+    }
+};
+
+if (_isCliEntry()) {
+    process.exit(main());
+}
+
+export { auditEntry, moduleLevelExitLines, BUNDLE_ENTRIES };

package/src/scripts/condense.ts

@@ -238,6 +238,13 @@ function _stripChars(s: string, chars: string): string {
 // the repo root.
 // =============================================================================
 
+// road-to-consistent-rule-scoping: the predicate moved to a side-effect-free
+// module so the consumer installer can import it WITHOUT pulling this file's
+// module-level CLI self-invoke into its bundle. Re-exported here because four
+// in-repo consumers import it from `condense.js`.
+export { rule_in_scope } from '../install/ruleInScope.js';
+import { rule_in_scope } from '../install/ruleInScope.js';
+
 const _HERE = path.dirname(fileURLToPath(import.meta.url)); // <repo>/src/scripts
 const _DEFAULT_PROJECT_ROOT = path.resolve(_HERE, '..', '..');
 
@@ -1014,34 +1021,6 @@ function _read_rule_packs(): string[] | null {
  * `null` (no role filtering), so every existing 2- and 3-arg call site
  * compiles and behaves unchanged.
  */
-export function rule_in_scope(
-    source_path: string,
-    scope: readonly string[] | null,
-    pack_scope: readonly string[] | null = null,
-    role_scope: readonly string[] | null = null,
-): boolean {
-    if (scope === null && pack_scope === null && role_scope === null) {
-        return true;
-    }
-    const [meta] = _parse_frontmatter(_readText(source_path));
-    if (meta['type'] === 'always' || meta['alwaysApply'] === true) {
-        return true; // kernel always projects
-    }
-    const axis = (key: string, configured: readonly string[] | null): boolean => {
-        if (configured === null) {
-            return true;
-        }
-        const values = Array.isArray(meta[key])
-            ? (meta[key] as unknown[]).map((w) => String(w))
-            : [];
-        if (values.length === 0) {
-            return true; // untagged → fail safe: ship it
-        }
-        return values.some((v) => configured.includes(v));
-    };
-    return axis('workspaces', scope) && axis('packs', pack_scope) && axis('roles', role_scope);
-}
-
 /** List rule basenames under RULES_SOURCE, workspace/pack scope applied. */
 function _scoped_rule_basenames(): string[] {
     const scope = _read_rule_workspaces();

package/src/scripts/install-hooks.sh

@@ -51,6 +51,27 @@ else
     fi
 fi
 
+# road-to-local-ci-trust Phase 2: the CI-only repo-content gates, as one task.
+# Deliberately placed AFTER the consistency block above — `task consistency`
+# runs `task sync`, which generates the `.augment/` projection. Several
+# preflight gates read that tree, so on a FRESH worktree (this repo's standard
+# workflow) running preflight first would fail with "produced by regeneration
+# but absent before" — red for a reason the contributor did not cause, which is
+# exactly the anti-pattern this gate set exists to avoid. Measured 15s against
+# the 25s `pre_push_budget_seconds` ceiling in src/config/ci-local-parity.yml.
+# `check_enforcement_coverage` (30.7s) stays out of preflight by design.
+echo "🔍 Preflight — the CI-only repo-content gates..."
+if [ "${AGENT_CONFIG_SKIP_PREPUSH_PREFLIGHT:-}" = "1" ]; then
+    echo "⏭️  skipped via AGENT_CONFIG_SKIP_PREPUSH_PREFLIGHT=1"
+elif ! command -v task >/dev/null 2>&1; then
+    echo "⚠️  'task' not found — skipping preflight for this push."
+elif ! task preflight; then
+    echo "❌  Preflight failed. These gates run in CI too, so pushing now buys a"
+    echo "    red run and a fixup re-push. Fix the failures above, or"
+    echo "    AGENT_CONFIG_SKIP_PREPUSH_PREFLIGHT=1 for a genuine WIP push."
+    exit 1
+fi
+
 echo "🔍 Checking for leftover conflict markers / unmerged paths..."
 if ! ./scripts-run src/scripts/check_no_conflict_markers --quiet; then
     echo "❌  Conflict markers or unmerged paths present. Resolve them (e.g. 'git checkout HEAD -- <file>' or finish the merge), then re-push."
@@ -127,11 +148,22 @@ if git diff --cached --name-only | grep -qE '^agents/roadmaps(-progress\.md|/)';
     ./scripts-run .augment/scripts/update_roadmap_progress --check
     rstatus=$?
     if [ $rstatus -ne 0 ]; then
+        # The check fails for THREE distinct reasons and prints the real one
+        # above: a stale dashboard, an unresolved `[~]` deferred item (Iron
+        # Law 3), or a completed-but-unarchived roadmap. Naming only the first
+        # sent a maintainer chasing a regeneration that was already correct —
+        # and a safety gate whose text points at the wrong cause trains people
+        # to distrust the gate, which costs more than the wrong message.
         echo ""
-        echo "❌  Commit blocked — agents/roadmaps-progress.md is stale."
-        echo "   Run './agent-config roadmap:progress' (or"
-        echo "   './scripts-run .augment/scripts/update_roadmap_progress'),"
-        echo "   stage agents/roadmaps-progress.md, then re-commit."
+        echo "❌  Commit blocked — the roadmap dashboard gate failed."
+        echo "   The cause is printed above. The three it reports:"
+        echo "     · dashboard stale      → './agent-config roadmap:progress',"
+        echo "                               then stage agents/roadmaps-progress.md"
+        echo "     · Iron Law 3           → unresolved '[~]' deferred items. Surface"
+        echo "                               them and ask the user; NOT the agent's"
+        echo "                               to clear (roadmap-management § 4b)"
+        echo "     · completed roadmap    → 'git mv' it into agents/roadmaps/archive/,"
+        echo "                               then regenerate"
         echo "   To bypass for an unrelated WIP commit: git commit --no-verify"
         exit 1
     fi