mandrel 1.57.0

package/.agents/scripts/lib/label-constants.js

@@ -0,0 +1,169 @@
+/**
+ * Central source of truth for all GitHub label names used by the orchestrator.
+ *
+ * Every other module (label-taxonomy, dispatch-engine, story-close,
+ * etc.) should import from here rather than using string literals. Renames
+ * land in one place.
+ */
+
+export const AGENT_LABELS = {
+  REVIEW_SPEC: 'agent::review-spec',
+  READY: 'agent::ready',
+  EXECUTING: 'agent::executing',
+  // Story #2144 — intermediate state owned by `story-close.js`. A Story
+  // flips to `agent::closing` after preflight validation succeeds and
+  // before the merge into `epic/<id>` is attempted. It flips to
+  // `agent::done` only after the post-merge pipeline confirms the merge
+  // landed; if the close is killed mid-flight, the Story remains at
+  // `agent::closing` so a `/story-execute --resume` can pick up at the
+  // post-merge phase rather than re-running preflight. The label is the
+  // distinguishing signal between "hung close" and "finished work".
+  CLOSING: 'agent::closing',
+  DONE: 'agent::done',
+  BLOCKED: 'agent::blocked',
+};
+
+/**
+ * Allowed state-machine transitions across `agent::*` labels.
+ *
+ * The validator is permissive in the directions that pre-Story #2144
+ * lifecycles relied on (e.g. `executing → done` for Tasks, which never
+ * route through the closing chokepoint) and restrictive on the post-
+ * `closing` exits: once a ticket is at `agent::closing` it may only
+ * advance to `done` (merge landed) or fall back to `blocked` (close
+ * failed and the operator must intervene).
+ *
+ * Each key is a source label; each value is the set of permitted target
+ * labels reachable in a single transition. Transitions absent from this
+ * map MUST be treated as invalid by the validator. Self-transitions
+ * (e.g. `executing → executing`) are not permitted.
+ */
+export const VALID_TRANSITIONS = {
+  'agent::review-spec': ['agent::ready', 'agent::blocked'],
+  'agent::ready': ['agent::executing', 'agent::blocked'],
+  'agent::executing': ['agent::closing', 'agent::done', 'agent::blocked'],
+  'agent::closing': ['agent::done', 'agent::blocked'],
+  'agent::blocked': [
+    'agent::ready',
+    'agent::executing',
+    'agent::closing',
+    'agent::done',
+  ],
+  // Terminal: no outbound transitions from done. (A ticket can be
+  // reopened by the operator, which removes the label entirely; that
+  // is not modelled as a transition because the from-state at re-open
+  // is `null`, not `agent::done`.)
+  'agent::done': [],
+};
+
+/**
+ * Returns true when transitioning from `fromState` to `toState` is allowed
+ * by {@link VALID_TRANSITIONS}. A `null` / `undefined` `fromState` is
+ * treated as the initial-entry edge and permits any state — the writer
+ * is establishing a state where there was none.
+ *
+ * @param {string|null|undefined} fromState
+ * @param {string} toState
+ * @returns {boolean}
+ */
+export function isValidTransition(fromState, toState) {
+  if (fromState == null) return Object.values(AGENT_LABELS).includes(toState);
+  if (fromState === toState) return false;
+  const allowed = VALID_TRANSITIONS[fromState];
+  if (!allowed) return false;
+  return allowed.includes(toState);
+}
+
+export const TYPE_LABELS = {
+  EPIC: 'type::epic',
+  FEATURE: 'type::feature',
+  STORY: 'type::story',
+};
+
+export const STATUS_LABELS = {
+  BLOCKED: 'status::blocked',
+};
+
+/**
+ * Persona labels are derived at bootstrap time from `.agents/personas/*.md`
+ * (see `label-taxonomy.js`), not hard-coded here — the persona file is the
+ * source of truth, and ticket hydration resolves the label value to the
+ * matching filename.
+ */
+export const PERSONA_LABEL_PREFIX = 'persona::';
+
+export const CONTEXT_LABELS = {
+  PRD: 'context::prd',
+  TECH_SPEC: 'context::tech-spec',
+  ACCEPTANCE_SPEC: 'context::acceptance-spec',
+};
+
+/** Convenience aliases so callers can reach the new constants by name without
+ * indexing into CONTEXT_LABELS. Mirrors the export ergonomics used by other
+ * consumers that import named constants (e.g. PERSONA_LABEL_PREFIX). */
+export const CONTEXT_ACCEPTANCE_SPEC = CONTEXT_LABELS.ACCEPTANCE_SPEC;
+
+/**
+ * Acceptance-axis labels for opt-out signalling on Stories and Features that
+ * intentionally have no acceptance-spec coverage. Separate namespace from
+ * `context::` because it expresses absence rather than a linked context
+ * ticket.
+ */
+export const ACCEPTANCE_LABELS = {
+  N_A: 'acceptance::n-a',
+};
+
+export const ACCEPTANCE_NA = ACCEPTANCE_LABELS.N_A;
+
+/**
+ * Meta-axis labels for retrospective signal routing (Epic #2547 — feedback
+ * loop). `meta::framework-gap` is applied to issues that surface a defect or
+ * missing capability in the framework itself; `meta::consumer-improvement`
+ * is applied to issues that surface improvements to a consumer project
+ * (workflow tweaks, ergonomic asks, doc polish). The `/epic-plan` Phase 0
+ * fetcher (see `lib/feedback-loop/prior-feedback-fetcher.js`) reads open
+ * issues carrying either label and surfaces them to the planner so retro
+ * signals are routed into durable substrates rather than lost in chat.
+ */
+export const META_LABELS = {
+  FRAMEWORK_GAP: 'meta::framework-gap',
+  CONSUMER_IMPROVEMENT: 'meta::consumer-improvement',
+};
+
+/**
+ * Planning-axis labels (Epic #2880 F7). Currently scoped to the
+ * `planning::healthcheck-waived` operator-applied waiver, which is the
+ * documented escape hatch for the `/epic-plan` Phase 10 readiness
+ * healthcheck (`epic-plan-healthcheck.js`). The persist half of
+ * `epic-plan-decompose.js` refuses to flip an Epic to `agent::ready`
+ * when the healthcheck returned `ok: false` unless this label is
+ * present — see `.agents/docs/SDLC.md` § "`agent::ready` exit conditions"
+ * for the full handoff contract.
+ *
+ * Future planning-axis waivers (one per failing exit condition) extend
+ * this enum so consumers can reference them by symbol.
+ */
+export const PLANNING_LABELS = {
+  HEALTHCHECK_WAIVED: 'planning::healthcheck-waived',
+};
+
+/**
+ * Convenience named export so callers can reach the constant without
+ * indexing into PLANNING_LABELS — mirrors the ergonomics used by
+ * ACCEPTANCE_NA / CONTEXT_ACCEPTANCE_SPEC. The literal value is
+ * duplicated here (rather than aliased through PLANNING_LABELS) so a
+ * grep for `PLANNING_HEALTHCHECK_WAIVED.*planning::healthcheck-waived`
+ * matches a single line — see Story #2921 Task #2933 AC #1.
+ */
+export const PLANNING_HEALTHCHECK_WAIVED = 'planning::healthcheck-waived';
+
+/** Palette for the taxonomy; consumed by label-taxonomy.js. */
+export const LABEL_COLORS = {
+  TYPE: '#7057FF',
+  AGENT: '#0E8A16',
+  STATUS_BLOCKED: '#D93F0B',
+  PERSONA: '#C5DEF5',
+  CONTEXT: '#D4C5F9',
+  ACCEPTANCE: '#FBCA04',
+  PLANNING: '#FEF2C0',
+};

