mandrel 2.32.0 → 2.34.0

package/.agents/scripts/lib/knip-config-resolver.js

@@ -0,0 +1,181 @@
+/**
+ * knip-config-resolver.js — resolve a repository's knip configuration the way
+ * knip itself would, and hand back its declared entry patterns.
+ *
+ * Split out of `knip-entry-sync.js` (Story #5039) because these are two
+ * concerns that change for different reasons: *what knip's config says* tracks
+ * knip's own releases, while *which CLIs something invokes* tracks this
+ * repository's callers. Keeping them in one file also pushed that module's
+ * maintainability index below its floor.
+ *
+ * Why not read the file ourselves: #5026 hardcoded
+ * `JSON.parse(<root>/knip.json)`, so all seven of knip's other config
+ * locations plus `package.json#knip` resolved to ENOENT and failed the gate
+ * closed. That made it unusable in exactly the repositories that adopt the
+ * shared `knip.base.json` — knip 6 has no root-level `extends`, so inheriting
+ * the base means spreading it inside a TypeScript module, which a static
+ * `knip.json` structurally cannot express.
+ *
+ * Going through `createOptions` also drops the assumption that `entry` is
+ * *statically declared*. A config may build the array programmatically, so
+ * even a purpose-built `knip.config.ts` parser would read the wrong thing;
+ * knip evaluates the module and returns the computed value.
+ */
+
+/**
+ * Load knip's own config resolver.
+ *
+ * Deliberately a dynamic import behind an injectable seam. `knip` is declared
+ * in `runtime-deps.json` as an **optional** dependency, mirroring `typescript`:
+ * the `.agents/` payload is materialized into consumers that may not run knip
+ * at all, so an unresolvable `knip` must degrade to the skip path rather than
+ * crash the gate at module load — and must never be preflight-blocked.
+ *
+ * @returns {Promise<{ createOptions?: Function }>}
+ */
+function importKnipSession() {
+  return import('knip/session');
+}
+
+/**
+ * Collect every declared entry pattern from a resolved knip configuration.
+ *
+ * Entries live in two places and #5026 read only the first. A pnpm-workspace
+ * config — the shape that made this gate unusable in `Beestera/swarm-os` —
+ * declares them per workspace, so a config with no top-level `entry` at all is
+ * still fully enumerated. A named workspace's patterns are workspace-relative
+ * and are joined to the workspace name; the root workspace (`.`) is already
+ * repo-relative. A leading `!` is knip's *negation* marker (as opposed to the
+ * trailing production marker) and stays at the front of the pattern rather
+ * than getting buried behind the workspace prefix.
+ *
+ * `sawEntryArray` separates "declared nothing under `.agents/scripts/`" — a
+ * legitimate result, reported as `missing` divergences — from "this config
+ * enumerates no entry points anywhere", which leaves the gate nothing to
+ * compare against.
+ *
+ * @param {object} parsedConfig knip's schema-parsed configuration
+ * @returns {{ patterns: string[], sawEntryArray: boolean }}
+ */
+function collectEntryPatterns(parsedConfig) {
+  const patterns = [];
+  let sawEntryArray = false;
+
+  const push = (value, prefix) => {
+    if (typeof value !== 'string') return;
+    if (!prefix) patterns.push(value);
+    else if (value.startsWith('!'))
+      patterns.push(`!${prefix}${value.slice(1)}`);
+    else patterns.push(`${prefix}${value}`);
+  };
+
+  const addAll = (entry, prefix) => {
+    if (!Array.isArray(entry)) return;
+    sawEntryArray = true;
+    for (const value of entry) push(value, prefix);
+  };
+
+  addAll(parsedConfig?.entry, '');
+
+  const workspaces = parsedConfig?.workspaces;
+  if (workspaces && typeof workspaces === 'object') {
+    for (const [name, workspace] of Object.entries(workspaces)) {
+      const trimmed = name.replace(/^\.\/+/, '').replace(/\/+$/, '');
+      const prefix = trimmed === '' || trimmed === '.' ? '' : `${trimmed}/`;
+      addAll(workspace?.entry, prefix);
+    }
+  }
+
+  return { patterns, sawEntryArray };
+}
+
+/**
+ * Resolve the entry patterns knip would see for `repoRoot`.
+ *
+ * Three outcomes, deliberately distinct — collapsing the first two is how a
+ * broken configuration would come to look like an absent one:
+ *
+ *   skipped — nothing to check (no config file, no `package.json#knip`, or no
+ *     resolvable `knip`). The gate exits 0. This is what makes it safe to wire
+ *     into every consumer, matching `qa.gherkinLint`'s opt-in posture.
+ *   error — a configuration exists but could not be resolved, or enumerates no
+ *     entry points at all. The gate exits 2.
+ *   resolved — `patterns` carries every declared entry, top-level and
+ *     per-workspace, with knip's trailing `!` production markers intact.
+ *
+ * @param {{ repoRoot: string, loadKnipSession?: () => Promise<object> }} opts
+ * @returns {Promise<{
+ *   patterns: string[],
+ *   configFilePath: string | null,
+ *   skipped: string | null,
+ *   error: string | null,
+ * }>}
+ */
+export async function resolveKnipEntryPatterns({
+  repoRoot,
+  loadKnipSession = importKnipSession,
+}) {
+  const nothing = { patterns: [], configFilePath: null };
+
+  let createOptions;
+  try {
+    ({ createOptions } = await loadKnipSession());
+  } catch (error) {
+    return {
+      ...nothing,
+      skipped: `the "knip" package is not resolvable from ${repoRoot} (${error.message})`,
+      error: null,
+    };
+  }
+  if (typeof createOptions !== 'function') {
+    return {
+      ...nothing,
+      skipped: null,
+      error:
+        'the installed "knip" does not export createOptions from "knip/session" — this gate needs knip 6 or newer',
+    };
+  }
+
+  let options;
+  try {
+    options = await createOptions({ cwd: repoRoot, args: {} });
+  } catch (error) {
+    return {
+      ...nothing,
+      skipped: null,
+      error: `cannot resolve the knip configuration: ${error.message}`,
+    };
+  }
+
+  const configFilePath = options?.configFilePath ?? null;
+  if (!configFilePath) {
+    return {
+      ...nothing,
+      skipped: `no knip configuration found under ${repoRoot} (no config file, no package.json#knip)`,
+      error: null,
+    };
+  }
+
+  const { patterns, sawEntryArray } = collectEntryPatterns(
+    options?.parsedConfig,
+  );
+  if (!sawEntryArray) {
+    return {
+      patterns: [],
+      configFilePath,
+      skipped: null,
+      error: `${configFilePath} declares no "entry" array, at the top level or in any workspace`,
+    };
+  }
+
+  return { patterns, configFilePath, skipped: null, error: null };
+}
+
+/**
+ * Test-only seam. Not API — `collectEntryPatterns` is exercised directly so the
+ * workspace-prefix and negation rules can be pinned without a fixture tree.
+ */
+export const __testing = Object.freeze({
+  collectEntryPatterns,
+  importKnipSession,
+});

