mandrel 1.62.0 → 1.63.0

package/.agents/scripts/lib/story-body/story-body.js

@@ -355,6 +355,96 @@ function splitSections(markdown) {
   return { sections, footer, preamble };
 }
 
+// ---------------------------------------------------------------------------
+// Parser — per-section sub-parsers
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the minimal {@link ParseResult} returned for a legacy string body —
+ * markdown that carries no recognised structured section. The goal falls
+ * back to the preamble text (or the whole trimmed input), `depends_on` is
+ * still recovered from the footer, and all section arrays are empty.
+ *
+ * @param {string} input - The original markdown string.
+ * @param {string} preamble - Text before the first heading (from splitSections).
+ * @param {string} footer - Footer block text (from splitSections).
+ * @returns {ParseResult}
+ */
+function parseLegacyStringBody(input, preamble, footer) {
+  const warnings = [
+    'legacy-string-body: no structured sections found; returning minimal body from preamble text.',
+    'test-surface-unestimated: estimated_test_files not present.',
+  ];
+  const body = {
+    goal: preamble || input.trim(),
+    changes: [],
+    acceptance: [],
+    verify: [],
+    references: [],
+    wide: null,
+    depends_on: extractBlockedBy(footer),
+    estimated_test_files: null,
+  };
+  return {
+    body,
+    warnings,
+    info: {
+      hasGoalSection: false,
+      hasChangesSection: false,
+      hasAcceptanceSection: false,
+      hasVerifySection: false,
+      hasReferencesSection: false,
+      isLegacyStringBody: true,
+    },
+  };
+}
+
+/**
+ * Parse the `## Goal` section: join its non-empty content lines into a
+ * single one-line goal string.
+ *
+ * @param {string[]} lines - Raw content lines under the heading.
+ * @returns {string}
+ */
+function parseGoalSection(lines) {
+  return lines
+    .map((l) => l.trim())
+    .filter(Boolean)
+    .join(' ');
+}
+
+/**
+ * Parse a `## Changes` / `## References` section into a list of
+ * `PathEntry | string` entries. List markers are stripped, blank entries are
+ * dropped, and each surviving entry is normalized via {@link parsePathEntry}
+ * (which appends `legacy-path-entry` warnings for bare-string bullets).
+ *
+ * @param {string[]} lines - Raw content lines under the heading.
+ * @param {string[]} warnings - Mutable warnings sink.
+ * @returns {Array<PathEntry|string>}
+ */
+function parsePathEntrySection(lines, warnings) {
+  const entries = [];
+  for (const line of lines) {
+    const stripped = stripListMarker(line);
+    if (!stripped) continue;
+    const entry = parsePathEntry(stripped, warnings);
+    if (entry !== null) entries.push(entry);
+  }
+  return entries;
+}
+
+/**
+ * Parse a plain bullet-list section (`## Acceptance` / `## Verify`) into a
+ * list of trimmed strings, dropping blank entries.
+ *
+ * @param {string[]} lines - Raw content lines under the heading.
+ * @returns {string[]}
+ */
+function parseTextListSection(lines) {
+  return lines.map((l) => stripListMarker(l)).filter(Boolean);
+}
+
 // ---------------------------------------------------------------------------
 // Parser
 // ---------------------------------------------------------------------------
