dev-loops 0.2.7 → 0.3.0

package/scripts/README.md

@@ -68,16 +68,17 @@ Failure behavior:
 - malformed arguments, invalid JSON, and `gh` failures emit `{ "ok": false, "error": "..." }` on stderr and exit non-zero
 - live capture is only allowed when both `--repo` and `--pr` are present
 
-### `scripts/github/create-draft-pr.mjs`
+### `scripts/github/create-pr.mjs`
 
-Thin wrapper around `gh pr create` for draft-first PR creation.
+Canonical wrapper around `gh pr create`. Every PR opened through this tool is ALWAYS a draft and is always assigned — self-assigned by default (`--assignee @me` when none is given), while still honoring an explicit `--assignee <login>`. Never call raw `gh pr create` to open a PR. (`dev-loops pr create` dispatches here; the legacy `dev-loops pr create-draft` subcommand still works as a deprecated alias.)
 
 Usage:
-- `node scripts/github/create-draft-pr.mjs [gh pr create args...]`
-- `node <resolved-skill-scripts>/github/create-draft-pr.mjs [gh pr create args...]`
+- `node scripts/github/create-pr.mjs [gh pr create args...]`
+- `node <resolved-skill-scripts>/github/create-pr.mjs [gh pr create args...]`
 
 Contract:
-- injects exactly one `--draft` when the caller did not already supply it
+- injects exactly one `--draft` when the caller did not already supply it (draft is the only mode)
+- self-assigns by default (defaults `--assignee @me` when no `--assignee` is provided); honors an explicit `--assignee <login>` when one is given
 - rejects `--ready` before invoking `gh`; use `gh pr ready` later after draft-gate approval
 - forwards every other argument to `gh pr create` unchanged and in order
 - preserves the underlying `gh pr create` stdout, stderr, and exit code without wrapping success output

package/scripts/_core-helpers.mjs

