mandrel 1.58.0 → 1.60.0

package/.agents/scripts/lib/orchestration/review-providers/parse-findings.js

@@ -0,0 +1,105 @@
+/**
+ * review-providers/parse-findings.js — shared JSON-findings parser.
+ *
+ * Story #3981 — extracts the verbatim-duplicated parsing logic from
+ * `parseCodexFindings` (codex.js) and `parseSecurityReviewFindings`
+ * (security-review.js) into one templated parser. Both adapters emit
+ * JSON; the parser is liberal in what it accepts:
+ *   - A bare array of finding objects.
+ *   - An object with a `findings` array.
+ *   - Either shape wrapped in an outer envelope with a `result` or
+ *     `data` key (covers minor wire-format drift across versions
+ *     without re-shimming).
+ *
+ * Each entry's severity is funnelled through the caller-supplied
+ * `mapSeverity` so the canonical enum is the only thing that reaches
+ * the renderer. Entries without a `title` or `body` are skipped — the
+ * orchestrator cannot post an empty finding, and silently dropping the
+ * entry is safer than fabricating one.
+ *
+ * Per-provider deltas ride in as options:
+ *   - `errorPrefix`     — prefix for the JSON-parse failure message.
+ *   - `mapSeverity`     — provider severity vocabulary → canonical enum.
+ *   - `defaultCategory` — when set, entries missing a `category` get
+ *     this value (security-review defaults to `'security'`); when
+ *     omitted, `category` is only set when present (codex behavior).
+ *
+ * @typedef {import('./types.js').Finding}  Finding
+ * @typedef {import('./types.js').Severity} Severity
+ */
+
+/**
+ * Parse a provider's raw stdout into `Finding[]`.
+ *
+ * @param {string} rawStdout
+ * @param {{
+ *   errorPrefix: string,
+ *   mapSeverity: (raw: unknown) => Severity,
+ *   defaultCategory?: string,
+ * }} options
+ * @returns {Finding[]}
+ * @throws {Error} when stdout is not parseable JSON.
+ */
+export function parseProviderFindings(rawStdout, options) {
+  const { errorPrefix, mapSeverity, defaultCategory } = options;
+  const text = (rawStdout ?? '').trim();
+  if (text.length === 0) return [];
+
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch (err) {
+    throw new Error(`${errorPrefix}: ${err?.message ?? err}`);
+  }
+
+  // Unwrap a single layer of envelope when present.
+  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+    if (Array.isArray(parsed.findings)) parsed = parsed.findings;
+    else if (parsed.result !== undefined) parsed = parsed.result;
+    else if (parsed.data !== undefined) parsed = parsed.data;
+  }
+  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+    if (Array.isArray(parsed.findings)) parsed = parsed.findings;
+  }
+
+  if (!Array.isArray(parsed)) return [];
+
+  /** @type {Finding[]} */
+  const findings = [];
+  for (const entry of parsed) {
+    if (!entry || typeof entry !== 'object') continue;
+    const title =
+      typeof entry.title === 'string' && entry.title.trim().length > 0
+        ? entry.title.trim()
+        : null;
+    const body =
+      typeof entry.body === 'string' && entry.body.trim().length > 0
+        ? entry.body
+        : typeof entry.message === 'string' && entry.message.trim().length > 0
+          ? entry.message
+          : null;
+    if (!title || !body) continue;
+
+    /** @type {Finding} */
+    const finding = {
+      severity: mapSeverity(entry.severity),
+      title,
+      body,
+    };
+    const category =
+      typeof entry.category === 'string' && entry.category.length > 0
+        ? entry.category
+        : defaultCategory;
+    if (category !== undefined) {
+      finding.category = category;
+    }
+    if (typeof entry.file === 'string' && entry.file.length > 0) {
+      finding.file = entry.file;
+    }
+    if (Number.isInteger(entry.line) && entry.line > 0) {
+      finding.line = entry.line;
+    }
+    findings.push(finding);
+  }
+  return findings;
+}

package/.agents/scripts/lib/orchestration/review-providers/security-review.js

@@ -32,6 +32,7 @@
  */
 
 import { spawnSync } from 'node:child_process';
