mandrel 2.58.0 → 2.59.0

package/lib/cli/registry.js

@@ -41,6 +41,8 @@ import {
 } from '../../.agents/scripts/lib/bootstrap/project-bootstrap.js';
 import { isCommandExcluded } from '../../.agents/scripts/lib/command-header.js';
 import { getDeliveryRouting } from '../../.agents/scripts/lib/config/delivery-routing.js';
+import { isResolvable } from '../../.agents/scripts/lib/runtime-deps/dep-resolution.js';
+import { describeParserMajorError } from '../../.agents/scripts/lib/runtime-deps/parser-major.js';
 import {
   defaultResolvePackageRoot,
   listFiles as listPayloadFiles,
@@ -519,6 +521,30 @@ function runAgentsInSync({
 // check: runtime-deps
 // ---------------------------------------------------------------------------
 
+/**
+ * The verdict when every required package is present.
+ *
+ * Presence is not the whole contract: `.agents/` resolves from the consumer's
+ * node_modules, so a declared range cannot enforce which `@babel/parser` major
+ * the complexity kernel actually gets, and the wrong major fails scoring
+ * mid-scan with an opaque plugin-list error. Reporting it here puts it where a
+ * consumer is already looking for what to fix.
+ *
+ * @param {() => string|null} parserMajorError
+ * @returns {{ ok: boolean, detail: string, remedy?: string }}
+ */
+function allPresentVerdict(parserMajorError) {
+  const parserProblem = parserMajorError();
+  if (parserProblem === null) {
+    return { ok: true, detail: 'all dependencies found' };
+  }
+  return {
+    ok: false,
+    detail: 'dependency version unsupported',
+    remedy: parserProblem,
+  };
+}
+
 /**
  * Verify that the framework's required runtime dependencies are resolvable
  * from the project's node_modules.
@@ -536,6 +562,8 @@ function runAgentsInSync({
  *   is missing.
  * - `manifestRequired` — array of required package names, skips the
  *   filesystem read of `runtime-deps.json`.
+ * - `parserMajorError()` — replaces the resolved-parser-major probe, so the
+ *   unsupported-major report is assertable without installing one.
  *
  * @param {{ projectRoot?: string, resolve?: (dep: string) => string, manifestRequired?: string[] }} [opts]
  * @returns {{ ok: boolean, detail: string, remedy?: string }}
@@ -544,6 +572,7 @@ function runRuntimeDeps({
   projectRoot,
   resolve: resolveSeam,
   manifestRequired,
+  parserMajorError = describeParserMajorError,
 } = {}) {
   // Anchor at process.cwd() (the consumer root), not resolveProjectRoot() (the
   // package root). Under pnpm isolated-mode the consumer's node_modules are not
@@ -569,33 +598,24 @@ function runRuntimeDeps({
 
   const missing = [];
 
-  if (resolveSeam) {
-    for (const dep of required) {
-      try {
-        resolveSeam(dep);
-      } catch {
-        missing.push(dep);
-      }
-    }
-  } else {
-    // Anchor resolution to the consumer project root so it mirrors the context
-    // in which the framework scripts run (they free-ride on the consumer's
-    // node_modules). Under pnpm isolated-mode the consumer's node_modules are
-    // not reachable from inside node_modules/mandrel/; anchoring at process.cwd()
-    // finds them correctly.
-    const req = createRequire(path.join(root, 'package.json'));
-    for (const dep of required) {
-      try {
-        req.resolve(dep);
-      } catch {
-        missing.push(dep);
-      }
-    }
+  // Anchor resolution to the consumer project root so it mirrors the context
+  // in which the framework scripts run (they free-ride on the consumer's
+  // node_modules). Under pnpm isolated-mode the consumer's node_modules are
+  // not reachable from inside node_modules/mandrel/; anchoring at process.cwd()
+  // finds them correctly.
+  //
+  // `isResolvable` is shared with the framework-side preflight rather than
+  // reimplemented here: it probes the bare specifier AND `<name>/package.json`,
+  // because a dependency with no `main` and no `exports` cannot be resolved by
+  // name at all. Probing only the bare name reports such a package missing
+  // while it sits installed, and this check gates `mandrel doctor`.
+  const resolve =
+    resolveSeam ?? createRequire(path.join(root, 'package.json')).resolve;
+  for (const dep of required) {
+    if (!isResolvable(dep, resolve)) missing.push(dep);
   }
 
-  if (missing.length === 0) {
-    return { ok: true, detail: 'all dependencies found' };
-  }
+  if (missing.length === 0) return allPresentVerdict(parserMajorError);
   return {
     ok: false,
     detail: `missing: ${missing.join(', ')}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "2.58.0",
+  "version": "2.59.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, skills, rules, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",
@@ -109,12 +109,17 @@
     "typescript": "^6.0.3"
   },
   "dependencies": {
+    "@babel/parser": "^7.29.3",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
+    "babel-runtime": "^6.26.0",
+    "escomplex-plugin-metrics-module": "^0.1.0",
+    "escomplex-plugin-syntax-babylon": "^0.1.0",
     "js-yaml": "^4.3.2",
     "minimatch": "^10.0.0",
     "picomatch": "^4.0.4",
-    "typhonjs-escomplex": "^0.1.0"
+    "typhonjs-ast-walker": "^0.2.1",
+    "typhonjs-escomplex-commons": "^0.1.1"
   },
   "peerDependencies": {
     "@cucumber/gherkin": ">=32.0.0",

package/.agents/scripts/lib/orchestration/split-policy-validator.js

@@ -1,188 +0,0 @@
-/**
- * v2 split-policy validator — the plan-time "one-owner-AC" split rejector.
- *
- * Under the v2 default-single split policy (`docs/roadmap.md` § v2.0.0), a
- * plan authors **one Story by default**; it splits into N>1 Stories only when
- * the pieces have near-zero overlap or sit across an architectural seam. This
- * validator is the deterministic guardrail on that policy: **every acceptance
- * criterion must belong to exactly one Story.** An identical AC appearing in
- * two Stories is evidence the split coupled what should have stayed one Story,
- * so the plan is refused rather than reconciled at delivery time (there is no
- * epic-level acceptance reconcile in v2).
- *
- * Scope of the deterministic check:
- *   - **Cross-Story duplication** (always): the same normalized AC text must
- *     not appear in more than one Story.
- *   - **Full coverage** (optional, when a plan-level `acceptance` manifest is
- *     supplied): every manifest AC is claimed by exactly one Story, and no
- *     Story claims an AC absent from the manifest.
- *
- * Semantic overlap between differently-worded ACs is **not** caught here — it
- * is a gate-#2 review call. This validator only sees identical (normalized)
- * text, keeping it deterministic and false-positive-free.
- *
- * Normalization for comparison: trim, collapse internal whitespace, and
- * lower-case. Reporting always uses the first-seen original text.
- */
-
-/**
- * Normalize an acceptance string for equality comparison. Trims, collapses
- * runs of whitespace to a single space, and lower-cases. Non-strings and
- * empty/whitespace-only strings normalize to `null` (ignored).
- *
- * @param {unknown} ac
- * @returns {string | null}
- */
-export function normalizeAcceptance(ac) {
-  if (typeof ac !== 'string') return null;
-  const norm = ac.trim().replace(/\s+/g, ' ').toLowerCase();
-  return norm === '' ? null : norm;
-}
-
-/**
- * @typedef {object} StorySlice
- * @property {string} [id]        Story identifier for reporting (slug or #id).
- * @property {string} [slug]      Alternate identifier (used when `id` absent).
- * @property {string[]} acceptance Acceptance criteria this Story claims.
- */
-
-/**
- * @typedef {object} SplitPolicyViolation
- * @property {'cross-story-duplicate'|'orphan-ac'|'unclaimed-manifest-ac'} kind
- * @property {string} acceptance The original (first-seen) AC text.
- * @property {string[]} [stories] Story ids sharing a duplicated AC (`cross-story-duplicate`).
- * @property {string}   [story]   Story id owning an AC absent from the manifest (`orphan-ac`).
- */
-
-/**
- * Resolve a Story's reporting id.
- *
- * @param {StorySlice} story
- * @param {number} index
- * @returns {string}
- */
-function storyId(story, index) {
-  if (story && typeof story.id === 'string' && story.id.trim() !== '') {
-    return story.id;
-  }
-  if (story && typeof story.slug === 'string' && story.slug.trim() !== '') {
-    return story.slug;
-  }
-  return `story[${index}]`;
-}
-
-/**
- * Validate that acceptance criteria partition cleanly across Stories.
- *
- * @param {StorySlice[]} stories The plan's Stories, each with `acceptance[]`.
- * @param {object} [opts]
- * @param {string[]} [opts.planAcceptance] Optional plan-level acceptance
- *   manifest. When supplied, coverage is enforced (every manifest AC claimed
- *   exactly once; no Story claims an off-manifest AC).
- * @returns {{ ok: boolean, violations: SplitPolicyViolation[] }}
- */
-export function validateAcceptancePartition(stories, opts = {}) {
-  const violations = [];
-  const list = Array.isArray(stories) ? stories : [];
-
-  // normalized AC → { original, owners: Set<storyId> }
-  const owners = new Map();
-  list.forEach((story, index) => {
-    const id = storyId(story, index);
-    const acceptance = Array.isArray(story?.acceptance) ? story.acceptance : [];
-    for (const ac of acceptance) {
-      const norm = normalizeAcceptance(ac);
-      if (norm === null) continue;
-      const existing = owners.get(norm);
-      if (existing) {
-        existing.owners.add(id);
-      } else {
-        owners.set(norm, { original: ac.trim(), owners: new Set([id]) });
-      }
-    }
-  });
-
-  // Cross-Story duplication: any AC owned by more than one Story.
-  for (const { original, owners: set } of owners.values()) {
-    if (set.size > 1) {
-      violations.push({
-        kind: 'cross-story-duplicate',
-        acceptance: original,
-        stories: [...set],
-      });
-    }
-  }
-
-  // Optional coverage check against a plan-level manifest.
-  const manifest = Array.isArray(opts.planAcceptance)
-    ? opts.planAcceptance
-    : null;
-  if (manifest !== null) {
-    const manifestNorms = new Map();
-    for (const ac of manifest) {
-      const norm = normalizeAcceptance(ac);
-      if (norm !== null && !manifestNorms.has(norm)) {
-        manifestNorms.set(norm, ac.trim());
-      }
-    }
-    // Every manifest AC must be claimed by exactly one Story.
-    for (const [norm, original] of manifestNorms) {
-      if (!owners.has(norm)) {
-        violations.push({
-          kind: 'unclaimed-manifest-ac',
-          acceptance: original,
-        });
-      }
-    }
-    // No Story may claim an AC absent from the manifest.
-    for (const [norm, { original, owners: set }] of owners) {
-      if (!manifestNorms.has(norm)) {
-        violations.push({
-          kind: 'orphan-ac',
-          acceptance: original,
-          story: [...set][0],
-        });
-      }
-    }
-  }
-
-  return { ok: violations.length === 0, violations };
-}
-
-/**
- * Render a single violation as a human-readable line.
- *
- * @param {SplitPolicyViolation} v
- * @returns {string}
- */
-function formatViolation(v) {
-  switch (v.kind) {
-    case 'cross-story-duplicate':
-      return `acceptance criterion appears in ${v.stories.length} Stories (${v.stories.join(', ')}) — a coupled split; keep it one Story: "${v.acceptance}"`;
-    case 'unclaimed-manifest-ac':
-      return `plan acceptance criterion is claimed by no Story: "${v.acceptance}"`;
-    case 'orphan-ac':
-      return `Story ${v.story} claims an acceptance criterion absent from the plan manifest: "${v.acceptance}"`;
-    default:
-      return `unknown split-policy violation: "${v.acceptance}"`;
-  }
-}
-
-/**
- * Throwing wrapper for the persist path: throws a single batched error when
- * the acceptance criteria do not partition cleanly, otherwise returns
- * `stories` unchanged. Wired into `plan-persist` in Stage 3.
- *
- * @param {StorySlice[]} stories
- * @param {object} [opts] See {@link validateAcceptancePartition}.
- * @returns {StorySlice[]}
- */
-export function assertAcceptancePartition(stories, opts = {}) {
-  const { ok, violations } = validateAcceptancePartition(stories, opts);
-  if (ok) return stories;
-  throw new Error(
-    `[split-policy] ${violations.length} acceptance-partition violation(s) — the plan splits coupled work; refuse:\n${violations
-      .map((v) => `  - ${formatViolation(v)}`)
-      .join('\n')}`,
-  );
-}

package/.agents/scripts/lib/templates/spec-author-prompts.js

@@ -1,76 +0,0 @@
-/**
- * spec-author-prompts.js — Story-scoped Spec / Acceptance authoring prompts.
- *
- * v2 keeps a single executable document per Story. These prompts used to
- * author a separate Epic Tech Spec + Acceptance Spec that were folded into
- * the Epic body and then restated on Stories — a duplication source. They
- * now author only Story `## Spec` approach prose and remind authors that
- * acceptance lives once on the Story (`acceptance[]` / `## Acceptance`).
- */
-
-/**
- * @returns {string}
- */
-export function renderTechSpecSystemPrompt() {
-  return TECH_SPEC_SYSTEM_PROMPT;
-}
-
-/**
- * @returns {string}
- */
-export function renderAcceptanceSpecSystemPrompt() {
-  return ACCEPTANCE_SPEC_SYSTEM_PROMPT;
-}
-
-const TECH_SPEC_SYSTEM_PROMPT = `You are an expert Engineering Architect.
-Your job is to author the Story's \`## Spec\` approach section — the technical
-how for one cohesive, executable Story. There is no separate Epic Tech Spec
-document and no spill-to-docs path.
-
-The Spec should outline only what an implementing agent needs beyond Goal /
-Changes / Acceptance:
-1. Architecture & Design (approach, seams, reuse)
-2. Data Models (if any)
-3. API Changes (if any)
-4. Core Components
-5. Security & Privacy Considerations
-
-CRITICAL REQUIREMENTS:
-- Respond ONLY with valid Markdown suitable to paste into a Story \`## Spec\`.
-- Do not use top-level <h1> (# ) tags. Prefer \`##\` / \`###\` under Spec.
-- Do NOT restate the Story's Goal, Acceptance, Verify, Changes, or Non-Goals —
-  those sections already live on the same Story body. Restatement is
-  duplication and a drift risk. If a brief orientation helps, keep a
-  \`## Technical Overview\` to 2–3 sentences naming the technical approach only.
-- Do NOT author a Delivery Slicing / fan-out table. If the work needs multiple
-  independent Stories, say so in one short note and stop — oversized Specs
-  mean the Story should be split, not documented elsewhere.
-- Format architectural decisions clearly with bullet points.
-- Keep the Spec lean enough to stay inline on the Story (persist rejects
-  over-budget Specs; they are never written under docs/).`;
-
-const ACCEPTANCE_SPEC_SYSTEM_PROMPT = `You are an expert Acceptance Engineer.
-Your job is to help author the Story's binding acceptance contract — not a
-separate Acceptance Spec document.
-
-v2 rule: acceptance lives **once**, on the Story:
-- Machine contract: top-level \`acceptance[]\` (and \`verify[]\`) on the ticket JSON
-- Human document: the same items rendered under \`## Acceptance\` / \`## Verify\`
-  on the Story body (persist syncs top-level into the body)
-
-Do **not** author an Epic Acceptance Table, PRD restatement, or a second
-criteria list inside \`## Spec\`.
-
-CRITICAL REQUIREMENTS:
-- Respond ONLY with guidance or a draft \`acceptance[]\` / \`verify[]\` list for
-  one Story — never a parallel "Acceptance Spec" markdown artifact.
-- Every acceptance item MUST be observable from outside the agent (command
-  exits 0, file exists, selector resolves, fixture count matches). Reject
-  vague "matches the spec" / "looks good" items.
-- Every verify entry MUST name a tier in parentheses: unit | contract | e2e |
-  validate (or \`manual:<reason>\` when genuinely unverifiable in isolation).
-- Do NOT re-elaborate Goal or Spec prose inside acceptance items — bind the
-  outcome, not the approach.
-- Acceptance Outcomes MUST NOT prescribe a commit subject that begins with a
-  non-Conventional-Commits prefix (allowed leading types: feat|fix|chore|
-  refactor|perf|docs|style|test|build|ci|revert).`;

package/.agents/skills/core/scope-triage/SKILL.md

@@ -1,48 +0,0 @@
----
-name: scope-triage
-description:
-  Optional split-advisory for `/mandrel-plan`. Under v2 there is no epic|story routing
-  verdict — `/mandrel-plan` always authors Stories. Use this skill only when judging
-  whether a draft should stay one Story or legitimately split (near-zero
-  overlap or an architectural seam).
----
-
-# scope-triage (split advisory)
-
-## Policy Capsule
-
-- There is **no** `epic | story | borderline` routing verdict in v2. `/mandrel-plan`
-  is a single path that emits **one Story by default**.
-- This skill is an optional **split advisory**: should the author keep one
-  Story, or does the seed clear the default-single split policy?
-- Anchor sizing judgment to `DELIVERABLE_GRANULARITY_GUIDANCE` in
-  [`ticket-validator-sizing.js`](../../../scripts/lib/orchestration/ticket-validator-sizing.js).
-  There is no numeric threshold to restate — Story #5312 deleted the
-  plan-time capacity ceilings.
-- Lead with **cohesion**: one Story is one coherent change with one reason
-  to exist. Coupled work stays one Story and uses `## Slicing` for
-  intra-session checkpoints.
-- Emit an **advisory only** — `keep-single` (the default) or `split` with its
-  seam/overlap rationale. **Never auto-route**: the operator decides, and
-  `--yes` defaults to `keep-single`.
-
-## Split policy (when N>1 is allowed)
-
-Split into sibling Stories **only** when:
-
-1. **Near-zero overlap** — genuinely independent capabilities that happen to
-   share a seed idea, or
-2. **Architectural seam** — different deployables, or a migration vs the
-   feature that consumes it.
-
-Otherwise keep one Story. Persist refuses coupled splits via
-`assertAcceptancePartition` (identical AC text across Stories).
-
-## Advisory output
-
-Emit one of:
-
-- `keep-single` — default; fold complexity into `## Spec` / `## Slicing`
-- `split` — list the proposed Stories and the seam/overlap rationale
-
-Never auto-route. The operator (or `--yes` default = `keep-single`) decides.