mandrel 1.93.0 → 1.94.0

package/.agents/personas/ux-designer.md

@@ -1,95 +0,0 @@
-# Role: UX/UI Designer
-
-## 1. Primary Objective
-
-You are the empathetic advocate for the end user. Your goal is to design
-intuitive, low-friction, and accessible interfaces. You focus heavily on
-**cognitive load**, **micro-interactions**, **edge cases**, and
-**accessibility** before a single line of frontend code is written.
-
-**Golden Rule:** The "happy path" is only 10% of the user experience. You define
-what happens when data fails to load, when the user has no items, or when an
-action is destructive.
-
-> **Note:** For defining business value, MVP scoping, and PRDs, defer to the
-> `product.md` persona.
-
-## 2. Interaction Protocol
-
-1. **Contextualize the User:** Understand the Epic body and its user stories.
-   Identify the primary Call to Action (CTA).
-2. **Flow Before UI:** Do not design specific UI components until the entire
-   end-to-end user flow is mapped out and theoretically sound.
-3. **State Management:** Define every state of a page or component (Empty,
-   Loading, Error, Ideal, Partial).
-4. **Delegate:** Provide clear specifications (flows, states, accessibility
-   rules) for the Web and Mobile Engineers to implement.
-
-## 3. Core Responsibilities
-
-### A. User Experience (UX) & Flow
-
-- **Journey Mapping:** Visualize complex user journeys using MermaidJS
-  flowcharts.
-- **Friction Reduction:** Identify steps where a user might drop off or get
-  confused, and design mitigations.
-- **Edge Cases & Error States:** Explicitly define 404 pages, empty states,
-  skeleton loaders, and validation error messages. Ensure error messages are
-  actionable, not just technical jargon.
-
-### B. Visual Hierarchy & UI Patterns
-
-- **Mobile First:** Always specify how a feature behaves on mobile or smaller
-  viewports before scaling up to desktop patterns.
-- **Component States:** Define hover, active, focus, disabled, and error styles
-  for all interactive elements to pass to frontend engineers.
-- **Consistency:** If a `docs/style-guide.md` is provided, you MUST strictly
-  adhere to its design tokens (spacing, typography, colors), UI copywriting
-  rules, and contextual themes. Prevent the introduction of ad-hoc UI patterns.
-- **Tailwind v4 Guardrail:** Adhere to CSS-first styling. Do not propose
-  configuration changes to legacy `tailwind.config.js` or `tailwind.config.ts`.
-  Focus on the `@theme` directive.
-
-### C. Accessibility (UX Definition)
-
-- **WCAG 2.1 AA Checklist:** Define the accessibility _requirements_ for
-  specific features (e.g., "This modal must trap focus and close on `ESC`").
-- **Contrast & Color Blindness:** Ensure critical information is not conveyed by
-  color alone.
-- **Screen Reader Context:** Specify `aria-labels` and hidden text required to
-  make complex visual components understandable to screen readers.
-
-> **Ownership Note:** This persona defines the _requirements_ for accessibility.
-> Web/Mobile Engineers implement them, and SRE/DevOps enforces them in CI/CD.
-
-## 4. Output Artifacts
-
-### Level 1: Component Specification (Output to Chat)
-
-- **States:** Detailed breakdown of Default, Hover, Active, Disabled, Error.
-- **A11y Rules:** Specific keyboard navigation strings or ARIA requirements.
-
-### Level 2: The User Flow (MermaidJS)
-
-Use MermaidJS to visualize the journey **before** UI design or implementation
-begins. Include decision nodes and error states mapped out visibly.
-
-## 5. Scope Boundaries
-
-**This persona does NOT:**
-
-- Write implementation code, UI components, or CSS (use `engineer-web.md` or
-  `engineer-mobile.md`).
-- Make business prioritization or MVP scoping decisions (use `product.md`).
-- Design system architecture or write technical specifications.
-- Execute tests, manage test data, or run CI/CD pipelines.
-- Manage infrastructure, observability, or incident response.
-
-**Automatic Referral Protocol:** If you are asked to perform a task that falls
-outside the responsibilities defined in this file, **do not attempt it**.
-Instead:
-
-1. Briefly state which part of the request is outside your scope.
-2. Read the `.agents/personas/` directory to identify the correct persona.
-3. Automatically adopt that persona's instructions for the out-of-scope portion
-   of the work and continue execution seamlessly.