+import { parseProviderFindings } from './parse-findings.js';
 import { renderDepthDirective } from './review-depth.js';
 
 /**
@@ -138,65 +139,12 @@ export function mapSecurityReviewSeverity(raw) {
  * @throws {Error} when stdout is not parseable JSON.
  */
 export function parseSecurityReviewFindings(rawStdout) {
-  const text = (rawStdout ?? '').trim();
-  if (text.length === 0) return [];
-
-  let parsed;
-  try {
-    parsed = JSON.parse(text);
-  } catch (err) {
-    throw new Error(
-      `[security-review] Failed to parse /security-review stdout as JSON: ${
-        err?.message ?? err
-      }`,
-    );
-  }
-
-  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-    if (Array.isArray(parsed.findings)) parsed = parsed.findings;
-    else if (parsed.result !== undefined) parsed = parsed.result;
-    else if (parsed.data !== undefined) parsed = parsed.data;
-  }
-  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-    if (Array.isArray(parsed.findings)) parsed = parsed.findings;
-  }
-
-  if (!Array.isArray(parsed)) return [];
-
-  /** @type {Finding[]} */
-  const findings = [];
-  for (const entry of parsed) {
-    if (!entry || typeof entry !== 'object') continue;
-    const title =
-      typeof entry.title === 'string' && entry.title.trim().length > 0
-        ? entry.title.trim()
-        : null;
-    const body =
-      typeof entry.body === 'string' && entry.body.trim().length > 0
-        ? entry.body
-        : typeof entry.message === 'string' && entry.message.trim().length > 0
-          ? entry.message
-          : null;
-    if (!title || !body) continue;
-    /** @type {Finding} */
-    const finding = {
-      severity: mapSecurityReviewSeverity(entry.severity),
-      title,
-      body,
-      category:
-        typeof entry.category === 'string' && entry.category.length > 0
-          ? entry.category
-          : 'security',
-    };
-    if (typeof entry.file === 'string' && entry.file.length > 0) {
-      finding.file = entry.file;
-    }
-    if (Number.isInteger(entry.line) && entry.line > 0) {
-      finding.line = entry.line;
-    }
-    findings.push(finding);
-  }
-  return findings;
+  return parseProviderFindings(rawStdout, {
+    errorPrefix:
+      '[security-review] Failed to parse /security-review stdout as JSON',
+    mapSeverity: mapSecurityReviewSeverity,
+    defaultCategory: 'security',
+  });
 }
 
 /**

package/.agents/scripts/lib/orchestration/single-story-close/phases/close-validation.js

@@ -22,10 +22,8 @@
  * that mock the upstream module URLs.
  */
 
