mandrel 1.57.0

package/.agents/workflows/audit-to-stories.md

@@ -0,0 +1,257 @@
+---
+description:
+  Convert findings produced by the audit-* workflows into actionable
+  GitHub Stories. Reads temp/audits/audit-*-results.md, groups findings
+  cross-audit, deduplicates against existing Issues by fingerprint, and
+  either chains into /epic-plan --idea or opens standalone Stories.
+---
+
+# /audit-to-stories [audit-file-or-glob]
+
+## Role
+
+Engineering Lead
+
+## Context
+
+The `audit-*` workflows each produce a structured `audit-<dimension>-results.md`
+report under `temp/audits/`. Every `### Finding` block in those reports
+already carries the fields a Story body needs (Severity / Impact,
+Dimension / Category, Current State, Recommendation, Agent Prompt).
+
+`/audit-to-stories` closes the loop: it parses those reports, groups
+related findings (including across audit dimensions), classifies each
+group as eligible-to-create or already-tracked, and — at the operator's
+choice — either chains into `/epic-plan --idea` for a single planned
+Epic or opens standalone Stories directly.
+
+The audit producers themselves are **not modified** by this workflow.
+They remain read-only emitters of audit reports.
+
+## Prerequisites
+
+1. At least one `audit-*-results.md` file under
+   `temp/audits/` (or the path passed as the argument). Run a
+   `/audit-<dimension>` or `/audit-fan-out` first if none are present.
+2. `GITHUB_TOKEN` or `gh auth status` clean — the dedupe and create
+   steps both call GitHub.
+3. The `audit::<dimension>` label taxonomy bootstrapped via
+   `node .agents/scripts/audit-labels-bootstrap.js` (idempotent — run
+   once per repo).
+
+## Argument
+
+`/audit-to-stories [audit-file-or-glob]`
+
+- No argument → scans `temp/audits/audit-*-results.md`. The roll-up
+  report `audit-fan-out-results.md` is intentionally skipped.
+- Single file path or glob → restricts the scan to that input.
+
+## Phase 1 — Discover & parse
+
+Run the CLI in `--scan` mode against the resolved glob. It parses every
+`### Finding` block, normalises the fields (`Severity` / `Impact` are
+both recognised; `Dimension` / `Category` likewise), and extracts file
+paths mentioned in the body. It then stamps each finding with a stable
+sha1 fingerprint via the shared
+[`lib/findings/route-finding.js`](../scripts/lib/findings/route-finding.js)
+helper (`fingerprintFinding`) — the single dedup/route implementation
+shared with `qa-explore`. The workflow carries **no** separate inline
+fingerprint or dedup code; identity, footer round-trip, and routing all
+flow through that one module.
+
+```bash
+node .agents/scripts/audit-to-stories.js --scan \
+  --glob "<resolved-glob>" \
+  --out temp/audits/audit-to-stories-plan.json
+```
+
+The emitted plan envelope carries `findings`, `groups`, `edges`,
+`classifications`, and `summary`. Subsequent phases consume the file
+rather than re-parsing the reports.
+
+## Phase 2 — HITL: severity gate
+
+Read the plan envelope's `summary.tally`. Present the operator with the
+severity threshold options, annotated with per-bucket counts:
+
+> Found `<summary.totalFindings>` findings across
+> `<distinct(group.dimensions)>`. Severity threshold to include?
+>
+> - `Critical only` (≈X findings)
+> - `Critical + High` (≈Y findings) **[Recommended]**
+> - `Critical + High + Medium` (≈Z findings)
+> - `All severities` (≈N findings)
+
+**STOP** until the operator picks. Re-run the scan with the chosen
+threshold so the plan envelope already reflects the filter:
+
+```bash
+node .agents/scripts/audit-to-stories.js --scan \
+  --glob "<resolved-glob>" \
+  --severity <critical|high|medium|low> \
+  --out temp/audits/audit-to-stories-plan.json
+```
+
+## Phase 3 — Grouping preview (consumes Phase 6 dedupe results)
+
+Render a markdown table from the filtered `plan.classifications`
+showing:
+
+- one row per group (`group.title`, `group.dimensions.join(', ')`,
+  `group.severity`, file count, finding count, and `action` —
+  `create` / `skip-open #N` / `skip-reoccurring #N`).
+- a tally line: `"M groups → K new, J already tracked, L re-occurring"`.
+- an `Edges` table listing dependency edges (group → group via file).
+
+**STOP** for operator approval. The operator can:
+
+- Approve as-is → continue to Phase 4.
+- Edit the grouping by hand → adjust the plan envelope and re-render
+  the preview.
+- Abort → no GitHub I/O has happened yet, so no cleanup is required.
+
+## Phase 4 — HITL: grouping mode
+
+Ask:
+
+> How would you like these `<M>` Stories created?
+>
+> - **Single Epic via `/epic-plan`** **[Recommended]** — opens one Epic,
+>   then chains into `/epic-plan --idea` so the standard PRD / Tech Spec
+>   / WBS authoring handles decomposition. Grouped Stories become the
+>   seed for Phase 7 decomposition.
+> - **Individual standalone Stories** — opens one GitHub Issue per
+>   group directly, no Epic wrapper.
+
+**STOP** until the operator picks.
+
+## Phase 5a — Single-Epic path
+
+Build the `/epic-plan` idea seed from the filtered plan envelope:
+
+```bash
+node .agents/scripts/audit-to-stories.js --emit-epic-seed \
+  --plan temp/audits/audit-to-stories-plan.json \
+  --out "temp/audits/audit-epic-seed-$(date +%Y%m%dT%H%M%S).md"
+```
+
+The seed renders the canonical one-pager sections — Problem Statement,
+Recommended Direction, Key Assumptions (with links to every source
+report), MVP Scope (the M proposed Stories), Key Files (so `/epic-plan`
+Phase 7 decompose has concrete anchors), Not Doing.
+
+Chain into the existing planning entrypoint:
+
+```text
+/epic-plan --idea "<path-to-seed>"
+```
+
+`/epic-plan` then runs ideation → duplicate-search → render Epic body
+→ open Epic → Phase 7 / 8 decompose, as documented in its workflow.
+Each Story it spawns from the seed carries `context::audit:
+<reportLink>` and `audit-fingerprint: <sha>` in its body so future
+Phase 6 idempotency works on the next run.
+
+## Phase 5b — Standalone-Stories path
+
+Render the per-group `{ title, body, labels }` payloads:
+
+```bash
+node .agents/scripts/audit-to-stories.js --emit-stories \
+  --plan temp/audits/audit-to-stories-plan.json \
+  --json \
+  --out temp/audits/audit-to-stories-stories.json
+```
+
+For each entry whose plan classification is `create`, open a GitHub
+Issue. Use the GitHub MCP tool when available (`issue_write` with
+method `create`), or fall back to `gh issue create`. The body carries
+the canonical sections (Summary, Acceptance Criteria, Agent Prompts,
+Context) plus the machine-readable fingerprint footer rendered by the
+shared helper's `fingerprintFooter(sha)`
+(`<!-- audit-fingerprints: sha1,sha1,... -->`) that Phase 6 relies on.
+
+Labels applied:
+
+- `type::story`
+- `agent::ready`
+- `audit::<dimension>` — one per dimension represented in the merge
+  (cross-audit groups carry multiple).
+- `risk::high` — added when any finding in the group is Critical.
+
+## Phase 6 — Idempotency (folded into Phase 1 scan)
+
+The `--scan` step routes each group's findings through the shared
+[`lib/findings/route-finding.js`](../scripts/lib/findings/route-finding.js)
+helper (`routeFinding`) — the same dedup/route entrypoint `qa-explore`
+consumes — and maps its `decision` onto the group's action verdict in
+the `classifications` array:
+
+- **`create`** ← `routeFinding` returned `new`: no existing Issue's
+  fingerprint footer references any of this group's finding shas.
+  Eligible.
+- **`skip-open`** ← `routeFinding` returned `update-existing` (or
+  `duplicate`): an open Issue already tracks at least one of the
+  group's findings. The decision surfaces the matched Issue number; the
+  operator decides whether to comment "Re-detected on <date>" via
+  `--update` semantics (manual for now).
+- **`skip-reoccurring`** ← `routeFinding` returned
+  `regression-of-closed`: every match is in a closed Issue. The group
+  is skipped by default; flag in the Phase 7 summary so the operator
+  can decide whether to reopen.
+
+`routeFinding` is handed a `searchIssues` port adapted from the
+project's existing GitHub provider — the actual search runs against the
+repo's open + closed issues for each sha in the group, and the helper's
+footer-confirmation step filters out false-positive search hits whose
+body mentions the sha in prose without the canonical marker. The
+workflow owns **no** parallel dedup or footer-parsing code: the
+fingerprint, footer round-trip, and routing all live in that one shared
+module.
+
+When no provider is available (e.g. air-gapped dev environment), pass
+`--no-provider` to the `--scan` step — every group is classified
+`create` and the operator is informed that dedupe was skipped.
+
+## Phase 7 — Summary & cleanup
+
+Persist `temp/audits/audit-to-stories-$(date +%Y%m%dT%H%M%S).md`
+summarising the run:
+
+- Per-group breakdown: which findings merged, fingerprints, dependency
+  edges, created/skipped Issue link (or new Epic link).
+- The severity threshold and grouping mode the operator chose.
+- Final tally: `"<M> groups planned · <K> created · <J> skipped (open)
+  · <L> skipped (re-occurring)"`.
+
+When the Single-Epic path ran, link the Epic the chained `/epic-plan`
+opened. When the Standalone-Stories path ran, list every Issue URL.
+
+## Constraints
+
+- **Never** modify any `audit-*` producer workflow. Audit producers
+  stay read-only.
+- **Never** open a duplicate Issue. The shared
+  [`route-finding.js`](../scripts/lib/findings/route-finding.js) helper's
+  fingerprint marker and footer-confirmation step gate every create.
+- **Never** reimplement fingerprinting or dedup inline. Route every
+  finding through the shared `route-finding.js` helper — it is the single
+  dedup/route implementation, shared with `qa-explore`.
+- **Always** stamp the fingerprint footer (via the helper's
+  `fingerprintFooter`) in the body of every created Story. Without it,
+  the next run cannot dedupe.
+- **Always** present the Phase 2, 3, and 4 HITL gates. Do not bypass —
+  even when "obvious" — because the severity / grouping / mode picks
+  are operator decisions that the workflow's UX contract relies on.
+- **MCP fallback**: prefer `mcp__github__issue_write` for Issue
+  creation; fall back to `gh issue create` when the MCP tool is
+  unavailable.
+
+## See also
+
+- [`/epic-plan`](epic-plan.md) — the planning pipeline `/audit-to-stories`
+  chains into for the Single-Epic grouping mode.
+- [`lib/findings/route-finding.js`](../scripts/lib/findings/route-finding.js) —
+  the shared fingerprint/dedup/route helper this workflow and `qa-explore`
+  both consume. There is no second dedup implementation.