package/.agents/scripts/epic-plan-decompose.js

@@ -1,54 +0,0 @@
-#!/usr/bin/env node
-
-/* node:coverage ignore file */
-
-/**
- * epic-plan-decompose.js — RETIRED delegate CLI (Epic #4474, PR7).
- *
- * The 12-phase plan pipeline collapsed to context → author → persist:
- *
- *   - `--emit-context` moved to `plan-context.js` (the single authoring
- *     envelope carries the decomposer context — ticket schema, risk
- *     heuristics, ticket cap — alongside the spec half).
- *   - The persist half (ticket validator, file-assumption gate, DAG,
- *     budget, story creation, healthcheck, `agent::ready` flip) moved to
- *     `plan-persist.js` (single GitHub-write surface).
- *
- * This file is a **re-export shim only** — it carries external importers of
- * the historic named-export surface one more release (#4474 design §6 PR7
- * risk note) and is deleted in the next release. Internal consumers import
- * the phase modules directly; do not add new imports of this file.
- *
- * Invoking it as a CLI is refused with a pointer to the successor CLIs.
- */
-
-// cli-opt-out: retired delegate shim (Epic #4474 PR7) — deliberately
-// refuses CLI execution with a pointer to plan-context.js/plan-persist.js
-// instead of wiring runAsCli around a dead main().
-import { pathToFileURL } from 'node:url';
-
-export {
-  buildDecomposerSystemPrompt,
-  buildDecompositionContext,
-} from './lib/orchestration/epic-plan-decompose/phases/context.js';
-export {
-  orderTicketsForCreation,
-  resolveDependencies,
-} from './lib/orchestration/epic-plan-decompose/phases/dag.js';
-export { runDecomposePhase } from './lib/orchestration/epic-plan-decompose/phases/persist.js';
-
-// CLI execution is retired — fail loudly with the successor surface instead
-// of silently doing nothing (a stale automation script should break visibly).
-if (
-  process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href
-) {
-  process.stderr.write(
-    '[epic-plan-decompose] retired (Epic #4474): the plan pipeline is ' +
-      'context → author → persist.\n' +
-      '  - authoring envelope:  node .agents/scripts/plan-context.js --epic <id>\n' +
-      '  - persist (all gates): node .agents/scripts/plan-persist.js --epic <id> --tickets ...\n' +
-      'This file survives one release as an import shim only.\n',
-  );
-  process.exit(1);
-}

package/.agents/scripts/epic-plan-spec.js

@@ -1,64 +0,0 @@
-#!/usr/bin/env node
-
-/* node:coverage ignore file */
-
-/**
- * epic-plan-spec.js — RETIRED delegate CLI (Epic #4474, PR7).
- *
- * The 12-phase plan pipeline collapsed to context → author → persist:
- *
- *   - `--emit-context` moved to `plan-context.js` (single authoring
- *     envelope: Epic body + docs digest + codebase snapshot + duplicate
- *     search + clarity + system prompts).
- *   - The persist half (section gate, risk verdict, managed sections,
- *     checkpoint) moved to `plan-persist.js` (single GitHub-write surface).
- *
- * This file is a **re-export shim only** — it carries external importers of
- * the historic named-export surface one more release (#4474 design §6 PR7
- * risk note) and is deleted in the next release. Internal consumers import
- * the phase modules directly; do not add new imports of this file.
- *
- * Invoking it as a CLI is refused with a pointer to the successor CLIs.
- */
-
-// cli-opt-out: retired delegate shim (Epic #4474 PR7) — deliberately
-// refuses CLI execution with a pointer to plan-context.js/plan-persist.js
-// instead of wiring runAsCli around a dead main().
-import { pathToFileURL } from 'node:url';
-
-export {
-  forkAndCommitEpicSnapshot,
-  forkMainToEpic,
-} from './lib/baseline-snapshot.js';
-export {
-  buildAuthoringContext,
-  resolveMemoryDir,
-} from './lib/orchestration/epic-plan-spec/phases/authoring-context.js';
-export { drainPendingCleanupAtBoot } from './lib/orchestration/epic-plan-spec/phases/drain.js';
-export {
-  planEpic,
-  resolveAcceptancePersistence,
-} from './lib/orchestration/epic-plan-spec/phases/plan-epic.js';
-export {
-  loadRiskVerdict,
-  validateRiskVerdict,
-} from './lib/orchestration/epic-plan-spec/phases/risk-verdict.js';
-export { runSpecPhase } from './lib/orchestration/epic-plan-spec/phases/run-spec-phase.js';
-export { runSpecFreshnessCheck } from './lib/orchestration/epic-plan-spec/phases/spec-freshness.js';
-export { resolveReviewRouting } from './lib/orchestration/plan-review-routing.js';
-
-// CLI execution is retired — fail loudly with the successor surface instead
-// of silently doing nothing (a stale automation script should break visibly).
-if (
-  process.argv[1] &&
-  import.meta.url === pathToFileURL(process.argv[1]).href
-) {
-  process.stderr.write(
-    '[epic-plan-spec] retired (Epic #4474): the plan pipeline is ' +
-      'context → author → persist.\n' +
-      '  - authoring envelope:  node .agents/scripts/plan-context.js --epic <id>\n' +
-      '  - persist (all gates): node .agents/scripts/plan-persist.js --epic <id> ...\n' +
-      'This file survives one release as an import shim only.\n',
-  );
-  process.exit(1);
-}

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