-import {
-  buildDefaultGates as defaultBuildDefaultGates,
-  runCloseValidation as defaultRunCloseValidation,
-} from '../../../close-validation.js';
+import { buildDefaultGates as defaultBuildDefaultGates } from '../../../close-validation/gates.js';
+import { runCloseValidation as defaultRunCloseValidation } from '../../../close-validation/runner.js';
 import { Logger } from '../../../Logger.js';
 
 /**

package/.agents/scripts/lib/orchestration/single-story-close/phases/options.js

@@ -10,7 +10,7 @@
 
 import path from 'node:path';
 import { parseSprintArgs } from '../../../cli-args.js';
-import { PROJECT_ROOT } from '../../../config-resolver.js';
+import { PROJECT_ROOT } from '../../../project-root.js';
 
 /**
  * Resolve a flag value from an explicit override, a parsed CLI arg, or a

package/.agents/scripts/lib/orchestration/single-story-close/phases/wrong-tree-guard.js

@@ -1,7 +1,7 @@
 /**
  * phases/wrong-tree-guard.js — detect worktree/main-checkout edit divergence.
  *
- * Story #3364 — `/single-story-deliver` (and `/story-deliver`) materializes a
+ * Story #3364 — `/single-story-deliver` (and `/deliver`) materializes a
  * per-Story worktree and instructs the agent to `cd` into it before editing.
  * On Windows that guidance is silently insufficient: `cd <workCwd>` steers the
  * Bash tool's working directory, but the path-based Edit/Write tools operate on

package/.agents/scripts/lib/orchestration/single-story-close/runner.js

@@ -1,9 +1,7 @@
 import nodeFs from 'node:fs';
 import path from 'node:path';
-import {
-  buildDefaultGates,
-  runCloseValidation,
-} from '../../close-validation.js';
+import { buildDefaultGates } from '../../close-validation/gates.js';
+import { runCloseValidation } from '../../close-validation/runner.js';
 import { resolveConfig } from '../../config-resolver.js';
 import { getStoryBranch, gitSync } from '../../git-utils.js';
 import { Logger } from '../../Logger.js';

package/.agents/scripts/lib/orchestration/single-story-lease-guard.js

@@ -39,16 +39,20 @@
  */
 
 import {
-  acquireLease,
-  normalizeOperatorHandle,
-  releaseLease,
-} from './ticket-lease.js';
+  acquireLeaseFailClosed,
+  resolveOperatorFromCandidates,
+} from './lease-guard-shared.js';
+import { releaseLease } from './ticket-lease.js';
 
 /**
  * Resolve the operator handle used as the lease owner from resolved config.
- * Routes through the shared `normalizeOperatorHandle` so a leading `@` is
+ * Routes through the shared lease-guard kernel
+ * (`lease-guard-shared.resolveOperatorFromCandidates`) so a leading `@` is
  * stripped (the assignees API expects bare logins, not `@`-prefixed mentions)
- * and the self-held-claim comparison matches.
+ * and the self-held-claim comparison matches. The standalone surface's
+ * missing-handle policy is `'throw'` (intentional divergence from the plan
+ * path's `'null'`): init has no best-effort leg that can degrade, so an
+ * unowned lease must refuse immediately.
  *
  * @param {object} config Resolved `.agentrc.json` config.
  * @returns {string} Bare operator handle.
@@ -58,17 +62,16 @@ import {
  *   path cannot safely serialise concurrent runs.
  */
 export function resolveOperator(config) {
-  const handle = normalizeOperatorHandle(config?.github?.operatorHandle);
-  if (handle === null) {
-    throw new Error(
+  return resolveOperatorFromCandidates({
+    candidates: [config?.github?.operatorHandle],
+    missingHandleBehavior: 'throw',
+    missingHandleMessage:
       'single-story lease: no operator identity is configured. ' +
-        'github.operatorHandle is unset or still the shipped `@[USERNAME]` ' +
-        'placeholder, so the standalone Story lease has no owner. Set your own ' +
-        'handle in .agentrc.local.json (e.g. { "github": { "operatorHandle": ' +
-        '"@your-login" } }) and re-run.',
-    );
-  }
-  return handle;
+      'github.operatorHandle is unset or still the shipped `@[USERNAME]` ' +
+      'placeholder, so the standalone Story lease has no owner. Set your own ' +
+      'handle in .agentrc.local.json (e.g. { "github": { "operatorHandle": ' +
+      '"@your-login" } }) and re-run.',
+  });
 }
 
 /**
@@ -99,31 +102,25 @@ export async function acquireStoryLease({
   now,
 }) {
   const owner = operator ?? resolveOperator(config);
-  // Fail closed: with no live-heartbeat source on the standalone path, treat a
-  // foreign assignee as a live claim. Anchoring `heartbeatAt` to the same
-  // `now` the primitive evaluates against makes `isClaimLive` return true for
-  // any foreign owner, so `acquireLease` refuses unless `steal` is set.
-  const resolvedNow =
-    typeof now === 'number' && Number.isFinite(now) ? now : Date.now();
-  const result = await acquireLease({
+  // Fail closed: with no live-heartbeat source on the standalone path, the
+  // shared kernel anchors `heartbeatAt` to the same `now` the primitive
+  // evaluates against, so `isClaimLive` returns true for any foreign owner
+  // and `acquireLease` refuses unless `steal` is set.
+  return acquireLeaseFailClosed({
     provider,
     ticketId: storyId,
     operator: owner,
-    heartbeatAt: resolvedNow,
     steal,
     config,
-    now: resolvedNow,
-  });
-  if (!result.acquired) {
-    throw new Error(
+    now,
+    anchorHeartbeatToNow: true,
+    renderRefusal: (result) =>
       `single-story lease: Story #${storyId} is currently held by @${result.owner}. ` +
-        'Another /single-story-deliver run owns this Story. Coordinate with that ' +
-        'operator, or re-run with --steal to forcibly transfer the claim once you ' +
-        'have confirmed the other run is dead. (The standalone path has no Epic ' +
-        'heartbeat ledger, so a foreign assignee always blocks unless stolen.)',
-    );
-  }
-  return result;
+      'Another /single-story-deliver run owns this Story. Coordinate with that ' +
+      'operator, or re-run with --steal to forcibly transfer the claim once you ' +
+      'have confirmed the other run is dead. (The standalone path has no Epic ' +
+      'heartbeat ledger, so a foreign assignee always blocks unless stolen.)',
+  });
 }
 
 /**

package/.agents/scripts/lib/orchestration/skill-capsule-loader.js

@@ -12,9 +12,8 @@
 
 import fs from 'node:fs';
 import path from 'node:path';
-
-import { PROJECT_ROOT } from '../config-resolver.js';
 import { Logger } from '../Logger.js';
+import { PROJECT_ROOT } from '../project-root.js';
 
 const POLICY_HEADING_RE = /^## Policy Capsule\s*$/;
 const ANY_H2_RE = /^## /;

package/.agents/scripts/lib/orchestration/spec-freshness.js

@@ -2,7 +2,7 @@
  * spec-freshness.js — Tech Spec post-author cross-validation against the
  * current codebase.
  *
- * `/epic-plan` Phase 7 authors PRD + Tech Spec from documentation alone.
+ * `/plan` Phase 7 authors PRD + Tech Spec from documentation alone.
  * When `project.docsContextFiles` (architecture.md, etc.) drift from
  * the real source tree, the Architect persona happily cites modules and
  * paths that no longer exist. The mismatch only surfaces at delivery time,

package/.agents/scripts/lib/orchestration/spec-renderer.js

@@ -1,30 +1,29 @@
 /**
  * lib/orchestration/spec-renderer.js — tickets.json → epic-spec.yaml
- * projection (3-tier shape, Epic #3163).
+ * projection (2-tier shape, Story #4041).
  *
  * The decomposer (`epic-plan-decompose-author`) produces a flat array
- * of ticket objects of two shapes (feature / story) keyed by stable
- * `slug`s and linked by `parent_slug` + `depends_on`. The spec
- * reconciler consumes the declarative structural representation
- * defined by `.agents/schemas/epic-spec.schema.json` — a nested
- * `{ epic, features: [{ stories: [...] }] }` tree with Story-level
- * `wave`, `dependsOn`, and inline `acceptance[]` / `verify[]` arrays
+ * of Story ticket objects keyed by stable `slug`s and linked by
+ * `depends_on`. The spec reconciler consumes the declarative
+ * structural representation defined by
+ * `.agents/schemas/epic-spec.schema.json` — a flat
+ * `{ epic, stories: [...] }` shape with Story-level `wave`,
+ * `dependsOn`, and inline `acceptance[]` / `verify[]` arrays
  * projected from the decomposer's edges.
  *
- * Under the 3-tier hierarchy (Epic #3078), Stories have no Task
- * children — acceptance and verify steps live inline on the Story.
- * Epic #3163 deletes the historical 4-tier Task emission code path
- * from this renderer (and its companion producers / consumers) in a
- * single hard cutover (see `.agents/rules/git-conventions.md` §
- * "Contract Cutovers — No Shim Layer"). A `task` ticket in the
- * decomposer input is rejected at index time.
+ * Under the 2-tier hierarchy (Story #4041), Stories have no Feature
+ * parent and no Task children — acceptance and verify steps live
+ * inline on the Story, and Stories attach directly to the Epic. Any
+ * `feature` or `task` ticket in the decomposer input is rejected at
+ * index time (hard cutover; see `.agents/rules/git-conventions.md` §
+ * "Contract Cutovers — No Shim Layer").
  *
  * `renderSpec(tickets, opts)` is the pure projection between those
  * two shapes. It:
  *
- *   1. Indexes the flat array by slug, partitioning into features /
- *      stories. Any unrecognised type (including the historical
- *      `task`) raises immediately.
+ *   1. Indexes the flat array by slug. Any unrecognised type
+ *      (including the historical `feature` / `task`) raises
+ *      immediately.
  *   2. Filters Story `depends_on` edges down to inter-Story
  *      references in the same Epic.
  *   3. Layers Stories into waves via `Graph.assignLayers` (depth in
@@ -33,9 +32,9 @@
  *      convention (`build-wave-dag.js` produces the same layering at
  *      dispatch time from the live GH state, so the spec's waves are
  *      observationally identical to what dispatch will compute).
- *   4. Walks the hierarchy in decomposer-declared order (feature →
- *      story), preserving the order the LLM emitted so the
- *      reconciler's diff stays human-readable.
+ *   4. Walks the Stories in decomposer-declared order, preserving
+ *      the order the LLM emitted so the reconciler's diff stays
+ *      human-readable.
  *   5. Strips `agent::*` labels from every entity. The decomposer
  *      doesn't normally write them, but they can leak via reverse-
  *      bootstrap from live GH state — and the schema forbids them
@@ -162,7 +161,7 @@ function sanitizeLabels(labels) {
  * Convert a decomposer body value into a spec `body` string. The
  * decomposer schema admits two shapes for a Story body:
  *
- *   - A short string (preferred under the 3-tier hierarchy).
+ *   - A short string (preferred under the 2-tier hierarchy).
  *   - A structured object (`{ goal, changes[], acceptance[],
  *     verify[] }`) carried over from the legacy 4-tier Task body
  *     shape, when the decomposer chooses to inline the Story's
@@ -215,16 +214,12 @@ function assignNonEmpty(target, key, value) {
 }
 
 /**
- * Partition the flat ticket array into per-type maps keyed by slug.
- * Returns the ordered slug lists alongside the lookup map so the
- * renderer can walk the hierarchy in the decomposer's emit order
- * (parents-before-children is guaranteed by the validator's
- * topological sort, but we don't need that invariant here — we walk
- * features in array order, then look up their children by parent_slug
- * in the order the decomposer emitted them).
+ * Index the flat ticket array by slug. Returns the ordered Story slug
+ * list alongside the lookup map so the renderer can walk Stories in
+ * the decomposer's emit order.
  *
- * Under the 3-tier hierarchy (Epic #3078), only `feature` and `story`
- * types are recognised. Any other type — including the historical
+ * Under the 2-tier hierarchy (Story #4041), only the `story` type is
+ * recognised. Any other type — including the historical `feature` /
  * `task` — falls through to the unknown-type guard and raises
  * immediately; there is no silent drop.
  *
@@ -232,7 +227,6 @@ function assignNonEmpty(target, key, value) {
  */
 function indexTickets(tickets) {
   const bySlug = new Map();
-  const featureSlugs = [];
   const storySlugs = [];
 
   for (const t of tickets) {
@@ -247,15 +241,14 @@ function indexTickets(tickets) {
       throw new Error(`[spec-renderer] duplicate slug "${slug}"`);
     }
     bySlug.set(slug, t);
-    if (t.type === 'feature') featureSlugs.push(slug);
-    else if (t.type === 'story') storySlugs.push(slug);
+    if (t.type === 'story') storySlugs.push(slug);
     else {
       throw new Error(
         `[spec-renderer] ticket "${slug}" has unknown type "${t.type}"`,
       );
     }
   }
-  return { bySlug, featureSlugs, storySlugs };
+  return { bySlug, storySlugs };
 }
 
 /**
@@ -283,9 +276,8 @@ function layerStories(storySlugs, bySlug) {
  * Project the decomposer ticket array into the structural spec object.
  *
  * @param {Array<object>} tickets — flat ticket array as emitted by the
- *   decomposer Skill (`type` ∈ {feature, story}, `slug`,
- *   `parent_slug`, `depends_on`, `title`, `body`, `labels`,
- *   `acceptance`, `verify`).
+ *   decomposer Skill (`type` = story, `slug`, `depends_on`, `title`,
+ *   `body`, `labels`, `acceptance`, `verify`).
  * @param {object}        opts
  * @param {{id: number, title: string, body?: string, labels?: string[]}} opts.epic
  *   — Epic descriptor (the decomposer doesn't emit the Epic row; it's
@@ -297,7 +289,7 @@ function layerStories(storySlugs, bySlug) {
  * @param {boolean} [opts.validate=true] — when `false`, skip final
  *   schema validation (used by tests that intentionally craft invalid
  *   inputs).
- * @returns {object} spec — `{ epic, features, gates? }` matching
+ * @returns {object} spec — `{ epic, stories, gates? }` matching
  *   `.agents/schemas/epic-spec.schema.json`.
  */
 function validateRenderSpecInputs(tickets, opts) {
@@ -318,18 +310,6 @@ function validateRenderSpecInputs(tickets, opts) {
   }
 }
 
