mandrel 1.57.0

package/.agents/scripts/lib/orchestration/epic-spec-reconciler-discriminator.js

@@ -0,0 +1,335 @@
+/**
+ * lib/orchestration/epic-spec-reconciler-discriminator.js — pure drift
+ * discriminator for the epic-spec reconciler (Epic #1182 / Tech Spec
+ * #1483 / Story #1493).
+ *
+ * The reconciler must never clobber state owned by the wave-runner. The
+ * spec carries structural fields (title, body, structural labels, parent,
+ * dependsOn) while the wave-runner owns execution state (`agent::*`
+ * labels, PR linkage, merge state, issue close state). When the spec
+ * drops a Story whose branch is already merged — or when a structural
+ * diff would touch an `agent::*` label — the reconciler must refuse.
+ *
+ * The module exports `mayClose` (Task #1512), `mayUpdate` (Task #1513),
+ * `STRUCTURAL_LABELS` plus the diff-time assertion (Task #1515), and is
+ * exercised by the regression suite in Task #1517.
+ *
+ * All predicates here are I/O-free and accept plain data objects only.
+ * Same inputs → same answer, every time. They do not call GitHub, the
+ * file system, the clock, or any provider — the reconciler's apply
+ * pipeline is the only place that touches the world.
+ *
+ * ## `mayClose(story, opts)`
+ *
+ * @typedef {object} StorySnapshot
+ * @property {string}  [status]        Current `agent::*` status string.
+ *                                     Compared against AGENT_LABELS.
+ * @property {boolean} [hasMergedPr]   True when an associated PR has
+ *                                     already merged into the epic branch.
+ * @property {number}  [openPrCount]   Open PR count linked to the Story
+ *                                     branch. Any positive value blocks.
+ *
+ * @typedef {object} MayCloseOptions
+ * @property {boolean} [explicitDelete]
+ *   Operator's explicit intent to delete the Story even if quiescent.
+ *   Omitted / false means "only close if every other signal is also
+ *   quiescent" — but the discriminator still requires an explicit
+ *   acknowledgement (the spec dropping the slug is NOT enough on its
+ *   own). When omitted, `mayClose` always returns
+ *   `{ allowed: false, reason: 'explicit-delete-required' }` so the diff
+ *   cannot accidentally close a Story the operator did not opt in to
+ *   deleting.
+ *
+ * @typedef {object} PredicateResult
+ * @property {boolean} allowed
+ * @property {string}  [reason]   Structured reason code when allowed=false.
+ */
+
+import { AGENT_LABELS } from '../label-constants.js';
+
+/**
+ * Execution-signal labels that block Close. Stored as a frozen Set for
+ * O(1) lookup. Anything in this set counts as live execution state the
+ * wave-runner owns — the reconciler must stand back.
+ */
+const EXECUTION_STATUS_LABELS = Object.freeze(
+  new Set([
+    AGENT_LABELS.DONE,
+    AGENT_LABELS.REVIEW_SPEC,
+    AGENT_LABELS.EXECUTING,
+  ]),
+);
+
+/**
+ * Predicate gating Close operations on a Story.
+ *
+ * Returns `{ allowed: true }` only when:
+ *   1. `opts.explicitDelete === true` (operator opted in), AND
+ *   2. `story.status` is NOT one of `agent::done|review-spec|executing`, AND
+ *   3. `story.hasMergedPr` is not truthy, AND
+ *   4. `story.openPrCount` is `0` or absent.
+ *
+ * The Tech Spec's destructive-replan regression case is the prime mover
+ * here: a Story whose branch is already merged must NEVER be closed by
+ * the reconciler, no matter what the spec says. Likewise, a Story
+ * `agent::executing` is live work the wave-runner is driving and the
+ * reconciler must stand back.
+ *
+ * Execution signals are checked **before** the explicit-delete gate so
+ * the reason code reports the most specific blocker rather than the
+ * broader opt-in failure.
+ *
+ * @param {StorySnapshot} [story]
+ * @param {MayCloseOptions} [opts]
+ * @returns {PredicateResult}
+ */
+export function mayClose(story = {}, opts = {}) {
+  if (story.status && EXECUTION_STATUS_LABELS.has(story.status)) {
+    return {
+      allowed: false,
+      reason: `execution-status:${story.status}`,
+    };
+  }
+  if (story.hasMergedPr) {
+    return { allowed: false, reason: 'merged-pr-exists' };
+  }
+  if (typeof story.openPrCount === 'number' && story.openPrCount > 0) {
+    return { allowed: false, reason: 'open-pr-exists' };
+  }
+  if (opts.explicitDelete !== true) {
+    return { allowed: false, reason: 'explicit-delete-required' };
+  }
+  return { allowed: true };
+}
+
+/**
+ * Frozen list of the AGENT_LABELS values, used by `mayUpdate` (and, when
+ * Task #1515 lands, by the diff-time assertion). Building this once at
+ * module load keeps the predicate allocation-free.
+ */
+const AGENT_LABEL_VALUES = Object.freeze(Object.values(AGENT_LABELS));
+
+/**
+ * The structural-field allow-list for `mayUpdate(story, field)`. These
+ * are the only fields the spec is authoritative over; anything outside
+ * the list is wave-runner state and must not be touched by the
+ * reconciler. Stored as a frozen Set for O(1) membership checks.
+ *
+ * `wave` is included because the reconciler is the only authority for
+ * wave numbering — wave-runner state lives in agent::* labels and PR
+ * linkage, not in the wave integer.
+ */
+const STRUCTURAL_FIELDS = Object.freeze(
+  new Set(['title', 'body', 'labels', 'parent', 'dependsOn', 'wave']),
+);
+
+/**
+ * Predicate gating Update operations on a Story field.
+ *
+ * Returns `{ allowed: false }` for any field name that:
+ *   - is not a string (defensive — diff engine should never reach here
+ *     with a non-string field), OR
+ *   - is a label value that intersects AGENT_LABELS (so callers can
+ *     pass either a field name like `'title'` or a candidate label like
+ *     `'agent::executing'` and the predicate rejects the latter), OR
+ *   - is not in the structural allow-list
+ *     (`title|body|labels|parent|dependsOn|wave`).
+ *
+ * The Task #1513 acceptance criteria require:
+ *   1. Every AGENT_LABELS value returns `allowed=false`.
+ *   2. `title|body|parent|dependsOn` return `allowed=true`.
+ *   3. The implementation imports AGENT_LABELS from label-constants.js
+ *      rather than maintaining a local copy.
+ *
+ * Reason codes are structured strings prefixed by the failure mode so
+ * callers can pattern-match without keeping the constant set in sync:
+ *
+ *   - `invalid-field`            — non-string / empty.
+ *   - `agent-label:<name>`       — field is an agent::* label.
+ *   - `non-structural-field:<n>` — field is not in the allow-list.
+ *
+ * @param {StorySnapshot} [_story]  Reserved for future signal-aware
+ *                                   predicates. Currently unused —
+ *                                   structural fields are universally
+ *                                   updatable regardless of story state.
+ * @param {string} field
+ * @returns {PredicateResult}
+ */
+export function mayUpdate(_story, field) {
+  if (typeof field !== 'string' || field.length === 0) {
+    return { allowed: false, reason: 'invalid-field' };
+  }
+  if (AGENT_LABEL_VALUES.includes(field)) {
+    return { allowed: false, reason: `agent-label:${field}` };
+  }
+  if (!STRUCTURAL_FIELDS.has(field)) {
+    return { allowed: false, reason: `non-structural-field:${field}` };
+  }
+  return { allowed: true };
+}
+
+/**
+ * STRUCTURAL_LABELS — the structural side of the project label namespace
+ * (complement of AGENT_LABELS).
+ *
+ * The Tech Spec wording — "STRUCTURAL_LABELS is the complement of
+ * AGENT_LABELS within the project's label namespace" — does not pin a
+ * static enumeration: the structural label set is open (type::*,
+ * persona::*, context::*, status::*, and bespoke per-Epic tags), while
+ * the agent set is closed and small. We therefore expose the membership
+ * filter rather than a static enumeration; consumers pass their full
+ * label list and the helper returns the complement.
+ *
+ * Helpers:
+ *
+ *   - `isStructuralLabel(label)` — true iff the label is NOT in AGENT_LABELS.
+ *   - `partitionLabels(labels)`  — split a label array into
+ *                                  `{ structural, agent }` buckets.
+ *   - `AGENT_LABEL_VALUES`       — the deny-list (frozen array).
+ *
+ * Tests assert `isStructuralLabel(agent::*)` is false for every entry of
+ * AGENT_LABELS and `partitionLabels(['type::story', 'agent::executing'])`
+ * splits cleanly, which is the closest finite assertion of the
+ * complement contract.
+ *
+ * @type {{
+ *   isStructuralLabel: (label: string) => boolean,
+ *   partitionLabels: (labels: string[]) => { structural: string[], agent: string[] },
+ *   AGENT_LABEL_VALUES: readonly string[],
+ * }}
+ */
+export const STRUCTURAL_LABELS = Object.freeze({
+  AGENT_LABEL_VALUES,
+  isStructuralLabel(label) {
+    return typeof label === 'string' && !AGENT_LABEL_VALUES.includes(label);
+  },
+  partitionLabels(labels) {
+    const structural = [];
+    const agent = [];
+    for (const label of labels ?? []) {
+      if (typeof label !== 'string') continue;
+      if (AGENT_LABEL_VALUES.includes(label)) {
+        agent.push(label);
+      } else {
+        structural.push(label);
+      }
+    }
+    return { structural, agent };
+  },
+});
+
+/**
+ * Error class thrown synchronously by the diff-time assertion when a
+ * plan operation targets an `agent::*` label. Named so callers can
+ * `instanceof`-check and so the apply pipeline distinguishes it from
+ * generic `TypeError`s emitted by the operation factories.
+ *
+ * The class carries structured metadata (`slug`, `field`,
+ * `offendingLabels`) so the dispatch manifest / wave-runner logs can
+ * route the failure back to the offending Story without re-parsing the
+ * message string.
+ */
+export class LabelAllowListViolation extends Error {
+  /**
+   * @param {string} message
+   * @param {{slug?: string, field?: string, offendingLabels?: string[]}} [meta]
+   */
+  constructor(message, meta = {}) {
+    super(message);
+    this.name = 'LabelAllowListViolation';
+    if (meta.slug !== undefined) this.slug = meta.slug;
+    if (meta.field !== undefined) this.field = meta.field;
+    if (meta.offendingLabels !== undefined) {
+      this.offendingLabels = [...meta.offendingLabels];
+    }
+  }
+}
+
+/**
+ * Diff-time assertion. Throws `LabelAllowListViolation` synchronously
+ * when an operation targets an `agent::*` label. The assertion is the
+ * safety net for the apply pipeline: plans fail loudly at construction
+ * time, not silently mis-apply at runtime.
+ *
+ * Accepts the change-key list either via `op.changes` (UpdateOp) or via
+ * a `labels` array (CreateOp). Other op kinds (Close, Relink) carry no
+ * label payload and are no-ops.
+ *
+ * @param {{kind?: string, slug?: string, changes?: Record<string, unknown>, labels?: string[]}} op
+ * @returns {void}
+ */
+export function assertNoAgentLabels(op) {
+  if (!op || typeof op !== 'object') return;
+
+  // UpdateOp — every key in `changes` must be either a structural field
+  // or a structural label name. The diff engine currently emits
+  // `title|body|labels|wave`, but the assertion also catches an apply-
+  // pipeline bug that would route an `agent::*` rename through here.
+  if (op.changes && typeof op.changes === 'object') {
+    const offending = Object.keys(op.changes).filter((key) =>
+      AGENT_LABEL_VALUES.includes(key),
+    );
+    if (offending.length > 0) {
+      throw new LabelAllowListViolation(
+        `update plan for slug=${op.slug ?? '?'} targets agent label(s): ${offending.join(', ')}`,
+        { slug: op.slug, field: offending[0], offendingLabels: offending },
+      );
+    }
+    // The `labels` change set itself must not write an agent::* into
+    // labels.after — an update that adds an agent label is just as bad
+    // as one keyed by the agent label name.
+    const labelChange = /** @type {{after?: unknown}} */ (op.changes.labels);
+    if (
+      labelChange &&
+      typeof labelChange === 'object' &&
+      Array.isArray(labelChange.after)
+    ) {
+      const after = /** @type {string[]} */ (labelChange.after);
+      const agentInAfter = after.filter((label) =>
+        AGENT_LABEL_VALUES.includes(label),
+      );
+      if (agentInAfter.length > 0) {
+        throw new LabelAllowListViolation(
+          `update plan for slug=${op.slug ?? '?'} writes agent label(s) into labels.after: ${agentInAfter.join(', ')}`,
+          {
+            slug: op.slug,
+            field: 'labels',
+            offendingLabels: agentInAfter,
+          },
+        );
+      }
+    }
+  }
+
+  // CreateOp — labels array must not contain any agent::* value.
+  if (Array.isArray(op.labels)) {
+    const offending = op.labels.filter((label) =>
+      AGENT_LABEL_VALUES.includes(label),
+    );
+    if (offending.length > 0) {
+      throw new LabelAllowListViolation(
+        `create plan for slug=${op.slug ?? '?'} carries agent label(s): ${offending.join(', ')}`,
+        {
+          slug: op.slug,
+          field: 'labels',
+          offendingLabels: offending,
+        },
+      );
+    }
+  }
+}
+
+/**
+ * Assert the same invariant over an entire plan. Convenience wrapper for
+ * the diff engine — iterates every bucket and throws on the first
+ * violation. Pure; raises synchronously.
+ *
+ * @param {{creates?: object[], updates?: object[], closes?: object[], relinks?: object[]}} plan
+ * @returns {void}
+ */
+export function assertPlanLabelAllowList(plan) {
+  if (!plan || typeof plan !== 'object') return;
+  for (const op of plan.creates ?? []) assertNoAgentLabels(op);
+  for (const op of plan.updates ?? []) assertNoAgentLabels(op);
+  // closes/relinks do not carry label payloads — nothing to assert.
+}