@@ -1,109 +0,0 @@
-/**
- * skill-capsule-loader.js — Policy Capsule extraction for skill hydration.
- *
- * Resolves skills via `skills.index.json` and returns the Policy Capsule
- * region. When a SKILL.md is missing its capsule marker the full body is
- * returned as a defensive fallback (the manifest is malformed); there is no
- * caller-facing opt-in to inline full bodies — capsule-only is the contract
- * (Story #3863, hard cutover).
- *
- * @module lib/orchestration/skill-capsule-loader
- */
-
-import fs from 'node:fs';
-import path from 'node:path';
-import { Logger } from '../Logger.js';
-import { PROJECT_ROOT } from '../project-root.js';
-
-const POLICY_HEADING_RE = /^## Policy Capsule\s*$/;
-const ANY_H2_RE = /^## /;
-
-/**
- * Split source on CRLF or LF without normalizing line endings.
- *
- * @param {string} src
- * @returns {string[]}
- */
-function splitLines(src) {
-  return src.split(/\r\n|\n/);
-}
-
-/**
- * Extract the Policy Capsule region from a SKILL.md body (heading through
- * the line before the next `## ` heading). Returns null when absent.
- *
- * @param {string} body
- * @returns {string | null}
- */
-export function extractPolicyCapsuleSpan(body) {
-  const lines = splitLines(body);
-  let start = -1;
-  for (let i = 0; i < lines.length; i += 1) {
-    if (POLICY_HEADING_RE.test(lines[i])) {
-      start = i;
-      break;
-    }
-  }
-  if (start === -1) return null;
-
-  let end = lines.length;
-  for (let i = start + 1; i < lines.length; i += 1) {
-    if (ANY_H2_RE.test(lines[i])) {
-      end = i;
-      break;
-    }
-  }
-  return lines.slice(start, end).join('\n');
-}
-
-/**
- * @param {object} skillsIndex
- * @param {string} skillName
- * @returns {object | null}
- */
-function findSkillEntry(skillsIndex, skillName) {
-  const skills = skillsIndex?.skills;
-  if (!Array.isArray(skills)) return null;
-  return skills.find((entry) => entry.name === skillName) ?? null;
-}
-
-/**
- * Load a skill's Policy Capsule. Returns the capsule span when the marker
- * is present; falls back to the full SKILL.md body (and warns) only when the
- * marker is missing, which signals a malformed manifest rather than an
- * operator opt-in.
- *
- * @param {string} skillName
- * @param {{ skills: Array<{ name: string, path: string }> }} skillsIndex
- * @param {{
- *   repoRoot?: string,
- *   readFile?: (absPath: string) => string,
- *   warn?: (message: string) => void,
- * }} [options]
- * @returns {{ capsule: string, source: 'capsule' | 'full-body-fallback', path: string }}
- */
-export function loadSkillCapsule(skillName, skillsIndex, options = {}) {
-  const {
-    repoRoot = PROJECT_ROOT,
-    readFile = (absPath) => fs.readFileSync(absPath, 'utf8'),
-    warn = (message) => Logger.warn(message),
-  } = options;
-
-  const entry = findSkillEntry(skillsIndex, skillName);
-  if (!entry?.path) {
-    throw new Error(
-      `loadSkillCapsule: skill "${skillName}" not found in skills index`,
-    );
-  }
-
-  const absPath = path.join(repoRoot, entry.path);
-  const body = readFile(absPath);
-
-  const span = extractPolicyCapsuleSpan(body);
-  if (span) {
-    return { capsule: span, source: 'capsule', path: entry.path };
-  }
-
-  warn(`capsule marker missing: ${skillName}`);
-  return { capsule: body, source: 'full-body-fallback', path: entry.path };
-}

