mandrel 1.93.0 → 2.0.0

package/.agents/scripts/lib/orchestration/plan-critic-conditions.js

@@ -28,8 +28,9 @@
  * skip decision this module produces is logged to the plan-metrics ledger
  * (`appendCriticSkip`) by the callers so under-firing is auditable.
  *
- * Pure, synchronous, no I/O — the `plan-critics.js` CLI owns reading the
- * authored artifacts and the resolved config.
+ * Pure, synchronous, no I/O — the folded pre-write phase inside
+ * `plan-persist.js` owns reading the authored artifacts and the resolved
+ * config.
  */
 
 import { evaluateConsolidationPrecondition } from './consolidation-precondition.js';

package/.agents/scripts/lib/orchestration/plan-critics-evaluate.js

@@ -36,7 +36,7 @@ function resolveRiskHeuristics(config = {}) {
   if (Array.isArray(config.planning?.riskHeuristics)) {
     return config.planning.riskHeuristics;
   }
-  return config.agentSettings?.planning?.riskHeuristics || [];
+  return [];
 }
 
 /**

package/.agents/scripts/lib/orchestration/plan-navigation.js

@@ -0,0 +1,92 @@
+/**
+ * plan-navigation.js — shared navigability helpers for the persist-side
+ * draft reachability check (`plan-reachability.js`).
+ *
+ * Extracted from the retired `epic-plan-healthcheck.js` so the live
+ * draft-ticket scan owns its own mechanics without pulling in the
+ * deleted post-plan healthcheck CLI.
+ */
+
+/**
+ * Resolve the navigation config that drives the reachability check.
+ *
+ * The check is opt-in: a consumer that has not configured
+ * `planning.navigation.routeGlobs` gets a silent no-op. The nav-registry
+ * token list is what a route-adding Story is expected to reference
+ * somewhere in its body or `## Acceptance` section.
+ *
+ * @param {object} config Resolved `.agentrc.json`.
+ * @returns {{ routeGlobs: string[], navRegistry: string[] }}
+ */
+export function resolveNavConfig(config) {
+  const nav = config?.planning?.navigation ?? {};
+  const toList = (v) =>
+    (Array.isArray(v) ? v : v == null ? [] : [v])
+      .filter((s) => typeof s === 'string' && s.trim().length > 0)
+      .map((s) => s.trim());
+  return {
+    routeGlobs: toList(nav.routeGlobs),
+    navRegistry: toList(nav.navRegistry),
+  };
+}
+
+/**
+ * Translate a route glob (`pages/**`, `app/**\/route.ts`) into a RegExp that
+ * matches a path string. Supports `**` (any depth, including `/`), `*` (any
+ * run of non-separator chars), and `?` (single non-separator char). All other
+ * characters are matched literally.
+ *
+ * @param {string} glob
+ * @returns {RegExp}
+ */
+export function globToRegExp(glob) {
+  // Collapse adjacent `**` segments before compiling. `**/**` and `***` both
+  // mean "any depth", but compiling them literally emits adjacent `.*` runs
+  // (`.*/.*` / `.*.*`) that backtrack catastrophically on a long non-matching
+  // path. Collapsing to a single `**` preserves semantics and keeps the
+  // matcher linear (ReDoS hardening).
+  const normalized = glob
+    .replace(/\*\*(?:\/\*\*)+/g, '**')
+    .replace(/\*{3,}/g, '**');
+  let re = '';
+  for (let i = 0; i < normalized.length; i++) {
+    const ch = normalized[i];
+    if (ch === '*') {
+      if (normalized[i + 1] === '*') {
+        re += '.*';
+        i++;
+      } else {
+        re += '[^/]*';
+      }
+    } else if (ch === '?') {
+      re += '[^/]';
+    } else {
+      re += ch.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+    }
+  }
+  return new RegExp(`^${re}$`);
+}
+
+/**
+ * Extract the candidate route-touching paths a Story declares. Reads the
+ * `## Changes` block (the decompose-author emits one `{"path":...}` JSON
+ * object per bullet) and falls back to any bare `` `path/like/this` ``
+ * inline-code spans in the body.
+ *
+ * @param {string} body
+ * @returns {string[]}
+ */
+export function extractStoryPaths(body) {
+  if (typeof body !== 'string' || body.length === 0) return [];
+  const paths = new Set();
+  // `{"path":"pages/foo.tsx", ...}` change descriptors.
+  for (const m of body.matchAll(/"path"\s*:\s*"([^"]+)"/g)) {
+    paths.add(m[1]);
+  }
+  // Inline-code spans that look like a path (contain a slash or a dotted ext).
+  for (const m of body.matchAll(/`([^`]+)`/g)) {
+    const token = m[1].trim();
+    if (/[/.]/.test(token) && !token.includes(' ')) paths.add(token);
+  }
+  return [...paths];
+}

package/.agents/scripts/lib/orchestration/plan-persist/fan-out-gate.js

@@ -0,0 +1,61 @@
+/**
+ * Fan-out / soft-conflict gates used by plan-persist (extracted from the
+ * retired epic-plan-decompose persist phase in Stage 5).
+ *
+ * @module lib/orchestration/plan-persist/fan-out-gate
+ */
+
+import { Logger } from '../../Logger.js';
+import { renderHardConflictError } from '../ticket-validator-conflicts.js';
+
+/**
+ * @param {object[]} findings
+ * @param {boolean} allowLargeFanOut
+ * @param {string} [tag]
+ */
+export function enforceFanOutGate(
+  findings,
+  allowLargeFanOut,
+  tag = 'plan-persist',
+) {
+  const fanOut = (findings ?? []).filter((f) => f.kind === 'fan-out-warning');
+  if (fanOut.length === 0) return;
+  if (allowLargeFanOut) {
+    for (const f of fanOut) {
+      Logger.warn(
+        `[${tag}] Persisting a large-fan-out deletion: ` +
+          `Task "${f.taskSlug}" deletes "${f.path}" with ${f.callSiteCount} ` +
+          `call site(s) (threshold ${f.threshold}). Operator override --allow-large-fan-out.`,
+      );
+    }
+    return;
+  }
+  const lines = fanOut
+    .map(
+      (f) =>
+        `  - Task "${f.taskSlug}" (Story "${f.storySlug}") deletes "${f.path}" — ${f.callSiteCount} call site(s) (threshold ${f.threshold})`,
+    )
+    .join('\n');
+  throw new Error(
+    `[${tag}] ${fanOut.length} Task(s) declare large-fan-out deletions:\n${lines}\n\n` +
+      `Split each deletion into a subsystem-by-subsystem migration across multiple Stories, ` +
+      `or rerun --allow-large-fan-out after confirming the deletion is intentional.`,
+  );
+}
+
+/**
+ * @param {object[]} findings
+ * @param {string} [tag]
+ */
+export function surfaceSoftConflictFindings(findings, tag = 'plan-persist') {
+  const soft = (findings ?? []).filter(
+    (f) => f?.severity === 'soft' && f?.kind !== 'fan-out-warning',
+  );
+  if (soft.length === 0) return;
+  Logger.warn(
+    `[${tag}] ${soft.length} soft cross-Story conflict finding(s) — review before approving the plan:`,
+  );
+  for (const finding of soft) {
+    Logger.warn(`[${tag}] soft conflict: ${renderHardConflictError(finding)}`);
+  }
+}

package/.agents/scripts/lib/orchestration/plan-persist/persist-helpers.js

@@ -0,0 +1,97 @@
+/**
+ * persist-helpers.js — pure helper surface for the flat Story `/plan` persist.
+ *
+ * Exports:
+ *   - `validateTickets(tickets, config)` — runs the cross-link, model-capacity,
+ *     freshness, and task-body validators in one pass. Capacity settings are
+ *     explicit inputs so the validator and decomposer share one live delivery
+ *     envelope instead of silently falling back to framework defaults.
+ *   - `makeDefaultFanOutCounter({ baseBranchRef, cwd })` — production
+ *     fan-out probe used by the conflict policy.
+ *
+ * @module lib/orchestration/plan-persist/persist-helpers
+ */
+
+import { resolveListValue } from '../../config/shared.js';
+import { gitSpawn } from '../../git-utils.js';
+import { validateTaskBodies } from '../task-body-validator.js';
+import { validateAndNormalizeTickets } from '../ticket-validator.js';
+import { DEFAULT_REGISTRY_PATTERNS } from '../ticket-validator-conflicts.js';
+
+/**
+ * Default fan-out counter — counts distinct files at `baseBranchRef` that
+ * reference the basename (without extension) of the deleted path. Uses
+ * `git grep -l` for a streaming-friendly probe; an empty grep returns
+ * exit code 1 which we map to a count of 0.
+ *
+ * Story #2962. Injected via opts in tests; this default runs in production.
+ */
+export function makeDefaultFanOutCounter({ baseBranchRef, cwd }) {
+  return ({ path }) => {
+    const lastSlash = path.lastIndexOf('/');
+    const base = lastSlash === -1 ? path : path.slice(lastSlash + 1);
+    const dotIdx = base.lastIndexOf('.');
+    const stem = dotIdx > 0 ? base.slice(0, dotIdx) : base;
+    if (stem.length < 3) return 0;
+    const result = gitSpawn(
+      cwd ?? process.cwd(),
+      'grep',
+      '-l',
+      '--fixed-strings',
+      stem,
+      baseBranchRef,
+    );
+    if (result.status !== 0) return 0;
+    const lines = result.stdout.split('\n').filter((l) => l.trim().length > 0);
+    // Exclude the deleted file itself from the call-site count.
+    return lines.filter((l) => !l.endsWith(`:${path}`)).length;
+  };
+}
+
+/**
+ * Resolve the cross-Story conflict-finding policy from `_config.planning`.
+ */
+function resolveConflictPolicy(cfg) {
+  const planning = cfg?.planning;
+  const policy = {
+    failOnSharedEditors: planning?.failOnSharedEditors === true,
+    requireExplicitCrossStoryDeps:
+      planning?.requireExplicitCrossStoryDeps === true,
+    failOnRegistryConflicts: planning?.failOnRegistryConflicts === true,
+    failOnLargeFanOut: planning?.failOnLargeFanOut === true,
+  };
+  if (Number.isFinite(planning?.largeFanOutThreshold)) {
+    policy.largeFanOutThreshold = planning.largeFanOutThreshold;
+  }
+  if (planning?.crossCuttingRegistries !== undefined) {
+    policy.registries = resolveListValue(
+      DEFAULT_REGISTRY_PATTERNS,
+      planning.crossCuttingRegistries,
+    );
+  }
+  return policy;
+}
+
+export function validateTickets(tickets, config, opts = {}) {
+  const baseBranchRef = config?.baseBranch ?? 'main';
+  const conflictPolicy = resolveConflictPolicy(config);
+  if (typeof opts.fanOutCounter === 'function') {
+    conflictPolicy.fanOutCounter = opts.fanOutCounter;
+  } else {
+    conflictPolicy.fanOutCounter = makeDefaultFanOutCounter({
+      baseBranchRef,
+      cwd: opts.cwd,
+    });
+  }
+  const validated = validateAndNormalizeTickets(tickets, {
+    baseBranchRef,
+    conflictPolicy,
+    modelCapacity: opts.modelCapacity,
+    // Thread the repo cwd into the AC-freshness / file-assumption git
+    // probes (#4474 PR7) — without it they silently ran against
+    // process.cwd(), which is only the repo root by coincidence.
+    cwd: opts.cwd,
+  });
+  validateTaskBodies(validated);
+  return validated;
+}