mandrel 1.94.0 → 2.1.0

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

@@ -1,389 +0,0 @@
-/**
- * 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, TYPE_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];
-    }
-  }
-}
-
-/**
- * Error class thrown synchronously by `assertStoryTypeLabel` when a Story
- * create operation carries no `type::story` label. Named distinctly from
- * `LabelAllowListViolation` so callers can route it separately.
- *
- * The class carries structured metadata (`slug`, `title`) so the error
- * message can name the offending Story clearly.
- */
-export class MissingTypeLabelError extends Error {
-  /**
-   * @param {string} message
-   * @param {{slug?: string, title?: string}} [meta]
-   */
-  constructor(message, meta = {}) {
-    super(message);
-    this.name = 'MissingTypeLabelError';
-    if (meta.slug !== undefined) this.slug = meta.slug;
-    if (meta.title !== undefined) this.title = meta.title;
-  }
-}
-
-/**
- * Diff-time assertion. Throws `MissingTypeLabelError` synchronously when a
- * Story create operation is missing the mandatory `type::story` label.
- *
- * Symmetric with `assertNoAgentLabels`: both fire at diff time so the plan
- * fails loudly before the apply pipeline touches GitHub.
- *
- * Only validates Story create ops — Epic creates carry a different mandatory
- * label (`type::epic`) that the caller already hard-codes at issue-creation
- * time; the assertion is not needed there.
- *
- * @param {{slug?: string, title?: string, entity?: string, labels?: string[]}} op
- * @returns {void}
- */
-export function assertStoryTypeLabel(op) {
-  if (!op || typeof op !== 'object') return;
-  if (op.entity !== 'story') return;
-  // A create op for a Story MUST carry type::story. An absent or empty labels
-  // array means the mandatory label is missing — fail loud so the operator
-  // sees a named Story rather than a silent unlabeled issue on GitHub.
-  if (!Array.isArray(op.labels) || !op.labels.includes(TYPE_LABELS.STORY)) {
-    throw new MissingTypeLabelError(
-      `create plan for story slug=${op.slug ?? '?'} ("${op.title ?? ''}") is ` +
-        `missing the mandatory "${TYPE_LABELS.STORY}" label. Add it to the ` +
-        `spec's labels array for this Story and re-run.`,
-      { slug: op.slug, title: op.title },
-    );
-  }
-}
-
-/**
- * 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);
-    assertStoryTypeLabel(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

@@ -1,230 +0,0 @@
-/**
- * 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');
-}