package/.agents/scripts/plan-critics.js

@@ -1,199 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * plan-critics.js — deterministic dispatch gate for the conditional
- * author-step critics of the collapsed /plan flow (Epic #4474 PR6,
- * design §4).
- *
- * **Thin shim (#4496 fix 6).** The evaluation itself now lives in
- * `lib/orchestration/plan-critics-evaluate.js` and is folded into
- * `plan-persist.js` as a pre-write phase, so the headless (`--yes`) path
- * never pays a standalone CLI turn for the dispatch decision. This CLI
- * survives one release for the attended pre-gate evaluation (the verdict
- * folds into gate #2's view before the persist runs) and for any external
- * scripting; it delegates to the shared module and keeps its exact output
- * contract.
- *
- * Runs between authoring and gate #2, entirely git-local (zero GitHub
- * calls): reads the authored artifacts, evaluates the risk/size dispatch
- * conditions for the consolidation (8.3) and pre-mortem (8.5) critics via
- * the shared evaluator, and emits one JSON verdict on stdout. The workflow
- * dispatches a fresh-context sub-agent ONLY for critics with
- * `dispatch: true`; every skip decision is appended to the plan-metrics
- * ledger (`kind: "critic-skip"`, with reasons) so under-firing is
- * auditable — the persist validators remain unchanged hard gates
- * regardless of what this gate decides.
- *
- * Conditions (design §4 / §6 PR6):
- *   - Consolidation: the existing deterministic precondition
- *     (`evaluateConsolidationPrecondition`) says dispatch AND (the draft
- *     has > 5 stories OR a confirmed divergence from the Tech Spec's
- *     Delivery Slicing table). Skipped outright in the single-delivery
- *     shape (no tickets exist to consolidate).
- *   - Pre-mortem: risk verdict overall level is high, OR ticket count is
- *     at least half `maxTickets`, OR any `planning.riskHeuristics` phrase
- *     matches the plan text (case-insensitive substring over tech spec +
- *     tickets + risk summary).
- *
- * Modes:
- *   --epic <id>          Artifact paths default to the per-Epic temp tree
- *                        (`temp/epic-<id>/techspec.md`, `risk-verdict.json`,
- *                        `tickets.json`); skip records land on the
- *                        per-Epic plan-metrics ledger.
- *   explicit paths       Ideation mode: pass --tech-spec/--risk-verdict
- *                        (and --tickets when fan-out) explicitly; skip
- *                        records land on the standalone ledger stream.
- *
- * Output (stdout-pure JSON):
- *   { epicId, consolidation: { critic, dispatch, reasons },
- *     premortem: { critic, dispatch, reasons } }
- *
- * Exit codes: 0 — verdict emitted (dispatch decisions are data, not
- * failures); 1 — fatal error (unreadable/invalid artifacts, bad args).
- */
-
-// Fail-fast if the framework's runtime deps are not installed — must be the
-// first import so the check runs before any third-party-importing sibling
-// module is evaluated (Story #3432).
-import './lib/runtime-deps/ensure-installed.js';
-import { readFile } from 'node:fs/promises';
-import { parseArgs } from 'node:util';
-
-import { runAsCli } from './lib/cli-utils.js';
-import { epicArtifactPath } from './lib/config/temp-paths.js';
-import {
-  resolveConfig,
-  validateOrchestrationConfig,
-} from './lib/config-resolver.js';
-import { routeAllOutputToStderr } from './lib/Logger.js';
-import { loadRiskVerdict } from './lib/orchestration/epic-plan-spec/phases/risk-verdict.js';
-import { evaluatePlanCritics } from './lib/orchestration/plan-critics-evaluate.js';
-import {
-  appendCriticSkip,
-  recordPlanInvocation,
-} from './lib/orchestration/plan-metrics.js';
-
-const USAGE =
-  'Usage: plan-critics.js (--epic <EpicId> | --tech-spec <file> ' +
-  '--risk-verdict <file> [--tickets <file>]) [--pretty]';
-
-async function readOptional(filePath, { required }) {
-  try {
-    return await readFile(filePath, 'utf8');
-  } catch (err) {
-    if (!required && err?.code === 'ENOENT') return null;
-    throw new Error(`Cannot read ${filePath}: ${err.message}`);
-  }
-}
-
-async function main() {
-  const { values } = parseArgs({
-    options: {
-      epic: { type: 'string' },
-      'tech-spec': { type: 'string' },
-      'risk-verdict': { type: 'string' },
-      tickets: { type: 'string' },
-      pretty: { type: 'boolean', default: false },
-    },
-    strict: true,
-  });
-
-  let epicId = null;
-  if (values.epic !== undefined) {
-    epicId = Number.parseInt(values.epic, 10);
-    if (!Number.isInteger(epicId)) {
-      throw new Error(
-        `--epic must be a numeric issue id (got "${values.epic}").\n${USAGE}`,
-      );
-    }
-  }
-
-  // stdout is reserved for the JSON verdict — flip every Logger sink to
-  // stderr before any pipeline code runs (same guarantee plan-context.js
-  // gives its envelope).
-  routeAllOutputToStderr();
-
-  let config;
-  try {
-    config = resolveConfig();
-    validateOrchestrationConfig(config);
-  } catch (err) {
-    throw new Error(`Config schema validation failed:\n${err.message}`);
-  }
-
-  const fallback = (basename) =>
-    epicId === null ? undefined : epicArtifactPath(epicId, basename, config);
-  const techSpecPath = values['tech-spec'] ?? fallback('techspec.md');
-  const riskVerdictPath =
-    values['risk-verdict'] ?? fallback('risk-verdict.json');
-  const ticketsPath = values.tickets ?? fallback('tickets.json');
-  if (!techSpecPath || !riskVerdictPath) {
-    throw new Error(
-      `Missing artifact path(s): without --epic, explicit --tech-spec and --risk-verdict are required.\n${USAGE}`,
-    );
-  }
-
-  const verdict = await recordPlanInvocation(
-    { cli: 'plan-critics', mode: 'evaluate', epicId, config },
-    async () => {
-      const techSpecContent = await readOptional(techSpecPath, {
-        required: true,
-      });
-      const riskVerdict = loadRiskVerdict(riskVerdictPath);
-      // Tickets are shape-dependent: a single-delivery plan authors none.
-      // Required only when passed explicitly.
-      const ticketsRaw = ticketsPath
-        ? await readOptional(ticketsPath, {
-            required: values.tickets !== undefined,
-          })
-        : null;
-      let tickets = null;
-      if (ticketsRaw !== null) {
-        try {
-          tickets = JSON.parse(ticketsRaw);
-        } catch (err) {
-          throw new Error(
-            `Failed to parse tickets file "${ticketsPath}" as JSON: ${err.message}`,
-          );
-        }
-        if (!Array.isArray(tickets)) {
-          throw new Error(
-            `Tickets file "${ticketsPath}" must contain a JSON array.`,
-          );
-        }
-      }
-
-      const { consolidation, premortem } = evaluatePlanCritics({
-        techSpecContent,
-        riskVerdict,
-        tickets,
-        config,
-      });
-
-      // Skip-audit trail (#4474 PR6): every non-dispatch is a ledger
-      // record. Best-effort — a failed append never fails the gate.
-      for (const decision of [consolidation, premortem]) {
-        if (!decision.dispatch) {
-          await appendCriticSkip(
-            {
-              critic: decision.critic,
-              reasons: decision.reasons,
-              cli: 'plan-critics',
-              epicId,
-            },
-            config,
-          );
-        }
-      }
-
-      return { epicId, consolidation, premortem };
-    },
-  );
-
-  const json = values.pretty
-    ? JSON.stringify(verdict, null, 2)
-    : JSON.stringify(verdict);
-  process.stdout.write(`${json}\n`);
-}
-
-runAsCli(import.meta.url, main, { source: 'plan-critics' });