@fringetools/cli 0.1.3 → 0.2.0

package/README.md

@@ -21,7 +21,9 @@ Prefer a permanent command? `npm install -D @fringetools/cli`, then `npx fringe
 
 | Command | What it does |
 |---|---|
-| `fringe check [path]` | Scan a directory (default `.`) and print findings + health score. Exit `1` on any `error`. |
+| `fringe check [dir\|file]` | Scan a directory (default `.`) or judge one file (the project root is found by climbing to the nearest `package.json`). Prints findings and the health score. Exit `1` on any `error`. |
+| `fringe plan [dir\|file] [--json] [--limit n]` | **Fix order for a repo with many findings**: P0 (errors in shared components or critical paths) → P1 (other errors, mechanical first) → P2 review → P3 polish, each cluster with its fix recipe. Never gates (exit 0). `--json` = `fringe/plan.v1`. |
+| `fringe explain [FR-203]` | Why a rule matters, the preferred fix and the tempting fix to avoid. No id lists all 29 rules. |
 | `fringe check --json` | Full report as JSON, schema `fringe/check.v1` (stack, files, findings, counts, score). |
 | `fringe check --claude-hook` | **For Claude Code hooks.** Silent when clean; on errors prints `{"decision":"block","reason":…}` (exit 0) so the agent sees and fixes them. |
 | `fringe check --hook` | One-line `fringe/hook.v1` JSON for CI / pre-commit. Exits `1` on errors. Claude Code does **not** feed this back — use `--claude-hook` for agents. Wins over `--json`. |
@@ -31,7 +33,7 @@ Prefer a permanent command? `npm install -D @fringetools/cli`, then `npx fringe
 | `fringe open [path] [--port <n>]` | Serve the ledger as a plain HTML page on `127.0.0.1:4173` (loopback only). Ctrl+C to stop. |
 | `fringe --help` · `--version` | Usage / version. |
 
-Notes: the first path is the check root (config + scan); extra paths are accepted and ignored so agent-invoked runs never crash. v0.1 takes directories, not single files. Unknown flags warn on stderr and are ignored.
+Notes: the first path is the check root (config + scan); extra paths are accepted and ignored so agent-invoked runs never crash. Unknown flags warn on stderr and are ignored.
 
 Default (human) output:
 
