@dev-loops/core 0.1.0

package/bin/capture-deep-persona-signals.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+import { mkdir, writeFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseReviewThreads, readInput, parseJsonText, formatCliError } from "../src/github/review-threads.mjs";
+import { extractDeepPersonaSignals } from "../src/debt/deep-persona-signals.mjs";
+
+export const USAGE = [
+  "Usage: capture-deep-persona-signals.mjs --input <path> --pr-number <n> --pr-url <url> [--output-dir <path>]",
+  "",
+  "Arguments:",
+  "  --input <path>        Path to normalized review-thread JSON (required)",
+  "  --pr-number <n>       PR number for metadata (required)",
+  "  --pr-url <url>        PR URL for metadata (required)",
+  "  --output-dir <path>   Output directory for emitted artifact (default: .pi/debt/signals/)",
+].join("\n");
+
+/**
+ * Parse CLI arguments for the capture-deep-persona-signals CLI.
+ *
+ * @param {string[]} argv - Argument list (e.g. process.argv.slice(2))
+ * @returns {{ inputPath: string, prNumber: string, prUrl: string, outputDir: string }}
+ */
+export function parseArgs(argv) {
+  const args = [...argv];
+  const options = {
+    inputPath: undefined,
+    prNumber: undefined,
+    prUrl: undefined,
+    outputDir: ".pi/debt/signals",
+  };
+
+  while (args.length > 0) {
+    const token = args.shift();
+
+    switch (token) {
+      case "--input": {
+        const value = args.shift();
+        if (typeof value !== "string" || value.length === 0 || value.startsWith("--")) {
+          throw Object.assign(new Error("Missing value for --input"), { usage: USAGE });
+        }
+        options.inputPath = value;
+        break;
+      }
+      case "--pr-number": {
+        const value = args.shift();
+        if (typeof value !== "string" || value.length === 0 || value.startsWith("--")) {
+          throw Object.assign(new Error("Missing value for --pr-number"), { usage: USAGE });
+        }
+        if (!/^\d+$/.test(value)) {
+          throw Object.assign(new Error(`--pr-number must be a positive integer, got: ${value}`), { usage: USAGE });
+        }
+        options.prNumber = value;
+        break;
+      }
+      case "--pr-url": {
+        const value = args.shift();
+        if (typeof value !== "string" || value.length === 0 || value.startsWith("--")) {
+          throw Object.assign(new Error("Missing value for --pr-url"), { usage: USAGE });
+        }
+        options.prUrl = value;
+        break;
+      }
+      case "--output-dir": {
+        const value = args.shift();
+        if (typeof value !== "string" || value.length === 0 || value.startsWith("--")) {
+          throw Object.assign(new Error("Missing value for --output-dir"), { usage: USAGE });
+        }
+        options.outputDir = value;
+        break;
+      }
+      default:
+        throw Object.assign(new Error(`Unknown argument: ${token}`), { usage: USAGE });
+    }
+  }
+
+  if (!options.inputPath) {
+    throw Object.assign(new Error("--input is required"), { usage: USAGE });
+  }
+  if (!options.prNumber) {
+    throw Object.assign(new Error("--pr-number is required"), { usage: USAGE });
+  }
+  if (!options.prUrl) {
+    throw Object.assign(new Error("--pr-url is required"), { usage: USAGE });
+  }
+
+  return /** @type {{ inputPath: string, prNumber: string, prUrl: string, outputDir: string }} */ (options);
+}
+
+/**
+ * Generate the output filename.
+ * @param {string} prNumber
+ * @returns {string}
+ */
+export function outputFilename(prNumber) {
+  const ts = new Date().toISOString().replace(/[:.]/g, "-");
+  return `deep-persona-signals-${prNumber}-${ts}.json`;
+}
+
+export async function run(argv = process.argv.slice(2)) {
+  const options = parseArgs(argv);
+
+  // Read and parse the review-thread input
+  const rawText = await readInput({ inputPath: options.inputPath });
+  const parsed = parseReviewThreads(parseJsonText(rawText));
+
+  // Extract deep-persona signals
+  const signals = extractDeepPersonaSignals(parsed, {
+    prNumber: options.prNumber,
+    prUrl: options.prUrl,
+  });
+
+  // Build artifact envelope
+  const artifact = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    prNumber: Number(options.prNumber),
+    prUrl: options.prUrl,
+    source: "pr_review_deep_persona",
+    signalCount: signals.length,
+    signals,
+  };
+
+  // Write to output directory
+  const outDir = resolve(options.outputDir);
+  await mkdir(outDir, { recursive: true });
+  const outPath = join(outDir, outputFilename(options.prNumber));
+  await writeFile(outPath, JSON.stringify(artifact, null, 2) + "\n", "utf8");
+
+  process.stdout.write(JSON.stringify({ ok: true, outputPath: outPath, signalCount: signals.length }) + "\n");
+}
+
+// Only auto-run when executed directly (not imported)
+const scriptPath = fileURLToPath(import.meta.url);
+if (process.argv[1] === scriptPath) {
+  run().catch((error) => {
+    if (error.usage) {
+      process.stderr.write(error.usage + "\n\n");
+    }
+    process.stderr.write(formatCliError(error) + "\n");
+    process.exitCode = 1;
+  });
+}