package/.agents/scripts/lib/label-taxonomy.js

@@ -0,0 +1,200 @@
+/**
+ * Shared data structures for GitHub labels and custom fields.
+ * Used by the bootstrap script to idempotently configure the project.
+ *
+ * All label names are sourced from `label-constants.js` so renames only need
+ * to happen in one place. Colors come from `LABEL_COLORS` in the same module.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  ACCEPTANCE_LABELS,
+  AGENT_LABELS,
+  CONTEXT_LABELS,
+  LABEL_COLORS,
+  PERSONA_LABEL_PREFIX,
+  PLANNING_LABELS,
+  STATUS_LABELS,
+  TYPE_LABELS,
+} from './label-constants.js';
+
+const PERSONAS_DIR = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  '..',
+  'personas',
+);
+
+/**
+ * Discover persona labels from `.agents/personas/*.md`. The filename
+ * (without extension) is the label suffix — this is the same value the
+ * context hydrator uses to resolve `persona::<name>` to its markdown file.
+ */
+function buildPersonaLabels() {
+  return fs
+    .readdirSync(PERSONAS_DIR)
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => f.slice(0, -3))
+    .sort()
+    .map((name) => ({
+      name: `${PERSONA_LABEL_PREFIX}${name}`,
+      color: LABEL_COLORS.PERSONA,
+      description: `${name} persona`,
+    }));
+}
+
+/** @type {Array<{ name: string, color: string, description: string }>} */
+export const LABEL_TAXONOMY = [
+  // Type
+  {
+    name: TYPE_LABELS.EPIC,
+    color: LABEL_COLORS.TYPE,
+    description: 'Epic-level work item',
+  },
+  {
+    name: TYPE_LABELS.FEATURE,
+    color: LABEL_COLORS.TYPE,
+    description: 'Feature under an Epic',
+  },
+  {
+    name: TYPE_LABELS.STORY,
+    color: LABEL_COLORS.TYPE,
+    description: 'User story under a Feature',
+  },
+
+  // Agent State
+  {
+    name: AGENT_LABELS.REVIEW_SPEC,
+    color: LABEL_COLORS.AGENT,
+    description:
+      'Parking state — PRD + Tech Spec exist; awaiting human review before decomposition',
+  },
+  {
+    name: AGENT_LABELS.READY,
+    color: LABEL_COLORS.AGENT,
+    description:
+      'Parking state — frozen dispatch manifest exists; awaiting local /epic-deliver',
+  },
+  {
+    name: AGENT_LABELS.EXECUTING,
+    color: LABEL_COLORS.AGENT,
+    description: 'Agent is working on this',
+  },
+  {
+    name: AGENT_LABELS.CLOSING,
+    color: LABEL_COLORS.AGENT,
+    description: 'Close preflight passed; awaiting merge into the Epic branch',
+  },
+  {
+    name: AGENT_LABELS.DONE,
+    color: LABEL_COLORS.AGENT,
+    description: 'Agent work completed',
+  },
+
+  // Status
+  {
+    name: STATUS_LABELS.BLOCKED,
+    color: LABEL_COLORS.STATUS_BLOCKED,
+    description: 'Blocked by a dependency',
+  },
+
+  // Persona — dynamically derived from .agents/personas/*.md
+  ...buildPersonaLabels(),
+
+  // Context
+  {
+    name: CONTEXT_LABELS.PRD,
+    color: LABEL_COLORS.CONTEXT,
+    description: 'Product Requirements Document',
+  },
+  {
+    name: CONTEXT_LABELS.TECH_SPEC,
+    color: LABEL_COLORS.CONTEXT,
+    description: 'Technical Specification',
+  },
+  {
+    name: CONTEXT_LABELS.ACCEPTANCE_SPEC,
+    color: LABEL_COLORS.CONTEXT,
+    description: 'Acceptance Specification (Gherkin scenarios)',
+  },
+
+  // Acceptance axis — explicit opt-out signal for Stories/Features that
+  // intentionally have no acceptance-spec coverage.
+  {
+    name: ACCEPTANCE_LABELS.N_A,
+    color: LABEL_COLORS.ACCEPTANCE,
+    description: 'No acceptance specification required',
+  },
+
+  // Planning axis — operator-applied waivers for the planning → delivery
+  // handoff gates. Currently the sole entry is the `healthcheck-waived`
+  // override consumed by the persist half of `epic-plan-decompose.js`
+  // when `epic-plan-healthcheck.js` returned `ok: false` for a reason
+  // the operator has triaged and accepted.
+  {
+    name: PLANNING_LABELS.HEALTHCHECK_WAIVED,
+    color: LABEL_COLORS.PLANNING,
+    description:
+      'Operator override — allows agent::ready handoff despite a failing post-plan healthcheck',
+  },
+];
+
+/** @type {Array<{ name: string, type: 'single_select', options?: string[] }>} */
+export const PROJECT_FIELD_DEFS = [
+  {
+    name: 'Execution',
+    type: 'single_select',
+    options: ['sequential', 'concurrent'],
+  },
+];
+
+/**
+ * Canonical lifecycle options for the Status single-select field. These are
+ * the three stock GitHub Projects v2 options; granular lifecycle state lives
+ * in the `agent::*` labels and `ColumnSync` collapses each label onto one of
+ * these three buckets via `LABEL_TO_COLUMN` in
+ * `lib/orchestration/column-sync.js`. Order matches the order options appear
+ * on a fresh GitHub board.
+ *
+ * @type {string[]}
+ */
+export const STATUS_FIELD_OPTIONS = ['Todo', 'In Progress', 'Done'];
+
+/**
+ * Default Projects V2 saved Views. Filter strings follow GitHub's Projects
+ * search syntax (`label:`, `status:`, `assignee:`). Each is grouped by the
+ * Status field to match the board's columnar layout.
+ *
+ * GitHub's GraphQL surface does not expose a public `createProjectV2View`
+ * mutation, so bootstrap creates these via the REST Projects V2 views
+ * endpoint best-effort and falls back to documenting the filter strings in
+ * `docs/project-board.md` when the endpoint is unavailable.
+ *
+ * @type {Array<{ name: string, filter: string, groupBy: string,
+ *   layout?: 'table'|'board'|'roadmap' }>}
+ */
+export const PROJECT_VIEW_DEFS = [
+  {
+    name: 'Mandrel Board',
+    filter: '',
+    groupBy: 'Status',
+    layout: 'board',
+  },
+  {
+    name: 'Epic Roadmap',
+    filter: 'label:type::epic',
+    groupBy: 'Status',
+  },
+  {
+    name: 'Active Stories',
+    filter: 'label:type::story -status:Done',
+    groupBy: 'Status',
+  },
+  {
+    name: 'My Queue',
+    filter: 'assignee:@me',
+    groupBy: 'Status',
+  },
+];