@@ -414,84 +504,20 @@ export function parse(input) {
     !hasVerifySection;
 
   if (isLegacyStringBody) {
-    // Extract depends_on from footer even for legacy bodies.
-    const dependsOn = extractBlockedBy(footer);
-    warnings.push(
-      'legacy-string-body: no structured sections found; returning minimal body from preamble text.',
-    );
-    warnings.push(
-      'test-surface-unestimated: estimated_test_files not present.',
-    );
-    const body = {
-      goal: preamble || input.trim(),
-      changes: [],
-      acceptance: [],
-      verify: [],
-      references: [],
-      wide: null,
-      depends_on: dependsOn,
-      estimated_test_files: null,
-    };
-    return {
-      body,
-      warnings,
-      info: {
-        hasGoalSection: false,
-        hasChangesSection: false,
-        hasAcceptanceSection: false,
-        hasVerifySection: false,
-        hasReferencesSection: false,
-        isLegacyStringBody: true,
-      },
-    };
+    return parseLegacyStringBody(input, preamble, footer);
   }
 
-  // --- Parse goal ---
-  const goalLines = sections.get('goal') ?? [];
-  const goal = goalLines
-    .map((l) => l.trim())
-    .filter(Boolean)
-    .join(' ');
-
-  // --- Parse changes ---
-  const changeLines = sections.get('changes') ?? [];
-  const changes = [];
-  for (const line of changeLines) {
-    const stripped = stripListMarker(line);
-    if (!stripped) continue;
-    const entry = parsePathEntry(stripped, warnings);
-    if (entry !== null) changes.push(entry);
-  }
-
-  // --- Parse acceptance ---
-  const acceptanceLines = sections.get('acceptance') ?? [];
-  const acceptance = acceptanceLines
-    .map((l) => stripListMarker(l))
-    .filter(Boolean);
-
-  // --- Parse verify ---
-  const verifyLines = sections.get('verify') ?? [];
-  const verify = verifyLines.map((l) => stripListMarker(l)).filter(Boolean);
-
-  // --- Parse references (optional) ---
-  const referenceLines = sections.get('references') ?? [];
-  const references = [];
-  for (const line of referenceLines) {
-    const stripped = stripListMarker(line);
-    if (!stripped) continue;
-    const entry = parsePathEntry(stripped, warnings);
-    if (entry !== null) {
-      // References MUST be object form (canonical).
-      if (typeof entry === 'string') {
-        // Already warned as legacy-path-entry; keep as string for now.
-        references.push(entry);
-      } else {
-        references.push(entry);
-      }
-    }
-  }
-
-  // --- Parse footer ---
+  const goal = parseGoalSection(sections.get('goal') ?? []);
+  const changes = parsePathEntrySection(
+    sections.get('changes') ?? [],
+    warnings,
+  );
+  const acceptance = parseTextListSection(sections.get('acceptance') ?? []);
+  const verify = parseTextListSection(sections.get('verify') ?? []);
+  const references = parsePathEntrySection(
+    sections.get('references') ?? [],
+    warnings,
+  );
   const dependsOn = extractBlockedBy(footer);
 
   // --- Recover wide / estimated_test_files from the meta block ---

package/.agents/scripts/providers/github/blocked-by-add.js

@@ -0,0 +1,252 @@
+/**
+ * GitHub Provider — shared "set native blocked-by dependency" helper.
+ *
+ * Story #4067 — after issue creation during Phase 8 decomposition, each
+ * Story's `depends_on` graph is known as a set of sibling slugs. This
+ * helper translates those slug-to-issueNumber pairs into native GitHub
+ * "blocked by" dependency edges so maintainers can see blocking
+ * relationships directly in the GitHub UI.
+ *
+ * API surface used:
+ *   Read:  GET  /repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by
+ *   Write: POST /repos/{owner}/{repo}/issues/{issue_number}/dependencies/blocked_by
+ *          body: { "issue_id": <integer db id of the blocking issue> }
+ *
+ * Contract:
+ *   - **Idempotent** — reads existing edges first; only POSTs missing ones.
+ *   - **Non-fatal** — catches all errors per edge, warns, and continues.
+ *     The overall function never throws; errors are returned in a summary.
+ *   - **No-op on empty input** — returns immediately when no depends_on
+ *     edges are present or the slug→issueNumber map is empty.
+ */
+
+import { Logger } from '../../lib/Logger.js';
+import { concurrentMap } from '../../lib/util/concurrent-map.js';
+import { parseApiJson } from './request-helpers.js';
+
+/**
+ * Bounded concurrency for the GitHub dependency-edge round-trips. Kept modest
+ * to respect GitHub's secondary rate limits while still collapsing the wall-
+ * clock latency from `sum(round-trips)` toward `sum(round-trips) / concurrency`.
+ */
+const EDGE_CONCURRENCY = 5;
+
+/**
+ * Fetch the existing blocked-by issue numbers for a given issue.
+ *
+ * Returns `[]` on any error so the caller falls back to posting the full
+ * set of missing edges (worst case: a duplicate POST, which GitHub
+ * handles idempotently).
+ *
+ * @param {{ gh: object, owner: string, repo: string, issueNumber: number }} opts
+ * @returns {Promise<number[]>} Database ids of the issues that currently block `issueNumber`.
+ */
+async function fetchExistingBlockedBy({ gh, owner, repo, issueNumber }) {
+  try {
+    const result = await gh.api({
+      method: 'GET',
+      endpoint: `/repos/${owner}/${repo}/issues/${issueNumber}/dependencies/blocked_by`,
+    });
+    const data = parseApiJson(result);
+    if (!Array.isArray(data)) return [];
+    return data.map((item) => item?.id).filter((id) => typeof id === 'number');
+  } catch (err) {
+    Logger.warn(
+      `[blocked-by-add] Could not fetch existing blocked-by for #${issueNumber}: ${err.message}`,
+    );
+    return [];
+  }
+}
+
+/**
+ * Set native GitHub "blocked by" dependency edges for a single issue.
+ *
+ * For each entry in `blockerInternalIds`, checks whether the edge already
+ * exists and POSTs only the missing ones. Every individual POST failure is
+ * caught, logged as a warning, and counted — the function never throws.
+ *
+ * @param {{
+ *   gh: object,
+ *   owner: string,
+ *   repo: string,
+ *   issueNumber: number,
+ *   blockerInternalIds: number[],
+ * }} opts
+ * @returns {Promise<{ added: number, skipped: number, failed: number }>}
+ */
+async function addBlockedByEdges({
+  gh,
+  owner,
+  repo,
+  issueNumber,
+  blockerInternalIds,
+}) {
+  if (blockerInternalIds.length === 0) {
+    return { added: 0, skipped: 0, failed: 0 };
+  }
+
+  const existing = await fetchExistingBlockedBy({
+    gh,
+    owner,
+    repo,
+    issueNumber,
+  });
+  const existingSet = new Set(existing);
+
+  // Partition up front so the skip count is deterministic regardless of the
+  // concurrent POST dispatch order, then POST only the missing edges in
+  // parallel under a modest cap.
+  const missing = blockerInternalIds.filter((id) => !existingSet.has(id));
+  const skipped = blockerInternalIds.length - missing.length;
+
+  const perEdge = await concurrentMap(
+    missing,
+    async (blockerId) => {
+      try {
+        await gh.api({
+          method: 'POST',
+          endpoint: `/repos/${owner}/${repo}/issues/${issueNumber}/dependencies/blocked_by`,
+          body: { issue_id: blockerId },
+        });
+        return { added: 1, failed: 0 };
+      } catch (err) {
+        Logger.warn(
+          `[blocked-by-add] Failed to add blocked-by edge #${issueNumber} ← blocker(id=${blockerId}): ${err.message}`,
+        );
+        return { added: 0, failed: 1 };
+      }
+    },
+    { concurrency: EDGE_CONCURRENCY },
+  );
+
+  let added = 0;
+  let failed = 0;
+  for (const r of perEdge) {
+    added += r.added;
+    failed += r.failed;
+  }
+
+  return { added, skipped, failed };
+}
+
+/**
+ * Translate a Story's `depends_on` slug list into native GitHub "blocked
+ * by" dependency edges, given the slug→issueNumber map from the reconciler
+ * state and a `getTicket` hook to resolve database ids.
+ *
+ * Iterates every Story that has a non-empty `dependsOn` array; for each
+ * depended-on slug, resolves the blocker's issue number (via the slug map),
+ * then resolves the blocker's database id via `getTicket`, and calls
+ * `addBlockedByEdges`. Any failure at any step is caught, logged as a
+ * warning, and reflected in the returned summary — the function never
+ * throws.
+ *
+ * @param {{
+ *   stories: Array<{ slug: string, dependsOn?: string[] }>,
+ *   slugToIssueNumber: Record<string, number>,
+ *   getTicket: (issueNumber: number) => Promise<{ internalId: number }>,
+ *   owner: string,
+ *   repo: string,
+ *   gh: object,
+ * }} opts
+ * @returns {Promise<{
+ *   edgesAdded: number,
+ *   edgesSkipped: number,
+ *   edgesFailed: number,
+ *   storiesProcessed: number,
+ * }>}
+ */
+export async function applyBlockedByDependencies({
+  stories,
+  slugToIssueNumber,
+  getTicket,
+  owner,
+  repo,
+  gh,
+}) {
+  let edgesAdded = 0;
+  let edgesSkipped = 0;
+  let edgesFailed = 0;
+  let storiesProcessed = 0;
+
+  // Process each story's GET + its POST batch under one bounded concurrentMap
+  // so the per-story round-trips overlap. Each mapper returns its own counter
+  // contribution; we sum them after the pass. The bodies swallow their own
+  // errors (per-edge try/catch + the non-fatal contract), so concurrentMap
+  // never sees a rejection and the no-throw guarantee is preserved.
+  const perStory = await concurrentMap(
+    stories,
+    async (story) => {
+      const deps = Array.isArray(story.dependsOn) ? story.dependsOn : [];
+      if (deps.length === 0) {
+        return { added: 0, skipped: 0, failed: 0, processed: 0 };
+      }
+
+      const storyIssueNumber = slugToIssueNumber[story.slug];
+      if (typeof storyIssueNumber !== 'number') {
+        Logger.warn(
+          `[blocked-by-add] No issue number for story slug "${story.slug}"; skipping depends_on edges.`,
+        );
+        return { added: 0, skipped: 0, failed: 0, processed: 0 };
+      }
+
+      let failed = 0;
+      const blockerInternalIds = [];
+
+      for (const depSlug of deps) {
+        const blockerIssueNumber = slugToIssueNumber[depSlug];
+        if (typeof blockerIssueNumber !== 'number') {
+          Logger.warn(
+            `[blocked-by-add] depends_on slug "${depSlug}" (from "${story.slug}") has no mapped issue number; skipping edge.`,
+          );
+          failed++;
+          continue;
+        }
+        try {
+          const blocker = await getTicket(blockerIssueNumber);
+          if (typeof blocker?.internalId !== 'number') {
+            Logger.warn(
+              `[blocked-by-add] Blocker #${blockerIssueNumber} ("${depSlug}") has no internalId; skipping edge.`,
+            );
+            failed++;
+            continue;
+          }
+          blockerInternalIds.push(blocker.internalId);
+        } catch (err) {
+          Logger.warn(
+            `[blocked-by-add] Could not resolve blocker "${depSlug}" (#${blockerIssueNumber}): ${err.message}`,
+          );
+          failed++;
+        }
+      }
+
+      if (blockerInternalIds.length === 0) {
+        return { added: 0, skipped: 0, failed, processed: 1 };
+      }
+
+      const result = await addBlockedByEdges({
+        gh,
+        owner,
+        repo,
+        issueNumber: storyIssueNumber,
+        blockerInternalIds,
+      });
+      return {
+        added: result.added,
+        skipped: result.skipped,
+        failed: failed + result.failed,
+        processed: 1,
+      };
+    },
+    { concurrency: EDGE_CONCURRENCY },
+  );
+
+  for (const r of perStory) {
+    edgesAdded += r.added;
+    edgesSkipped += r.skipped;
+    edgesFailed += r.failed;
+    storiesProcessed += r.processed;
+  }
+
+  return { edgesAdded, edgesSkipped, edgesFailed, storiesProcessed };
+}

package/.agents/scripts/single-story-init.js

@@ -36,7 +36,7 @@
  * @see .agents/workflows/helpers/single-story-deliver.md
  */
 
-import { spawnSync } from 'node:child_process';
+import { spawnSync as defaultSpawnSync } from 'node:child_process';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { parseSprintArgs } from './lib/cli-args.js';
@@ -109,12 +109,25 @@ const progress = Logger.createProgress('single-story-init', { stderr: true });
  * ripple into the single-story-sweep planner, which is intentionally out
  * of scope for the callers-only provider migration.
  *
+ * Story #4073: the `spawnImpl` seam injects the `spawnSync` boundary so the
+ * runner's success/error handling can be unit-tested without a live `gh`
+ * binary. It defaults to `child_process.spawnSync` (mirroring the
+ * `spawnImpl` seam in `lib/gh-exec.js` and the `runner` seam in
+ * `lib/bootstrap/gh-preflight.js`), so the production CLI path is unchanged.
+ * The synchronous `spawnSync` shape is preserved deliberately — the
+ * candidate-filter loop in `executeCleanup` is synchronous, so converting
+ * this to the async `lib/gh-exec.js` facade would ripple into the
+ * single-story-sweep planner.
+ *
  * @param {string} cwd Repo root used as the default spawn cwd.
+ * @param {typeof defaultSpawnSync} [spawnImpl] Injectable spawn boundary —
+ *   defaults to `child_process.spawnSync`. Tests pass a fake to assert the
+ *   error/exit-code handling without spawning a real child process.
  * @returns {(args: string[], opts?: { cwd?: string }) => string}
  */
-export function makeGhRunner(cwd) {
+export function makeGhRunner(cwd, spawnImpl = defaultSpawnSync) {
   return (args, opts) => {
-    const result = spawnSync('gh', args, {
+    const result = spawnImpl('gh', args, {
       cwd: opts?.cwd ?? cwd,
       encoding: 'utf-8',
       shell: false,

package/.agents/workflows/audit-architecture.md

@@ -129,6 +129,14 @@ legitimately have no layered architecture to guard.
 
 ## Step 2: Analysis Dimensions
 
+For every finding you surface, grade **Impact** on a High / Medium / Low axis
+reflecting the severity of the architectural risk (how much correctness,
+maintainability, or testability the gap erodes), independent of the
+**Category** effort axis — a Quick Win can still be High Impact, and a
+Structural Change can be Medium. As a loose default, Quick Wins typically land
+High (cheap to fix, real payoff) and Structural Changes Medium/High, but grade
+Impact on the risk itself rather than deriving it mechanically from Category.
+
 Evaluate the gathered context against the following clean code dimensions:
 
 1. **Over-Engineering & Abstractions:** Identify "dry-run" complexity, premature
@@ -294,6 +302,7 @@ marked `n/a`.]
 
 ### [Short Title of the Issue]
 
+- **Impact:** [High | Medium | Low]
 - **Category:** [Quick Win | Structural Change]
 - **Dimension:** [e.g., Cognitive Load & Nesting | Testable Surface (Humble-Object Boundary) | Automated Architecture Guardrails]
 - **Current State:** [The specific file/function and why it is problematic]

package/README.md

@@ -163,7 +163,7 @@ Deeper reference material lives in `docs/` rather than inline here:
 - [`.agents/docs/workflows.md`](.agents/docs/workflows.md) — slash-command
   index (auto-generated from the workflow set).
 - [`docs/CHANGELOG.md`](docs/CHANGELOG.md) — release history.
-- [`AGENTS.md`](AGENTS.md) — repository onboarding, the two-package release
+- [`AGENTS.md`](AGENTS.md) — repository onboarding, the single-package release
   topology, PAT / npm-token setup, and major-version policy. Releases are
   automated by `release-please`: land Conventional Commits on `main` and it
   opens a combined `chore: release main` PR that squash-merges itself once

package/docs/CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to this project will be documented in this file.
 
+## [1.63.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.62.0...mandrel-v1.63.0) (2026-06-13)
+
+
+### Added
+
+* **decompose:** set native GitHub blocked-by dependencies from Story depends_on graph (refs [#4067](https://github.com/dsj1984/mandrel/issues/4067)) ([#4068](https://github.com/dsj1984/mandrel/issues/4068)) ([1799659](https://github.com/dsj1984/mandrel/commit/1799659a84b06555c9caa1193aec59113c943b78))
+
+
+### Fixed
+
+* **audit-architecture:** add Impact severity field to Detailed Findings (refs [#4085](https://github.com/dsj1984/mandrel/issues/4085)) ([#4096](https://github.com/dsj1984/mandrel/issues/4096)) ([d72c109](https://github.com/dsj1984/mandrel/commit/d72c109195955eff70d7d926abb36a88e32d3f6e))
+* fix stale architecture.md/README docs and broaden the import-cycle gate scan root ([#4071](https://github.com/dsj1984/mandrel/issues/4071)) ([#4090](https://github.com/dsj1984/mandrel/issues/4090)) ([2e97b45](https://github.com/dsj1984/mandrel/commit/2e97b45f9ed43398dc703dd735394c7483329033))
+
+
+### Performance
+
+* **decompose:** parallelize blocked-by edge creation with bounded concurrentMap (refs [#4082](https://github.com/dsj1984/mandrel/issues/4082)) ([#4094](https://github.com/dsj1984/mandrel/issues/4094)) ([a9f38da](https://github.com/dsj1984/mandrel/commit/a9f38da2d44941a164865a6ad291c2da01ee4ed6))
+
+
+### Changed
+
+* `parseProviderFindings` is a CC-30 ternary thicket ([#4074](https://github.com/dsj1984/mandrel/issues/4074)) ([#4089](https://github.com/dsj1984/mandrel/issues/4089)) ([5ed693c](https://github.com/dsj1984/mandrel/commit/5ed693c3325c05a36251b859be5873ab0378031c))
+* extract shared createDriftDetector skeleton for CRAP and MI drift detectors (refs [#4076](https://github.com/dsj1984/mandrel/issues/4076)) ([#4091](https://github.com/dsj1984/mandrel/issues/4091)) ([e8a81a8](https://github.com/dsj1984/mandrel/commit/e8a81a82307a12c3d6e58275d4c4554b07659f4f))
+* **scripts:** reduce CC of CLI orchestration bodies below the must-fix band (refs [#4075](https://github.com/dsj1984/mandrel/issues/4075)) ([#4093](https://github.com/dsj1984/mandrel/issues/4093)) ([53519de](https://github.com/dsj1984/mandrel/commit/53519de7968e59c08479c886ca3713f53f5c039d))
+* **signals:** hoist shared detector validation preamble into common.js (refs [#4077](https://github.com/dsj1984/mandrel/issues/4077)) ([#4092](https://github.com/dsj1984/mandrel/issues/4092)) ([2f6fe7b](https://github.com/dsj1984/mandrel/commit/2f6fe7b103c208fbd3ea4cfedf63d2a7aa412e24))
+* **single-story-init:** inject spawnSync boundary into makeGhRunner (refs [#4073](https://github.com/dsj1984/mandrel/issues/4073)) ([#4087](https://github.com/dsj1984/mandrel/issues/4087)) ([8fae355](https://github.com/dsj1984/mandrel/commit/8fae35568523e3997d8f7e79580c0cc8e0625072))
+* **story-body:** extract per-section sub-parsers from parse() (refs [#4072](https://github.com/dsj1984/mandrel/issues/4072)) ([#4088](https://github.com/dsj1984/mandrel/issues/4088)) ([aa9e472](https://github.com/dsj1984/mandrel/commit/aa9e47204728da0ab4f547927af251fce6a85b69))
+
 ## [1.62.0](https://github.com/dsj1984/mandrel/compare/mandrel-v1.61.0...mandrel-v1.62.0) (2026-06-12)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel",
-  "version": "1.62.0",
+  "version": "1.63.0",
   "description": "Claude Code-first opinionated workflow framework: instructions, personas, skills, and SDLC workflows that govern AI coding assistants.",
   "files": [
     ".agents/",