package/.agents/scripts/lib/knip-entry-sync.js

@@ -1,6 +1,8 @@
 /**
  * knip-entry-sync.js — derive which top-level `.agents/scripts/*.js` CLIs are
- * actually invoked, and diff that set against `knip.json`'s `entry` array.
+ * actually invoked, and diff that set against the `entry` array of whatever
+ * configuration knip itself would load (Story #5039; #5026 could only read a
+ * literal `knip.json`).
  *
  * Why this exists (Story #5001 → the #5012 near-miss):
  *
@@ -20,7 +22,7 @@
  * real death later. It was caught only because a base-sync conflict forced a
  * manual read of the diff.
  *
- * The fix is to stop depending on a human remembering to edit `knip.json`.
+ * The fix is to stop depending on a human remembering to edit the config.
  * #5001's own wording already names the derivation rule — entries are derived
  * "from what package.json scripts, husky hooks, .github/workflows, and the
  * .agents workflow/skill markdown actually invoke". This module mechanizes
@@ -53,6 +55,10 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
+import {
+  resolveKnipEntryPatterns,
+  __testing as resolverTesting,
+} from './knip-config-resolver.js';
 
 // Only `resolveEntrySync` and `renderEntrySyncReport` are public — they are
 // what `check-knip-entries.js` calls. Everything else is module-private and
@@ -261,9 +267,13 @@ function listTopLevelClis({ repoRoot, fsImpl = fs }) {
 }
 
 /**
- * Read the top-level `.agents/scripts/*.js` basenames declared in `knip.json`'s
- * `entry` array. Glob-bearing patterns are ignored — this reads the explicit
- * enumeration only, which is the surface #5001 made authoritative.
+ * Read the `.agents/scripts/*.js` basenames declared as knip entry points.
+ *
+ * Resolution goes through knip's own loader — see
+ * `knip-config-resolver.js` for why, and for the skipped / error / resolved
+ * contract this forwards. All this adds is the projection onto top-level CLI
+ * basenames: glob-bearing patterns are dropped, so what remains is the explicit
+ * enumeration #5001 made authoritative.
  *
  * The trailing `!` is knip's production-mode marker and is load-bearing, not
  * decoration: in a `--production` run knip keeps only the suffixed entries and
@@ -272,45 +282,41 @@ function listTopLevelClis({ repoRoot, fsImpl = fs }) {
  * unreachable in exactly the pass that emits whole-file rows — the #5012 shape
  * this gate exists to catch. Reading it as satisfied would point the operator
  * away from the cause, so unsuffixed entries are reported as their own
- * divergence rather than silently normalized.
+ * divergence rather than silently normalized. `createOptions` preserves the
+ * suffix, so the marker survives resolution.
  *
- * @param {{ repoRoot: string, fsImpl?: typeof fs }} opts
- * @returns {{ entries: string[], unsuffixed: string[], error: string | null }}
+ * @param {{ repoRoot: string, loadKnipSession?: () => Promise<object> }} opts
+ * @returns {Promise<{
+ *   entries: string[],
+ *   unsuffixed: string[],
+ *   configFilePath: string | null,
+ *   skipped: string | null,
+ *   error: string | null,
+ * }>}
  */