package/.agents/scripts/lib/orchestration/epic-spec-reconciler-format.js

@@ -0,0 +1,230 @@
+/**
+ * lib/orchestration/epic-spec-reconciler-format.js — human-readable plan
+ * renderer for the epic-spec reconciler (Story #1492 / Task #1511).
+ *
+ * Takes a `Plan` (from `epic-spec-reconciler-diff.js`) and returns a
+ * deterministic Markdown block suitable for:
+ *
+ *   • CLI dry-run output (`reconciler --dry-run`).
+ *   • Sticky comment bodies on the Epic ticket (apply preview).
+ *   • Test fixtures that snapshot a plan's rendering.
+ *
+ * ## Determinism guarantees
+ *
+ *   • Operations are emitted in four fixed sections — Create, Update,
+ *     Close, Relink — in that order. Sections always appear, even when
+ *     empty (the empty marker is `_no operations_`), so the structure
+ *     of the output is stable across plans.
+ *   • Within each section, operations are sorted by slug. This matches
+ *     the sort the diff engine already applies, so the formatter never
+ *     reorders relative to the plan input; the assertion just guards
+ *     callers that hand-build a plan.
+ *   • Each operation line names the slug, the target issue number (when
+ *     known), and the changed fields. Changed-field keys are sorted so
+ *     `body, labels, title` always appears in that order.
+ *   • Label arrays are pre-sorted by the operation constructors, so the
+ *     output never reorders them.
+ *
+ * The formatter performs no I/O and consumes no external state.
+ */
+
+import { isPlan } from './epic-spec-reconciler-ops.js';
+
+const HEADINGS = Object.freeze({
+  creates: '## Creates',
+  updates: '## Updates',
+  closes: '## Closes',
+  relinks: '## Relinks',
+});
+
+/**
+ * Render an issue-number suffix (e.g. ` (#123)`) when known, else empty.
+ *
+ * @param {number|undefined} issueNumber
+ * @returns {string}
+ */
+function issueSuffix(issueNumber) {
+  if (typeof issueNumber !== 'number' || !Number.isFinite(issueNumber)) {
+    return '';
+  }
+  return ` (#${issueNumber})`;
+}
+
+/**
+ * Format a single CreateOp as a Markdown bullet line.
+ *
+ *   - `slug` [entity]: <title> [labels=…] [parent=…] [wave=…] [dependsOn=…]
+ *
+ * @param {import('./epic-spec-reconciler-ops.js').CreateOp} op
+ * @returns {string}
+ */
+function formatCreate(op) {
+  const parts = [`- \`${op.slug}\` [${op.entity}]: ${op.title}`];
+  if (op.labels?.length) parts.push(`labels=[${op.labels.join(', ')}]`);
+  if (op.parentSlug) parts.push(`parent=${op.parentSlug}`);
+  if (typeof op.wave === 'number') parts.push(`wave=${op.wave}`);
+  if (op.dependsOn?.length)
+    parts.push(`dependsOn=[${op.dependsOn.join(', ')}]`);
+  return parts.join(' · ');
+}
+
+/**
+ * Render a single field change as `field: <before> → <after>`. Strings
+ * are bounded so the line stays single-line-readable; arrays render as
+ * bracketed comma-separated lists; objects fall back to JSON.
+ *
+ * @param {string} field
+ * @param {{before: unknown, after: unknown}} change
+ * @returns {string}
+ */
+function formatChange(field, change) {
+  return `${field}: ${stringifyValue(change.before)} → ${stringifyValue(change.after)}`;
+}
+
+/**
+ * Render a single primitive/array/object for the dry-run output. Strings
+ * are quoted when they contain whitespace or are empty, so a label-strip
+ * (`"x" → ""`) is visually obvious in the rendered output.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+function stringifyValue(value) {
+  if (value === null) return 'null';
+  if (value === undefined) return '∅';
+  if (Array.isArray(value)) {
+    return `[${value.map(stringifyValue).join(', ')}]`;
+  }
+  if (typeof value === 'string') {
+    if (value === '' || /\s/.test(value)) return JSON.stringify(value);
+    return value;
+  }
+  if (typeof value === 'object') {
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+
+/**
+ * Format a single UpdateOp.
+ *
+ *   - `slug` [entity] (#123): body: "…" → "…", title: "…" → "…"
+ *
+ * @param {import('./epic-spec-reconciler-ops.js').UpdateOp} op
+ * @returns {string}
+ */
+function formatUpdate(op) {
+  const fields = Object.keys(op.changes ?? {}).sort();
+  const rendered = fields.map((f) => formatChange(f, op.changes[f]));
+  const head = `- \`${op.slug}\` [${op.entity}]${issueSuffix(op.issueNumber)}`;
+  if (rendered.length === 0) return `${head}: (no changes)`;
+  return `${head}: ${rendered.join('; ')}`;
+}
+
+/**
+ * Format a single CloseOp.
+ *
+ *   - `slug` [entity] (#123): <title>
+ *
+ * @param {import('./epic-spec-reconciler-ops.js').CloseOp} op
+ * @returns {string}
+ */
+function formatClose(op) {
+  const head = `- \`${op.slug}\` [${op.entity}]${issueSuffix(op.issueNumber)}`;
+  return op.title ? `${head}: ${op.title}` : head;
+}
+
+/**
+ * Format a single RelinkOp.
+ *
+ *   - `slug` [entity] (#123): parent: a → b · dependsOn: [x] → [y, z]
+ *
+ * @param {import('./epic-spec-reconciler-ops.js').RelinkOp} op
+ * @returns {string}
+ */
+function formatRelink(op) {
+  const head = `- \`${op.slug}\` [${op.entity}]${issueSuffix(op.issueNumber)}`;
+  const parts = [];
+  if (op.parent) {
+    parts.push(
+      `parent: ${stringifyValue(op.parent.before)} → ${stringifyValue(op.parent.after)}`,
+    );
+  }
+  if (op.dependsOn) {
+    parts.push(
+      `dependsOn: ${stringifyValue(op.dependsOn.before)} → ${stringifyValue(op.dependsOn.after)}`,
+    );
+  }
+  if (parts.length === 0) return `${head}: (no edge changes)`;
+  return `${head}: ${parts.join(' · ')}`;
+}
+
+/**
+ * Sort operations by slug; defensive copy so we never mutate the caller's
+ * plan even if they handed in an unsorted bucket.
+ *
+ * @template {{slug: string}} T
+ * @param {T[]} ops
+ * @returns {T[]}
+ */
+function sortBySlug(ops) {
+  return [...ops].sort((a, b) => a.slug.localeCompare(b.slug));
+}
+
+/**
+ * Render a single section (heading + body). Always emits the heading so
+ * the four-section structure is invariant.
+ *
+ * @param {string} heading
+ * @param {string[]} lines
+ * @returns {string}
+ */
+function renderSection(heading, lines) {
+  if (lines.length === 0) {
+    return `${heading}\n\n_no operations_`;
+  }
+  return `${heading}\n\n${lines.join('\n')}`;
+}
+
+/**
+ * Header line for the rendered plan.
+ *
+ * @param {import('./epic-spec-reconciler-ops.js').Plan} plan
+ * @returns {string}
+ */
+function renderHeader(plan) {
+  const total =
+    plan.creates.length +
+    plan.updates.length +
+    plan.closes.length +
+    plan.relinks.length;
+  if (total === 0) {
+    return '# Reconciler plan — no operations (idempotent)';
+  }
+  return `# Reconciler plan — ${total} operation${total === 1 ? '' : 's'}`;
+}
+
+/**
+ * Render `plan` to a deterministic Markdown block. The output is stable
+ * for a given plan; rendering an empty plan returns the canonical
+ * "no operations" form so consumers can detect idempotent reconciles
+ * by string equality.
+ *
+ * @param {import('./epic-spec-reconciler-ops.js').Plan} plan
+ * @returns {string}
+ */
+export function formatPlan(plan) {
+  if (!isPlan(plan)) {
+    throw new TypeError(
+      'formatPlan: input is not a Plan (expected { creates, updates, closes, relinks })',
+    );
+  }
+  const sections = [
+    renderHeader(plan),
+    renderSection(HEADINGS.creates, sortBySlug(plan.creates).map(formatCreate)),
+    renderSection(HEADINGS.updates, sortBySlug(plan.updates).map(formatUpdate)),
+    renderSection(HEADINGS.closes, sortBySlug(plan.closes).map(formatClose)),
+    renderSection(HEADINGS.relinks, sortBySlug(plan.relinks).map(formatRelink)),
+  ];
+  return sections.join('\n\n');
+}