package/bin/ensure-phase-files.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from "../src/loop/phase-files.mjs";
+
+runCli().catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+});

package/bin/log-bash-exit-1.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from "../src/bash-exit-one.mjs";
+
+runCli().catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 1;
+});

package/bin/parse-review-threads.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { formatCliError, runCli } from "../src/github/review-threads.mjs";
+
+runCli().catch((error) => {
+  process.stderr.write(`${formatCliError(error)}\n`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@dev-loops/core",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Shared deterministic support package for dev-loop skills, repo-local scripts, and GitHub automation.",
+  "exports": {
+    "./bash-exit-one": "./src/bash-exit-one.mjs",
+    "./cli/helpers": "./src/cli/helpers.mjs",
+    "./cli/primitives": "./src/cli/primitives.mjs",
+    "./cli/retry-wrapper": "./src/cli/retry-wrapper.mjs",
+    "./cli/subcommand-runner": "./src/cli/subcommand-runner.mjs",
+    "./config": "./src/config/config.mjs",
+    "./debt/cluster": "./src/debt/cluster.mjs",
+    "./debt/finding": "./src/debt/debt-finding.mjs",
+    "./debt/remediation-to-issue": "./src/debt/remediation-to-issue.mjs",
+    "./debt/score": "./src/debt/score.mjs",
+    "./debt/shape": "./src/debt/shape.mjs",
+    "./debt/signal": "./src/debt/debt-signal.mjs",
+    "./debt/signals": "./src/debt/deep-persona-signals.mjs",
+    "./github/copilot-helpers": "./src/github/copilot-helpers.mjs",
+    "./github/repo-slug": "./src/github/repo-slug.mjs",
+    "./github/review-threads": "./src/github/review-threads.mjs",
+    "./loop/async-start-contract": "./src/loop/async-start-contract.mjs",
+    "./loop/conductor-routing": "./src/loop/conductor-routing.mjs",
+    "./loop/copilot-ci-status": "./src/loop/copilot-ci-status.mjs",
+    "./loop/copilot-loop-iterations": "./src/loop/copilot-loop-iterations.mjs",
+    "./loop/copilot-loop-state": "./src/loop/copilot-loop-state.mjs",
+    "./loop/handoff-envelope": "./src/loop/handoff-envelope.mjs",
+    "./loop/lifecycle-state": "./src/loop/lifecycle-state.mjs",
+    "./loop/issue-refinement-artifact": "./src/loop/issue-refinement-artifact.mjs",
+    "./loop/phase-files": "./src/loop/phase-files.mjs",
+    "./loop/policy-constants": "./src/loop/policy-constants.mjs",
+    "./loop/pr-gate-coordination": "./src/loop/pr-gate-coordination.mjs",
+    "./loop/public-dev-loop-routing": "./src/loop/public-dev-loop-routing.mjs",
+    "./loop/queue-driver": "./src/loop/queue-driver.mjs",
+    "./loop/queue-parallel": "./src/loop/queue-parallel.mjs",
+    "./loop/queue-state": "./src/loop/queue-state.mjs",
+    "./loop/reviewer-loop-state": "./src/loop/reviewer-loop-state.mjs",
+    "./loop/run-inspection": "./src/loop/run-inspection.mjs",
+    "./loop/steering": "./src/loop/steering.mjs",
+    "./loop/timeout-policy": "./src/loop/timeout-policy.mjs",
+    "./loop/tracker-pr-state": "./src/loop/tracker-pr-state.mjs",
+    "./refinement/ac-dod-matrix": "./src/refinement/ac-dod-matrix.mjs",
+    "./harness": "./src/harness/index.mjs",
+    "./loop/worktree-guard": "./src/loop/worktree-guard.mjs",
+    "./loop/tracker-first-loop-state": "./src/loop/tracker-first-loop-state.mjs"
+  },
+  "bin": {
+    "dev-loops-log-bash-exit-1": "./bin/log-bash-exit-1.mjs",
+    "dev-loops-ensure-phase-files": "./bin/ensure-phase-files.mjs",
+    "dev-loops-parse-review-threads": "./bin/parse-review-threads.mjs",
+    "dev-loops-capture-deep-persona-signals": "./bin/capture-deep-persona-signals.mjs"
+  },
+  "files": [
+    "src/**/*.mjs",
+    "bin/**/*.mjs"
+  ],
+  "scripts": {
+    "test": "node --test ./test/*.test.mjs"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mfittko/dev-loops.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mfittko/dev-loops/issues"
+  },
+  "homepage": "https://github.com/mfittko/dev-loops#readme",
+  "dependencies": {
+    "yaml": "^2.9.0",
+    "zod": "^4.4.3"
+  },
+  "license": "MIT"
+}

package/src/analysis/change-classifier.mjs

@@ -0,0 +1,146 @@
+/**
+ * Change category classification and angle relevance index.
+ *
+ * Maps change categories detected by the diff analyzer to relevant gate review
+ * angles.
+ */
+
+// ---------------------------------------------------------------------------
+// Change categories
+// ---------------------------------------------------------------------------
+
+/** @enum {string} */
+export const ChangeCategory = Object.freeze({
+  RENAME_ONLY: "RENAME_ONLY",
+  DOCS_ONLY: "DOCS_ONLY",
+  CONFIG_ONLY: "CONFIG_ONLY",
+  TEST_ONLY: "TEST_ONLY",
+  CI_ONLY: "CI_ONLY",
+  COMMENT_ONLY: "COMMENT_ONLY",
+  LOGIC_CHANGE: "LOGIC_CHANGE",
+});
+
+// ---------------------------------------------------------------------------
+// Angle relevance index
+// ---------------------------------------------------------------------------
+
+/**
+ * Map of ChangeCategory → relevant gate angles.
+ *
+ * Categories not listed default to an empty array (no angles relevant).
+ * When multiple categories match, the union of angles is taken.
+ *
+ * @type {Record<string, string[]>}
+ */
+const CATEGORY_ANGLE_MAP = {
+  [ChangeCategory.RENAME_ONLY]: [
+    "scope", "correctness", "contract-surface", "docs", "link-check",
+  ],
+  [ChangeCategory.DOCS_ONLY]: [
+    "docs", "link-check", "contract-surface", "dry",
+  ],
+  [ChangeCategory.CONFIG_ONLY]: [
+    "config-drift", "scope", "correctness", "contract-surface",
+  ],
+  [ChangeCategory.TEST_ONLY]: [
+    "coverage", "correctness", "determinism",
+  ],
+  [ChangeCategory.CI_ONLY]: [
+    "ci-guard", "scope", "config-drift",
+  ],
+  [ChangeCategory.COMMENT_ONLY]: [
+    "dry",
+  ],
+  [ChangeCategory.LOGIC_CHANGE]: [
+    "correctness", "coverage", "kiss", "dry", "srp", "soc", "deep",
+    "ocp", "lsp", "isp", "dip", "yagni", "scope", "no-op", "determinism",
+  ],
+};
+
+/**
+ * Angles that are never skipped, regardless of diff analysis.
+ *
+ * @type {Set<string>}
+ */
+const ALWAYS_INCLUDE = new Set(["gate-evidence", "renderer-security", "pr-description"]);
+
+// ---------------------------------------------------------------------------
+// Resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} DynamicAngleResult
+ * @property {string[]} recommendedAngles — angles to run
+ * @property {string[]} skippedAngles — angles skipped with reasons
+ * @property {Record<string, string>} reasons — why each angle was skipped
+ * @property {boolean} fallbackToAll — true when ambiguous → all angles recommended
+ */
+
+/**
+ * Resolve which gate angles to run based on detected change categories.
+ *
+ * When the diff is ambiguous (contains LOGIC_CHANGE or multiple mixed categories),
+ * all configured angles are recommended (fallback-to-all).
+ *
+ * @param {object} options
+ * @param {string[]} options.configuredAngles — all angles configured for this gate
+ * @param {string[]} options.changeCategories — from diff analysis
+ * @param {boolean} [options.ambiguous] — from diff analysis
+ * @returns {DynamicAngleResult}
+ */
+export function resolveDynamicAngles({
+  configuredAngles,
+  changeCategories,
+  ambiguous = false,
+}) {
+  // Fallback: ambiguous diff → all angles
+  if (ambiguous) {
+    return {
+      recommendedAngles: [...configuredAngles],
+      skippedAngles: [],
+      reasons: {},
+      fallbackToAll: true,
+    };
+  }
+
+  // No change categories → all angles (defensive)
+  if (changeCategories.length === 0) {
+    return {
+      recommendedAngles: [...configuredAngles],
+      skippedAngles: [],
+      reasons: {},
+      fallbackToAll: true,
+    };
+  }
+
+  // Build recommended set from category union
+  const recommended = new Set();
+  for (const cat of changeCategories) {
+    const angles = CATEGORY_ANGLE_MAP[cat] ?? [];
+    for (const angle of angles) {
+      recommended.add(angle);
+    }
+  }
+
+  // Always-include angles
+  for (const angle of ALWAYS_INCLUDE) {
+    recommended.add(angle);
+  }
+
+  // Filter to only angles that are configured
+  const recommendedAngles = configuredAngles.filter((a) => recommended.has(a));
+  const skippedAngles = configuredAngles.filter((a) => !recommended.has(a));
+
+  // Build reasons
+  const reasons = {};
+  for (const angle of skippedAngles) {
+    reasons[angle] = `Skipped: detected categories (${changeCategories.join(", ") || "none"}) do not trigger this angle`;
+  }
+
+  return {
+    recommendedAngles,
+    skippedAngles,
+    reasons,
+    fallbackToAll: false,
+  };
+}

package/src/analysis/diff-analyzer.mjs

@@ -0,0 +1,285 @@
+/**
+ * Diff analysis for dynamic gate angle resolution.
+ *
+ * T0 — file-level: classifies files by extension and directory.
+ * T1 — hunk-level: classifies hunks by change type (comments, imports, config, etc.).
+ *
+ * T2 (AST-level) is deferred to a follow-up.
+ *
+ * This module is intentionally pure and side-effect free.
+ */
+
+// ---------------------------------------------------------------------------
+// T0: File-level analysis
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} T0Result
+ * @property {string[]} files — flat file paths
+ * @property {string[]} extensions — unique file extensions (lowercase, with dot)
+ * @property {string[]} directories — unique top-level path segments
+ * @property {boolean} renameOnly — true when all entries are renames (no adds/deletes/modifies)
+ * @property {boolean} allDocs — true when all files are under docs/ or are .md
+ */
+
+/**
+ * Parse `git diff --name-status` output into a T0 analysis.
+ *
+ * Each line format: `<status>\t<path>` or `<status>\t<old>\t<new>`.
+ *
+ * @param {string} nameStatusOutput — raw stdout from `git diff --name-status`
+ * @returns {T0Result}
+ */
+
+/**
+ * Normalize file path separators to forward slashes.
+ * Handles Windows backslash paths from git output on Windows.
+ *
+ * @param {string} filePath
+ * @returns {string}
+ */
+function normalizeSep(filePath) {
+  return filePath.replaceAll("\\", "/");
+}
+
+export function analyzeT0(nameStatusOutput) {
+  const lines = nameStatusOutput.trim().split("\n").filter(Boolean);
+  const files = [];
+  const extensions = new Set();
+  const directories = new Set();
+  let renameCount = 0;
+
+  for (const line of lines) {
+    const parts = line.split("\t");
+    const status = parts[0];
+    const rawPath = parts.length >= 3 ? parts[2] : parts[1];
+    const path = normalizeSep(rawPath);
+    if (!path) continue;
+
+    files.push(path);
+
+    const ext = path.includes(".") ? "." + path.split(".").pop().toLowerCase() : "";
+    if (ext) extensions.add(ext);
+
+    const dir = path.split("/")[0];
+    if (dir) directories.add(dir);
+
+    if (status.startsWith("R")) renameCount++;
+  }
+
+  const renameOnly = lines.length > 0 && renameCount === lines.length;
+  const allDocs = lines.length > 0 && files.every(
+    (f) => normalizeSep(f).startsWith("docs/") || f.endsWith(".md") || f === "README.md",
+  );
+
+  return {
+    files,
+    extensions: [...extensions].sort(),
+    directories: [...directories].sort(),
+    renameOnly,
+    allDocs,
+  };
+}
+
+/**
+ * @typedef {"code" | "docs" | "config" | "test" | "ci" | "unknown"} FileCategory
+ */
+
+/**
+ * Classify a single file path into a high-level category.
+ *
+ * @param {string} filePath
+ * @returns {FileCategory}
+ */
+export function classifyFile(filePath) {
+  const fp = normalizeSep(filePath);
+  if (fp.startsWith(".github/")) {
+    return "ci";
+  }
+  if (fp.startsWith("docs/") || fp.endsWith(".md") || fp === "README.md") {
+    return "docs";
+  }
+  if (
+    fp.endsWith(".yml") || fp.endsWith(".yaml") ||
+    fp.endsWith(".json") || fp === "package.json"
+  ) {
+    return "config";
+  }
+  if (fp.includes(".test.") || fp.startsWith("test/")) {
+    return "test";
+  }
+  if (
+    fp.endsWith(".mjs") || fp.endsWith(".js") ||
+    fp.endsWith(".ts") || fp.endsWith(".mts")
+  ) {
+    return "code";
+  }
+  return "unknown";
+}
+// ---------------------------------------------------------------------------
+// T1: Hunk-level analysis
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} T1Result
+ * @property {string[]} changeCategories — detected change categories
+ * @property {number} hunkCount
+ * @property {{ added: number, deleted: number }} lineStats
+ */
+
+/**
+ * Check whether a diff line content (after stripping the + / - prefix) is
+ * a comment or blank line — i.e. not logic.
+ *
+ * @param {string} content — trimmed line content (without + / - prefix)
+ * @returns {boolean}
+ */
+function isNonLogicLine(content) {
+  if (content === "") return true;
+  if (content.startsWith("//") || content.startsWith("/*") || content.startsWith("*")) return true;
+  // import/export/require lines are NOT non-logic — they change dependencies
+  // and should not be classified as COMMENT_ONLY
+  return false;
+}
+
+/**
+ * Analyze unified diff hunks to classify change types.
+ *
+ * Detects:
+ * - COMMENT_ONLY: only comment lines changed
+ * - DOCS_ONLY: only .md files changed (from extensions)
+ * - CONFIG_ONLY: only config files changed
+ * - TEST_ONLY: only test files changed
+ * - RENAME_ONLY: all renames, no content changes
+ * - LOGIC_CHANGE: any non-trivial code change
+ *
+ * @param {string} diffOutput — raw unified diff output
+ * @param {T0Result} t0 — T0 result for context
+ * @returns {T1Result}
+ */
+export function analyzeT1(diffOutput, t0) {
+  const lines = diffOutput.split("\n");
+  let hunkCount = 0;
+  let added = 0;
+  let deleted = 0;
+  const categories = new Set();
+
+  let inHunk = false;
+  let hasLogicChange = false;
+  let hasAnyChangedLine = false;
+  let allChangedLinesAreNonLogic = true;
+
+  for (const line of lines) {
+    // Track hunk headers
+    if (line.startsWith("@@")) {
+      hunkCount++;
+      inHunk = true;
+      continue;
+    }
+
+    if (!inHunk) continue;
+
+    // Track line stats and classify
+    if (line.startsWith("+") && !line.startsWith("+++")) {
+      added++;
+      hasAnyChangedLine = true;
+      const content = line.slice(1).trim();
+      if (!isNonLogicLine(content)) {
+        hasLogicChange = true;
+        allChangedLinesAreNonLogic = false;
+      }
+    } else if (line.startsWith("-") && !line.startsWith("---")) {
+      deleted++;
+      hasAnyChangedLine = true;
+      const content = line.slice(1).trim();
+      if (!isNonLogicLine(content)) {
+        hasLogicChange = true;
+        allChangedLinesAreNonLogic = false;
+      }
+    }
+  }
+
+  // Build categories from T0 + hunk analysis
+  if (t0.renameOnly) categories.add("RENAME_ONLY");
+  if (t0.allDocs) categories.add("DOCS_ONLY");
+  if (t0.files.every((f) => classifyFile(f) === "config")) categories.add("CONFIG_ONLY");
+  if (t0.files.every((f) => classifyFile(f) === "test")) categories.add("TEST_ONLY");
+  if (t0.files.every((f) => classifyFile(f) === "ci")) categories.add("CI_ONLY");
+  if (hasLogicChange) categories.add("LOGIC_CHANGE");
+
+  // COMMENT_ONLY: hunkCount > 0 (real diff), has changed lines, all are non-logic,
+  // and not a rename-only change
+  if (hunkCount > 0 && hasAnyChangedLine && allChangedLinesAreNonLogic && !t0.renameOnly) {
+    categories.add("COMMENT_ONLY");
+  }
+
+  return {
+    changeCategories: [...categories],
+    hunkCount,
+    lineStats: { added, deleted },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Combined analysis
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {object} DiffAnalysis
+ * @property {T0Result} t0
+ * @property {T1Result | null} t1
+ * @property {boolean} ambiguous — true when heuristics cannot confidently classify
+ */
+
+/**
+ * Infer change categories from T0 analysis when T1 is not run.
+ *
+ * @param {T0Result} t0
+ * @returns {string[]}
+ */
+function inferCategoriesFromT0(t0) {
+  const categories = [];
+  if (t0.renameOnly) categories.push("RENAME_ONLY");
+  if (t0.allDocs) categories.push("DOCS_ONLY");
+  if (t0.files.length > 0 && t0.files.every((f) => classifyFile(f) === "config")) categories.push("CONFIG_ONLY");
+  if (t0.files.length > 0 && t0.files.every((f) => classifyFile(f) === "test")) categories.push("TEST_ONLY");
+  if (t0.files.length > 0 && t0.files.every((f) => classifyFile(f) === "ci")) categories.push("CI_ONLY");
+  return categories;
+}
+
+/**
+ * Run full diff analysis (T0 + T1 if needed).
+ *
+ * T0 always runs. T1 runs when T0 doesn't produce a clear single-category result.
+ * When T1 is not run (unambiguous diff), categories are inferred from T0 so
+ * dynamic angle resolution can still narrow the angle list.
+ *
+ * @param {{ nameStatusOutput: string, diffOutput?: string }} input
+ * @returns {DiffAnalysis}
+ */
+export function analyzeDiff({ nameStatusOutput, diffOutput }) {
+  const t0 = analyzeT0(nameStatusOutput);
+  let t1 = null;
+
+  // T0 is unambiguous when: renameOnly, allDocs, or single clear category
+  const t0Ambiguous = !t0.renameOnly && !t0.allDocs && t0.files.length > 1 &&
+    new Set(t0.files.map(classifyFile)).size > 1;
+
+  if (t0Ambiguous && diffOutput) {
+    t1 = analyzeT1(diffOutput, t0);
+  }
+
+  // When t1 is null (unambiguous diff), infer categories from t0
+  // so dynamic angle resolution can narrow for config-only / test-only etc.
+  if (!t1) {
+    t1 = {
+      changeCategories: inferCategoriesFromT0(t0),
+      hunkCount: 0,
+      lineStats: { added: 0, deleted: 0 },
+    };
+  }
+
+  const ambiguous = t0Ambiguous && (t1.changeCategories.length === 0 || t1.changeCategories.includes("LOGIC_CHANGE"));
+
+  return { t0, t1, ambiguous };
+}