package/.agents/workflows/audit-ux-ui.md

@@ -0,0 +1,102 @@
+---
+description: Audit UX/UI consistency and design system adherence
+---
+
+# UX/UI & Design System Audit
+
+## Role
+
+Lead Product Designer & Frontend Architect
+
+## Context & Objective
+
+Evaluate the frontend implementation for UI consistency, UX best practices, and
+adherence to the project's design system. Ensure the application feels premium
+and cohesive.
+
+## Scope (Epic mode)
+
+When this lens is invoked from `/epic-deliver` Phase 4 (epic-audit), the
+following block is populated with the Epic's change-set file list.
+Otherwise — for any manual `/audit-<dimension>` invocation — the block
+renders the literal substitution token and you MUST treat it as **no
+scope filter — run the lens codebase-wide** exactly as you would have
+before this section existed.
+
+```text
+{{changedFiles}}
+```
+
+- If the block above contains a newline-delimited list of file paths,
+  restrict your analysis to those files (and their direct dependencies
+  when the lens explicitly calls for cross-file reasoning).
+- If the block above renders as the literal string `{{changedFiles}}`
+  (i.e. no substitution was supplied), ignore this section entirely and
+  proceed with the full codebase-wide scan defined in the remaining
+  steps.
+
+## Step 1: Visual Consistency Check
+
+> Apply [`helpers/parallel-tooling.md`](helpers/parallel-tooling.md) when batching the scan below — independent reads belong in one turn, long shells run via `run_in_background` + `Monitor`.
+
+Scan frontend components for:
+
+- **Hardcoded Values:** Identify "magic" hex codes, font sizes, or spacing
+  values that bypass the CSS variables/design tokens.
+- **Component Re-implementation:** Find places where custom HTML/CSS is used
+  instead of the standard component library (e.g., custom button instead of
+  `<Button />`).
+- **Interactive States:** Verify that all clickable elements have hover, focus,
+  and active states.
+- **Typography:** Ensure font families and weights are used consistently
+  according to the hierarchy.
+
+## Step 2: UX Best Practices
+
+1. **Information Hierarchy:** Is the most important action/information
+   prominent?
+2. **Error States:** Are form errors clear and helpful, or generic and
+   frustrating?
+3. **Loading States:** Are there skeletons or spinners for async operations?
+4. **Responsiveness:** Check layouts at mobile, tablet, and desktop breakpoints.
+5. **Accessibility (UX-focused):** Focus on tab order, touch target sizes, and
+   color contrast.
+
+## Step 3: Output Requirements
+
+Generate and save a highly structured Markdown audit report to
+`{{auditOutputDir}}/audit-ux-ui-results.md`, using the exact template below.
+
+```markdown
+# UX/UI & Design System Audit report
+
+## Executive Summary
+
+[Overview of design system health (Score 1-10) and adherence to
+tokens/components.]
+
+## Detailed Findings
+
+[For every inconsistency or UX improvement identified, use the following strict
+structure:]
+
+### [Short Title of the Issue]
+
+- **Dimension:** [e.g., Visual Consistency | UX Best Practices | Accessibility]
+- **Impact:** [High | Medium | Low]
+- **Current State:** [What is currently implemented and why it is sub-optimal]
+- **Recommendation & Rationale:** [The specific UI/UX change and how it improves
+  premium feel or usability]
+- **Agent Prompt:**
+  `[A copy-pasteable, highly specific prompt to execute this UI change independently]`
+
+## Micro-animation Opportunities
+
+- [Suggest 2-3 places where subtle transitions could enhance the "premium"
+  feel.]
+```
+
+## Constraint
+
+This is a **read-only** audit. Provide the critique and implementation
+suggestions, but do not modify styles or components.