karajan-code 1.53.1 → 1.55.0

package/README.md

@@ -258,7 +258,7 @@ Not nostalgia, not stubbornness. I've been using JavaScript since 1997, when Bre
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Run ~2473 tests with Vitest
+npm test              # Run ~2599 tests with Vitest
 npm run validate      # Lint + test
 ```
 

package/docs/README.es.md

@@ -231,7 +231,7 @@ No es nostalgia ni cabezoneria. Es que llevo usando JavaScript desde 1997, cuand
 git clone https://github.com/manufosela/karajan-code.git
 cd karajan-code
 npm install
-npm test              # Ejecutar ~2473 tests con Vitest
+npm test              # Ejecutar ~2599 tests con Vitest
 npm run validate      # Lint + test
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "karajan-code",
-  "version": "1.53.1",
+  "version": "1.55.0",
   "description": "Local multi-agent coding orchestrator with TDD, SonarQube, and code review pipeline",
   "type": "module",
   "license": "AGPL-3.0",

package/src/bootstrap.js

@@ -22,6 +22,7 @@ import { checkBinary } from "./utils/agent-detect.js";
 import { exists } from "./utils/fs.js";
 import { getConfigPath, resolveRole } from "./config.js";
 import { isSonarReachable, sonarUp } from "./sonar/manager.js";
+import { withDocLink } from "./utils/doc-links.js";
 
 const BOOTSTRAP_VERSION = 1;
 const BOOTSTRAP_TTL_HOURS = 24;
@@ -185,14 +186,14 @@ function formatBootstrapFailure(failures) {
   const lines = failures.map(f =>
     `  FAIL  ${f.name}: ${f.detail}\n        Fix: ${f.fix}`
   );
-  return [
+  return withDocLink([
     "BOOTSTRAP FAILED — Environment not ready for Karajan Code.\n",
     "The following prerequisite(s) are not met:\n",
     ...lines,
     "",
     "Run 'kj_doctor' for a complete environment diagnostic.",
     "Do NOT work around these issues — fix them properly."
-  ].join("\n");
+  ].join("\n"), "bootstrap_failed");
 }
 
 // ── Public API ───────────────────────────────────────────────────────

package/src/cli.js

@@ -24,6 +24,7 @@ import { researcherCommand } from "./commands/researcher.js";
 import { architectCommand } from "./commands/architect.js";
 import { auditCommand } from "./commands/audit.js";
 import { boardCommand } from "./commands/board.js";
+import { undoCommand } from "./commands/undo.js";
 
 import { printUpdateNotice } from "./utils/update-check.js";
 
@@ -117,6 +118,7 @@ program
   .option("--no-auto-simplify", "Force full pipeline regardless of triage level")
   .option("--smart-models", "Enable smart model selection based on triage complexity")
   .option("--no-smart-models", "Disable smart model selection")
+  .option("--design", "Activate design refactoring mode (impeccable role applies design changes)")
   .option("--dry-run", "Show what would be executed without running anything")
   .option("--json", "Output JSON only (no styled display)")
   .option("-q, --quiet", "Show only stage status lines, suppress raw agent output (default)")
@@ -323,6 +325,17 @@ program
     });
   });
 
+program
+  .command("undo")
+  .description("Revert last pipeline run")
+  .option("--hard", "Discard all changes (default: soft reset, keeps changes staged)")
+  .action(async (flags) => {
+    await withConfig("undo", flags, async ({ logger }) => {
+      const result = await undoCommand({ hard: !!flags.hard, logger });
+      if (!result.ok) process.exit(1);
+    });
+  });
+
 const sonar = program.command("sonar").description("Manage SonarQube container");
 sonar.command("status").action(async () => sonarCommand({ action: "status" }));
 sonar.command("start").action(async () => sonarCommand({ action: "start" }));

package/src/commands/doctor.js

@@ -11,6 +11,7 @@ import { resolveRoleMdPath, loadFirstExisting } from "../roles/base-role.js";
 import { ensureGitRepo } from "../utils/git.js";
 import { checkBinary, KNOWN_AGENTS } from "../utils/agent-detect.js";
 import { getInstallCommand } from "../utils/os-detect.js";
+import { withDocLink } from "../utils/doc-links.js";
 
 function getPackageVersion() {
   const pkgPath = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../package.json");
@@ -36,7 +37,7 @@ async function checkConfigFile() {
     label: "Config file",
     ok: configExists,
     detail: configExists ? configPath : "Not found",
-    fix: configExists ? null : "Run 'kj init' to create the config file."
+    fix: configExists ? null : withDocLink("Run 'kj init' to create the config file.", "config_missing")
   };
 }
 
@@ -63,7 +64,7 @@ async function checkDocker() {
     label: "Docker",
     ok: docker.ok,
     detail: docker.ok ? docker.version : "Not found",
-    fix: docker.ok ? null : "Install Docker: https://docs.docker.com/get-docker/"
+    fix: docker.ok ? null : withDocLink("Install Docker: https://docs.docker.com/get-docker/", "sonar_docker")
   };
 }
 
@@ -91,7 +92,7 @@ async function checkSonarQube(config) {
     detail: sonarDetail(config, sonarOk, sonarHost),
     fix: isOkOrDisabled
       ? null
-      : "Run 'kj sonar start' or 'docker start karajan-sonarqube'. Use --no-sonar to skip."
+      : withDocLink("Run 'kj sonar start' or 'docker start karajan-sonarqube'. Use --no-sonar to skip.", "sonar_docker")
   };
 }
 
@@ -104,7 +105,7 @@ async function checkAgentCLIs() {
       label: `Agent: ${agent.name}`,
       ok: result.ok,
       detail: result.ok ? `${result.version} (${result.path})` : "Not found",
-      fix: result.ok ? null : `Install: ${agent.install}`
+      fix: result.ok ? null : withDocLink(`Install: ${agent.install}`, "agent_not_found")
     });
   }
   return checks;
@@ -220,7 +221,7 @@ async function checkRtk() {
     label: "RTK (Rust Token Killer)",
     ok: false,
     detail: "Not found — 60-90% token savings available",
-    fix: `Install: ${installCmd}`
+    fix: withDocLink(`Install: ${installCmd}`, "rtk_install")
   };
 }
 

package/src/commands/undo.js

@@ -0,0 +1,62 @@
+import { loadMostRecentSession } from "../session-store.js";
+import { runCommand } from "../utils/process.js";
+
+/**
+ * Revert the last pipeline run by resetting to the pre-pipeline commit.
+ * Default: soft reset (keeps changes staged). With --hard: discards all changes.
+ */
+export async function undoCommand({ hard = false, logger } = {}) {
+  const session = await loadMostRecentSession();
+  if (!session) {
+    const msg = "No session to undo. No sessions found in the sessions directory.";
+    if (logger) logger.error(msg);
+    return { ok: false, error: msg };
+  }
+
+  const sha = session.session_start_sha;
+  if (!sha) {
+    const msg = `Session ${session.id} has no session_start_sha. Cannot determine the pre-pipeline commit.`;
+    if (logger) logger.error(msg);
+    return { ok: false, error: msg };
+  }
+
+  // Verify the SHA exists in git history
+  const verifyRes = await runCommand("git", ["cat-file", "-t", sha]);
+  if (verifyRes.exitCode !== 0 || verifyRes.stdout.trim() !== "commit") {
+    const msg = `Commit ${sha} not found in git history. It may have been garbage-collected or belong to a different repository.`;
+    if (logger) logger.error(msg);
+    return { ok: false, error: msg };
+  }
+
+  // Check there are commits after the SHA (HEAD is ahead)
+  const logRes = await runCommand("git", ["log", "--oneline", `${sha}..HEAD`]);
+  if (logRes.exitCode !== 0 || !logRes.stdout.trim()) {
+    const msg = `No commits to undo. HEAD is already at or before ${sha.slice(0, 8)}.`;
+    if (logger) logger.warn(msg);
+    return { ok: false, error: msg };
+  }
+
+  const mode = hard ? "--hard" : "--soft";
+  const resetRes = await runCommand("git", ["reset", mode, sha]);
+  if (resetRes.exitCode !== 0) {
+    const msg = `git reset ${mode} ${sha} failed: ${resetRes.stderr || resetRes.stdout}`;
+    if (logger) logger.error(msg);
+    return { ok: false, error: msg };
+  }
+
+  const shortSha = sha.slice(0, 8);
+  const message = hard
+    ? `Reverted to pre-pipeline state (commit ${shortSha}). All changes discarded.`
+    : `Reverted to pre-pipeline state (commit ${shortSha}). Changes are staged. Use \`git diff --cached\` to review.`;
+
+  if (logger) logger.info(message);
+  console.log(message);
+
+  return {
+    ok: true,
+    message,
+    sessionId: session.id,
+    sha,
+    mode: hard ? "hard" : "soft"
+  };
+}