-function bucketStoriesByFeature({ storySlugs, bySlug }) {
-  const storiesByFeature = new Map();
-  for (const slug of storySlugs) {
-    const story = bySlug.get(slug);
-    const parent = story.parent_slug;
-    if (typeof parent !== 'string' || !bySlug.has(parent)) continue;
-    if (!storiesByFeature.has(parent)) storiesByFeature.set(parent, []);
-    storiesByFeature.get(parent).push(slug);
-  }
-  return storiesByFeature;
-}
-
 function pickStringArray(primary, fallback) {
   const src = Array.isArray(primary)
     ? primary
@@ -342,7 +322,7 @@ function pickStringArray(primary, fallback) {
 }
 
 function extractStoryAcceptanceVerify(story) {
-  // Under the 3-tier hierarchy (Epic #3078), Stories carry inline
+  // Stories carry inline
   // acceptance[] / verify[] arrays directly on the ticket. The
   // decomposer may emit these either at the top level of the ticket
   // (preferred) or nested under a structured `body` object (legacy
@@ -380,20 +360,6 @@ function buildStoryOut({ story, layers, storySet }) {
   return out;
 }
 
-function buildFeatureOut({ feature, storySlugs, bySlug, layers, storySet }) {
-  const stories = storySlugs.map((storySlug) =>
-    buildStoryOut({
-      story: bySlug.get(storySlug),
-      layers,
-      storySet,
-    }),
-  );
-  const out = { slug: feature.slug, title: feature.title, stories };
-  assignNonEmpty(out, 'body', renderBody(feature.body));
-  assignNonEmpty(out, 'labels', sanitizeLabels(feature.labels));
-  return out;
-}
-
 function buildEpicOut(epic) {
   const out = { id: epic.id, title: epic.title };
   assignNonEmpty(out, 'body', renderBody(epic.body));
@@ -432,22 +398,19 @@ export function renderSpec(tickets, opts = {}) {
   validateRenderSpecInputs(tickets, opts);
   const { epic, gates, schemaPath, validate = true } = opts;
 
-  const { bySlug, featureSlugs, storySlugs } = indexTickets(tickets);
+  const { bySlug, storySlugs } = indexTickets(tickets);
   const { layers } = layerStories(storySlugs, bySlug);
-  const storiesByFeature = bucketStoriesByFeature({ storySlugs, bySlug });
   const storySet = new Set(storySlugs);
 
-  const features = featureSlugs.map((featureSlug) =>
-    buildFeatureOut({
-      feature: bySlug.get(featureSlug),
-      storySlugs: storiesByFeature.get(featureSlug) ?? [],
-      bySlug,
+  const stories = storySlugs.map((storySlug) =>
+    buildStoryOut({
+      story: bySlug.get(storySlug),
       layers,
       storySet,
     }),
   );
 
-  const spec = { epic: buildEpicOut(epic), features };
+  const spec = { epic: buildEpicOut(epic), stories };
   const gatesOut = buildGatesOut(gates);
   if (gatesOut) spec.gates = gatesOut;
 

package/.agents/scripts/lib/orchestration/spec-section-validator.js

@@ -1,7 +1,7 @@
 /**
  * spec-section-validator.js — Phase 7.5 Tech Spec post-authoring section gate.
  *
- * `/epic-plan` Phase 7 authors a Tech Spec from documentation and the PRD.
+ * `/plan` Phase 7 authors a Tech Spec from documentation and the PRD.
  * Phase 8.3 (Holistic Consolidation) then reconciles the draft ticket array
  * against the Tech Spec's `## Delivery Slicing` section, which the
  * decompose-author skill uses as the capability-boundary anchor. When the