-function readKnipEntries({ repoRoot, fsImpl = fs }) {
-  const configPath = path.join(repoRoot, 'knip.json');
-  let parsed;
-  try {
-    parsed = JSON.parse(fsImpl.readFileSync(configPath, 'utf8'));
-  } catch (error) {
-    return {
-      entries: [],
-      unsuffixed: [],
-      error: `cannot read knip.json: ${error.message}`,
-    };
-  }
-  if (!Array.isArray(parsed?.entry)) {
-    return {
-      entries: [],
-      unsuffixed: [],
-      error: 'knip.json has no "entry" array',
-    };
+async function readKnipEntries({ repoRoot, loadKnipSession }) {
+  const { patterns, configFilePath, skipped, error } =
+    await resolveKnipEntryPatterns({ repoRoot, loadKnipSession });
+  if (skipped || error) {
+    return { entries: [], unsuffixed: [], configFilePath, skipped, error };
   }
+
   const prefix = '.agents/scripts/';
-  const declared = parsed.entry
-    .filter((e) => typeof e === 'string' && e.startsWith(prefix))
-    .filter((e) => !e.includes('*'))
+  const declared = patterns
+    .filter((e) => e.startsWith(prefix) && !e.includes('*'))
     .map((e) => ({
       cli: e.slice(prefix.length).replace(/!$/, ''),
       suffixed: e.endsWith('!'),
     }))
     .filter((e) => !e.cli.includes('/'));
 
-  const entries = declared.map((e) => e.cli);
-  const unsuffixed = declared.filter((e) => !e.suffixed).map((e) => e.cli);
   return {
-    entries: [...new Set(entries)].sort(),
-    unsuffixed: [...new Set(unsuffixed)].sort(),
+    entries: [...new Set(declared.map((e) => e.cli))].sort(),
+    unsuffixed: [
+      ...new Set(declared.filter((e) => !e.suffixed).map((e) => e.cli)),
+    ].sort(),
+    configFilePath,
+    skipped: null,
     error: null,
   };
 }
@@ -318,16 +324,27 @@ function readKnipEntries({ repoRoot, fsImpl = fs }) {
 /**
  * Resolve the full entry-sync report for a repository.
  *
- * @param {{ repoRoot: string, fsImpl?: typeof fs }} opts
- * @returns {{
+ * Async because knip's config loader is: a `knip.config.ts` has to be
+ * *evaluated*, not read. `EntrySync` names entry-list synchronization, not
+ * synchronous I/O, so the name still describes what this returns.
+ *
+ * @param {{
+ *   repoRoot: string,
+ *   fsImpl?: typeof fs,
+ *   loadKnipSession?: () => Promise<object>,
+ * }} opts
+ * @returns {Promise<{
  *   error: string | null,
+ *   skipped: string | null,
+ *   configFilePath: string | null,
  *   clis: string[],
  *   declared: string[],
  *   missing: Array<{ cli: string, invokers: string[] }>,
  *   stale: string[],
  *   phantom: string[],
  *   unsuffixed: string[],
- * }}
+ * }>}
+ *   `skipped` — nothing to check; the caller passes rather than failing.
  *   `missing` — invoked but not declared (the #5012 bug).
  *   `stale` — declared but invoked by nothing.
  *   `phantom` — declared but no such file on disk (a rename left the list behind).
@@ -335,13 +352,21 @@ function readKnipEntries({ repoRoot, fsImpl = fs }) {
  *     production pass negates rather than honours (the #5012 bug wearing a
  *     declared entry).
  */
-export function resolveEntrySync({ repoRoot, fsImpl = fs }) {
+export async function resolveEntrySync({
+  repoRoot,
+  fsImpl = fs,
+  loadKnipSession,
+}) {
   const {
     entries: declared,
     unsuffixed,
+    configFilePath,
+    skipped,
     error,
-  } = readKnipEntries({ repoRoot, fsImpl });
+  } = await readKnipEntries({ repoRoot, loadKnipSession });
   const empty = {
+    skipped: null,
+    configFilePath,
     clis: [],
     declared,
     missing: [],
@@ -349,6 +374,7 @@ export function resolveEntrySync({ repoRoot, fsImpl = fs }) {
     phantom: [],
     unsuffixed: [],
   };
+  if (skipped) return { error: null, ...empty, skipped };
   if (error) return { error, ...empty };
 
   const clis = listTopLevelClis({ repoRoot, fsImpl });
@@ -379,7 +405,17 @@ export function resolveEntrySync({ repoRoot, fsImpl = fs }) {
   const onDisk = new Set(clis);
   const phantom = declared.filter((cli) => !onDisk.has(cli));
 
-  return { error: null, clis, declared, missing, stale, phantom, unsuffixed };
+  return {
+    error: null,
+    skipped: null,
+    configFilePath,
+    clis,
+    declared,
+    missing,
+    stale,
+    phantom,
+    unsuffixed,
+  };
 }
 
 /**
@@ -460,6 +496,9 @@ export function renderEntrySyncReport(report) {
  */
 export const __testing = Object.freeze({
   buildInvocationPatterns,
+  // Re-exported from `knip-config-resolver.js` so the suite reaches the whole
+  // gate through one seam rather than importing two modules to test one gate.
+  collectEntryPatterns: resolverTesting.collectEntryPatterns,
   collectInvocationSurfaces,
   INVOCATION_SURFACES,
   listTopLevelClis,

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

@@ -15,11 +15,10 @@
  */
 
 import posix from 'node:path/posix';
-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';
+import { resolveConflictPolicy } from '../ticket-validator-conflicts.js';
 import { normalizeVerifyTiers } from '../verify-tier-repair.js';
 
 /**
@@ -176,30 +175,6 @@ export function makeDefaultFanOutCounter({ baseBranchRef, cwd, git } = {}) {
   };
 }
 
-/**
- * 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;
-}
-
 /**
  * Resolve the ref the persist gates probe against.
  *

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

@@ -62,6 +62,11 @@ import {
   evaluateDraftReachability,
   renderReachabilityOrphans,
 } from '../plan-reachability.js';
+import {
+  computeAssembledConflictFindings,
+  conflictFindingKey,
+  renderHardConflictError,
+} from '../ticket-validator-conflicts.js';
 import { upsertStructuredComment } from '../ticketing.js';
 import {
   enforceFanOutGate,
@@ -376,6 +381,50 @@ function resolveEffectiveRoute({
   };
 }
 
+/**
+ * Re-run the cross-Story conflict passes over the assembled bodies and route
+ * the result (Story #5045).
+ *
+ * `validateTickets` runs before assembly, over the raw payload, so until now
+ * plan-time conflict analysis judged an artifact that is not the one persist
+ * writes — and the passes that scan `body.acceptance` / `body.verify` were
+ * inert on the canonical top-level authoring shape as a result.
+ *
+ * Three outcomes, in order:
+ *
+ * 1. **Hard findings throw.** Policy upgrades (`planning.failOnSharedEditors`,
+ *    `planning.requireExplicitCrossStoryDeps`) are off by default; when an
+ *    operator turns one on it must bite on the persisted artifact too, and it
+ *    must bite **before** the first `createIssue`.
+ * 2. **Soft findings the raw pass already reported are dropped**, so the same
+ *    collision is not announced twice per run.
+ * 3. **Everything else is returned** for the plan-summary comment, which is
+ *    where these findings stop being a stderr line nobody keeps.
+ *
+ * @param {{ stories: object[], config: object, rawFindings: object[] }} args
+ * @returns {object[]} The assembled-pass findings, for the summary comment.
+ */
+function analyzeAssembledStories({ stories, config, rawFindings }) {
+  const findings = computeAssembledConflictFindings({ stories, config });
+  const hard = findings.filter((finding) => finding.severity === 'hard');
+  if (hard.length > 0) {
+    throw new Error(
+      `[plan-persist] ${hard.length} cross-Story conflict(s) in the assembled ` +
+        `Story bodies:\n${hard.map((f) => `  - ${renderHardConflictError(f)}`).join('\n')}`,
+    );
+  }
+  const alreadyReported = new Set(
+    (rawFindings ?? []).map((finding) => conflictFindingKey(finding)),
+  );
+  surfaceSoftConflictFindings(
+    findings.filter(
+      (finding) => !alreadyReported.has(conflictFindingKey(finding)),
+    ),
+    'plan-persist/assembled',
+  );
+  return findings;
+}
+
 /**
  * Reap abandoned `plan-*` directories under the temp root (Story #4541).
  *
@@ -702,14 +751,25 @@ export async function runPlanPersist({
     sharedSpec: techSpecContent,
     planAcceptance: planAcceptance ?? undefined,
     sourceTicketIds,
-    // The seed this plan was authored from is the provenance source: an audit
-    // sweep's Single-plan seed carries the `audit-fingerprints` /
-    // `audit-semantic-keys` footers, which assembly copies into every persisted
-    // Story body so the next sweep recognises what it already planned
-    // (Story #4877). Empty for a `--tickets` run, which is a no-op.
+    // The seed this plan was authored from: an audit sweep's Single-plan seed
+    // carries the `audit-fingerprints` / `audit-semantic-keys` footers, and
+    // assembly copies them into the persisted Story bodies so the next sweep
+    // recognises what it already planned (Story #4877). Since Story #5045 this
+    // is the **fallback** — it is carried onto every Story that did not
+    // attribute its own `provenance`, which keeps an un-attributed plan exactly
+    // as recall-safe as it was. Empty for a `--tickets` run, a no-op there.
     provenanceSource: planContextEnvelope?.seed?.content ?? '',
   });
 
+  // Story #5045: the cross-Story conflict passes re-run over the assembled,
+  // footer-stamped bodies — the artifact persist actually writes — before any
+  // GitHub call, so a policy upgrade still refuses the plan pre-creation.
+  const assembledConflicts = analyzeAssembledStories({
+    stories,
+    config,
+    rawFindings: validated.findings,
+  });
+
   // Effective complexity route (Story #4722): the planner's authored lite
   // verdict (recorded reason), validated against every assembled Story's own
   // shape — a claim exceeding the shape ceilings fails closed to full. Lite
@@ -764,6 +824,10 @@ export async function runPlanPersist({
     mode: 'stories',
     planMetricsLine,
     stories: created,
+    // Story #5045: the wave table promises what can run in parallel; the
+    // collisions the conflict passes found belong on the same surface, or the
+    // promise is the only half anyone reads.
+    conflictFindings: assembledConflicts,
   });
 
   if (!dryRun) {