@@ -19,6 +19,7 @@ export {
   normalizeTimestamp,
   parseGateReviewCommentBody,
   parseGateReviewCommentMarkerBody,
+  resolveDraftGateRoundResetMs,
   summarizeCopilotReviews,
   summarizeGateReviewCommentMarkers,
   summarizeGateReviewComments,

package/scripts/claude/headless-dev-loop.mjs

@@ -20,6 +20,7 @@
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
 
 import { ensureRunId } from "@dev-loops/core/loop/run-context";
 import {
@@ -28,22 +29,61 @@ import {
   DEFAULT_CLAUDE_BIN,
 } from "@dev-loops/core/claude/headless-entry";
 
-function parseArgs(argv) {
+function parseCliArgs(argv) {
   const opts = { dryRun: false, claudeBin: DEFAULT_CLAUDE_BIN };
-  const requireValue = (name, i) => {
-    const v = argv[i + 1];
-    if (v === undefined || v.startsWith("--")) throw new Error(`${name} requires a value`);
+  const requireValue = (name, token) => {
+    const v = token.value;
+    if (typeof v !== "string" || v.length === 0 || v.startsWith("--")) {
+      throw new Error(`${name} requires a value`);
+    }
     return v;
   };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--dry-run") opts.dryRun = true;
-    else if (a === "--issue") { opts.issue = requireValue(a, i); i++; }
-    else if (a === "--pr") { opts.pr = requireValue(a, i); i++; }
-    else if (a === "--claude-bin") { opts.claudeBin = requireValue(a, i); i++; }
-    else if (a === "--prompt") { opts.prompt = requireValue(a, i); i++; }
-    else throw new Error(`unknown argument: ${a}`);
+
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      "dry-run": { type: "boolean" },
+      issue: { type: "string" },
+      pr: { type: "string" },
+      "claude-bin": { type: "string" },
+      prompt: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw new Error(`unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    switch (token.name) {
+      case "dry-run":
+        if (token.value !== undefined) {
+          throw new Error(`unknown argument: ${token.rawName}=${token.value}`);
+        }
+        opts.dryRun = true;
+        break;
+      case "issue":
+        opts.issue = requireValue("--issue", token);
+        break;
+      case "pr":
+        opts.pr = requireValue("--pr", token);
+        break;
+      case "claude-bin":
+        opts.claudeBin = requireValue("--claude-bin", token);
+        break;
+      case "prompt":
+        opts.prompt = requireValue("--prompt", token);
+        break;
+      default:
+        throw new Error(`unknown argument: ${token.rawName}`);
+    }
   }
+
   if (opts.issue != null && opts.pr != null) {
     throw new Error("--issue and --pr are mutually exclusive");
   }
@@ -53,7 +93,7 @@ function parseArgs(argv) {
 function main(argv) {
   let opts;
   try {
-    opts = parseArgs(argv);
+    opts = parseCliArgs(argv);
   } catch (error) {
     process.stderr.write(JSON.stringify({ ok: false, error: error.message }) + "\n");
     return 1;

package/scripts/claude/headless-info-smoke.mjs

@@ -18,21 +18,55 @@
 import { spawnSync } from "node:child_process";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
 
-function parseArgs(argv) {
+function parseCliArgs(argv) {
   const opts = { loopInfo: false };
-  const requireValue = (name, i) => {
-    const v = argv[i + 1];
-    if (v === undefined || v.startsWith("--")) throw new Error(`${name} requires a value`);
+  const requireValue = (name, token) => {
+    const v = token.value;
+    if (typeof v !== "string" || v.length === 0 || v.startsWith("--")) {
+      throw new Error(`${name} requires a value`);
+    }
     return v;
   };
-  for (let i = 0; i < argv.length; i++) {
-    const a = argv[i];
-    if (a === "--loop-info") opts.loopInfo = true;
-    else if (a === "--issue") { opts.issue = requireValue(a, i); i++; }
-    else if (a === "--pr") { opts.pr = requireValue(a, i); i++; }
-    else throw new Error(`unknown argument: ${a}`);
+
+  const { tokens } = parseArgs({
+    args: [...argv],
+    options: {
+      "loop-info": { type: "boolean" },
+      issue: { type: "string" },
+      pr: { type: "string" },
+    },
+    allowPositionals: true,
+    strict: false,
+    tokens: true,
+  });
+
+  for (const token of tokens) {
+    if (token.kind === "positional") {
+      throw new Error(`unknown argument: ${token.value}`);
+    }
+    if (token.kind !== "option") {
+      continue;
+    }
+    switch (token.name) {
+      case "loop-info":
+        if (token.value !== undefined) {
+          throw new Error(`unknown argument: ${token.rawName}=${token.value}`);
+        }
+        opts.loopInfo = true;
+        break;
+      case "issue":
+        opts.issue = requireValue("--issue", token);
+        break;
+      case "pr":
+        opts.pr = requireValue("--pr", token);
+        break;
+      default:
+        throw new Error(`unknown argument: ${token.rawName}`);
+    }
   }
+
   if (opts.issue != null && opts.pr != null) {
     throw new Error("--issue and --pr are mutually exclusive");
   }
@@ -46,7 +80,7 @@ function runCli(cliEntry, repoRoot, args) {
 function main(argv) {
   let opts;
   try {
-    opts = parseArgs(argv);
+    opts = parseCliArgs(argv);
   } catch (error) {
     process.stderr.write(JSON.stringify({ ok: false, error: error.message }) + "\n");
     return 1;

package/scripts/github/build-adjacent-bundle.mjs

@@ -0,0 +1,448 @@
+#!/usr/bin/env node
+/**
+ * build-adjacent-bundle.mjs — deterministic, neutral adjacent-code bundle builder.
+ *
+ * Part of issue #895 (build-once neutral context bundle for the gate fan-out).
+ * The gate context-builder runs ONCE and emits a generous, NEUTRAL bundle that
+ * every independent reviewer is seeded with verbatim — instead of every reviewer
+ * re-deriving the diff + adjacent code from scratch (the actual N× waste this
+ * fixes). The primary win is WORK-DEDUP (build once vs. N× re-derivation);
+ * prompt-cache of the shared prefix is an opportunistic bonus.
+ *
+ * Neutrality + determinism are guaranteed because this is a SCRIPT, not an
+ * agent: it cannot editorialize, and identical (head + changed files) input
+ * always produces an identical bundle (sorted file list, stable JSON shape).
+ *
+ * Bundle contents: for each changed JS/.mjs/.cjs file we include
+ *   - the files it imports (1-hop out-edges), and
+ *   - the files that import it (1-hop in-edges, via a repo-wide import scan)
+ * resolved against the repo (deterministic 1-hop import/require graph).
+ *
+ * Size guards (record, do not silently drop):
+ *   - skip lockfiles (package-lock.json / *-lock.yaml), generated trees
+ *     (.claude/, dist/, lib/, node_modules/, coverage/), binary, and minified
+ *     files (*.min.*) — recorded in `stripped` with a reason.
+ *   - cap per-file bytes (default ~48KB) and truncate the long tail —
+ *     recorded in `truncated` with original/included byte counts.
+ *
+ * The output is purely structural adjacency; it does NOT carry any opinion,
+ * verdict, or main-agent state, so seeding a reviewer with it is the INTENDED
+ * neutral seed (RFC-2), not contamination.
+ */
+import { open, readFile, readdir, stat } from "node:fs/promises";
+import path from "node:path";
+
+/** Default per-file byte cap before truncation. */
+export const DEFAULT_MAX_FILE_BYTES = 48 * 1024;
+
+/**
+ * Binary-sniff window: the NUL-byte heuristic inspects this many leading bytes.
+ * The guarded read must cover at least this window even when the per-file cap is
+ * configured smaller, so a small cap can't cause a binary (whose first NUL is
+ * past the cap) to be misclassified as text.
+ */
+const BINARY_SNIFF_BYTES = 8 * 1024;
+
+/** Source extensions we resolve import edges for (JS family, this repo). */
+const SOURCE_EXTENSIONS = [".mjs", ".js", ".cjs"];
+
+/** Directory prefixes treated as generated / vendored and skipped. */
+const GENERATED_DIR_PREFIXES = [
+  ".claude/",
+  "dist/",
+  "lib/",
+  "node_modules/",
+  "coverage/",
+  ".git/",
+];
+
+/**
+ * Classify why a file is skipped from the bundle, or null when it is includable.
+ * Deterministic, path-shape based. Exported for tests.
+ * @param {string} relPath — repo-relative POSIX path
+ * @returns {"lockfile"|"generated"|"binary"|"minified"|null}
+ */
+export function classifyStripReason(relPath) {
+  const posix = String(relPath).replace(/\\/g, "/");
+  const base = posix.split("/").pop() ?? posix;
+
+  if (base === "package-lock.json" || base === "npm-shrinkwrap.json" || /-lock\.ya?ml$/.test(base) || base === "yarn.lock" || base === "pnpm-lock.yaml") {
+    return "lockfile";
+  }
+  for (const prefix of GENERATED_DIR_PREFIXES) {
+    if (posix === prefix.slice(0, -1) || posix.startsWith(prefix) || posix.includes(`/${prefix}`)) {
+      return "generated";
+    }
+  }
+  if (/\.min\.[a-z0-9]+$/i.test(base)) return "minified";
+  if (isBinaryPath(base)) return "binary";
+  return null;
+}
+
+const BINARY_EXTENSIONS = new Set([
+  ".png", ".jpg", ".jpeg", ".gif", ".webp", ".ico", ".bmp", ".pdf",
+  ".zip", ".gz", ".tgz", ".tar", ".bz2", ".7z", ".rar",
+  ".woff", ".woff2", ".ttf", ".otf", ".eot",
+  ".mp3", ".mp4", ".mov", ".avi", ".wav", ".ogg", ".webm",
+  ".so", ".dylib", ".dll", ".exe", ".bin", ".wasm", ".class", ".o", ".a",
+  ".node", ".lockb",
+]);
+
+function isBinaryPath(base) {
+  const dot = base.lastIndexOf(".");
+  if (dot < 0) return false;
+  return BINARY_EXTENSIONS.has(base.slice(dot).toLowerCase());
+}
+
+/**
+ * Heuristic binary-content sniff: a NUL byte within the first 8KB marks the
+ * file as binary regardless of extension (covers extension-less binaries).
+ * @param {Buffer} buf
+ * @returns {boolean}
+ */
+function looksBinaryContent(buf) {
+  const limit = Math.min(buf.length, BINARY_SNIFF_BYTES);
+  for (let i = 0; i < limit; i++) {
+    if (buf[i] === 0) return true;
+  }
+  return false;
+}
+
+/**
+ * Extract the static import/require specifiers from JS source text.
+ * Deterministic regex scan (no execution). Captures:
+ *   - import ... from "x"        / export ... from "x"
+ *   - import("x")                (dynamic import)
+ *   - require("x")
+ * Returns specifiers in a deterministic, grouped-by-kind order — each kind is
+ * scanned in its own pass (export/import-from → bare side-effect import →
+ * dynamic import() → require()), so the output is grouped by form rather than
+ * by position in the source. De-duplicated (first occurrence wins).
+ * @param {string} source
+ * @returns {string[]}
+ */
+export function extractImportSpecifiers(source) {
+  if (typeof source !== "string" || source.length === 0) return [];
+  const specs = [];
+  const seen = new Set();
+  const push = (s) => {
+    if (typeof s === "string" && s.length > 0 && !seen.has(s)) {
+      seen.add(s);
+      specs.push(s);
+    }
+  };
+  // import ... from "x" | export ... from "x"
+  const fromRe = /\b(?:import|export)\b[^;'"]*?\bfrom\s*['"]([^'"]+)['"]/g;
+  // bare side-effect import "x"
+  const bareRe = /\bimport\s+['"]([^'"]+)['"]/g;
+  // dynamic import("x")
+  const dynRe = /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+  // require("x")
+  const reqRe = /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/g;
+  for (const re of [fromRe, bareRe, dynRe, reqRe]) {
+    let m;
+    while ((m = re.exec(source)) !== null) push(m[1]);
+  }
+  return specs;
+}
+
+/**
+ * Resolve a RELATIVE import specifier (./ or ../) from a source file to a
+ * repo-relative POSIX path, trying common extensions and index files.
+ * Bare/package specifiers (no leading dot) are NOT resolved (out of repo).
+ * Pure path math against the provided existing-files set — deterministic.
+ * @param {string} fromRelPath — repo-relative path of the importing file
+ * @param {string} specifier
+ * @param {Set<string>} existing — set of repo-relative POSIX paths that exist
+ * @returns {string|null}
+ */
+export function resolveRelativeImport(fromRelPath, specifier, existing) {
+  if (typeof specifier !== "string" || !specifier.startsWith(".")) return null;
+  const fromDir = path.posix.dirname(String(fromRelPath).replace(/\\/g, "/"));
+  const base = path.posix.normalize(path.posix.join(fromDir, specifier));
+  if (base.startsWith("..")) return null; // escaped the repo root
+  const candidates = [base];
+  for (const ext of SOURCE_EXTENSIONS) candidates.push(base + ext);
+  for (const ext of SOURCE_EXTENSIONS) candidates.push(path.posix.join(base, "index" + ext));
+  for (const c of candidates) {
+    if (existing.has(c)) return c;
+  }
+  return null;
+}
+
+function isSourceFile(relPath) {
+  const ext = path.posix.extname(String(relPath).replace(/\\/g, "/")).toLowerCase();
+  return SOURCE_EXTENSIONS.includes(ext);
+}
+
+/**
+ * Recursively list repo-relative POSIX paths under repoRoot, skipping
+ * generated/vendored dirs and the tmp/ scratch tree for determinism+speed.
+ * @param {string} repoRoot
+ * @returns {Promise<string[]>} sorted repo-relative POSIX paths
+ */
+export async function listRepoFiles(repoRoot) {
+  const out = [];
+  const skipDir = new Set([".git", "node_modules", "dist", "lib", ".claude", "coverage", "tmp"]);
+  async function walk(absDir, relDir) {
+    let entries;
+    try {
+      entries = await readdir(absDir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const ent of entries) {
+      if (ent.isSymbolicLink()) continue;
+      const relPath = relDir ? `${relDir}/${ent.name}` : ent.name;
+      if (ent.isDirectory()) {
+        if (skipDir.has(ent.name)) continue;
+        await walk(path.join(absDir, ent.name), relPath);
+      } else if (ent.isFile()) {
+        out.push(relPath);
+      }
+    }
+  }
+  await walk(repoRoot, "");
+  out.sort();
+  return out;
+}
+
+/**
+ * Build the reverse-import (importers) index: for each source file, which other
+ * source files import it (1-hop in-edges). Deterministic given the repo files.
+ * @param {string[]} repoFiles — repo-relative POSIX paths
+ * @param {string} repoRoot
+ * @returns {Promise<Map<string, string[]>>} target → sorted importers
+ */
+export async function buildImporterIndex(repoFiles, repoRoot) {
+  const existing = new Set(repoFiles);
+  const importers = new Map();
+  for (const file of repoFiles) {
+    if (!isSourceFile(file)) continue;
+    // Skip minified artifacts: they are stripped from the final bundle anyway and
+    // are not meaningful import sources, so reading them here is wasted I/O/memory
+    // on repos with large minified files.
+    if (/\.min\.[a-z0-9]+$/i.test(file)) continue;
+    let source;
+    try {
+      source = await readFile(path.resolve(repoRoot, file), "utf8");
+    } catch {
+      continue;
+    }
+    for (const spec of extractImportSpecifiers(source)) {
+      const target = resolveRelativeImport(file, spec, existing);
+      if (!target) continue;
+      if (!importers.has(target)) importers.set(target, []);
+      const list = importers.get(target);
+      if (!list.includes(file)) list.push(file);
+    }
+  }
+  for (const list of importers.values()) list.sort();
+  return importers;
+}
+
+/**
+ * Decide whether a repo-relative path is safe to resolve+read under repoRoot.
+ * Fails closed: rejects absolute paths, any `..` segment, and any resolved
+ * absolute path that escapes repoRoot. Deterministic, pure path math.
+ * @param {string} repoRoot
+ * @param {string} relPath — repo-relative POSIX path
+ * @returns {{ ok: true, abs: string } | { ok: false }}
+ */
+export function resolveSafeRepoPath(repoRoot, relPath) {
+  const posix = String(relPath).replace(/\\/g, "/");
+  if (posix.length === 0) return { ok: false };
+  if (path.posix.isAbsolute(posix) || path.win32.isAbsolute(posix)) return { ok: false };
+  if (posix.split("/").includes("..")) return { ok: false };
+  const root = path.resolve(repoRoot);
+  const abs = path.resolve(root, posix);
+  if (abs !== root && !abs.startsWith(root + path.sep)) return { ok: false };
+  return { ok: true, abs };
+}
+
+/**
+ * Read a file with the size guards applied. Returns the (possibly truncated)
+ * content plus guard metadata. Never throws on a missing/unreadable file.
+ *
+ * Path safety: unsafe relPaths (absolute, `..` segments, or escaping repoRoot)
+ * are NOT read — they are recorded with strip reason "unsafe-path".
+ *
+ * Bounded read: when the file is over the cap it is truncated, so we read at
+ * most maxFileBytes+1 bytes (the +1 lets us also sniff binary content past the
+ * cap without loading the whole file). The full original size is read from
+ * stat() for the manifest.
+ * @param {string} repoRoot
+ * @param {string} relPath
+ * @param {number} maxFileBytes
+ * @returns {Promise<{ relPath: string, content: string|null, bytes: number, includedBytes: number, truncated: boolean, missing: boolean, strip: string|null }>}
+ */
+async function readGuardedFile(repoRoot, relPath, maxFileBytes) {
+  const strip = classifyStripReason(relPath);
+  if (strip) {
+    return { relPath, content: null, bytes: 0, includedBytes: 0, truncated: false, missing: false, strip };
+  }
+  const safe = resolveSafeRepoPath(repoRoot, relPath);
+  if (!safe.ok) {
+    return { relPath, content: null, bytes: 0, includedBytes: 0, truncated: false, missing: false, strip: "unsafe-path" };
+  }
+  const abs = safe.abs;
+  let handle;
+  try {
+    const info = await stat(abs);
+    if (!info.isFile()) {
+      return { relPath, content: null, bytes: 0, includedBytes: 0, truncated: false, missing: true, strip: null };
+    }
+    const bytes = info.size;
+    // Read enough to (a) detect over-cap and truncate, and (b) always cover the
+    // binary-sniff window — so a cap configured below BINARY_SNIFF_BYTES can't let
+    // a binary slip through as text. Still bounded (never the whole large file).
+    const readCap = Math.min(bytes, Math.max(maxFileBytes + 1, BINARY_SNIFF_BYTES));
+    const buf = Buffer.allocUnsafe(readCap);
+    handle = await open(abs, "r");
+    const { bytesRead } = await handle.read(buf, 0, readCap, 0);
+    const data = buf.subarray(0, bytesRead);
+    if (looksBinaryContent(data)) {
+      return { relPath, content: null, bytes, includedBytes: 0, truncated: false, missing: false, strip: "binary" };
+    }
+    let truncated = false;
+    let slice = data;
+    if (bytes > maxFileBytes) {
+      slice = data.subarray(0, maxFileBytes);
+      truncated = true;
+    }
+    return {
+      relPath,
+      content: slice.toString("utf8"),
+      bytes,
+      includedBytes: slice.length,
+      truncated,
+      missing: false,
+      strip: null,
+    };
+  } catch {
+    return { relPath, content: null, bytes: 0, includedBytes: 0, truncated: false, missing: true, strip: null };
+  } finally {
+    if (handle) await handle.close().catch(() => {});
+  }
+}
+
+/**
+ * Build the deterministic, neutral adjacent-code bundle for a set of changed
+ * files. For each changed source file, collect its 1-hop import out-edges
+ * (resolved relative imports) and in-edges (files that import it) and include
+ * each adjacent file's (guarded) content.
+ *
+ * Output shape (added to the gate-context artifact under `adjacentCode`):
+ *   {
+ *     maxFileBytes,
+ *     files: [{ path, role: "changed"|"imports"|"importedBy", relatedTo: [..],
+ *               bytes, includedBytes, truncated, content }],  // sorted by path
+ *     stripped: [{ path, reason, role: "changed"|"imports"|"importedBy",
+ *                 relatedTo: [..] }],                          // sorted by path
+ *     truncated: [{ path, bytes, includedBytes }],            // sorted by path
+ *     missing: [string],                                      // sorted
+ *   }
+ *
+ * Deterministic: same (repoRoot contents + changedFiles) → identical bundle.
+ *
+ * @param {object} input
+ * @param {string[]} input.changedFiles — repo-relative paths from the diff
+ * @param {string} [input.repoRoot]
+ * @param {number} [input.maxFileBytes]
+ * @returns {Promise<object>}
+ */
+export async function buildAdjacentBundle({ changedFiles, repoRoot = process.cwd(), maxFileBytes = DEFAULT_MAX_FILE_BYTES }) {
+  const changed = Array.from(
+    new Set((Array.isArray(changedFiles) ? changedFiles : []).map((f) => String(f).replace(/\\/g, "/")).filter((f) => f.length > 0)),
+  ).sort();
+
+  // No changed files → empty bundle. Return early so the empty case is O(1) and
+  // skips the whole-repo scan + importer-index build entirely.
+  if (changed.length === 0) {
+    return { maxFileBytes, files: [], stripped: [], truncated: [], missing: [] };
+  }
+
+  const repoFiles = await listRepoFiles(repoRoot);
+  const existing = new Set(repoFiles);
+  const importerIndex = await buildImporterIndex(repoFiles, repoRoot);
+
+  // role per path: changed > imports/importedBy. relatedTo accumulates the
+  // changed files an adjacent file is adjacent to (sorted, deduped).
+  /** @type {Map<string, { role: string, relatedTo: Set<string> }>} */
+  const selected = new Map();
+  const note = (relPath, role, relatedTo) => {
+    if (!relPath) return;
+    let entry = selected.get(relPath);
+    if (!entry) {
+      entry = { role, relatedTo: new Set() };
+      selected.set(relPath, entry);
+    } else if (entry.role !== "changed" && role === "changed") {
+      entry.role = "changed";
+    }
+    if (relatedTo) entry.relatedTo.add(relatedTo);
+  };
+
+  for (const file of changed) {
+    note(file, "changed", null);
+  }
+
+  for (const file of changed) {
+    // Out-edges: imports declared by the changed file (source files only).
+    if (isSourceFile(file) && existing.has(file)) {
+      try {
+        const source = await readFile(path.resolve(repoRoot, file), "utf8");
+        for (const spec of extractImportSpecifiers(source)) {
+          const target = resolveRelativeImport(file, spec, existing);
+          if (target && !changed.includes(target)) note(target, "imports", file);
+        }
+      } catch {
+        // unreadable changed file — diff still carries it; skip out-edges
+      }
+    }
+    // In-edges: files that import the changed file.
+    const importers = importerIndex.get(file) ?? [];
+    for (const imp of importers) {
+      if (!changed.includes(imp)) note(imp, "importedBy", file);
+    }
+  }
+
+  const files = [];
+  const stripped = [];
+  const truncatedList = [];
+  const missing = [];
+
+  for (const relPath of Array.from(selected.keys()).sort()) {
+    const entry = selected.get(relPath);
+    const relatedTo = Array.from(entry.relatedTo).sort();
+    const guarded = await readGuardedFile(repoRoot, relPath, maxFileBytes);
+    if (guarded.strip) {
+      stripped.push({ path: relPath, reason: guarded.strip, role: entry.role, relatedTo });
+      continue;
+    }
+    if (guarded.missing) {
+      // A changed file deleted by the diff legitimately won't exist on disk.
+      missing.push(relPath);
+      continue;
+    }
+    if (guarded.truncated) {
+      truncatedList.push({ path: relPath, bytes: guarded.bytes, includedBytes: guarded.includedBytes });
+    }
+    files.push({
+      path: relPath,
+      role: entry.role,
+      relatedTo,
+      bytes: guarded.bytes,
+      includedBytes: guarded.includedBytes,
+      truncated: guarded.truncated,
+      content: guarded.content,
+    });
+  }
+
+  return {
+    maxFileBytes,
+    files,
+    stripped,
+    truncated: truncatedList,
+    missing: missing.sort(),
+  };
+}