@getcodesentinel/codesentinel 1.13.0 → 1.15.0

package/dist/index.js

@@ -1656,6 +1656,7 @@ var createReport = (snapshot, diff) => {
       confidence: repositoryConfidence(snapshot),
       dimensionScores: repositoryDimensionScores(snapshot)
     },
+    quality: snapshot.analysis.quality,
     hotspots: hotspotItems(snapshot),
     structural: {
       cycleCount: snapshot.analysis.structural.metrics.cycleCount,
@@ -1727,6 +1728,22 @@ var renderTextReport = (report) => {
   lines.push(`  external: ${report.repository.dimensionScores.external ?? "n/a"}`);
   lines.push(`  interactions: ${report.repository.dimensionScores.interactions ?? "n/a"}`);
   lines.push("");
+  lines.push("Quality Summary");
+  lines.push(`  qualityScore: ${report.quality.qualityScore}`);
+  lines.push(`  normalizedScore: ${report.quality.normalizedScore}`);
+  lines.push(`  modularity: ${report.quality.dimensions.modularity}`);
+  lines.push(`  changeHygiene: ${report.quality.dimensions.changeHygiene}`);
+  lines.push(`  testHealth: ${report.quality.dimensions.testHealth}`);
+  lines.push("  topIssues:");
+  for (const issue of report.quality.topIssues.slice(0, 5)) {
+    lines.push(
+      `    - [${issue.severity}] (${issue.dimension}) ${issue.id} @ ${issue.target}: ${issue.message}`
+    );
+  }
+  if (report.quality.topIssues.length === 0) {
+    lines.push("    - none");
+  }
+  lines.push("");
   lines.push("Top Hotspots");
   for (const hotspot of report.hotspots) {
     lines.push(`  - ${hotspot.target} | score=${hotspot.score}`);
@@ -1736,8 +1753,7 @@ var renderTextReport = (report) => {
       );
       lines.push(`    evidence: ${factor.evidence}`);
     }
-    lines.push(`    actions: ${hotspot.suggestedActions.join(" | ") || "none"}`);
-    lines.push(`    levers: ${hotspot.biggestLevers.join(" | ") || "none"}`);
+    lines.push(`    priority actions: ${hotspot.suggestedActions.join(" | ") || "none"}`);
   }
   lines.push("");
   lines.push("Structural Observations");
@@ -1803,6 +1819,23 @@ var renderMarkdownReport = (report) => {
   lines.push(`- external: \`${report.repository.dimensionScores.external ?? "n/a"}\``);
   lines.push(`- interactions: \`${report.repository.dimensionScores.interactions ?? "n/a"}\``);
   lines.push("");
+  lines.push("## Quality Summary");
+  lines.push(`- qualityScore: \`${report.quality.qualityScore}\``);
+  lines.push(`- normalizedScore: \`${report.quality.normalizedScore}\``);
+  lines.push(`- modularity: \`${report.quality.dimensions.modularity}\``);
+  lines.push(`- changeHygiene: \`${report.quality.dimensions.changeHygiene}\``);
+  lines.push(`- testHealth: \`${report.quality.dimensions.testHealth}\``);
+  if (report.quality.topIssues.length === 0) {
+    lines.push("- top issues: none");
+  } else {
+    lines.push("- top issues:");
+    for (const issue of report.quality.topIssues.slice(0, 5)) {
+      lines.push(
+        `  - [${issue.severity}] \`${issue.id}\` (\`${issue.dimension}\`) @ \`${issue.target}\`: ${issue.message}`
+      );
+    }
+  }
+  lines.push("");
   lines.push("## Top Hotspots");
   for (const hotspot of report.hotspots) {
     lines.push(`- **${hotspot.target}** (score: \`${hotspot.score}\`)`);
@@ -1813,8 +1846,7 @@ var renderMarkdownReport = (report) => {
       );
       lines.push(`  - evidence: \`${factor.evidence}\``);
     }
-    lines.push(`  - Suggested actions: ${hotspot.suggestedActions.join(" | ") || "none"}`);
-    lines.push(`  - Biggest levers: ${hotspot.biggestLevers.join(" | ") || "none"}`);
+    lines.push(`  - Priority actions: ${hotspot.suggestedActions.join(" | ") || "none"}`);
   }
   lines.push("");
   lines.push("## Structural Observations");
@@ -2461,6 +2493,7 @@ var resolveAutoBaselineRef = async (input) => {
 
 // src/index.ts
 import { readFileSync as readFileSync2 } from "fs";
+import { readFile as readFile6, writeFile as writeFile5 } from "fs/promises";
 import { dirname as dirname2, resolve as resolve5 } from "path";
 import { fileURLToPath } from "url";
 
@@ -2501,6 +2534,12 @@ var createSummaryShape = (summary) => ({
     })),
     fragileClusterCount: summary.risk.fragileClusters.length,
     dependencyAmplificationZoneCount: summary.risk.dependencyAmplificationZones.length
+  },
+  quality: {
+    qualityScore: summary.quality.qualityScore,
+    normalizedScore: summary.quality.normalizedScore,
+    dimensions: summary.quality.dimensions,
+    topIssues: summary.quality.topIssues.slice(0, 5)
   }
 });
 var formatAnalyzeOutput = (summary, mode) => mode === "json" ? JSON.stringify(summary, null, 2) : JSON.stringify(createSummaryShape(summary), null, 2);
@@ -2544,6 +2583,7 @@ var formatFactorLabel = (factorId) => factorLabelById2[factorId] ?? factorId;
 var formatNumber = (value) => value === null || value === void 0 ? "n/a" : `${value}`;
 var formatDimension = (value) => value === null ? "n/a" : `${value}`;
 var formatFactorSummary = (factor) => `${formatFactorLabel(factor.factorId)} (+${factor.contribution}, confidence=${factor.confidence})`;