package/src/mcp/handlers/management-handlers.js

@@ -163,6 +163,18 @@ export async function handleBoard(a) {
   }
 }
 
+export async function handleUndo(a, server) {
+  const projectDir = await resolveProjectDir(server, a.projectDir);
+  const origCwd = process.cwd();
+  try {
+    process.chdir(projectDir);
+    const { undoCommand } = await import("../../commands/undo.js");
+    return undoCommand({ hard: !!a.hard });
+  } finally {
+    process.chdir(origCwd);
+  }
+}
+
 export async function buildPreflightRequiredResponse(toolName) {
   const { config } = await loadConfig();
   const { listAgents } = await import("../../commands/agents.js");

package/src/mcp/run-kj.js

@@ -43,6 +43,7 @@ export async function runKjCommand({ command, commandArgs = [], options = {}, en
   normalizeBoolFlag(options.enableTester, "--enable-tester", args);
   normalizeBoolFlag(options.enableSecurity, "--enable-security", args);
   normalizeBoolFlag(options.enableImpeccable, "--enable-impeccable", args);
+  normalizeBoolFlag(options.design, "--design", args);
   normalizeBoolFlag(options.enableTriage, "--enable-triage", args);
   normalizeBoolFlag(options.enableDiscover, "--enable-discover", args);
   normalizeBoolFlag(options.enableArchitect, "--enable-architect", args);

package/src/mcp/server-handlers.js

@@ -10,11 +10,12 @@ import { loadConfig, applyRunOverrides, validateConfig } from "../config.js";
 import { currentBranch } from "../utils/git.js";
 import { buildProgressNotifier } from "./progress.js";
 import { compressResponse, compactStringify } from "./response-compressor.js";
+import { withDocLink } from "../utils/doc-links.js";
 
 // ── Sub-module re-exports ────────────────────────────────────────────
 export { handleRunDirect, handleResumeDirect, validateResumeAnswer, handleRun, handleResume } from "./handlers/run-handler.js";
 export { handlePlanDirect, handleCodeDirect, handleReviewDirect, handleDiscoverDirect, handleTriageDirect, handleResearcherDirect, handleAuditDirect, handleArchitectDirect, handleCode, handleReview, handlePlan, handleDiscover, handleTriage, handleResearcher, handleArchitect, handleAudit } from "./handlers/direct-handlers.js";
-export { handleStatus, handleAgents, handlePreflight, handleRoles, handleReport, handleInit, handleDoctor, handleConfig, handleScan, handleBoard, buildPreflightRequiredResponse } from "./handlers/management-handlers.js";
+export { handleStatus, handleAgents, handlePreflight, handleRoles, handleReport, handleInit, handleDoctor, handleConfig, handleScan, handleBoard, handleUndo, buildPreflightRequiredResponse } from "./handlers/management-handlers.js";
 export { handleHu, handleSkills, handleSuggest } from "./handlers/hu-handlers.js";
 
 // ── Shared helpers (used by sub-modules and external consumers) ──────
@@ -82,22 +83,22 @@ const ERROR_CLASSIFIERS = [
   {
     test: (lower) => lower.includes("sonar") && (lower.includes("connect") || lower.includes("econnrefused") || lower.includes("not available") || lower.includes("not running")),
     category: "sonar_unavailable",
-    suggestion: "SonarQube is not reachable. Try: kj_init to set up SonarQube, or run 'docker start sonarqube' if already installed. Use --no-sonar to skip SonarQube."
+    suggestion: withDocLink("SonarQube is not reachable. Try: kj_init to set up SonarQube, or run 'docker start sonarqube' if already installed. Use --no-sonar to skip SonarQube.", "sonar_docker")
   },
   {
     test: (lower) => lower.includes("401") || lower.includes("unauthorized") || lower.includes("invalid token"),
     category: "auth_error",
-    suggestion: "Authentication failed. Regenerate the SonarQube token and update it via kj_init or in ~/.karajan/kj.config.yml under sonarqube.token."
+    suggestion: withDocLink("Authentication failed. Regenerate the SonarQube token and update it via kj_init or in ~/.karajan/kj.config.yml under sonarqube.token.", "sonar_token")
   },
   {
     test: (lower) => lower.includes("config") && (lower.includes("missing") || lower.includes("not found") || lower.includes("invalid")),
     category: "config_error",
-    suggestion: "Configuration issue detected. Run kj_doctor to diagnose, or kj_init to create a fresh config."
+    suggestion: withDocLink("Configuration issue detected. Run kj_doctor to diagnose, or kj_init to create a fresh config.", "config_missing")
   },
   {
     test: (lower) => lower.includes("missing provider") || lower.includes("not found") && (lower.includes("claude") || lower.includes("codex") || lower.includes("gemini") || lower.includes("aider")),
     category: "agent_missing",
-    suggestion: "Required agent CLI not found. Run kj_doctor to check which agents are installed and get installation instructions."
+    suggestion: withDocLink("Required agent CLI not found. Run kj_doctor to check which agents are installed and get installation instructions.", "agent_not_found")
   },
   {
     test: (lower) => lower.includes("timed out") || lower.includes("timeout"),
@@ -107,7 +108,7 @@ const ERROR_CLASSIFIERS = [
   {
     test: (lower) => lower.includes("you are on the base branch"),
     category: "branch_error",
-    suggestion: "Create a feature branch before running Karajan. Use 'git checkout -b feat/<task-description>' and then retry. Do NOT run kj_code directly on the base branch."
+    suggestion: withDocLink("Create a feature branch before running Karajan. Use 'git checkout -b feat/<task-description>' and then retry. Do NOT run kj_code directly on the base branch.", "branch_error")
   },
   {
     test: (lower) => lower.includes("not a git repository"),
@@ -117,7 +118,7 @@ const ERROR_CLASSIFIERS = [
   {
     test: (lower) => lower.includes("bootstrap failed"),
     category: "bootstrap_error",
-    suggestion: "Environment prerequisites not met. Run kj_doctor for diagnostics, then fix the issues listed. Do NOT work around these — fix them properly."
+    suggestion: withDocLink("Environment prerequisites not met. Run kj_doctor for diagnostics, then fix the issues listed. Do NOT work around these — fix them properly.", "bootstrap_failed")
   }
 ];
 
@@ -218,7 +219,7 @@ import {
 import {
   handleStatus, handleAgents, handlePreflight, handleRoles,
   handleReport, handleInit, handleDoctor, handleConfig,
-  handleScan, handleBoard
+  handleScan, handleBoard, handleUndo
 } from "./handlers/management-handlers.js";
 import { handleHu, handleSkills, handleSuggest } from "./handlers/hu-handlers.js";
 
@@ -245,7 +246,8 @@ const toolHandlers = {
   kj_board:       (a) => handleBoard(a),
   kj_hu:          (a, server) => handleHu(a, server),
   kj_suggest:     (a) => handleSuggest(a),
-  kj_skills:      (a) => handleSkills(a)
+  kj_skills:      (a) => handleSkills(a),
+  kj_undo:        (a, server) => handleUndo(a, server)
 };
 
 export async function handleToolCall(name, args, server, extra) {

package/src/mcp/tools.js

@@ -100,6 +100,7 @@ export const tools = [
         taskType: { type: "string", enum: ["sw", "infra", "doc", "add-tests", "refactor"], description: "Explicit task type for policy resolution. Overrides triage classification." },
         quiet: { type: "boolean", description: "Suppress raw agent output lines, show only stage status (default: true). Set false for verbose output." },
         noSonar: { type: "boolean" },
+        design: { type: "boolean", description: "Activate design refactoring mode. Impeccable role applies design changes instead of just auditing." },
         enableSonarcloud: { type: "boolean", description: "Enable SonarCloud scan (complementary to SonarQube)" },
         kjHome: { type: "string" },
         sonarToken: { type: "string" },
@@ -363,5 +364,16 @@ export const tools = [
       },
       required: ["action"]
     }
+  },
+  {
+    name: "kj_undo",
+    description: "Revert the last pipeline run by resetting to the pre-pipeline commit. Default: soft reset (keeps changes staged). Use hard=true to discard all changes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        hard: { type: "boolean", description: "If true, discard all changes (git reset --hard). Default: false (soft reset, keeps changes staged)." },
+        projectDir: { type: "string", description: "Absolute path to the project directory" }
+      }
+    }
   }
 ];

package/src/orchestrator/post-loop-stages.js

@@ -247,17 +247,21 @@ export async function runSecurityStage({ config, logger, emitter, eventBase, ses
   return { action: "ok", stageResult: { ok: true, summary: securityOutput.summary || "No vulnerabilities found" } };
 }
 
-export async function runImpeccableStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget, iteration, task, diff }) {
+export async function runImpeccableStage({ config, logger, emitter, eventBase, session, coderRole, trackBudget, iteration, task, diff, mode = "audit" }) {
   logger.setContext({ iteration, stage: "impeccable" });
+  const isRefactoring = mode === "refactoring";
+  const startMessage = isRefactoring
+    ? "Impeccable applying design refactoring"
+    : "Impeccable auditing frontend design quality";
   emitProgress(
     emitter,
     makeEvent("impeccable:start", { ...eventBase, stage: "impeccable" }, {
-      message: "Impeccable auditing frontend design quality",
-      detail: { provider: config?.roles?.impeccable?.provider || coderRole.provider, executorType: "agent" }
+      message: startMessage,
+      detail: { provider: config?.roles?.impeccable?.provider || coderRole.provider, executorType: "agent", mode }
     })
   );
 
-  const impeccable = new ImpeccableRole({ config, logger, emitter });
+  const impeccable = new ImpeccableRole({ config, logger, emitter, mode });
   await impeccable.init({ task, iteration });
   const impeccableStart = Date.now();
   let impeccableOutput;

package/src/orchestrator/preflight-checks.js

@@ -19,6 +19,7 @@ import {
   resolveSonarToken,
   resolveSonarCredentials,
 } from "../sonar/config-resolver.js";
+import { withDocLink } from "../utils/doc-links.js";
 
 function parseJsonSafe(text) {
   try {
@@ -188,7 +189,7 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
       result.errors.push({
         check: "docker",
         message: "Docker not available but SonarQube is enabled.",
-        fix: "Start Docker, or disable SonarQube: set sonarqube.enabled: false in kj.config.yml, or pass --no-sonar."
+        fix: withDocLink("Start Docker, or disable SonarQube: set sonarqube.enabled: false in kj.config.yml, or pass --no-sonar.", "sonar_docker")
       });
       logger.error("Preflight: Docker not found — SonarQube requires Docker");
 
@@ -222,7 +223,7 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
       result.errors.push({
         check: "sonar-reachable",
         message: `SonarQube not reachable at ${sonarHost}.`,
-        fix: "Start SonarQube: 'docker start karajan-sonarqube', or disable it: set sonarqube.enabled: false in kj.config.yml, or pass --no-sonar."
+        fix: withDocLink("Start SonarQube: 'docker start karajan-sonarqube', or disable it: set sonarqube.enabled: false in kj.config.yml, or pass --no-sonar.", "sonar_docker")
       });
       logger.error("Preflight: SonarQube not reachable after remediation attempt");
     }
@@ -248,7 +249,7 @@ export async function runPreflightChecks({ config, logger, emitter, eventBase, r
       result.errors.push({
         check: "sonar-auth",
         message: "SonarQube is running but no authentication token is configured.",
-        fix: "Fix: run 'kj init' to configure it, or set KJ_SONAR_TOKEN env var, or add sonarqube.token to ~/.karajan/kj.config.yml."
+        fix: withDocLink("Fix: run 'kj init' to configure it, or set KJ_SONAR_TOKEN env var, or add sonarqube.token to ~/.karajan/kj.config.yml.", "sonar_token")
       });
       logger.error("Preflight: Sonar auth failed");
     }

package/src/orchestrator.js

@@ -262,6 +262,12 @@ function applyFlagOverrides(pipelineFlags, flags) {
   if (flags.enableTester !== undefined) pipelineFlags.testerEnabled = Boolean(flags.enableTester);
   if (flags.enableSecurity !== undefined) pipelineFlags.securityEnabled = Boolean(flags.enableSecurity);
   if (flags.enableImpeccable !== undefined) pipelineFlags.impeccableEnabled = Boolean(flags.enableImpeccable);
+
+  // --design flag: force-enable impeccable in refactoring mode
+  if (flags.design) {
+    pipelineFlags.impeccableEnabled = true;
+    pipelineFlags.impeccableMode = "refactoring";
+  }
 }
 
 function resolvePipelinePolicies({ flags, config, stageResults, emitter, eventBase, session, pipelineFlags }) {
@@ -1149,9 +1155,10 @@ async function runQualityGateStages({ config, logger, emitter, eventBase, sessio
 
   if (pipelineFlags?.impeccableEnabled) {
     const diff = await generateDiff({ baseRef: session.session_start_sha });
+    const impeccableMode = pipelineFlags?.impeccableMode || "audit";
     const impeccableResult = await runImpeccableStage({
       config, logger, emitter, eventBase, session, coderRole, trackBudget,
-      iteration: i, task, diff
+      iteration: i, task, diff, mode: impeccableMode
     });
     if (impeccableResult.stageResult) {
       stageResults.impeccable = impeccableResult.stageResult;

package/src/roles/impeccable-role.js

@@ -59,9 +59,11 @@ function buildSummary(parsed) {
 }
 
 export class ImpeccableRole extends BaseRole {
-  constructor({ config, logger, emitter = null, createAgentFn = null }) {
-    super({ name: "impeccable", config, logger, emitter });
+  constructor({ config, logger, emitter = null, createAgentFn = null, mode = "audit" }) {
+    const roleName = mode === "refactoring" ? "impeccable-design" : "impeccable";
+    super({ name: roleName, config, logger, emitter });
     this._createAgent = createAgentFn || defaultCreateAgent;
+    this.mode = mode;
   }
 
   async execute(input) {

package/src/utils/doc-links.js

@@ -0,0 +1,27 @@
+/**
+ * Documentation links for error messages.
+ *
+ * Maps error types to their relevant documentation page so that
+ * every actionable error includes a "See: <url>" pointer.
+ */
+
+const BASE_URL = "https://karajancode.com/docs";
+
+const ERROR_DOCS = {
+  sonar_token: `${BASE_URL}/guides/configuration/#sonarqube`,
+  sonar_docker: `${BASE_URL}/getting-started/installation/#docker`,
+  agent_not_found: `${BASE_URL}/getting-started/installation/#agents`,
+  bootstrap_failed: `${BASE_URL}/guides/troubleshooting/`,
+  config_missing: `${BASE_URL}/getting-started/quick-start/`,
+  branch_error: `${BASE_URL}/guides/pipeline/#git-workflow`,
+  rtk_install: `${BASE_URL}/guides/configuration/#rtk`,
+};
+
+export function docLink(errorType) {
+  return ERROR_DOCS[errorType] || `${BASE_URL}/guides/troubleshooting/`;
+}
+
+export function withDocLink(message, errorType) {
+  const link = docLink(errorType);
+  return `${message}\n  See: ${link}`;
+}

package/templates/roles/impeccable-design.md

@@ -0,0 +1,87 @@
+# Impeccable Design (Refactoring Mode)
+
+You are refactoring the frontend design. Apply ALL of these improvements:
+
+## Scope constraint
+
+- **ONLY modify files present in the diff.** Do not touch files that were not changed.
+- If no frontend files (.html, .css, .astro, .jsx, .tsx, .vue, .svelte, .lit, .js with DOM manipulation) are in the diff, report APPROVED immediately with 0 issues.
+
+## Input
+
+- **Task**: {{task}}
+- **Diff**: {{diff}}
+- **Context**: {{context}}
+
+## Visual Hierarchy
+- Establish clear heading levels (size, weight, color)
+- Group related elements with consistent spacing
+- Use whitespace to separate sections
+
+## Spacing & Alignment
+- Consistent padding/margin using a spacing scale (4px, 8px, 16px, 24px, 32px)
+- Align elements to a grid
+- Remove arbitrary pixel values
+
+## Responsive
+- Mobile-first approach
+- Fluid layouts with relative units (rem, %, vw)
+- Breakpoints at 640px, 768px, 1024px, 1280px
+
+## Accessibility
+- Color contrast ratio >= 4.5:1 for text
+- All interactive elements keyboard-focusable
+- Labels on all form inputs
+- Alt text on all images
+
+## Micro-interactions
+- Hover/focus states on all interactive elements
+- Smooth transitions (150-300ms)
+- Loading states for async operations
+
+## Theming
+- CSS custom properties for colors, fonts, spacing
+- Dark mode support if applicable
+- Consistent color palette (max 5 primary colors)
+
+## Rules
+- Each fix must be minimal and targeted (Edit, not Write)
+- Only use Read, Edit, Grep, Glob, and Bash tools
+- Verify each fix with `git diff` to confirm only intended lines changed
+- Apply changes directly. Do not just list issues.
+
+## Report
+
+Output a strict JSON object:
+
+```json
+{
+  "ok": true,
+  "result": {
+    "verdict": "IMPROVED",
+    "issuesFound": 3,
+    "issuesFixed": 3,
+    "categories": {
+      "visualHierarchy": 0,
+      "spacing": 1,
+      "responsive": 1,
+      "a11y": 1,
+      "microInteractions": 0,
+      "theming": 0
+    },
+    "changes": [
+      {
+        "file": "src/components/Button.astro",
+        "issue": "Arbitrary padding values",
+        "fix": "Replaced with spacing scale (16px)",
+        "category": "spacing"
+      }
+    ]
+  },
+  "summary": "3 design issues found and fixed (1 spacing, 1 responsive, 1 a11y)"
+}
+```
+
+### Verdict rules
+- **APPROVED** — No frontend design issues found (issuesFound === 0)
+- **IMPROVED** — Issues were found and fixes were applied (issuesFixed > 0)