mandrel 1.94.0 → 2.1.0

package/.agents/scripts/lib/orchestration/ticket-validator-conflicts.js

@@ -10,8 +10,7 @@ import { computeStoryReachability } from './story-reachability.js';
  *
  * The decomposer emits `body` as the canonical serialized **string**, but
  * the conflict passes (`indexConsumers`, `indexAssumptionEntries`,
- * `computeMissingBddScaffoldFindings`, the sibling-create scan in
- * `computeRegistryFindings`, and the legacy-bullet branch of
+ * `computeMissingBddScaffoldFindings`, and the producer path scan in
  * `collectStoryProducerPaths`) historically read `story.body` only when it
  * was already an object — so on the production string shape the
  * `implicit-cross-story-dep`, `fan-out`, registry, and `missing-bdd-scaffold`
@@ -144,71 +143,26 @@ const WRITE_IMPLYING_ASSUMPTIONS = Object.freeze(
   new Set(['creates', 'refactors-existing', 'deletes']),
 );
 
-/**
- * Extract the path-shaped head from a single legacy string-form
- * `body.changes` bullet.
- *
- * Conventional shape is `"<path>: <verb> <object>"`; we slice on the first
- * colon and return the head when it contains a slash or a dot, otherwise
- * `null`. Mirrors the heuristic in `ticket-validator-sizing.js` so producer
- * extraction and `fileCount` accounting agree on what counts as a path.
- *
- * Object-form entries (`{ path, assumption }`) are *not* handled here — they
- * are extracted via `collectStoryAssumptionEntries` in `indexProducers`. This
- * helper only understands the legacy string shape and returns `null` for any
- * non-string input.
- */
-function extractChangeBulletPath(bullet) {
-  if (typeof bullet !== 'string') return null;
-  const colonIdx = bullet.indexOf(':');
-  if (colonIdx <= 0) return null;
-  const head = bullet.slice(0, colonIdx).trim();
-  if (!/[\\/.]/.test(head)) return null;
-  return head;
-}
-
 /**
  * Collect the write-implying producer paths a single Story declares.
  *
- * Two shapes are honoured so the modern object-form `changes` contract and
- * the legacy string-bullet contract both feed the producer index:
- *
- *   - **Object form** (`{ path, assumption }`) — reuses
- *     `collectStoryAssumptionEntries` (the same extractor the Phase-8
- *     file-assumption gate uses), then keeps only `changes`-sourced entries
- *     whose assumption writes the path (`creates` / `refactors-existing` /
- *     `deletes`). `exists` reads and `references` entries are dropped.
- *   - **Legacy string bullets** (`"<path>: <verb> ..."`) — slice the
- *     colon-head via `extractChangeBulletPath`. Legacy bullets carry no
- *     assumption, so they are treated as writes (preserving pre-migration
- *     behaviour).
+ * Uses object-form `{ path, assumption }` entries via
+ * `collectStoryAssumptionEntries` (the same extractor the Phase-8
+ * file-assumption gate uses), keeping only `changes`-sourced entries
+ * whose assumption writes the path (`creates` / `refactors-existing` /
+ * `deletes`). `exists` reads and `references` entries are dropped.
  *
  * Returns a de-duplicated array of producer paths for the Story.
  */
 function collectStoryProducerPaths(story) {
   const paths = new Set();
 
-  // Object-form entries via the shared extractor. Only `changes`-sourced
-  // write-implying assumptions count as producers.
   for (const entry of collectStoryAssumptionEntries(story)) {
     if (entry.source !== 'changes') continue;
     if (!WRITE_IMPLYING_ASSUMPTIONS.has(entry.assumption)) continue;
     paths.add(entry.path);
   }
 
-  // Legacy string bullets — extract the colon-head path. Skip non-string
-  // entries (object-form already handled above).
-  const body = story?.body;
-  const changes =
-    body && typeof body === 'object' && Array.isArray(body.changes)
-      ? body.changes
-      : [];
-  for (const bullet of changes) {
-    if (typeof bullet !== 'string') continue;
-    const path = extractChangeBulletPath(bullet);
-    if (path) paths.add(path);
-  }
-
   return Array.from(paths);
 }
 