+var formatFactorContribution = (factor) => `${formatFactorLabel(factor.factorId)}=${factor.contribution}`;
 var formatFactorEvidence = (factor) => {
   if (factor.factorId === "repository.structural") {
     return `structural dimension=${formatNumber(factor.rawMetrics["structuralDimension"])}`;
@@ -2676,20 +2716,15 @@ var renderText = (payload) => {
   lines.push("");
   lines.push("explanation:");
   lines.push(
-    `  why risky: ${repositoryTopFactors.map(formatFactorSummary).join("; ") || "insufficient data"}`
-  );
-  lines.push(
-    `  what specifically contributed: ${repositoryTopFactors.map((factor) => `${formatFactorLabel(factor.factorId)}=${factor.contribution}`).join(", ") || "insufficient data"}`
-  );
-  lines.push(
-    `  dominant factors: ${repositoryTopFactors.map((factor) => formatFactorLabel(factor.factorId)).join(", ") || "insufficient data"}`
+    `  key drivers: ${repositoryTopFactors.map(formatFactorSummary).join("; ") || "insufficient data"}`
   );
   lines.push(
-    `  intersected signals: ${compositeFactors.map((factor) => `${formatFactorLabel(factor.factorId)} [${formatFactorEvidence(factor)}]`).join("; ") || "none"}`
+    `  contributions: ${repositoryTopFactors.map(formatFactorContribution).join(", ") || "insufficient data"}`
   );
   lines.push(
-    `  what could reduce risk most: ${buildRepositoryActions(payload, repositoryTarget).join(" ")}`
+    `  interaction effects: ${compositeFactors.map((factor) => `${formatFactorLabel(factor.factorId)} [${formatFactorEvidence(factor)}]`).join("; ") || "none"}`
   );
+  lines.push(`  priority actions: ${buildRepositoryActions(payload, repositoryTarget).join(" ")}`);
   lines.push("");
   for (const target of payload.selectedTargets) {
     lines.push(renderTargetText(target));
@@ -2717,25 +2752,19 @@ var renderMarkdown = (payload) => {
   lines.push("");
   lines.push(`## Summary`);
   lines.push(
-    `- why risky: ${repositoryTopFactors.map(formatFactorSummary).join("; ") || "insufficient data"}`
+    `- key drivers: ${repositoryTopFactors.map(formatFactorSummary).join("; ") || "insufficient data"}`
   );
   lines.push(
-    `- what specifically contributed: ${repositoryTopFactors.map((factor) => `${formatFactorLabel(factor.factorId)}=${factor.contribution}`).join(", ") || "insufficient data"}`
+    `- contributions: ${repositoryTopFactors.map(formatFactorContribution).join(", ") || "insufficient data"}`
   );
   lines.push(
-    `- dominant factors: ${repositoryTopFactors.map((factor) => formatFactorLabel(factor.factorId)).join(", ") || "insufficient data"}`
-  );
-  lines.push(
-    `- intersected signals: ${compositeFactors.map((factor) => `${formatFactorLabel(factor.factorId)} [${formatFactorEvidence(factor)}]`).join("; ") || "none"}`
-  );
-  lines.push(
-    `- what could reduce risk most: ${buildRepositoryActions(payload, repositoryTarget).join(" ")}`
+    `- interaction effects: ${compositeFactors.map((factor) => `${formatFactorLabel(factor.factorId)} [${formatFactorEvidence(factor)}]`).join("; ") || "none"}`
   );
+  lines.push(`- priority actions: ${buildRepositoryActions(payload, repositoryTarget).join(" ")}`);
   lines.push("");
   for (const target of payload.selectedTargets) {
     lines.push(`## ${target.targetType}: \`${target.targetId}\``);
     lines.push(`- score: \`${target.totalScore}\` (\`${target.normalizedScore}\`)`);
-    lines.push(`- dominantFactors: \`${target.dominantFactors.join(", ")}\``);
     lines.push(`- Top factors:`);
     for (const factor of [...target.factors].sort(sortFactorByContribution).slice(0, 5)) {
       lines.push(
@@ -3187,7 +3216,8 @@ var checkForCliUpdates = async (input) => {
 };
 
 // src/application/run-analyze-command.ts
-import { resolve as resolve3 } from "path";
+import { readFile as readFile2 } from "fs/promises";
+import { join as join4, resolve as resolve3 } from "path";
 
 // ../code-graph/dist/index.js
 import { extname, isAbsolute, relative, resolve as resolve2 } from "path";
@@ -4235,6 +4265,208 @@ var analyzeRepositoryEvolutionFromGit = (input, onProgress) => {
   return analyzeRepositoryEvolution(input, historyProvider, onProgress);
 };
 
+// ../quality-engine/dist/index.js
+var clamp01 = (value) => {
+  if (!Number.isFinite(value)) {
+    return 0;
+  }
+  if (value <= 0) {
+    return 0;
+  }
+  if (value >= 1) {
+    return 1;
+  }
+  return value;
+};
+var round45 = (value) => Number(value.toFixed(4));
+var average = (values) => {
+  if (values.length === 0) {
+    return 0;
+  }
+  const total = values.reduce((sum, value) => sum + value, 0);
+  return total / values.length;
+};
+var concentration = (rawValues) => {
+  const values = rawValues.filter((value) => value > 0);
+  const count = values.length;
+  if (count <= 1) {
+    return 0;
+  }
+  const total = values.reduce((sum, value) => sum + value, 0);
+  if (total <= 0) {
+    return 0;
+  }
+  const hhi = values.reduce((sum, value) => {
+    const share = value / total;
+    return sum + share * share;
+  }, 0);
+  const minHhi = 1 / count;
+  const normalized = (hhi - minHhi) / (1 - minHhi);
+  return clamp01(normalized);
+};
+var DIMENSION_WEIGHTS = {
+  modularity: 0.45,
+  changeHygiene: 0.35,
+  testHealth: 0.2
+};
+var TODO_FIXME_MAX_IMPACT = 0.08;
+var toPercentage = (normalizedQuality) => round45(clamp01(normalizedQuality) * 100);
+var filePaths = (structural) => structural.files.map((file) => file.relativePath);
+var isTestPath = (path) => {
+  const normalized = path.toLowerCase();
+  return normalized.includes("/__tests__/") || normalized.includes("\\__tests__\\") || normalized.includes(".test.") || normalized.includes(".spec.");
+};
+var isSourcePath = (path) => {
+  if (path.endsWith(".d.ts")) {
+    return false;
+  }
+  return !isTestPath(path);
+};
+var pushIssue = (issues, issue) => {
+  issues.push({
+    ...issue,
+    severity: issue.severity ?? "warn"
+  });
+};
+var computeRepositoryQualitySummary = (input) => {
+  const issues = [];
+  const sourceFileSet = new Set(input.structural.files.map((file) => file.relativePath));
+  const cycleCount = input.structural.metrics.cycleCount;
+  const cycleSizeAverage = input.structural.cycles.length === 0 ? 0 : average(input.structural.cycles.map((cycle) => cycle.nodes.length));
+  const cyclePenalty = clamp01(cycleCount / 6) * 0.7 + clamp01((cycleSizeAverage - 2) / 8) * 0.3;
+  if (cycleCount > 0) {
+    pushIssue(issues, {
+      id: "quality.modularity.structural_cycles",
+      dimension: "modularity",
+      target: input.structural.cycles[0]?.nodes.slice().sort((a, b) => a.localeCompare(b)).join(" -> ") ?? input.structural.targetPath,
+      message: `${cycleCount} structural cycle(s) increase coupling and refactor cost.`,
+      severity: cycleCount >= 3 ? "error" : "warn",
+      impact: round45(cyclePenalty * 0.6)
+    });
+  }
+  const fanInConcentration = concentration(input.structural.files.map((file) => file.fanIn));
+  const fanOutConcentration = concentration(input.structural.files.map((file) => file.fanOut));
+  const centralityConcentration = average([fanInConcentration, fanOutConcentration]);
+  if (centralityConcentration >= 0.5) {
+    const hottest = [...input.structural.files].map((file) => ({
+      path: file.relativePath,
+      pressure: file.fanIn + file.fanOut
+    })).sort((a, b) => b.pressure - a.pressure || a.path.localeCompare(b.path))[0];
+    pushIssue(issues, {
+      id: "quality.modularity.centrality_concentration",
+      dimension: "modularity",
+      target: hottest?.path ?? input.structural.targetPath,
+      message: "Fan-in/fan-out pressure is concentrated in a small set of files.",
+      impact: round45(centralityConcentration * 0.5)
+    });
+  }
+  let churnConcentration = 0;
+  let volatilityConcentration = 0;
+  let couplingDensity = 0;
+  let couplingIntensity = 0;
+  if (input.evolution.available) {
+    const evolutionSourceFiles = input.evolution.files.filter(
+      (file) => sourceFileSet.has(file.filePath)
+    );
+    churnConcentration = concentration(evolutionSourceFiles.map((file) => file.churnTotal));
+    volatilityConcentration = concentration(
+      evolutionSourceFiles.map((file) => file.recentVolatility)
+    );
+    const fileCount = Math.max(1, evolutionSourceFiles.length);
+    const maxPairs = fileCount * (fileCount - 1) / 2;
+    const sourcePairs = input.evolution.coupling.pairs.filter(
+      (pair) => sourceFileSet.has(pair.fileA) && sourceFileSet.has(pair.fileB)
+    );
+    couplingDensity = maxPairs <= 0 ? 0 : clamp01(sourcePairs.length / maxPairs);
+    couplingIntensity = average(sourcePairs.map((pair) => pair.couplingScore));
+    if (churnConcentration >= 0.45) {
+      const mostChurn = [...evolutionSourceFiles].sort(
+        (a, b) => b.churnTotal - a.churnTotal || a.filePath.localeCompare(b.filePath)
+      )[0];
+      pushIssue(issues, {
+        id: "quality.change_hygiene.churn_concentration",
+        dimension: "changeHygiene",
+        target: mostChurn?.filePath ?? input.structural.targetPath,
+        message: "Churn is concentrated in a narrow part of the codebase.",
+        impact: round45(churnConcentration * 0.45)
+      });
+    }
+    if (volatilityConcentration >= 0.45) {
+      const volatileFile = [...evolutionSourceFiles].sort(
+        (a, b) => b.recentVolatility - a.recentVolatility || a.filePath.localeCompare(b.filePath)
+      )[0];
+      pushIssue(issues, {
+        id: "quality.change_hygiene.volatility_concentration",
+        dimension: "changeHygiene",
+        target: volatileFile?.filePath ?? input.structural.targetPath,
+        message: "Recent volatility is concentrated in files that change frequently.",
+        impact: round45(volatilityConcentration * 0.4)
+      });
+    }
+    if (couplingDensity >= 0.35 || couplingIntensity >= 0.45) {
+      const strongestPair = [...sourcePairs].sort(
+        (a, b) => b.couplingScore - a.couplingScore || `${a.fileA}|${a.fileB}`.localeCompare(`${b.fileA}|${b.fileB}`)
+      )[0];
+      pushIssue(issues, {
+        id: "quality.change_hygiene.coupling_density",
+        dimension: "changeHygiene",
+        target: strongestPair === void 0 ? input.structural.targetPath : `${strongestPair.fileA}<->${strongestPair.fileB}`,
+        message: "Co-change relationships are dense, increasing coordination overhead.",
+        impact: round45(average([couplingDensity, couplingIntensity]) * 0.35)
+      });
+    }
+  }
+  const modularityPenalty = clamp01(cyclePenalty * 0.55 + centralityConcentration * 0.45);
+  const changeHygienePenalty = input.evolution.available ? clamp01(
+    churnConcentration * 0.4 + volatilityConcentration * 0.35 + couplingDensity * 0.15 + couplingIntensity * 0.1
+  ) : 0.25;
+  const paths = filePaths(input.structural);
+  const testFiles = paths.filter((path) => isTestPath(path)).length;
+  const sourceFiles = paths.filter((path) => isSourcePath(path)).length;
+  const testRatio = sourceFiles <= 0 ? 1 : testFiles / sourceFiles;
+  const testPresencePenalty = sourceFiles <= 0 ? 0 : 1 - clamp01(testRatio / 0.3);
+  if (sourceFiles > 0 && testRatio < 0.2) {
+    pushIssue(issues, {
+      id: "quality.test_health.low_test_presence",
+      dimension: "testHealth",
+      target: input.structural.targetPath,
+      message: `Detected ${testFiles} test file(s) for ${sourceFiles} source file(s).`,
+      severity: testRatio === 0 ? "error" : "warn",
+      impact: round45(testPresencePenalty * 0.5)
+    });
+  }
+  const todoFixmeCount = Math.max(0, input.todoFixmeCount ?? 0);
+  const todoFixmePenalty = clamp01(todoFixmeCount / 120) * TODO_FIXME_MAX_IMPACT;
+  if (todoFixmeCount > 0) {
+    pushIssue(issues, {
+      id: "quality.change_hygiene.todo_fixme_load",
+      dimension: "changeHygiene",
+      target: input.structural.targetPath,
+      message: `Found ${todoFixmeCount} TODO/FIXME marker(s); cleanup debt is accumulating.`,
+      impact: round45(todoFixmePenalty * 0.2)
+    });
+  }
+  const modularityQuality = clamp01(1 - modularityPenalty);
+  const changeHygieneQuality = clamp01(1 - clamp01(changeHygienePenalty + todoFixmePenalty));
+  const testHealthQuality = clamp01(1 - testPresencePenalty);
+  const normalizedScore = clamp01(
+    modularityQuality * DIMENSION_WEIGHTS.modularity + changeHygieneQuality * DIMENSION_WEIGHTS.changeHygiene + testHealthQuality * DIMENSION_WEIGHTS.testHealth
+  );
+  const topIssues = [...issues].sort(
+    (a, b) => b.impact - a.impact || a.id.localeCompare(b.id) || a.target.localeCompare(b.target)
+  ).slice(0, 8).map(({ impact: _impact, ...issue }) => issue);
+  return {
+    qualityScore: toPercentage(normalizedScore),
+    normalizedScore: round45(normalizedScore),
+    dimensions: {
+      modularity: toPercentage(modularityQuality),
+      changeHygiene: toPercentage(changeHygieneQuality),
+      testHealth: toPercentage(testHealthQuality)
+    },
+    topIssues
+  };
+};
+
 // ../risk-engine/dist/index.js
 var DEFAULT_RISK_ENGINE_CONFIG = {
   // Base dimensional influence. Risk is never dominated by a single dimension by default.
@@ -4320,8 +4552,8 @@ var DEFAULT_RISK_ENGINE_CONFIG = {
   }
 };
 var toUnitInterval = (value) => Number.isFinite(value) ? Math.min(1, Math.max(0, value)) : 0;
-var round45 = (value) => Number(value.toFixed(4));
-var average = (values) => {
+var round46 = (value) => Number(value.toFixed(4));
+var average2 = (values) => {
   if (values.length === 0) {
     return 0;
   }
@@ -4429,14 +4661,14 @@ var computeAggregatorAttenuation = (input) => {
   const fanOutSignal = toUnitInterval((fanOut - config.minFanOut) / Math.max(1, config.minFanOut));
   const lowChurnPerCommitSignal = 1 - toUnitInterval(churnPerCommit / config.maxChurnPerCommit);
   const lowChurnPerDependencySignal = 1 - toUnitInterval(churnPerDependency / config.maxChurnPerDependency);
-  const attenuationConfidence = average([
+  const attenuationConfidence = average2([
     fanInSignal,
     fanOutSignal,
     lowChurnPerCommitSignal,
     lowChurnPerDependencySignal
   ]);
   const reduction = toUnitInterval(config.maxStructuralReduction) * attenuationConfidence;
-  return round45(toUnitInterval(1 - reduction));
+  return round46(toUnitInterval(1 - reduction));
 };
 var dependencySignalWeights = {
   single_maintainer: 0.3,
@@ -4466,12 +4698,12 @@ var computeDependencySignalScore = (ownSignals, inheritedSignals, inheritedSigna
   }
   return toUnitInterval(weightedTotal / maxWeightedTotal);
 };
-var clampConfidence = (value) => round45(toUnitInterval(value));
+var clampConfidence = (value) => round46(toUnitInterval(value));
 var computeExternalMetadataConfidence = (external) => {
   if (!external.available) {
     return 0;
   }
-  return round45(toUnitInterval(0.35 + external.metrics.metadataCoverage * 0.65));
+  return round46(toUnitInterval(0.35 + external.metrics.metadataCoverage * 0.65));
 };
 var computeEvolutionHistoryConfidence = (structural, evolution, evolutionByFile) => {
   if (!evolution.available) {
@@ -4488,7 +4720,7 @@ var computeEvolutionHistoryConfidence = (structural, evolution, evolutionByFile)
     }
   }
   const coverage = coveredFiles / totalFiles;
-  return round45(toUnitInterval(0.3 + coverage * 0.7));
+  return round46(toUnitInterval(0.3 + coverage * 0.7));
 };
 var buildFactorTraces = (totalScore, inputs) => {
   const positiveInputs = inputs.filter((input) => input.strength > 0);
@@ -4526,7 +4758,7 @@ var buildFactorTraces = (totalScore, inputs) => {
       continue;
     }
     if (index === scored.length - 1) {
-      const remaining = round45(totalScore - distributed);
+      const remaining = round46(totalScore - distributed);
       traces[traceIndex] = {
         ...existing,
         contribution: Math.max(0, remaining)
@@ -4534,7 +4766,7 @@ var buildFactorTraces = (totalScore, inputs) => {
       distributed += Math.max(0, remaining);
       continue;
     }
-    const rounded = round45(current.contribution);
+    const rounded = round46(current.contribution);
     traces[traceIndex] = {
       ...existing,
       contribution: rounded
@@ -4545,15 +4777,15 @@ var buildFactorTraces = (totalScore, inputs) => {
 };
 var buildReductionLevers = (factors) => factors.filter((factor) => factor.contribution > 0).sort((a, b) => b.contribution - a.contribution || a.factorId.localeCompare(b.factorId)).slice(0, 3).map((factor) => ({
   factorId: factor.factorId,
-  estimatedImpact: round45(factor.contribution)
+  estimatedImpact: round46(factor.contribution)
 }));
 var buildTargetTrace = (targetType, targetId, totalScore, normalizedScore, factors) => {
   const dominantFactors = [...factors].filter((factor) => factor.contribution > 0).sort((a, b) => b.contribution - a.contribution || a.factorId.localeCompare(b.factorId)).slice(0, 3).map((factor) => factor.factorId);
   return {
     targetType,
     targetId,
-    totalScore: round45(totalScore),
-    normalizedScore: round45(normalizedScore),
+    totalScore: round46(totalScore),
+    normalizedScore: round46(normalizedScore),
     factors,
     dominantFactors,
     reductionLevers: buildReductionLevers(factors)
@@ -4627,14 +4859,14 @@ var computeDependencyScores = (external, config) => {
     ].filter((value) => value !== null).length;
     const confidence = toUnitInterval((0.5 + availableMetricCount * 0.125) * metadataConfidence);
     dependencyContexts.set(dependency.name, {
-      signalScore: round45(signalScore),
-      stalenessRisk: round45(stalenessRisk),
-      maintainerConcentrationRisk: round45(maintainerConcentrationRisk),
-      transitiveBurdenRisk: round45(transitiveBurdenRisk),
-      centralityRisk: round45(centralityRisk),
-      chainDepthRisk: round45(chainDepthRisk),
-      busFactorRisk: round45(busFactorRisk),
-      popularityDampener: round45(popularityDampener),
+      signalScore: round46(signalScore),
+      stalenessRisk: round46(stalenessRisk),
+      maintainerConcentrationRisk: round46(maintainerConcentrationRisk),
+      transitiveBurdenRisk: round46(transitiveBurdenRisk),
+      centralityRisk: round46(centralityRisk),
+      chainDepthRisk: round46(chainDepthRisk),
+      busFactorRisk: round46(busFactorRisk),
+      popularityDampener: round46(popularityDampener),
       rawMetrics: {
         daysSinceLastRelease: dependency.daysSinceLastRelease,
         maintainerCount: dependency.maintainerCount,
@@ -4644,12 +4876,12 @@ var computeDependencyScores = (external, config) => {
         busFactor: dependency.busFactor,
         weeklyDownloads: dependency.weeklyDownloads
       },
-      confidence: round45(confidence)
+      confidence: round46(confidence)
     });
     return {
       dependency: dependency.name,
-      score: round45(normalizedScore * 100),
-      normalizedScore: round45(normalizedScore),
+      score: round46(normalizedScore * 100),
+      normalizedScore: round46(normalizedScore),
       ownRiskSignals: dependency.ownRiskSignals,
       inheritedRiskSignals: dependency.inheritedRiskSignals
     };
@@ -4658,7 +4890,7 @@ var computeDependencyScores = (external, config) => {
   );
   const normalizedValues = dependencyScores.map((score) => score.normalizedScore);
   const highDependencyRisk = dependencyScores.length === 0 ? 0 : percentile(normalizedValues, config.externalDimension.topDependencyPercentile);
-  const averageDependencyRisk = average(normalizedValues);
+  const averageDependencyRisk = average2(normalizedValues);
   const depthRisk = halfLifeRisk(
     external.metrics.dependencyDepth,
     config.externalDimension.dependencyDepthHalfLife
@@ -4668,7 +4900,7 @@ var computeDependencyScores = (external, config) => {
   );
   return {
     dependencyScores,
-    repositoryExternalPressure: round45(repositoryExternalPressure),
+    repositoryExternalPressure: round46(repositoryExternalPressure),
     dependencyContexts
   };
 };
@@ -4729,11 +4961,11 @@ var buildFragileClusters = (structural, evolution, fileScoresByFile, config) =>
       continue;
     }
     files.sort((a, b) => a.localeCompare(b));
-    const averageRisk = average(
+    const averageRisk = average2(
       files.map((filePath) => fileScoresByFile.get(filePath)?.normalizedScore ?? 0)
     );
     const cycleSizeRisk = toUnitInterval((files.length - 1) / 5);
-    const score = round45(toUnitInterval(averageRisk * 0.75 + cycleSizeRisk * 0.25) * 100);
+    const score = round46(toUnitInterval(averageRisk * 0.75 + cycleSizeRisk * 0.25) * 100);
     cycleClusterCount += 1;
     clusters.push({
       id: `cycle:${cycleClusterCount}`,
@@ -4803,11 +5035,11 @@ var buildFragileClusters = (structural, evolution, fileScoresByFile, config) =>
       const componentPairs = selectedPairs.filter(
         (pair) => fileSet.has(pair.fileA) && fileSet.has(pair.fileB)
       );
-      const meanFileRisk = average(
+      const meanFileRisk = average2(
         files.map((filePath) => fileScoresByFile.get(filePath)?.normalizedScore ?? 0)
       );
-      const meanCoupling = average(componentPairs.map((pair) => pair.couplingScore));
-      const score = round45(toUnitInterval(meanFileRisk * 0.65 + meanCoupling * 0.35) * 100);
+      const meanCoupling = average2(componentPairs.map((pair) => pair.couplingScore));
+      const score = round46(toUnitInterval(meanFileRisk * 0.65 + meanCoupling * 0.35) * 100);
       couplingClusterCount += 1;
       clusters.push({
         id: `coupling:${couplingClusterCount}`,
@@ -4918,21 +5150,21 @@ var computeRiskSummary = (structural, evolution, external, config, traceCollecto
     const normalizedScore = saturatingComposite(baseline, interactions);
     return {
       file: filePath,
-      score: round45(normalizedScore * 100),
-      normalizedScore: round45(normalizedScore),
+      score: round46(normalizedScore * 100),
+      normalizedScore: round46(normalizedScore),
       factors: {
-        structural: round45(structuralFactor),
-        evolution: round45(evolutionFactor),
-        external: round45(externalFactor)
+        structural: round46(structuralFactor),
+        evolution: round46(evolutionFactor),
+        external: round46(externalFactor)
       },
-      structuralCentrality: round45(structuralCentrality),
+      structuralCentrality: round46(structuralCentrality),
       traceTerms: {
-        structuralBase: round45(structuralBase),
-        evolutionBase: round45(evolutionBase),
-        externalBase: round45(externalBase),
-        interactionStructuralEvolution: round45(interactionStructuralEvolution),
-        interactionCentralInstability: round45(interactionCentralInstability),
-        interactionDependencyAmplification: round45(interactionDependencyAmplification)
+        structuralBase: round46(structuralBase),
+        evolutionBase: round46(evolutionBase),
+        externalBase: round46(externalBase),
+        interactionStructuralEvolution: round46(interactionStructuralEvolution),
+        interactionCentralInstability: round46(interactionCentralInstability),
+        interactionDependencyAmplification: round46(interactionDependencyAmplification)
       },
       rawMetrics: {
         fanIn: file.fanIn,
@@ -4944,19 +5176,19 @@ var computeRiskSummary = (structural, evolution, external, config, traceCollecto
         recentVolatility: evolutionMetrics?.recentVolatility ?? null,
         topAuthorShare: evolutionMetrics?.topAuthorShare ?? null,
         busFactor: evolutionMetrics?.busFactor ?? null,
-        dependencyAffinity: round45(dependencyAffinity),
-        repositoryExternalPressure: round45(dependencyComputation.repositoryExternalPressure),
-        structuralAttenuation: round45(structuralAttenuation)
+        dependencyAffinity: round46(dependencyAffinity),
+        repositoryExternalPressure: round46(dependencyComputation.repositoryExternalPressure),
+        structuralAttenuation: round46(structuralAttenuation)
       },
       normalizedMetrics: {
-        fanInRisk: round45(fanInRisk),
-        fanOutRisk: round45(fanOutRisk),
-        depthRisk: round45(depthRisk),
-        frequencyRisk: round45(frequencyRisk),
-        churnRisk: round45(churnRisk),
-        volatilityRisk: round45(volatilityRisk),
-        ownershipConcentrationRisk: round45(ownershipConcentrationRisk),
-        busFactorRisk: round45(busFactorRisk)
+        fanInRisk: round46(fanInRisk),
+        fanOutRisk: round46(fanOutRisk),
+        depthRisk: round46(depthRisk),
+        frequencyRisk: round46(frequencyRisk),
+        churnRisk: round46(churnRisk),
+        volatilityRisk: round46(volatilityRisk),
+        ownershipConcentrationRisk: round46(ownershipConcentrationRisk),
+        busFactorRisk: round46(busFactorRisk)
       }
     };
   }).sort((a, b) => b.score - a.score || a.file.localeCompare(b.file));
@@ -5082,29 +5314,29 @@ var computeRiskSummary = (structural, evolution, external, config, traceCollecto
     moduleFiles.set(moduleName, values);
   }
   const moduleScores = [...moduleFiles.entries()].map(([module, values]) => {
-    const averageScore = average(values);
+    const averageScore = average2(values);
     const peakScore = values.reduce((max, value) => Math.max(max, value), 0);
     const normalizedScore = toUnitInterval(averageScore * 0.65 + peakScore * 0.35);
     return {
       module,
-      score: round45(normalizedScore * 100),
-      normalizedScore: round45(normalizedScore),
+      score: round46(normalizedScore * 100),
+      normalizedScore: round46(normalizedScore),
       fileCount: values.length
     };
   }).sort((a, b) => b.score - a.score || a.module.localeCompare(b.module));
   if (collector !== void 0) {
     for (const [module, values] of moduleFiles.entries()) {
-      const averageScore = average(values);
+      const averageScore = average2(values);
       const peakScore = values.reduce((max, value) => Math.max(max, value), 0);
       const normalizedScore = toUnitInterval(averageScore * 0.65 + peakScore * 0.35);
-      const totalScore = round45(normalizedScore * 100);
+      const totalScore = round46(normalizedScore * 100);
       const factors = buildFactorTraces(totalScore, [
         {
           factorId: "module.average_file_risk",
           family: "composite",
           strength: averageScore * 0.65,
-          rawMetrics: { averageFileRisk: round45(averageScore), fileCount: values.length },
-          normalizedMetrics: { normalizedModuleRisk: round45(normalizedScore) },
+          rawMetrics: { averageFileRisk: round46(averageScore), fileCount: values.length },
+          normalizedMetrics: { normalizedModuleRisk: round46(normalizedScore) },
           weight: 0.65,
           amplification: null,
           evidence: [{ kind: "repository_metric", metric: "moduleAggregation.average" }],
@@ -5114,8 +5346,8 @@ var computeRiskSummary = (structural, evolution, external, config, traceCollecto
           factorId: "module.peak_file_risk",
           family: "composite",
           strength: peakScore * 0.35,
-          rawMetrics: { peakFileRisk: round45(peakScore), fileCount: values.length },
-          normalizedMetrics: { normalizedModuleRisk: round45(normalizedScore) },
+          rawMetrics: { peakFileRisk: round46(peakScore), fileCount: values.length },
+          normalizedMetrics: { normalizedModuleRisk: round46(normalizedScore) },
           weight: 0.35,
           amplification: null,
           evidence: [{ kind: "repository_metric", metric: "moduleAggregation.peak" }],
@@ -5138,12 +5370,12 @@ var computeRiskSummary = (structural, evolution, external, config, traceCollecto
     const normalizedZoneScore = toUnitInterval(intensity * 0.7 + fileScore.normalizedScore * 0.3);
     return {
       file: fileScore.file,
-      score: round45(normalizedZoneScore * 100),
+      score: round46(normalizedZoneScore * 100),
       externalPressure: fileScore.factors.external
     };
   }).filter((zone) => external.available && zone.externalPressure >= pressureThreshold).sort((a, b) => b.score - a.score || a.file.localeCompare(b.file)).slice(0, config.amplificationZone.maxZones).map((zone) => ({
     ...zone,
-    externalPressure: round45(zone.externalPressure)
+    externalPressure: round46(zone.externalPressure)
   }));
   if (collector !== void 0 && external.available) {
     const dependencyByName = new Map(
@@ -5256,16 +5488,16 @@ var computeRiskSummary = (structural, evolution, external, config, traceCollecto
       );
     }
   }
-  const structuralDimension = average(fileScores.map((fileScore) => fileScore.factors.structural));
-  const evolutionDimension = average(fileScores.map((fileScore) => fileScore.factors.evolution));
+  const structuralDimension = average2(fileScores.map((fileScore) => fileScore.factors.structural));
+  const evolutionDimension = average2(fileScores.map((fileScore) => fileScore.factors.evolution));
   const externalDimension = dependencyComputation.repositoryExternalPressure;
   const topCentralSlice = Math.max(1, Math.ceil(fileRiskContexts.length * 0.1));
-  const criticalInstability = average(
+  const criticalInstability = average2(
     [...fileRiskContexts].sort(
       (a, b) => b.structuralCentrality * b.factors.evolution - a.structuralCentrality * a.factors.evolution || a.file.localeCompare(b.file)
     ).slice(0, topCentralSlice).map((context) => context.structuralCentrality * context.factors.evolution)
   );
-  const dependencyAmplification = average(
+  const dependencyAmplification = average2(
     dependencyAmplificationZones.map(
       (zone) => toUnitInterval(zone.externalPressure * zone.score / 100)
     )
@@ -5276,15 +5508,15 @@ var computeRiskSummary = (structural, evolution, external, config, traceCollecto
     criticalInstability * config.interactionWeights.centralInstability,
     dependencyAmplification * config.interactionWeights.dependencyAmplification
   ]);
-  const riskScore = round45(repositoryNormalizedScore * 100);
+  const riskScore = round46(repositoryNormalizedScore * 100);
   if (collector !== void 0) {
     const repositoryFactors = buildFactorTraces(riskScore, [
       {
         factorId: "repository.structural",
         family: "structural",
         strength: structuralDimension * dimensionWeights.structural,
-        rawMetrics: { structuralDimension: round45(structuralDimension) },
-        normalizedMetrics: { dimensionWeight: round45(dimensionWeights.structural) },
+        rawMetrics: { structuralDimension: round46(structuralDimension) },
+        normalizedMetrics: { dimensionWeight: round46(dimensionWeights.structural) },
         weight: dimensionWeights.structural,
         amplification: null,
         evidence: [{ kind: "repository_metric", metric: "structuralDimension" }],
@@ -5294,8 +5526,8 @@ var computeRiskSummary = (structural, evolution, external, config, traceCollecto
         factorId: "repository.evolution",
         family: "evolution",
         strength: evolutionDimension * dimensionWeights.evolution,
-        rawMetrics: { evolutionDimension: round45(evolutionDimension) },
-        normalizedMetrics: { dimensionWeight: round45(dimensionWeights.evolution) },
+        rawMetrics: { evolutionDimension: round46(evolutionDimension) },
+        normalizedMetrics: { dimensionWeight: round46(dimensionWeights.evolution) },
         weight: dimensionWeights.evolution,
         amplification: null,
         evidence: [{ kind: "repository_metric", metric: "evolutionDimension" }],
@@ -5305,8 +5537,8 @@ var computeRiskSummary = (structural, evolution, external, config, traceCollecto
         factorId: "repository.external",
         family: "external",
         strength: externalDimension * dimensionWeights.external,
-        rawMetrics: { externalDimension: round45(externalDimension) },
-        normalizedMetrics: { dimensionWeight: round45(dimensionWeights.external) },
+        rawMetrics: { externalDimension: round46(externalDimension) },
+        normalizedMetrics: { dimensionWeight: round46(dimensionWeights.external) },
         weight: dimensionWeights.external,
         amplification: null,
         evidence: [{ kind: "repository_metric", metric: "externalDimension" }],
@@ -5317,19 +5549,19 @@ var computeRiskSummary = (structural, evolution, external, config, traceCollecto
         family: "composite",
         strength: structuralDimension * evolutionDimension * config.interactionWeights.structuralEvolution + criticalInstability * config.interactionWeights.centralInstability + dependencyAmplification * config.interactionWeights.dependencyAmplification,
         rawMetrics: {
-          structuralEvolution: round45(
+          structuralEvolution: round46(
             structuralDimension * evolutionDimension * config.interactionWeights.structuralEvolution
           ),
-          centralInstability: round45(
+          centralInstability: round46(
             criticalInstability * config.interactionWeights.centralInstability
           ),
-          dependencyAmplification: round45(
+          dependencyAmplification: round46(
             dependencyAmplification * config.interactionWeights.dependencyAmplification
           )
         },
         normalizedMetrics: {
-          criticalInstability: round45(criticalInstability),
-          dependencyAmplification: round45(dependencyAmplification)
+          criticalInstability: round46(criticalInstability),
+          dependencyAmplification: round46(dependencyAmplification)
         },
         weight: null,
         amplification: config.interactionWeights.structuralEvolution + config.interactionWeights.centralInstability + config.interactionWeights.dependencyAmplification,
@@ -5349,7 +5581,7 @@ var computeRiskSummary = (structural, evolution, external, config, traceCollecto
   }
   return {
     riskScore,
-    normalizedScore: round45(repositoryNormalizedScore),
+    normalizedScore: round46(repositoryNormalizedScore),
     hotspots,
     fragileClusters,
     dependencyAmplificationZones,
@@ -5472,6 +5704,28 @@ var evaluateRepositoryRisk = (input, options = {}) => {
   };
 };
 
+// src/application/todo-fixme-counter.ts
+import * as ts2 from "typescript";
+var markerRegex = /\b(?:TODO|FIXME)\b/gi;
+var countMarkers = (text) => text.match(markerRegex)?.length ?? 0;
+var countTodoFixmeInComments = (content) => {
+  const scanner = ts2.createScanner(
+    ts2.ScriptTarget.Latest,
+    false,
+    ts2.LanguageVariant.Standard,
+    content
+  );
+  let total = 0;
+  let token = scanner.scan();
+  while (token !== ts2.SyntaxKind.EndOfFileToken) {
+    if (token === ts2.SyntaxKind.SingleLineCommentTrivia || token === ts2.SyntaxKind.MultiLineCommentTrivia) {
+      total += countMarkers(scanner.getTokenText());
+    }
+    token = scanner.scan();
+  }
+  return total;
+};
+
 // src/application/run-analyze-command.ts
 var resolveTargetPath = (inputPath, cwd) => resolve3(cwd, inputPath ?? ".");
 var riskProfileConfig = {
@@ -5600,6 +5854,18 @@ var createEvolutionProgressReporter = (logger) => {
     }
   };
 };
+var collectTodoFixmeCount = async (targetPath, structural) => {
+  const filePaths2 = [...structural.files].map((file) => file.relativePath).sort((a, b) => a.localeCompare(b));
+  let total = 0;
+  for (const relativePath of filePaths2) {
+    try {
+      const content = await readFile2(join4(targetPath, relativePath), "utf8");
+      total += countTodoFixmeInComments(content);
+    } catch {
+    }
+  }
+  return total;
+};
 var collectAnalysisInputs = async (inputPath, authorIdentityMode, options = {}, logger = createSilentLogger()) => {
   const invocationCwd = process.env["INIT_CWD"] ?? process.cwd();
   const targetPath = resolveTargetPath(inputPath, invocationCwd);
@@ -5642,10 +5908,14 @@ var collectAnalysisInputs = async (inputPath, authorIdentityMode, options = {},
   } else {
     logger.warn(`external analysis unavailable: ${external.reason}`);
   }
+  logger.info("collecting quality text signals");
+  const todoFixmeCount = await collectTodoFixmeCount(targetPath, structural);
+  logger.debug(`quality text signals: todoFixmeCount=${todoFixmeCount}`);
   return {
     structural,
     evolution,
-    external
+    external,
+    todoFixmeCount
   };
 };
 var runAnalyzeCommand = async (inputPath, authorIdentityMode, options = {}, logger = createSilentLogger()) => {
@@ -5658,18 +5928,30 @@ var runAnalyzeCommand = async (inputPath, authorIdentityMode, options = {}, logg
   logger.info("computing risk summary");
   const riskConfig = resolveRiskConfigForProfile(options.riskProfile);
   const risk = computeRepositoryRiskSummary({
-    ...analysisInputs,
+    structural: analysisInputs.structural,
+    evolution: analysisInputs.evolution,
+    external: analysisInputs.external,
     ...riskConfig === void 0 ? {} : { config: riskConfig }
   });
-  logger.info(`analysis completed (riskScore=${risk.riskScore})`);
+  const quality = computeRepositoryQualitySummary({
+    structural: analysisInputs.structural,
+    evolution: analysisInputs.evolution,
+    todoFixmeCount: analysisInputs.todoFixmeCount
+  });
+  logger.info(
+    `analysis completed (riskScore=${risk.riskScore}, qualityScore=${quality.qualityScore})`
+  );
   return {
-    ...analysisInputs,
-    risk
+    structural: analysisInputs.structural,
+    evolution: analysisInputs.evolution,
+    external: analysisInputs.external,
+    risk,
+    quality
   };
 };
 
 // src/application/run-check-command.ts
-import { readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
+import { readFile as readFile3, writeFile as writeFile2 } from "fs/promises";
 
 // src/application/build-analysis-snapshot.ts
 var buildAnalysisSnapshot = async (inputPath, authorIdentityMode, options, logger) => {
@@ -5684,14 +5966,23 @@ var buildAnalysisSnapshot = async (inputPath, authorIdentityMode, options, logge
   const riskConfig = resolveRiskConfigForProfile(options.riskProfile);
   const evaluation = evaluateRepositoryRisk(
     {
-      ...analysisInputs,
+      structural: analysisInputs.structural,
+      evolution: analysisInputs.evolution,
+      external: analysisInputs.external,
       ...riskConfig === void 0 ? {} : { config: riskConfig }
     },
     { explain: options.includeTrace }
   );
   const summary = {
-    ...analysisInputs,
-    risk: evaluation.summary
+    structural: analysisInputs.structural,
+    evolution: analysisInputs.evolution,
+    external: analysisInputs.external,
+    risk: evaluation.summary,
+    quality: computeRepositoryQualitySummary({
+      structural: analysisInputs.structural,
+      evolution: analysisInputs.evolution,
+      todoFixmeCount: analysisInputs.todoFixmeCount
+    })
   };
   return createSnapshot({
     analysis: summary,
@@ -5743,7 +6034,7 @@ var runCheckCommand = async (inputPath, authorIdentityMode, options, logger = cr
   let diff;
   if (options.baselinePath !== void 0) {
     logger.info(`loading baseline snapshot: ${options.baselinePath}`);
-    const baselineRaw = await readFile2(options.baselinePath, "utf8");
+    const baselineRaw = await readFile3(options.baselinePath, "utf8");
     try {
       baseline = parseSnapshot(baselineRaw);
     } catch (error) {
@@ -5782,7 +6073,7 @@ var runCheckCommand = async (inputPath, authorIdentityMode, options, logger = cr
 };
 
 // src/application/run-ci-command.ts
-import { readFile as readFile3, writeFile as writeFile3 } from "fs/promises";
+import { readFile as readFile4, writeFile as writeFile3 } from "fs/promises";
 import { relative as relative2, resolve as resolve4 } from "path";
 var isPathOutsideBase = (value) => {
   return value === ".." || value.startsWith("../") || value.startsWith("..\\");
@@ -5882,7 +6173,7 @@ var runCiCommand = async (inputPath, authorIdentityMode, options, logger = creat
     diff = compareSnapshots(current, baseline);
   } else if (options.baselinePath !== void 0) {
     logger.info(`loading baseline snapshot: ${options.baselinePath}`);
-    const baselineRaw = await readFile3(options.baselinePath, "utf8");
+    const baselineRaw = await readFile4(options.baselinePath, "utf8");
     try {
       baseline = parseSnapshot(baselineRaw);
     } catch (error) {
@@ -5930,7 +6221,7 @@ ${ciMarkdown}`;
 };
 
 // src/application/run-report-command.ts
-import { readFile as readFile4, writeFile as writeFile4 } from "fs/promises";
+import { readFile as readFile5, writeFile as writeFile4 } from "fs/promises";
 var runReportCommand = async (inputPath, authorIdentityMode, options, logger = createSilentLogger()) => {
   logger.info("building analysis snapshot");
   const current = await buildAnalysisSnapshot(
@@ -5952,7 +6243,7 @@ var runReportCommand = async (inputPath, authorIdentityMode, options, logger = c
     report = createReport(current);
   } else {
     logger.info(`loading baseline snapshot: ${options.comparePath}`);
-    const baselineRaw = await readFile4(options.comparePath, "utf8");
+    const baselineRaw = await readFile5(options.comparePath, "utf8");
     const baseline = parseSnapshot(baselineRaw);
     const diff = compareSnapshots(current, baseline);
     report = createReport(current, diff);
@@ -5998,7 +6289,9 @@ var runExplainCommand = async (inputPath, authorIdentityMode, options, logger =
   const riskConfig = resolveRiskConfigForProfile(options.riskProfile);
   const evaluation = evaluateRepositoryRisk(
     {
-      ...analysisInputs,
+      structural: analysisInputs.structural,
+      evolution: analysisInputs.evolution,
+      external: analysisInputs.external,
       ...riskConfig === void 0 ? {} : { config: riskConfig }
     },
     { explain: true }
@@ -6007,10 +6300,19 @@ var runExplainCommand = async (inputPath, authorIdentityMode, options, logger =
     throw new Error("risk trace unavailable");
   }
   const summary = {
-    ...analysisInputs,
-    risk: evaluation.summary
+    structural: analysisInputs.structural,
+    evolution: analysisInputs.evolution,
+    external: analysisInputs.external,
+    risk: evaluation.summary,
+    quality: computeRepositoryQualitySummary({
+      structural: analysisInputs.structural,
+      evolution: analysisInputs.evolution,
+      todoFixmeCount: analysisInputs.todoFixmeCount
+    })
   };
-  logger.info(`explanation completed (riskScore=${summary.risk.riskScore})`);
+  logger.info(
+    `explanation completed (riskScore=${summary.risk.riskScore}, qualityScore=${summary.quality.qualityScore})`
+  );
   return {
     summary,
     trace: evaluation.trace,
@@ -6029,6 +6331,122 @@ var parseRecentWindowDays = (value) => {
   }
   return parsed;
 };
+var stripLeadingMarkdownHeading = (value, heading) => {
+  const prefix = `${heading}
+`;
+  if (value.startsWith(prefix)) {
+    return value.slice(prefix.length).trimStart();
+  }
+  return value;
+};
+var extractExplainTextSummary = (text) => {
+  const splitIndex = text.search(/\n\n(?:file|module|dependency|repository): /);
+  if (splitIndex < 0) {
+    return text.trim();
+  }
+  return text.slice(0, splitIndex).trim();
+};
+var extractExplainMarkdownSummary = (markdown) => {
+  const splitIndex = markdown.search(/\n\n## (?:file|module|dependency|repository): /);
+  if (splitIndex < 0) {
+    return markdown.trim();
+  }
+  return markdown.slice(0, splitIndex).trim();
+};
+var extractSummaryValue = (summary, key) => {
+  const prefix = `${key}: `;
+  for (const rawLine of summary.split("\n")) {
+    const line = rawLine.trimStart();
+    if (line.startsWith(prefix)) {
+      return line.slice(prefix.length).trim();
+    }
+  }
+  return void 0;
+};
+var renderReportHighlightsText = (report) => {
+  const lines = [];
+  lines.push("Repository Summary");
+  lines.push(`  target: ${report.repository.targetPath}`);
+  lines.push(`  riskScore: ${report.repository.riskScore}`);
+  lines.push(`  qualityScore: ${report.quality.qualityScore}`);
+  lines.push(`  normalizedScore: ${report.repository.normalizedScore}`);
+  lines.push(`  riskTier: ${report.repository.riskTier}`);
+  lines.push("");
+  lines.push("Top Hotspots");
+  for (const hotspot of report.hotspots.slice(0, 5)) {
+    lines.push(`  - ${hotspot.target} | score=${hotspot.score}`);
+    lines.push(`    priority actions: ${hotspot.suggestedActions.join(" | ") || "none"}`);
+  }
+  return lines.join("\n");
+};
+var renderReportHighlightsMarkdown = (report) => {
+  const lines = [];
+  lines.push("## Repository Summary");
+  lines.push(`- target: \`${report.repository.targetPath}\``);
+  lines.push(`- riskScore: \`${report.repository.riskScore}\``);
+  lines.push(`- qualityScore: \`${report.quality.qualityScore}\``);
+  lines.push(`- normalizedScore: \`${report.repository.normalizedScore}\``);
+  lines.push(`- riskTier: \`${report.repository.riskTier}\``);
+  lines.push("");
+  lines.push("## Top Hotspots");
+  for (const hotspot of report.hotspots.slice(0, 5)) {
+    lines.push(`- **${hotspot.target}** (score: \`${hotspot.score}\`)`);
+    lines.push(`  - priority actions: ${hotspot.suggestedActions.join(" | ") || "none"}`);
+  }
+  return lines.join("\n");
+};
+var renderCompactText = (report, explainSummary) => {
+  const lines = [];
+  lines.push("CodeSentinel Run (compact)");
+  lines.push("");
+  lines.push("Repository");
+  lines.push(`  target: ${report.repository.targetPath}`);
+  lines.push(`  riskScore: ${report.repository.riskScore}`);
+  lines.push(`  qualityScore: ${report.quality.qualityScore}`);
+  lines.push(`  riskTier: ${report.repository.riskTier}`);
+  lines.push(
+    `  dimensions: structural=${report.repository.dimensionScores.structural ?? "n/a"}, evolution=${report.repository.dimensionScores.evolution ?? "n/a"}, external=${report.repository.dimensionScores.external ?? "n/a"}, interactions=${report.repository.dimensionScores.interactions ?? "n/a"}`
+  );
+  lines.push("");
+  lines.push(
+    `Key Drivers: ${extractSummaryValue(explainSummary, "key drivers") ?? "insufficient data"}`
+  );
+  lines.push(
+    `Priority Actions: ${extractSummaryValue(explainSummary, "priority actions") ?? "insufficient data"}`
+  );
+  lines.push("");
+  lines.push("Top Hotspots");
+  for (const hotspot of report.hotspots.slice(0, 3)) {
+    lines.push(`  - ${hotspot.target} | score=${hotspot.score}`);
+  }
+  return lines.join("\n");
+};
+var renderCompactMarkdown = (report, explainSummary) => {
+  const lines = [];
+  lines.push("# CodeSentinel Run (compact)");
+  lines.push("");
+  lines.push("## Repository");
+  lines.push(`- target: \`${report.repository.targetPath}\``);
+  lines.push(`- riskScore: \`${report.repository.riskScore}\``);
+  lines.push(`- qualityScore: \`${report.quality.qualityScore}\``);
+  lines.push(`- riskTier: \`${report.repository.riskTier}\``);
+  lines.push(
+    `- dimensions: structural=\`${report.repository.dimensionScores.structural ?? "n/a"}\`, evolution=\`${report.repository.dimensionScores.evolution ?? "n/a"}\`, external=\`${report.repository.dimensionScores.external ?? "n/a"}\`, interactions=\`${report.repository.dimensionScores.interactions ?? "n/a"}\``
+  );
+  lines.push("");
+  lines.push(
+    `- key drivers: ${extractSummaryValue(explainSummary, "- key drivers") ?? "insufficient data"}`
+  );
+  lines.push(
+    `- priority actions: ${extractSummaryValue(explainSummary, "- priority actions") ?? "insufficient data"}`
+  );
+  lines.push("");
+  lines.push("## Top Hotspots");
+  for (const hotspot of report.hotspots.slice(0, 3)) {
+    lines.push(`- \`${hotspot.target}\` (score: \`${hotspot.score}\`)`);
+  }
+  return lines.join("\n");
+};
 var riskProfileOption = () => new Option(
   "--risk-profile <profile>",
   "risk profile: default (balanced) or personal (down-weights single-maintainer ownership penalties)"
@@ -6169,6 +6587,220 @@ program.command("report").argument("[path]", "path to the project to analyze").a
     }
   }
 );
+program.command("run").argument("[path]", "path to the project to analyze").addOption(riskProfileOption()).addOption(
+  new Option(
+    "--author-identity <mode>",
+    "author identity mode: likely_merge (heuristic) or strict_email (deterministic)"
+  ).choices(["likely_merge", "strict_email"]).default("likely_merge")
+).addOption(
+  new Option(
+    "--log-level <level>",
+    "log verbosity: silent, error, warn, info, debug (logs are written to stderr)"
+  ).choices(["silent", "error", "warn", "info", "debug"]).default(parseLogLevel(process.env["CODESENTINEL_LOG_LEVEL"]))
+).addOption(
+  new Option("--format <mode>", "combined output format: text, md, json").choices(["text", "md", "json"]).default("text")
+).addOption(
+  new Option("--detail <level>", "run detail level: compact (default), standard, full").choices(["compact", "standard", "full"]).default("compact")
+).option("--file <path>", "explain a specific file target").option("--module <name>", "explain a specific module target").option("--top <count>", "number of top hotspots to explain when no target is selected", "5").option("--compare <baseline>", "compare against a baseline snapshot JSON file").option("--snapshot <path>", "write current snapshot JSON artifact").option("--no-trace", "disable trace embedding in generated snapshot").addOption(
+  new Option(
+    "--recent-window-days <days>",
+    "git recency window in days used for evolution volatility metrics"
+  ).argParser(parseRecentWindowDays).default(30)
+).action(
+  async (path, options) => {
+    const logger = createStderrLogger(options.logLevel);
+    const top = Number.parseInt(options.top, 10);
+    const explain = await runExplainCommand(
+      path,
+      options.authorIdentity,
+      {
+        ...options.file === void 0 ? {} : { file: options.file },
+        ...options.module === void 0 ? {} : { module: options.module },
+        top: Number.isFinite(top) ? top : 5,
+        format: options.format,
+        recentWindowDays: options.recentWindowDays,
+        riskProfile: options.riskProfile
+      },
+      logger
+    );
+    const snapshot = createSnapshot({
+      analysis: explain.summary,
+      ...options.trace === true ? { trace: explain.trace } : {}
+    });
+    if (options.snapshot !== void 0) {
+      await writeFile5(options.snapshot, JSON.stringify(snapshot, null, 2), "utf8");
+      logger.info(`snapshot written: ${options.snapshot}`);
+    }
+    const report = options.compare === void 0 ? createReport(snapshot) : createReport(
+      snapshot,
+      compareSnapshots(snapshot, parseSnapshot(await readFile6(options.compare, "utf8")))
+    );
+    if (options.format === "json") {
+      const analyzeSummaryOutput = formatAnalyzeOutput(explain.summary, "summary");
+      if (options.detail === "compact") {
+        process.stdout.write(
+          `${JSON.stringify(
+            {
+              schemaVersion: "codesentinel.run.v1",
+              generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+              repository: report.repository,
+              keyDrivers: extractSummaryValue(
+                extractExplainTextSummary(formatExplainOutput(explain, "text")),
+                "key drivers"
+              ),
+              priorityActions: extractSummaryValue(
+                extractExplainTextSummary(formatExplainOutput(explain, "text")),
+                "priority actions"
+              ),
+              topHotspots: report.hotspots.slice(0, 3).map((hotspot) => ({
+                target: hotspot.target,
+                score: hotspot.score
+              }))
+            },
+            null,
+            2
+          )}
+`
+        );
+        return;
+      }
+      if (options.detail === "standard") {
+        const analyzeSummaryPayload = JSON.parse(analyzeSummaryOutput);
+        process.stdout.write(
+          `${JSON.stringify(
+            {
+              schemaVersion: "codesentinel.run.v1",
+              generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+              analyze: analyzeSummaryPayload,
+              explain: {
+                summary: extractExplainTextSummary(formatExplainOutput(explain, "text"))
+              },
+              report: {
+                repository: report.repository,
+                quality: report.quality,
+                hotspots: report.hotspots.slice(0, 5),
+                structural: report.structural,
+                external: report.external
+              }
+            },
+            null,
+            2
+          )}
+`
+        );
+        return;
+      }
+      process.stdout.write(
+        `${JSON.stringify(
+          {
+            schemaVersion: "codesentinel.run.v1",
+            generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+            analyze: explain.summary,
+            explain,
+            report
+          },
+          null,
+          2
+        )}
+`
+      );
+      return;
+    }
+    const analyzeRendered = formatAnalyzeOutput(explain.summary, "summary");
+    const explainRendered = formatExplainOutput(explain, options.format);
+    if (options.detail === "compact") {
+      if (options.format === "md") {
+        process.stdout.write(
+          `${renderCompactMarkdown(
+            report,
+            extractExplainMarkdownSummary(formatExplainOutput(explain, "md"))
+          )}
+`
+        );
+        return;
+      }
+      process.stdout.write(
+        `${renderCompactText(report, extractExplainTextSummary(formatExplainOutput(explain, "text")))}
+`
+      );
+      return;
+    }
+    if (options.detail === "standard") {
+      if (options.format === "md") {
+        process.stdout.write(
+          `# CodeSentinel Run
+
+## Analyze
+\`\`\`json
+${analyzeRendered}
+\`\`\`
+
+## Explain
+${extractExplainMarkdownSummary(
+            formatExplainOutput(explain, "md")
+          )}
+
+${renderReportHighlightsMarkdown(report)}
+`
+        );
+        return;
+      }
+      process.stdout.write(
+        `CodeSentinel Run
+
+Analyze
+${analyzeRendered}
+
+Explain
+${extractExplainTextSummary(
+          formatExplainOutput(explain, "text")
+        )}
+
+Report
+${renderReportHighlightsText(report)}
+`
+      );
+      return;
+    }
+    const reportRendered = formatReport(report, options.format);
+    if (options.format === "md") {
+      const explainSection = stripLeadingMarkdownHeading(
+        explainRendered,
+        "# CodeSentinel Explanation"
+      );
+      const reportSection = stripLeadingMarkdownHeading(reportRendered, "# CodeSentinel Report");
+      process.stdout.write(
+        `# CodeSentinel Run
+
+## Analyze
+\`\`\`json
+${analyzeRendered}
+\`\`\`
+
+## Explain
+${explainSection}
+
+## Report
+${reportSection}
+`
+      );
+      return;
+    }
+    process.stdout.write(
+      `CodeSentinel Run
+
+Analyze
+${analyzeRendered}
+
+Explain
+${explainRendered}
+
+Report
+${reportRendered}
+`
+    );
+  }
+);
 var parseGateNumber = (value, optionName) => {
   if (value === void 0) {
     return void 0;