mandrel 1.69.0 → 1.71.0

package/.agents/scripts/lib/orchestration/retro/phases/compose-body.js

@@ -415,6 +415,94 @@ function shellEscape(s) {
   return `'${str.replace(/'/g, `'\\''`)}'`;
 }
 
+/**
+ * Render the body lines (everything below a section heading and its trailing
+ * blank) for a "proposed issues" bucket — the consumer and framework sections
+ * share this shape. Empty buckets collapse to a single `_None._`; populated
+ * buckets emit one fenced `gh issue create` stanza per item.
+ *
+ * @param {object[]} items
+ * @returns {string[]}
+ */
+function renderIssueBucket(items) {
+  if (items.length === 0) return ['_None._'];
+  const lines = [];
+  for (const item of items) {
+    lines.push(`- **${item.title ?? item.category}**`);
+    lines.push('');
+    lines.push('```sh');
+    lines.push(String(item.command ?? ''));
+    lines.push('```');
+    lines.push('');
+  }
+  return lines;
+}
+
+/**
+ * Render the body lines for the "proposed memory updates" bucket — a plain
+ * instruction prelude followed by one bullet per insight, or `_None._` when
+ * empty. Deliberately NOT YAML frontmatter (asserted by the routed-sections
+ * contract test).
+ *
+ * @param {object[]} items
+ * @returns {string[]}
+ */
+function renderMemoryBucket(items) {
+  if (items.length === 0) return ['_None._'];
+  return [
+    'update your memory with the following insights:',
+    '',
+    ...items.map((m) => `- ${m.insight}`),
+  ];
+}
+
+/**
+ * Render the body lines for the "one-off / discarded" bucket — one bullet per
+ * discarded class naming its occurrence count and source, or `_None._`.
+ *
+ * @param {object[]} items
+ * @returns {string[]}
+ */
+function renderDiscardedBucket(items) {
+  if (items.length === 0) return ['_None._'];
+  return items.map(
+    (d) =>
+      `- \`${d.category}\` (${d.occurrences ?? 1} occurrence, source: ${d.source ?? 'consumer'})`,
+  );
+}
+
+/**
+ * Descriptor table for the four routed-proposal sections, in deterministic
+ * emit order (consumer → framework → memory → discarded). Each descriptor
+ * pairs a heading, the `routedProposals` field it reads, and a body renderer.
+ * {@link renderRoutedSections} walks the table once, so reordering or adding a
+ * section is a data edit here rather than another copy-pasted emit block.
+ *
+ * @type {Array<{ heading: string, field: string, renderBucket: (items: object[]) => string[] }>}
+ */
+const ROUTED_SECTIONS = [
+  {
+    heading: '### Proposed issues — consumer repo',
+    field: 'consumer',
+    renderBucket: renderIssueBucket,
+  },
+  {
+    heading: '### Proposed issues — framework repo',
+    field: 'framework',
+    renderBucket: renderIssueBucket,
+  },
+  {
+    heading: '### Proposed memory updates',
+    field: 'memory',
+    renderBucket: renderMemoryBucket,
+  },
+  {
+    heading: '### One-off / discarded',
+    field: 'discarded',
+    renderBucket: renderDiscardedBucket,
+  },
+];
+
 /**
  * Pure: render the four routed-proposal sections in deterministic order.
  * Returns `null` when `routedProposals` is absent or fully empty — the
@@ -432,80 +520,23 @@ function renderRoutedSections(routedProposals) {
   ) {
     return null;
   }
-  const framework = Array.isArray(routedProposals.framework)
-    ? routedProposals.framework
-    : [];
-  const consumer = Array.isArray(routedProposals.consumer)
-    ? routedProposals.consumer
-    : [];
-  const memory = Array.isArray(routedProposals.memory)
-    ? routedProposals.memory
-    : [];
-  const discarded = Array.isArray(routedProposals.discarded)
-    ? routedProposals.discarded
-    : [];
-  if (
-    framework.length === 0 &&
-    consumer.length === 0 &&
-    memory.length === 0 &&
-    discarded.length === 0
-  ) {
+  const buckets = ROUTED_SECTIONS.map((section) => {
+    const items = Array.isArray(routedProposals[section.field])
+      ? routedProposals[section.field]
+      : [];
+    return { section, items };
+  });
+  if (buckets.every(({ items }) => items.length === 0)) {
     return null;
   }
 
+  // Each section renders as `[heading, '', ...body]`; a single blank-line
+  // separator sits between consecutive sections (no trailing separator after
+  // the last), reproducing the original hand-unrolled push sequence exactly.
   const out = [];
-  out.push('### Proposed issues — consumer repo');
-  out.push('');
-  if (consumer.length === 0) {
-    out.push('_None._');
-  } else {
-    for (const item of consumer) {
-      out.push(`- **${item.title ?? item.category}**`);
-      out.push('');
-      out.push('```sh');
-      out.push(String(item.command ?? ''));
-      out.push('```');
-      out.push('');
-    }
-  }
-  out.push('');
-  out.push('### Proposed issues — framework repo');
-  out.push('');
-  if (framework.length === 0) {
-    out.push('_None._');
-  } else {
-    for (const item of framework) {
-      out.push(`- **${item.title ?? item.category}**`);
-      out.push('');
-      out.push('```sh');
-      out.push(String(item.command ?? ''));
-      out.push('```');
-      out.push('');
-    }
-  }
-  out.push('');
-  out.push('### Proposed memory updates');
-  out.push('');
-  if (memory.length === 0) {
-    out.push('_None._');
-  } else {
-    out.push('update your memory with the following insights:');
-    out.push('');
-    for (const m of memory) {
-      out.push(`- ${m.insight}`);
-    }
-  }
-  out.push('');
-  out.push('### One-off / discarded');
-  out.push('');
-  if (discarded.length === 0) {
-    out.push('_None._');
-  } else {
-    for (const d of discarded) {
-      out.push(
-        `- \`${d.category}\` (${d.occurrences ?? 1} occurrence, source: ${d.source ?? 'consumer'})`,
-      );
-    }
+  for (const { section, items } of buckets) {
+    if (out.length > 0) out.push('');
+    out.push(section.heading, '', ...section.renderBucket(items));
   }
   return out;
 }

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

@@ -157,6 +157,45 @@ function sanitizeLabels(labels) {
   return out.length > 0 ? out : undefined;
 }
 
+/**
+ * Descriptor table for the structured-body → markdown projection, in
+ * canonical emit order (`## Goal`, `## Changes`, `## Acceptance`,
+ * `## Verify`). Each descriptor reads one body field and returns the
+ * section's markdown block when the field is present and non-empty, or `null`
+ * to omit it. Adding a section is a one-line data edit rather than a new
+ * branch in {@link renderBody}.
+ *
+ * @type {Array<{ field: string, render: (value: unknown) => string | null }>}
+ */
+const SPEC_BODY_SECTIONS = [
+  {
+    field: 'goal',
+    render: (goal) =>
+      typeof goal === 'string' && goal.length > 0 ? `## Goal\n${goal}` : null,
+  },
+  {
+    field: 'changes',
+    render: (changes) =>
+      Array.isArray(changes) && changes.length > 0
+        ? `## Changes\n${changes.map((c) => `- ${String(c)}`).join('\n')}`
+        : null,
+  },
+  {
+    field: 'acceptance',
+    render: (acceptance) =>
+      Array.isArray(acceptance) && acceptance.length > 0
+        ? `## Acceptance\n${acceptance.map((a) => `- [ ] ${String(a)}`).join('\n')}`
+        : null,
+  },
+  {
+    field: 'verify',
+    render: (verify) =>
+      Array.isArray(verify) && verify.length > 0
+        ? `## Verify\n${verify.map((v) => `- ${String(v)}`).join('\n')}`
+        : null,
+  },
+];
+
 /**
  * Convert a decomposer body value into a spec `body` string. The
  * decomposer schema admits two shapes for a Story body:
@@ -190,20 +229,9 @@ function renderBody(body) {
   if (typeof body !== 'object') return undefined;
 
   const sections = [];
-  if (typeof body.goal === 'string' && body.goal.length > 0) {
-    sections.push(`## Goal\n${body.goal}`);
-  }
-  if (Array.isArray(body.changes) && body.changes.length > 0) {
-    const items = body.changes.map((c) => `- ${String(c)}`).join('\n');
-    sections.push(`## Changes\n${items}`);
-  }
-  if (Array.isArray(body.acceptance) && body.acceptance.length > 0) {
-    const items = body.acceptance.map((a) => `- [ ] ${String(a)}`).join('\n');
-    sections.push(`## Acceptance\n${items}`);
-  }
-  if (Array.isArray(body.verify) && body.verify.length > 0) {
-    const items = body.verify.map((v) => `- ${String(v)}`).join('\n');
-    sections.push(`## Verify\n${items}`);
+  for (const descriptor of SPEC_BODY_SECTIONS) {
+    const block = descriptor.render(body[descriptor.field]);
+    if (block !== null) sections.push(block);
   }
   return sections.length > 0 ? sections.join('\n\n') : undefined;
 }

package/.agents/scripts/lib/orchestration/ticket-lease.js

@@ -56,6 +56,9 @@ import { parseLedger } from './lifecycle/trace-logger.js';
  * coordinated under a shared identity) and no assignee PATCH ever writes a
  * literal `[USERNAME]` (HTTP 422).
  */