package/.agents/scripts/lib/maintainability-engine.js

@@ -0,0 +1,164 @@
+import fs from 'node:fs';
+import escomplex from 'typhonjs-escomplex';
+import { transpileIfNeeded } from './maintainability-utils.js';
+
+/**
+ * Calculates the maintainability score of a JavaScript source file or string.
+ * Uses `typhonjs-escomplex` internally, which provides a maintainability index
+ * based on the Halstead Volume, Cyclomatic Complexity, and Lines of Code.
+ */
+/**
+ * Calculate score for a raw string of source code.
+ * @param {string} sourceCode The JavaScript source code.
+ * @returns {number} Score between 0 and 171. Higher is better.
+ */
+export function calculateForSource(sourceCode) {
+  try {
+    const result = escomplex.analyzeModule(sourceCode);
+    return result.maintainability;
+  } catch (_err) {
+    // Return 0 if the parser fails (e.g. invalid syntax)
+    return 0;
+  }
+}
+
+/**
+ * Calculate score for a given file. TypeScript and TSX sources are
+ * pre-transpiled in memory via `transpileIfNeeded` before being fed to
+ * the JS-only escomplex kernel; the score for a TS file is identical to
+ * the score the same logic would produce as plain JS, because TS type
+ * annotations introduce no control flow.
+ *
+ * @param {string} filePath Path to the JS/TS source file.
+ * @returns {number} Maintainability index, or 0 when the source cannot
+ *   be parsed (escomplex parse error or TS transpile failure).
+ */
+export function calculateForFile(filePath) {
+  try {
+    const sourceCode = fs.readFileSync(filePath, 'utf-8');
+    const prepared = transpileIfNeeded(filePath, sourceCode);
+    if (prepared === null) return 0;
+    return calculateForSource(prepared);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new Error(`File not found: ${filePath}`);
+    }
+    throw err;
+  }
+}
+
+/**
+ * Produce a richer maintainability report that includes per-method scores.
+ *
+ * The module-level index from escomplex is heavily penalised by Halstead
+ * volume, which means well-structured but long files (many small helpers)
+ * score as "critical" even when no single function is complex. Consumers
+ * that need to tier findings by real complexity should use `worstMethod`
+ * (the lowest per-method maintainability) and fall back to `moduleScore`
+ * for files that contain no methods (scripts that are purely top-level
+ * statements).
+ *
+ * @param {string} sourceCode
+ * @returns {{
+ *   moduleScore: number,
+ *   methods: Array<{ name: string, maintainability: number, cyclomatic: number, sloc: number|null }>,
+ *   worstMethod: number|null,
+ *   meanMethod: number|null,
+ *   parseError: boolean,
+ * }}
+ */
+export function calculateReport(sourceCode) {
+  try {
+    const result = escomplex.analyzeModule(sourceCode);
+    const methods = (result.methods ?? []).map((m) => ({
+      name: m.name,
+      maintainability:
+        typeof m.maintainability === 'number'
+          ? m.maintainability
+          : (result.maintainability ?? 0),
+      cyclomatic: m.cyclomatic ?? 0,
+      sloc: m.sloc?.logical ?? null,
+    }));
+    const scores = methods.map((m) => m.maintainability);
+    const worstMethod = scores.length > 0 ? Math.min(...scores) : null;
+    const meanMethod =
+      scores.length > 0
+        ? scores.reduce((a, b) => a + b, 0) / scores.length
+        : null;
+    return {
+      moduleScore: result.maintainability,
+      methods,
+      worstMethod,
+      meanMethod,
+      parseError: false,
+    };
+  } catch (_err) {
+    return {
+      moduleScore: 0,
+      methods: [],
+      worstMethod: null,
+      meanMethod: null,
+      parseError: true,
+    };
+  }
+}
+
+/**
+ * Convenience wrapper that reads a file from disk and produces a report.
+ * TypeScript and TSX sources are transpiled in memory before scoring.
+ *
+ * @param {string} filePath
+ * @returns {ReturnType<typeof calculateReport>}
+ */
+export function calculateReportForFile(filePath) {
+  try {
+    const sourceCode = fs.readFileSync(filePath, 'utf-8');
+    const prepared = transpileIfNeeded(filePath, sourceCode);
+    if (prepared === null) {
+      return {
+        moduleScore: 0,
+        methods: [],
+        worstMethod: null,
+        meanMethod: null,
+        parseError: true,
+      };
+    }
+    return calculateReport(prepared);
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      throw new Error(`File not found: ${filePath}`);
+    }
+    throw err;
+  }
+}
+
+/**
+ * Classify a maintainability report into a severity tier.
+ *
+ * Tiering rules (chosen after the v5.11 calibration issue where clean
+ * multi-hundred-line scripts scored 0 at the module level):
+ *
+ *   - 🔴 critical  — a real hotspot: some method scores < 20, OR the file
+ *                    contains no methods and the module scores < 40.
+ *   - 🟡 warning   — size- or volume-driven signal: worst method < 50
+ *                    OR module score < 65 (but no critical method).
+ *   - 🟢 healthy   — every method scores ≥ 50 and module ≥ 65.
+ *
+ * File-size-driven module-score drops land in the warning tier, not the
+ * critical tier — they should nudge the reviewer, not block the sprint.
+ *
+ * @param {ReturnType<typeof calculateReport>} report
+ * @returns {'critical' | 'warning' | 'healthy' | 'parse-error'}
+ */
+export function classifyReport(report) {
+  if (!report || report.parseError) return 'parse-error';
+  const { moduleScore, worstMethod, methods } = report;
+
+  if (worstMethod !== null && worstMethod < 20) return 'critical';
+  if (methods.length === 0 && moduleScore < 40) return 'critical';
+
+  if (worstMethod !== null && worstMethod < 50) return 'warning';
+  if (moduleScore < 65) return 'warning';
+
+  return 'healthy';
+}