@@ -223,11 +177,9 @@ function storySlugOf(story) {
 
 /**
  * Build the producers index — `Map<path, Array<{storySlug, taskSlug}>>` —
- * by walking every Story's declared writes. Both object-form
- * `{ path, assumption }` entries and legacy `"<path>: <verb> ..."` string
- * bullets are honoured via `collectStoryProducerPaths`; only write-implying
- * assumptions (and legacy bullets, which carry no assumption) count as
- * producers.
+ * by walking every Story's declared writes. Only object-form
+ * `{ path, assumption }` entries count as producers via
+ * `collectStoryProducerPaths`; only write-implying assumptions count.
  *
  * `taskSlug` is retained in the entry shape for finding/render
  * compatibility; in the 2-tier model it carries the Story's own slug since
@@ -519,9 +471,8 @@ function computeRegistryFindings({
     existing.push(entry);
     perStory.set(entry.storySlug, existing);
   }
-  // (a) direct registry edits — accept both legacy string-form producers
-  // (from `indexProducers`) and modern object-form `{ path, assumption }`
-  // entries (from `indexAssumptionEntries`).
+  // (a) direct registry edits — object-form `{ path, assumption }` entries
+  // from `indexAssumptionEntries` (and the producer index built from them).
   for (const [path, entries] of producers.entries()) {
     if (!isRegistryPath(path, patterns)) continue;
     for (const e of entries) {
@@ -638,13 +589,53 @@ function registryRegistry(producers, assumptionEntries, patterns, cache) {
 }
 
 /**
- * Compute `fan-out-warning` findings (Story #2962).
+ * Normalize a fan-out probe result into `{ count, files, probe }`.
+ *
+ * The production probe reports its referencing files and the exact command
+ * that found them so an operator can reproduce the figure (Story #4547).
+ * A bare number stays valid — injected test counters and any consumer
+ * counter written against the Story #2962 contract keep working, they just
+ * carry no audit trail.
+ */
+function normalizeFanOutProbe(result) {
+  if (typeof result === 'number') {
+    return { count: result, files: [], probe: null };
+  }
+  if (result === null || typeof result !== 'object') {
+    return { count: 0, files: [], probe: null };
+  }
+  const files = Array.isArray(result.files) ? result.files : [];
+  const count = Number.isFinite(result.count) ? result.count : files.length;
+  return { count, files, probe: result.probe ?? null };
+}
+
+/**
+ * Index the basenames this spec *creates*, so a deletion that is really one
+ * half of a move can be told apart from a genuine wide-coupling removal.
+ */
+function indexCreatedBasenames(assumptionEntries) {
+  const byBasename = new Map();
+  for (const entry of assumptionEntries) {
+    if (entry.assumption !== 'creates') continue;
+    const base = entry.path.slice(entry.path.lastIndexOf('/') + 1);
+    if (!byBasename.has(base)) byBasename.set(base, entry.path);
+  }
+  return byBasename;
+}
+
+/**
+ * Compute `fan-out-warning` findings (Story #2962, reworked in #4547).
+ *
+ * For each `body.changes` entry whose `assumption` is `"deletes"`, probe the
+ * files at the base branch that genuinely import or require the deleted
+ * module. When that count exceeds the configured `largeFanOutThreshold`,
+ * emit a finding carrying the referencing files and the probe that produced
+ * them.
  *
- * For each `body.changes` entry whose `assumption` is `"deletes"` (or
- * `"refactors-existing"` when the planner declared a symbol replacement),
- * count the number of distinct files in the base branch that reference
- * the deleted module via its basename. When the count exceeds the
- * configured `largeFanOutThreshold`, emit a finding.
+ * The finding also records whether the deletion is **rename-shaped** — the
+ * same spec creates a file with the deleted module's basename elsewhere —
+ * because the remedy diverges: a move wants its importers repointed in one
+ * Story, not a subsystem-by-subsystem migration split across several.
  *
  * The default severity is always `'soft'` — the persist gate enforces a
  * hard refusal via the `--allow-large-fan-out` operator flag, since the
@@ -662,21 +653,28 @@ function computeFanOutFindings({
   if (!Number.isFinite(threshold) || threshold < 0) return [];
   const findings = [];
   const cache = new Map();
+  const createdBasenames = indexCreatedBasenames(assumptionEntries);
   for (const entry of assumptionEntries) {
     if (entry.assumption !== 'deletes') continue;
-    let count = cache.get(entry.path);
-    if (count === undefined) {
-      count = counter({ path: entry.path }) ?? 0;
-      cache.set(entry.path, count);
+    let probed = cache.get(entry.path);
+    if (probed === undefined) {
+      probed = normalizeFanOutProbe(counter({ path: entry.path }));
+      cache.set(entry.path, probed);
     }
-    if (count <= threshold) continue;
+    if (probed.count <= threshold) continue;
+    const base = entry.path.slice(entry.path.lastIndexOf('/') + 1);
+    const renameTarget = createdBasenames.get(base);
     findings.push({
       kind: 'fan-out-warning',
       severity,
       taskSlug: entry.taskSlug,
       storySlug: entry.storySlug,
       path: entry.path,
-      callSiteCount: count,
+      callSiteCount: probed.count,
+      callSites: probed.files,
+      probe: probed.probe,
+      renameShaped: renameTarget !== undefined && renameTarget !== entry.path,
+      renameTarget: renameTarget === entry.path ? null : (renameTarget ?? null),
       threshold,
     });
   }
@@ -750,6 +748,60 @@ export function computeConflictFindings({ stories, policy } = {}) {
   ];
 }
 
+/**
+ * Render the audit trail behind a fan-out finding's number, so an operator
+ * can check the figure rather than trust it (Story #4547).
+ *
+ * Every importer is named — the list is deliberately **not** truncated. A
+ * gate that fires at 100 importers is precisely when the operator needs the
+ * list, and a `…and 109 more` tail would leave the figure uncheckable in
+ * exactly the case the gate exists for. This message is a fail-closed stop,
+ * not a log line; its length is the point.
+ *
+ * The probe is reported as what it is — the *candidate* net, which each hit
+ * is then re-resolved against. It will report at least as many lines as the
+ * gate counts files, so labelling it as the thing that produced the number
+ * would send an operator chasing a discrepancy that is by design.
+ *
+ * Returns `''` for a bare-number counter, which carries no audit trail.
+ */
+export function renderFanOutEvidence(finding) {
+  const files = Array.isArray(finding.callSites) ? finding.callSites : [];
+  const parts = [];
+  if (files.length > 0) {
+    parts.push(`    Importers (${files.length}):`);
+    for (const file of files) parts.push(`      ${file}`);
+  }
+  if (finding.probe) {
+    parts.push(
+      `    Candidate probe (each hit re-resolved against its importer's directory):`,
+      `      ${finding.probe}`,
+    );
+  }
+  return parts.length > 0 ? `\n${parts.join('\n')}` : '';
+}
+
+/**
+ * Render the remedy that actually fits the finding. A rename-shaped
+ * deletion has nowhere to split to — the importers just need repointing at
+ * the path the same plan creates — so telling the operator to split it
+ * across Stories leaves the override as the only exit, which is exactly the
+ * habit that defeats the gate (Story #4547).
+ */
+export function renderFanOutRemedy(finding) {
+  if (finding.renameShaped && finding.renameTarget) {
+    return (
+      `This deletion is rename-shaped: the same plan creates "${finding.renameTarget}" under the same basename. ` +
+      `Repoint the importer(s) at the new path inside this Story — a move has no subsystems to split across — ` +
+      `then rerun --allow-large-fan-out.`
+    );
+  }
+  return (
+    `Split the deletion into a subsystem-by-subsystem migration across multiple Stories, ` +
+    `or rerun --allow-large-fan-out after confirming the deletion is intentional.`
+  );
+}
+
 /**
  * Render a `'hard'`-severity conflict finding as a human-readable error
  * message. Used by the validator when policy flags upgrade a finding to
@@ -761,14 +813,18 @@ export function renderHardConflictError(finding) {
     return `Shared-editor conflict: "${finding.path}" is written by ${finding.storySlugs.length} concurrent Stories (${stories}). Add depends_on chains between them or split the edits into a dedicated late-wave wiring Story.`;
   }
   if (finding.kind === 'implicit-cross-story-dep') {
-    return `Implicit cross-Story dependency: Task "${finding.consumer.taskSlug}" in Story "${finding.consumer.storySlug}" references "${finding.path}" (produced by Task "${finding.producer.taskSlug}" in Story "${finding.producer.storySlug}") via body.${finding.consumer.sourceField}, but Story "${finding.consumer.storySlug}" has no depends_on link to Story "${finding.producer.storySlug}". Add depends_on: ["${finding.producer.storySlug}"] to the consumer Story or remove the reference.`;
+    return `Implicit cross-Story dependency: Story "${finding.consumer.storySlug}" references "${finding.path}" (produced by Story "${finding.producer.storySlug}") via body.${finding.consumer.sourceField}, but Story "${finding.consumer.storySlug}" has no depends_on link to Story "${finding.producer.storySlug}". Add depends_on: ["${finding.producer.storySlug}"] to the consumer Story or remove the reference.`;
   }
   if (finding.kind === 'cross-cutting-registries') {
     const stories = finding.storySlugs.map((s) => `"${s}"`).join(', ');
     return `Cross-cutting registry conflict: ${finding.storySlugs.length} concurrent Stories (${stories}) edit or register into "${finding.registryPath}". Add depends_on chains between them so the registry updates serialize, or split the registration into a dedicated late-wave wiring Story.`;
   }
   if (finding.kind === 'fan-out-warning') {
-    return `Large fan-out: Task "${finding.taskSlug}" in Story "${finding.storySlug}" deletes "${finding.path}" with ${finding.callSiteCount} call site(s) on the base branch (threshold ${finding.threshold}). Split into a subsystem-by-subsystem migration across multiple Stories, or rerun --allow-large-fan-out after confirming the deletion is intentional.`;
+    return (
+      `Large fan-out: Story "${finding.storySlug}" deletes "${finding.path}" ` +
+      `with ${finding.callSiteCount} importer(s) on the base branch (threshold ${finding.threshold}). ` +
+      `${renderFanOutRemedy(finding)}${renderFanOutEvidence(finding)}`
+    );
   }
   if (finding.kind === 'missing-bdd-scaffold') {
     return `Missing BDD scaffold: Story "${finding.consumer.storySlug}" verifies against "${finding.path}" (created by Story "${finding.producer.storySlug}") via body.${finding.consumer.sourceField}, but "${finding.consumer.storySlug}" has no depends_on path to "${finding.producer.storySlug}" — the .feature file is scaffolded in the same wave (or later), so verification runs before the file exists. Add depends_on: ["${finding.producer.storySlug}"] to the consumer Story so the scaffold lands in an earlier wave.`;
@@ -778,7 +834,6 @@ export function renderHardConflictError(finding) {
 
 // Internal helpers exposed for unit tests; not part of the public surface.
 export const _internal = {
-  extractChangeBulletPath,
   collectStoryProducerPaths,
   WRITE_IMPLYING_ASSUMPTIONS,
   indexProducers,