@@ -57,6 +59,23 @@ When a baseline or inline suppressions are in play, the last line adds `· N bas
 
 Each finding costs its weight (default error 10, review 3, signal 1). The total is scaled to a 10-file baseline (`× 10 / max(files, 10)`), so repo size doesn't flatten the score. Score = `100 − penalty` up to a penalty of 75; beyond that it decays smoothly (`25·75/penalty`) and never pins at 0. Repos under 10 files score exactly `100 − total`. Weights live in `fringe.config.json`.
 
+## Priority, clusters and fix plans
+
+Every finding in `--json` carries `priority`, `cluster` and `fixability`, and the result has a `clusters` list. A cluster is one rule in one file: usually one root cause and one fix.
+
+`priority = tier + WCAG level + critical path + blast radius`
+
+| Part | Value |
+|---|---|
+| Tier | error 1000 · review 400 · signal 100 (so any error outranks any review, whatever else is true) |
+| WCAG level | A +30 · AA +15 |
+| Critical path | +40 when the file matches `critical` in `fringe.config.json` (e.g. `"critical": ["src/checkout/**", "src/auth/**"]`) |
+| Blast radius | up to +20, growing with the number of files that import this one |
+
+A cluster is a **shared component** when 3 or more files import its file; fix those first, since one change clears every use. Repeats lift a cluster slightly (never across a tier). Blast radius matches importers by file base name, a deliberate shortcut.
+
+`fringe plan` turns this into the work order; `fringe explain FR-203` gives the recipe for one rule. The `--claude-hook` message includes each shown rule's recipe once, so the agent gets "how to fix it well", not just "what is wrong".
+
 ## Baseline
 
 Adopting Fringe on a repo that already has problems? Don't fix 300 findings first.
@@ -170,12 +189,13 @@ Optional, at the check root. Everything defaults sensibly; all keys are optional
 
 ```json
 {
-  "ignore": ["node_modules/**", "dist/**", "build/**", "out/**", "coverage/**", ".fringe/**", "*.min.*", "examples/**"],
+  "ignore": ["node_modules/**", "**/dist/**", "**/build/**", "**/out/**", "**/coverage/**", ".fringe/**", "*.min.*", "examples/**"],
   "disable": ["FR-214"],
   "weights": { "error": 10, "review": 3, "signal": 1 }
 }
 ```
 
+- `critical` — globs for the files that matter most (checkout, auth, sign-up). Their findings rank higher in `plan` and `--json`.
 - `ignore` — glob list matched against paths relative to the root. **Use the `dir/**` form to skip a directory** — a bare-dir glob like `"dist"` matches only the directory entry itself and does **not** prune the files inside it. (`node_modules` and dot-directories are always skipped.)
 - `disable` — rule IDs to turn off.
 - `weights` — per-finding penalties into the health score (see [Health score](#health-score)).

package/dist/bin.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import {
   runCli
-} from "./chunk-MOTRTP2I.js";
+} from "./chunk-ZK2GPUZF.js";
 
 // src/bin.ts
 process.exitCode = await runCli(process.argv.slice(2));

package/dist/{chunk-MOTRTP2I.js → chunk-ZK2GPUZF.js}

@@ -1,10 +1,10 @@
 // src/index.ts
 import { randomUUID } from "crypto";
-import { readFileSync as readFileSync8 } from "fs";
-import { resolve } from "path";
+import { existsSync as existsSync3, readFileSync as readFileSync8, statSync } from "fs";
+import { dirname as dirname2, join as join8, resolve } from "path";
 
 // src/version.ts
-var VERSION = "0.1.3";
+var VERSION = "0.2.0";
 
 // src/check.ts
 import { readFileSync as readFileSync5 } from "fs";
@@ -13,7 +13,8 @@ import { readFileSync as readFileSync5 } from "fs";
 import { readFileSync } from "fs";
 import { join } from "path";
 var DEFAULT_CONFIG = {
-  ignore: ["node_modules/**", "dist/**", "build/**", "out/**", "coverage/**", ".fringe/**", "*.min.*"],
+  // Both forms: `dist/**` matches only at the root, `**/dist/**` matches nested build output (e.g. frontend/dist).
+  ignore: ["node_modules/**", "dist/**", "build/**", "out/**", "coverage/**", "**/dist/**", "**/build/**", "**/out/**", "**/coverage/**", ".fringe/**", "*.min.*"],
   disable: [],
   weights: { error: 10, review: 3, signal: 1 }
 };
@@ -28,6 +29,10 @@ function loadConfig(root) {
       weights: { ...DEFAULT_CONFIG.weights, ...user.weights ?? {} }
     };
     validateWeights(cfg.weights);
+    if (user.critical !== void 0) {
+      if (!Array.isArray(user.critical) || user.critical.some((g) => typeof g !== "string")) throw new Error("fringe.config.json: critical must be an array of glob strings");
+      cfg.critical = user.critical;
+    }
     if (user.tokenSource !== void 0) {
       cfg.tokenSource = validateTokenSource(user.tokenSource);
     }
@@ -1013,8 +1018,220 @@ function suppressedIds(lines, line) {
   return ids;
 }
 
+// src/prioritize.ts
+import { basename, extname, relative as relative3 } from "path";
+
+// src/guidance.ts
+var GUIDANCE = {
+  "FR-201": {
+    why: "A screen reader announces an image with no alt as its file name, or skips it.",
+    recipe: 'Informative image: describe its purpose, not its look (alt="Order #4521 receipt"). Decorative image: alt="".',
+    avoid: 'alt="image", alt="photo", or the file name.',
+    example: { before: '<img src="/hero.png" />', after: '<img src="/hero.png" alt="Team reviewing a dashboard" />' },
+    fixability: "judgment"
+  },
+  "FR-202": {
+    why: 'A button or link with no text is announced as just "button" or "link".',
+    recipe: 'Put visible text inside it. For an icon-only control, add aria-label naming the action and aria-hidden="true" on the icon.',
+    avoid: 'title alone (not reliably announced) or an aria-label that repeats the icon name ("cross").',
+    example: { before: "<button><CloseIcon /></button>", after: '<button aria-label="Close dialog"><CloseIcon aria-hidden="true" /></button>' },
+    fixability: "mechanical"
+  },
+  "FR-203": {
+    why: "A form field with no label is announced without a name, and the placeholder vanishes as soon as the user types.",
+    recipe: "Add a visible <label htmlFor> bound to the input id. Use aria-label only where a visible label is genuinely wrong for the design (e.g. a search box beside a magnifier button).",
+    avoid: "Placeholder as the only label; aria-label when a visible label would fit.",
+    example: { before: '<input id="email" placeholder="Email" />', after: '<label htmlFor="email">Email</label>\n<input id="email" />' },
+    fixability: "mechanical"
+  },
+  "FR-204": {
+    why: "Screen reader users navigate by headings; skipped levels or several h1s break the outline.",
+    recipe: "Use one h1 per page, then h2, h3 in order. Choose the level by structure and style it with CSS.",
+    avoid: "Picking h3 because it looks smaller.",
+    fixability: "mechanical"
+  },
+  "FR-205": {
+    why: "Keyboard users cannot see where focus is when the outline is removed.",
+    recipe: "Keep a visible focus style. Replace outline-none with focus-visible:outline-2 focus-visible:outline-offset-2 (or a :focus-visible rule with a visible outline).",
+    avoid: "outline: none with no replacement; styling :focus only for mouse users.",
+    fixability: "mechanical"
+  },
+  "FR-206": {
+    why: "A clickable div is not reachable by keyboard and has no role for assistive technology.",
+    recipe: 'Use a <button> (or <a href> for navigation). Only if that is impossible, add role="button", tabIndex={0} and Enter/Space key handlers.',
+    avoid: 'role="button" without keyboard handlers.',
+    example: { before: "<div onClick={open}>Open</div>", after: '<button type="button" onClick={open}>Open</button>' },
+    fixability: "mechanical"
+  },
+  "FR-207": {
+    why: "A positive tabIndex pulls the element out of the natural order and makes focus jump unpredictably.",
+    recipe: "Use tabIndex={0} (join the natural order) or -1 (focusable by script only), and fix the order by moving the element in the DOM.",
+    avoid: "tabIndex={1}, {2}... to force an order.",
+    fixability: "mechanical"
+  },
+  "FR-208": {
+    why: "Data that loads, comes back empty or fails leaves the user staring at nothing.",
+    recipe: "Render three states next to the data: loading (skeleton or spinner with a text label), empty (what to do next), error (what failed and a retry).",
+    avoid: "A spinner with no failure path.",
+    fixability: "judgment"
+  },
+  "FR-209": {
+    why: "A misspelled aria-* attribute is ignored, so the intended name or state never reaches the user.",
+    recipe: "Correct the attribute name against the ARIA spec (aria-labelledby, aria-describedby, aria-expanded...).",
+    example: { before: '<input aria-labeledby="h" />', after: '<input aria-labelledby="h" />' },
+    fixability: "mechanical"
+  },
+  "FR-210": {
+    why: "A fake countdown pressures users into rushed decisions.",
+    recipe: "State the real deadline as a date, or remove the urgency wording.",
+    fixability: "judgment"
+  },
+  "FR-211": {
+    why: "A pre-checked consent box opts people in without a decision.",
+    recipe: "Leave consent boxes unchecked and make the choice explicit.",
+    fixability: "mechanical"
+  },
+  "FR-212": {
+    why: "Guilt-trip wording on the decline option manipulates the choice.",
+    recipe: 'Make both options neutral ("No thanks").',
+    fixability: "judgment"
+  },
+  "FR-213": {
+    why: "Infinite scroll with no way to stop traps keyboard users and buries the footer.",
+    recipe: 'Offer a "Load more" button or pagination, and keep the footer reachable.',
+    fixability: "judgment"
+  },
+  "FR-214": {
+    why: '"Free", then a price later, erodes trust.',
+    recipe: "Show the full price up front, including recurring cost.",
+    fixability: "judgment"
+  },
+  "FR-215": {
+    why: '"Something went wrong" tells the user nothing about what to do next.',
+    recipe: "Say what failed in plain words and give a next step: retry, a link, or a way to contact support.",
+    fixability: "judgment"
+  },
+  "FR-301": {
+    why: "Hardcoded colors drift from the design system and make theming painful.",
+    recipe: "Use the project tokens (CSS variables or palette utilities) instead of literal hex values.",
+    fixability: "mechanical"
+  },
+  "FR-302": {
+    why: "Off-scale font sizes break the type rhythm.",
+    recipe: "Use the type scale (text-sm, text-base, ...) or add the size to the theme.",
+    fixability: "mechanical"
+  },
+  "FR-303": {
+    why: "Off-scale spacing makes layouts inconsistent.",
+    recipe: "Use the spacing scale (p-4, gap-2, ...) or extend the theme.",
+    fixability: "mechanical"
+  },
+  "FR-304": {
+    why: "Low contrast text is hard to read for many people, and unreadable in sunlight.",
+    recipe: "Raise the contrast to at least 4.5:1 for body text (3:1 for large text) by darkening the text or lightening the background.",
+    fixability: "judgment"
+  },
+  "FR-305": {
+    why: "Tiny hit areas are hard to tap, especially for people with motor impairments.",
+    recipe: "Give interactive elements at least 24x24px (44x44px on touch) with padding, not just font size.",
+    fixability: "mechanical"
+  },
+  "FR-361": {
+    why: "Italic serif display headlines are a recognisable AI-generated look.",
+    recipe: "Choose type from the project design system for headlines.",
+    fixability: "judgment"
+  },
+  "FR-362": {
+    why: "The uppercase eyebrow chip above a headline is a recognisable AI-generated look.",
+    recipe: "Drop the chip or fold the content into the heading or subheading.",
+    fixability: "judgment"
+  },
+  "FR-363": {
+    why: "Cards nested in cards add visual noise and hide hierarchy.",
+    recipe: "Flatten: use spacing and one border level.",
+    fixability: "judgment"
+  },
+  "FR-364": {
+    why: "A stack of icon tiles is a recognisable AI-generated layout.",
+    recipe: "Replace with content that carries information, or vary the structure.",
+    fixability: "judgment"
+  },
+  "FR-365": {
+    why: "A thin border with a wide shadow signals elevation inconsistently.",
+    recipe: "Pick one: a border for flat surfaces or a soft shadow for raised ones.",
+    fixability: "judgment"
+  },
+  "FR-366": {
+    why: "Many status chips make a page read as noise.",
+    recipe: "Keep chips that carry state the user acts on; merge or drop the rest.",
+    fixability: "judgment"
+  },
+  "FR-367": {
+    why: '"01 Discover" style labels are a recognisable AI-generated look.',
+    recipe: "Use plain section headings.",
+    fixability: "judgment"
+  },
+  "FR-368": {
+    why: "The violet/indigo gradient is a recognisable AI-generated look.",
+    recipe: "Use the project brand colors.",
+    fixability: "judgment"
+  },
+  "FR-369": {
+    why: "Emoji in headings read as decoration and can be announced noisily.",
+    recipe: "Remove the emoji, or put a real icon beside the heading with aria-hidden.",
+    fixability: "judgment"
+  }
+};
+function renderExplain(id) {
+  if (!id) return ALL_RULES.map((r) => `${r.id}  ${r.severity.padEnd(6)} ${GUIDANCE[r.id].why}`).join("\n");
+  const rule = ALL_RULES.find((r) => r.id === id.toUpperCase());
+  if (!rule) return void 0;
+  const g = GUIDANCE[rule.id];
+  const out = [`${rule.id} \xB7 ${rule.severity} \xB7 ${g.fixability} fix`, `Why:     ${g.why}`, `Fix:     ${g.recipe}`];
+  if (g.avoid) out.push(`Avoid:   ${g.avoid}`);
+  if (g.example) out.push("Before:  " + g.example.before.replace(/\n/g, "\n         "), "After:   " + g.example.after.replace(/\n/g, "\n         "));
+  return out.join("\n");
+}
+
+// src/prioritize.ts
+var TIER = { error: 1e3, review: 400, signal: 100 };
+var WCAG_A = /* @__PURE__ */ new Set(["1.1.1", "1.3.1", "2.1.1", "2.4.3", "3.3.2", "4.1.2"]);
+var WCAG_AA = /* @__PURE__ */ new Set(["1.4.3", "2.4.7", "2.5.8"]);
+var CRITICAL_BONUS = 40;
+var SHARED_FROM = 3;
+var IMPORT = /(?:from\s+|import\s*\(\s*|require\(\s*)['"]([^'"]+)['"]/g;
+function importerCounts(sources) {
+  const counts = /* @__PURE__ */ new Map();
+  for (const src of sources.values()) {
+    const seen = /* @__PURE__ */ new Set();
+    for (const m of src.matchAll(IMPORT)) seen.add(basename(m[1], extname(m[1])));
+    for (const b of seen) counts.set(b, (counts.get(b) ?? 0) + 1);
+  }
+  return counts;
+}
+function prioritize(findings, sources, root, critical) {
+  const crit = critical.map(globToRegex);
+  const importers = importerCounts(sources);
+  const clusters = /* @__PURE__ */ new Map();
+  const out = findings.map((f) => {
+    const rel = relative3(root, f.loc.file);
+    const blast = Math.min(20, 4 * Math.log2(1 + (importers.get(basename(rel, extname(rel))) ?? 0)));
+    const level = f.wcag && WCAG_A.has(f.wcag) ? 30 : f.wcag && WCAG_AA.has(f.wcag) ? 15 : 0;
+    const priority = Math.round(TIER[f.severity] + level + (crit.some((r) => r.test(rel)) ? CRITICAL_BONUS : 0) + blast);
+    const id = `${f.rule}@${rel}`;
+    const by = importers.get(basename(rel, extname(rel))) ?? 0;
+    const c = clusters.get(id) ?? { id, rule: f.rule, file: rel, count: 0, priority: 0, fixability: GUIDANCE[f.rule]?.fixability ?? "judgment", rootCause: by >= SHARED_FROM ? "shared component" : "local", importedBy: by, critical: crit.some((r) => r.test(rel)) };
+    c.count++;
+    c.priority = Math.max(c.priority, priority);
+    clusters.set(id, c);
+    return { ...f, priority, cluster: id, fixability: c.fixability };
+  });
+  for (const c of clusters.values()) c.priority += Math.round(Math.min(15, 3 * Math.log2(c.count)));
+  return { findings: out, clusters: [...clusters.values()].sort((a, b) => b.priority - a.priority || a.id.localeCompare(b.id)) };
+}
+
 // src/check.ts
-async function runCheck(root, cfg = loadConfig(root), useBaseline = true) {
+async function runCheck(root, cfg = loadConfig(root), useBaseline = true, only) {
   const stack = detectStack(root);
   const files = walk(root, cfg);
   const rules = activeRules(cfg);
@@ -1050,6 +1267,7 @@ async function runCheck(root, cfg = loadConfig(root), useBaseline = true) {
   const tokenColors = gatherTokenColors(root, cfg, cssSources);
   for (const ctx of contexts) ctx.tokenColors = tokenColors;
   for (const ctx of contexts) {
+    if (only && !only.has(ctx.file)) continue;
     for (const rule of rules) findings.push(...rule.check(ctx));
   }
   const lines = new Map(contexts.map((c) => [c.file, c.source.split("\n")]));
@@ -1058,7 +1276,8 @@ async function runCheck(root, cfg = loadConfig(root), useBaseline = true) {
   const { fresh, known } = useBaseline ? applyBaseline(root, live) : { fresh: live, known: 0 };
   const counts = { error: 0, review: 0, signal: 0 };
   for (const f of fresh) counts[f.severity]++;
-  return { stack, files: files.length, skipped, findings: fresh, counts, score: score(counts, cfg.weights, files.length), ...known ? { baselined: known } : {}, ...suppressed ? { suppressed } : {} };
+  const ranked = prioritize(fresh, new Map(contexts.map((c) => [c.file, c.source])), root, cfg.critical ?? []);
+  return { stack, files: only ? only.size : files.length, skipped, findings: ranked.findings, clusters: ranked.clusters, counts, score: score(counts, cfg.weights, only ? only.size : files.length), ...known ? { baselined: known } : {}, ...suppressed ? { suppressed } : {} };
 }
 
 // src/report/json.ts
@@ -1067,7 +1286,7 @@ function toJson(r) {
 }
 
 // src/report/hook.ts
-import { relative as relative3 } from "path";
+import { relative as relative4 } from "path";
 var RANK = { error: 0, review: 1, signal: 2 };
 function topFinding(r) {
   return [...r.findings].sort((a, b) => {
@@ -1091,13 +1310,20 @@ function toHook(r) {
 function toClaudeHook(r, root) {
   const errs = r.findings.filter((f) => f.severity === "error");
   if (errs.length === 0) return "";
-  const shown = errs.slice(0, 8).map((f) => `- ${f.rule} ${relative3(root, f.loc.file)}:${f.loc.line} \u2014 ${f.message} (${f.hint})`);
+  const shown = errs.slice(0, 8).map((f) => `- ${f.rule} ${relative4(root, f.loc.file)}:${f.loc.line} \u2014 ${f.message} (${f.hint})`);
+  const shownRules = [...new Set(errs.slice(0, 8).map((f) => f.rule))];
+  const recipes = shownRules.map((id) => {
+    const g = GUIDANCE[id];
+    return g ? `- ${id}: ${g.recipe}${g.avoid ? ` Avoid: ${g.avoid}` : ""}` : "";
+  }).filter(Boolean);
   const more = errs.length > shown.length ? `
 \u2026and ${errs.length - shown.length} more (run \`fringe check\`).` : "";
   return JSON.stringify({
     decision: "block",
     reason: `Fringe found ${errs.length} accessibility error(s). Fix them before finishing:
 ${shown.join("\n")}${more}
+How to fix them well:
+${recipes.join("\n")}
 Use a fringe-ignore comment only for a genuine false positive, and say so.`
   });
 }
@@ -1226,6 +1452,66 @@ function initProject(root) {
   return done;
 }
 
+// src/report/plan.ts
+var TITLES = {
+  P0: ["Fix first", "errors in shared components or critical paths: one fix clears many uses"],
+  P1: ["Then the other errors", "blocking problems; mechanical fixes first"],
+  P2: ["Review", "heuristics that need your judgment"],
+  P3: ["Polish", "advice only; never blocks"]
+};
+function buildPlan(r, limit = 15) {
+  const lines = /* @__PURE__ */ new Map();
+  for (const f of r.findings) if (f.cluster) lines.set(f.cluster, [...lines.get(f.cluster) ?? [], f.loc.line]);
+  const sev = new Map(r.findings.map((f) => [f.cluster, f.severity]));
+  const items = (r.clusters ?? []).map((c) => ({ ...c, lines: lines.get(c.id) ?? [], recipe: GUIDANCE[c.rule]?.recipe, avoid: GUIDANCE[c.rule]?.avoid }));
+  const mechFirst = (a, b) => (a.fixability === b.fixability ? 0 : a.fixability === "mechanical" ? -1 : 1) || b.priority - a.priority;
+  const pick = (id) => items.filter((c) => {
+    const s = sev.get(c.id);
+    if (id === "P0") return s === "error" && (c.rootCause === "shared component" || c.critical);
+    if (id === "P1") return s === "error" && !(c.rootCause === "shared component" || c.critical);
+    return s === (id === "P2" ? "review" : "signal");
+  }).sort(id === "P1" ? mechFirst : (a, b) => b.priority - a.priority);
+  return ["P0", "P1", "P2", "P3"].map((id) => {
+    const all = pick(id);
+    return { id, title: TITLES[id][0], why: TITLES[id][1], items: all.slice(0, limit), more: Math.max(0, all.length - limit) };
+  }).filter((b) => b.items.length > 0);
+}
+function toPlanJson(r, limit) {
+  return JSON.stringify({ schema: "fringe/plan.v1", score: r.score, counts: r.counts, batches: buildPlan(r, limit) }, null, 2);
+}
+function toPlanMarkdown(r, target, limit) {
+  const batches = buildPlan(r, limit);
+  const head = `# Fringe fix plan
+
+health ${r.score}/100 \xB7 ${r.counts.error} errors \xB7 ${r.counts.review} review \xB7 ${r.counts.signal} signals`;
+  if (batches.length === 0) return `${head}
+
+Nothing to fix.`;
+  const out = [head];
+  for (const b of batches) {
+    out.push(`
+## ${b.id} \xB7 ${b.title}
+_${b.why}_`);
+    const shown = /* @__PURE__ */ new Set();
+    for (const c of b.items) {
+      const tags = [c.rootCause === "shared component" ? `shared component, imported by ${c.importedBy} files` : "", c.critical ? "critical path" : "", `${c.fixability} fix`].filter(Boolean);
+      out.push(`
+### ${c.rule} \xB7 \xD7${c.count} \xB7 ${c.file} (${tags.join("; ")})`);
+      out.push(`Lines: ${c.lines.slice(0, 8).join(", ")}${c.lines.length > 8 ? ", \u2026" : ""}`);
+      if (c.recipe && !shown.has(c.rule)) {
+        shown.add(c.rule);
+        out.push(`Fix: ${c.recipe}${c.avoid ? `
+Avoid: ${c.avoid}` : ""}`);
+      } else if (c.recipe) out.push(`Fix: as for ${c.rule} above (\`fringe explain ${c.rule}\`).`);
+    }
+    if (b.more) out.push(`
+\u2026and ${b.more} more in this batch (raise --limit).`);
+  }
+  out.push(`
+After each batch, verify: \`fringe check ${target}\``);
+  return out.join("\n");
+}
+
 // src/index.ts
 var log = (o) => o.log ?? ((s) => console.log(s));
 var err = (o) => o.err ?? ((s) => process.stderr.write(s));
@@ -1255,10 +1541,24 @@ function readManifest(path2, warn) {
     return void 0;
   }
 }
+function resolveTarget(arg) {
+  if (!statSync(arg).isFile()) return { root: arg };
+  let dir = dirname2(arg);
+  for (let d = dir, i = 0; i < 12; i++, d = dirname2(d)) {
+    if (existsSync3(join8(d, "package.json")) || existsSync3(join8(d, "fringe.config.json"))) {
+      dir = d;
+      break;
+    }
+    if (dirname2(d) === d) break;
+  }
+  return { root: dir, only: /* @__PURE__ */ new Set([arg]) };
+}
 var weakEvidence = (e) => typeof e !== "string" || e.trim().length < 12 || /^(n\/?a|none|tbd|obvious|unnecessary|clutter|unused)\.?$/i.test(e.trim());
 var HELP = `fringe check [--json] [--hook] [--record] [--manifest <path>] [path]
 fringe check --claude-hook [path]       for Claude Code hooks (feeds errors back to the agent)
 fringe check --update-baseline [path]   accept today's findings; only new ones gate
+fringe plan [dir|file] [--json] [--limit n]   ordered fix batches with recipes
+fringe explain [FR-203]                 why a rule matters and how to fix it well
 fringe init [path]                       add the Claude Code hook + skill
 fringe open [path] [--port <n>]   serve the .fringe ledger on 127.0.0.1
 fringe --help | --version`;
@@ -1290,7 +1590,7 @@ async function runCli(argv, opts = {}) {
     try {
       const paths = parseArgs(rest, err(opts));
       const cwd = opts.cwd ?? process.cwd();
-      const root = paths.length > 0 ? resolve(cwd, paths[0]) : cwd;
+      const { root, only } = resolveTarget(paths.length > 0 ? resolve(cwd, paths[0]) : cwd);
       const cfg = loadConfig(root);
       if (rest.includes("--update-baseline")) {
         const all = await runCheck(root, cfg, false);
@@ -1298,7 +1598,7 @@ async function runCli(argv, opts = {}) {
         log(opts)(`fringe: baseline written \u2014 ${all.findings.length} known findings in fringe.baseline.json (commit it); only new ones gate from now on`);
         return 0;
       }
-      const result = await runCheck(root, cfg);
+      const result = await runCheck(root, cfg, true, only);
       if (rest.includes("--claude-hook")) {
         const out = toClaudeHook(result, root);
         if (out) log(opts)(out);
@@ -1330,6 +1630,32 @@ async function runCli(argv, opts = {}) {
       return 2;
     }
   }
+  if (cmd === "plan") {
+    try {
+      const li = rest.indexOf("--limit");
+      const limit = li !== -1 ? Number(rest[li + 1]) || void 0 : void 0;
+      const paths = parseArgs(rest.filter((a, i) => a !== "--limit" && rest[i - 1] !== "--limit" && a !== "--json"), err(opts));
+      const arg = resolve(opts.cwd ?? process.cwd(), paths[0] ?? ".");
+      const { root, only } = resolveTarget(arg);
+      const result = await runCheck(root, loadConfig(root), true, only);
+      log(opts)(rest.includes("--json") ? toPlanJson(result, limit) : toPlanMarkdown(result, paths[0] ?? ".", limit));
+      return 0;
+    } catch (e) {
+      err(opts)(`fringe: internal error: ${e.message}
+`);
+      return 2;
+    }
+  }
+  if (cmd === "explain") {
+    const out = renderExplain(rest[0]);
+    if (out === void 0) {
+      err(opts)(`fringe: unknown rule '${rest[0]}' \u2014 run 'fringe explain' to list them
+`);
+      return 2;
+    }
+    log(opts)(out);
+    return 0;
+  }
   if (cmd === "init") {
     try {
       for (const line of initProject(resolve(opts.cwd ?? process.cwd(), rest[0] ?? "."))) log(opts)(`fringe: ${line}`);

package/dist/index.js

@@ -1,6 +1,6 @@
 import {
   runCli
-} from "./chunk-MOTRTP2I.js";
+} from "./chunk-ZK2GPUZF.js";
 export {
   runCli
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fringetools/cli",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "bin": {

package/skill/fringe/SKILL.md

@@ -11,6 +11,7 @@ Ponytail trims your code. Fringe handles your edges. Work the ladder in order.
 
 1. **Flow (judged).** Before building, ask what the user can skip. Cut steps, screens or options nobody needs. Write each decision with its evidence to `.fringe/manifest.json`: `{"flows":[{"action":"cut"|"kept","what":"...","evidence":"..."}]}`. No evidence, no cut.
 2. **Edges (verified, gates).** After every edit the hook runs `fringe check --claude-hook` and feeds errors back to you. Fix every listed finding. If there is no hook, run `fringe check --hook` yourself from the project root and do not finish while `block` is `true`.
+   On a repo with many existing findings, run `fringe plan` and work it batch by batch (shared components first, since one fix clears many uses), re-running `fringe check` after each batch. `fringe explain <rule>` gives the recipe and what to avoid.
 3. **Polish (verified, never gates).** Run `fringe check` once before finishing. Fix `review` items you agree with. Fix `signal` items that are cheap. Say which you left and why.
 
 When done: `fringe check --record --manifest .fringe/manifest.json`. Report the health score as measured; never estimate it yourself.

package/skill/fringe-audit/SKILL.md

@@ -7,7 +7,7 @@ description: Use when the user wants a whole-repo UX/accessibility audit, a plan
 
 Command: use `fringe` if it is on the PATH, otherwise `npx -y @fringetools/cli` in its place (e.g. `npx -y @fringetools/cli check --json .`).
 
-1. Run `fringe check --json .` and note the totals. Do not print every finding.
+1. Run `fringe plan --json --limit 5` (or `fringe plan` for Markdown). It already orders the work: P0 errors in shared components or critical paths, P1 other errors with mechanical fixes first, P2 review, P3 polish, each cluster with its recipe. Use that order; do not re-derive it. Add `"critical": ["src/checkout/**"]` to `fringe.config.json` if the user names the pages that matter most. Do not print every finding.
 2. Summarize as a plan:
    - Totals by severity and the health score, plus files scanned and skipped.
    - **Top rules** by count, and **top files** by error count (the 5 worst of each).

package/skill/fringe-help/SKILL.md

@@ -24,6 +24,8 @@ Fringe checks agent-written frontends for accessibility, state, dark-pattern and
 | `check [dir]` | Scan and print findings and the health score; exit 1 on any error |
 | `check --json` / `--hook` / `--claude-hook` | Machine output; CI gate; agent feedback form |
 | `check --update-baseline` | Accept today's findings; only new ones gate |
+| `plan [dir\|file]` | Ordered fix batches (shared components first) with recipes |
+| `explain [FR-203]` | Why a rule matters and how to fix it well |
 | `check --record [--manifest f]` | Append the run to `.fringe/ledger.jsonl` |
 | `init` | Add the hook and install the skills |
 | `open` | View the ledger at 127.0.0.1:4173 |

package/skill/fringe-review/SKILL.md

@@ -7,7 +7,7 @@ description: Use when the user asks to review, check or critique a UI, page or c
 
 Command: use `fringe` if it is on the PATH, otherwise `npx -y @fringetools/cli` in its place (e.g. `npx -y @fringetools/cli check --json .`).
 
-1. Run `fringe check --json .` from the project root. Fringe takes directories, not single files, so if the user named one file or page, run on the folder and keep only the findings whose `loc.file` matches it.
+1. Run `fringe check --json <file or folder>` from the project root: the file or page the user named, else `.`. Each finding already carries `priority` and `fixability`; report highest priority first. For the fix text use `fringe explain <rule>` (why, recipe, what to avoid) rather than improvising.
 2. Report in plain English, no jargon left unexplained:
    - **Must fix** — `error` findings. Group by rule. For each: where (`file:line`), what is wrong in one sentence, the exact fix, and who is hurt (for example "a screen reader says only 'button'"). Cite the `wcag` criterion when present.
    - **Worth a look** — `review` findings. These are heuristics: say they need your judgment, and give your call on each.