+// kept (dead-export allowlist): public config sentinel — the distributed
+// `.agentrc.json` / templates carry this literal; exported so consumers and
+// future call sites resolve it by symbol rather than re-typing the string.
 export const OPERATOR_HANDLE_PLACEHOLDER = '@[USERNAME]';
 const OPERATOR_HANDLE_PLACEHOLDER_BARE = '[USERNAME]';
 

package/.agents/scripts/lib/qa/qa-context-hydrator.js

@@ -1,7 +1,7 @@
 /**
  * QA context hydrator — Story #3805, Epic #3798 (f1-shared-qa-core).
  *
- * Both QA front-ends (`/qa-explore` and `/qa-run-harness`) need to load the
+ * Both QA front-ends (`/qa-explore` and `/qa-run`) need to load the
  * *grounded* surface context for an Epic before they reason about what to test:
  * the Epic body, its linked context tickets (PRD / Tech Spec / Acceptance
  * Spec), the project's `.feature` files, the implementation files the surface

package/.agents/scripts/lib/qa/resolve-qa-contract.js

@@ -1,7 +1,7 @@
 /**
  * `qa` contract resolver — Epic #3214, Story #3294.
  *
- * The agent-driven QA harness (`/qa-run-harness`) needs the
+ * The agent-driven QA harness (`/qa-run`) needs the
  * consumer's `.agentrc.json` `qa` block to know where the `.feature` root
  * lives, how to sign in, and which personas the seam accepts. The block is
  * *optional in the schema* (most repos never bind the harness, so config

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

@@ -683,6 +683,108 @@ function serializePathEntry(entry) {
   return JSON.stringify({ path: entry.path, assumption: entry.assumption });
 }
 
+/**
+ * Descriptor table for the human-readable Story-body sections, in canonical
+ * emit order (`## Goal`, `## Changes`, `## Acceptance`, `## Verify`,
+ * `## References`). Each descriptor reads one body field and returns the
+ * section's markdown block when the field is present and non-empty, or `null`
+ * to omit the section.
+ *
+ * Standardising the section ladder as a single data table makes adding a new
+ * optional section a one-line edit here rather than a new control-flow branch
+ * in {@link serialize}.
+ *
+ * @type {Array<{ field: string, render: (value: unknown) => string | null }>}
+ */
+const SERIALIZE_SECTIONS = [
+  {
+    field: 'goal',
+    render: (goal) =>
+      typeof goal === 'string' && goal.trim().length > 0
+        ? `## Goal\n${goal.trim()}`
+        : null,
+  },
+  {
+    field: 'changes',
+    render: (changes) =>
+      Array.isArray(changes) && changes.length > 0
+        ? `## Changes\n${changes.map((c) => `- ${serializePathEntry(c)}`).join('\n')}`
+        : null,
+  },
+  {
+    field: 'acceptance',
+    render: (acceptance) =>
+      Array.isArray(acceptance) && acceptance.length > 0
+        ? `## Acceptance\n${acceptance.map((a) => `- [ ] ${a}`).join('\n')}`
+        : null,
+  },
+  {
+    field: 'verify',
+    render: (verify) =>
+      Array.isArray(verify) && verify.length > 0
+        ? `## Verify\n${verify.map((v) => `- ${v}`).join('\n')}`
+        : null,
+  },
+  {
+    field: 'references',
+    render: (references) =>
+      Array.isArray(references) && references.length > 0
+        ? `## References\n${references.map((r) => `- ${serializePathEntry(r)}`).join('\n')}`
+        : null,
+  },
+];
+
+/**
+ * Build the trailing `<!-- meta: {...} -->` block carrying the fields that
+ * have no human-readable section (`wide`, `reason_to_exist`,
+ * `estimated_test_files`). Returns the empty string when no meta field is
+ * present so {@link serialize} appends nothing.
+ *
+ * Key insertion order (`wide` → `reason_to_exist` → `estimated_test_files`)
+ * is load-bearing: it fixes the serialized JSON byte sequence the parser's
+ * meta round-trip and the unit suite assert against.
+ *
+ * @param {StoryBody} body
+ * @returns {string}
+ */
+function serializeMetaBlock(body) {
+  const metaFields = {};
+  const wide = normalizeWide(body.wide);
+  if (wide !== null) {
+    metaFields.wide = wide;
+  }
+  const reasonToExist = normalizeReasonToExist(body.reason_to_exist);
+  if (reasonToExist !== null) {
+    metaFields.reason_to_exist = reasonToExist;
+  }
+  if (typeof body.estimated_test_files === 'number') {
+    metaFields.estimated_test_files = body.estimated_test_files;
+  }
+  if (Object.keys(metaFields).length === 0) return '';
+  return `\n\n<!-- meta: ${JSON.stringify(metaFields)} -->`;
+}
+
+/**
+ * Build the optional `---` footer block (`parent` / `Epic` / `blocked by`
+ * lines). Returns the empty string when `opts.includeFooter` is falsy.
+ *
+ * @param {StoryBody} body
+ * @param {SerializeOptions} opts
+ * @returns {string}
+ */
+function serializeFooter(body, opts) {
+  if (!opts.includeFooter) return '';
+  const footerLines = ['---'];
+  if (opts.footer?.parent) footerLines.push(`parent: #${opts.footer.parent}`);
+  if (opts.footer?.epic) footerLines.push(`Epic: #${opts.footer.epic}`);
+  if (Array.isArray(body.depends_on)) {
+    for (const dep of body.depends_on) {
+      footerLines.push(`blocked by ${dep}`);
+    }
+  }
+  return `\n\n${footerLines.join('\n')}`;
+}
+
 /**
  * Serialize a structured {@link StoryBody} back to the canonical markdown
  * format written to GitHub issue bodies.
@@ -707,73 +809,16 @@ export function serialize(body, opts = {}) {
   }
 
   const sections = [];
-
-  // ## Goal
-  if (typeof body.goal === 'string' && body.goal.trim().length > 0) {
-    sections.push(`## Goal\n${body.goal.trim()}`);
-  }
-
-  // ## Changes
-  if (Array.isArray(body.changes) && body.changes.length > 0) {
-    const items = body.changes
-      .map((c) => `- ${serializePathEntry(c)}`)
-      .join('\n');
-    sections.push(`## Changes\n${items}`);
-  }
-
-  // ## Acceptance
-  if (Array.isArray(body.acceptance) && body.acceptance.length > 0) {
-    const items = body.acceptance.map((a) => `- [ ] ${a}`).join('\n');
-    sections.push(`## Acceptance\n${items}`);
-  }
-
-  // ## Verify
-  if (Array.isArray(body.verify) && body.verify.length > 0) {
-    const items = body.verify.map((v) => `- ${v}`).join('\n');
-    sections.push(`## Verify\n${items}`);
-  }
-
-  // ## References (only when non-empty)
-  if (Array.isArray(body.references) && body.references.length > 0) {
-    const items = body.references
-      .map((r) => `- ${serializePathEntry(r)}`)
-      .join('\n');
-    sections.push(`## References\n${items}`);
+  for (const descriptor of SERIALIZE_SECTIONS) {
+    const block = descriptor.render(body[descriptor.field]);
+    if (block !== null) sections.push(block);
   }
 
-  let out = sections.join('\n\n');
-
-  // Meta block for fields not representable as human-readable sections.
-  const metaFields = {};
-  const wide = normalizeWide(body.wide);
-  if (wide !== null) {
-    metaFields.wide = wide;
-  }
-  const reasonToExist = normalizeReasonToExist(body.reason_to_exist);
-  if (reasonToExist !== null) {
-    metaFields.reason_to_exist = reasonToExist;
-  }
-  if (typeof body.estimated_test_files === 'number') {
-    metaFields.estimated_test_files = body.estimated_test_files;
-  }
-  if (Object.keys(metaFields).length > 0) {
-    out += `\n\n<!-- meta: ${JSON.stringify(metaFields)} -->`;
-  }
-
-  // Footer
-  if (opts.includeFooter) {
-    const footerLines = ['---'];
-    if (opts.footer?.parent) footerLines.push(`parent: #${opts.footer.parent}`);
-    if (opts.footer?.epic) footerLines.push(`Epic: #${opts.footer.epic}`);
-    if (Array.isArray(body.depends_on)) {
-      for (const dep of body.depends_on) {
-        footerLines.push(`blocked by ${dep}`);
-      }
-    }
-    out += `\n\n${footerLines.join('\n')}`;
-  }
-
-  return out;
+  return (
+    sections.join('\n\n') +
+    serializeMetaBlock(body) +
+    serializeFooter(body, opts)
+  );
 }
 
 // ---------------------------------------------------------------------------

package/.agents/scripts/lib/test-tiers.js

@@ -33,20 +33,26 @@ const matchesIntegration = picomatch(INTEGRATION_INCLUDE, { dot: true });
  * `tests` holds the framework's suite tree; `lib` holds the published CLI
  * (under `lib/cli` and `lib/migrations`) whose tests are colocated in
  * `__tests__` directories per the unit-tier convention in
- * `rules/testing-standards.md`. Without `lib` here, both the quick /
- * integration walk and the full-tier glob set miss the colocated CLI tests,
+ * `rules/testing-standards.md`. `.agents/scripts` holds the orchestration
+ * engine; some of its modules colocate tests in `__tests__` directories the
+ * same way (Story #4195). Without each root here, both the quick /
+ * integration walk and the full-tier glob set miss the colocated tests,
  * leaving that coverage dark in `npm test`. The matching full-tier globs
  * live in `FULL_TIER_GLOBS`.
  */
-const TEST_WALK_ROOTS = ['tests', 'lib'];
+const TEST_WALK_ROOTS = ['tests', 'lib', '.agents/scripts'];
 
 /**
  * Glob targets for the `full` tier — one per walk root in `TEST_WALK_ROOTS`.
- * The `tests` glob is a flat recursive sweep; the `lib` glob is scoped to
- * `__tests__` subtrees so it only matches colocated tests, never the shipped
- * source modules themselves.
+ * The `tests` glob is a flat recursive sweep; the `lib` and `.agents/scripts`
+ * globs are scoped to `__tests__` subtrees so they only match colocated
+ * tests, never the shipped source modules themselves.
  */
-const FULL_TIER_GLOBS = ['tests/**/*.test.js', 'lib/**/__tests__/**/*.test.js'];
+const FULL_TIER_GLOBS = [
+  'tests/**/*.test.js',
+  'lib/**/__tests__/**/*.test.js',
+  '.agents/scripts/**/__tests__/**/*.test.js',
+];
 
 /**
  * @param {string} dir