archondev 2.19.56 → 2.19.57

package/README.md

@@ -27,22 +27,29 @@ npm install -g archondev; archon
 - Multi-provider key support with adversarial features
 
 ### Option 2: Lite Package
-Copy governance files into any project. Works with your existing AI tools: **Cursor, Claude Code, Windsurf, Amp, Copilot, Gemini**, and more.
+Context-aware intelligence for your existing AI tools: **Cursor, Claude Code, Windsurf, Amp, Copilot, Gemini**, and more. Your AI detects what you're doing and proactively offers the right help — no commands to memorize.
 
 [Download Lite Packages →](https://archondev.io/download)
 
-**What you get:**
+**Context-Aware Intelligence (NEW):**
+- **Fix-First Code Review** — Auto-fixes mechanical issues, only asks about ambiguous ones
+- **AI Slop Detection** — 10-item blacklist catches generic AI design patterns, scored A-F
+- **Systematic Debugging** — Root cause first, 3-strike hypothesis testing, regression prevention
+- **Ship Readiness Dashboard** — Pre-deploy checklist tracks all quality gates across your session
+- **Scope Management** — 4 modes (expand/selective/hold/reduce) when scope creep detected
+- **Self-Regulation Guardrails** — Blast radius checks, file limits, automatic checkpoints
+- **Design Governance** — DESIGN.md as design source of truth with visual audit
+- **Completion Status** — Clear DONE/CONCERNS/BLOCKED/NEEDS_CONTEXT reporting
+- **Progress Reflection** — Solo retro at natural milestones
+
+**Governance Foundation:**
 - .archon/active/architecture.md template with best practices
-- **Quality Level / Posture** — Tell AI if it's prototype, production, or enterprise-grade
+- **Quality Level / Posture** — prototype/production/enterprise-grade behavior
+- **DEPENDENCIES.md** — File-level dependency tracking to prevent regressions
 - IDE-specific rule files (.cursorrules, CLAUDE.md, GEMINI.md, etc.)
-- Progress tracking templates
-- **DEPENDENCIES.md** — Track file-level dependencies to prevent regressions
-- **First-Run Walkthrough** — Guided onboarding when AI detects your governance files
-- **Code Review Mode** — Structured code review without changing your code
-- **Local Database** — Track atoms and learnings in SQLite (no CLI required)
-- **Memory Management** — Context handoff protocol for long sessions
-- **Task Extraction Protocol** — AI confirms all items before starting, nothing gets forgotten
-- **Pre-Deploy Accessibility** — WCAG 2.2 AA check before going live, legal liability warnings
+- **14 scenario protocols** — Design review, debugging, ship readiness, scope review, accessibility, SEO/GEO, and more
+- **Task Extraction** — AI confirms all items before starting, nothing gets forgotten
+- **Context Handoff** — Memory management for long sessions
 - Works with any AI coding assistant
 
 ### Local Governance SQLite (Dev Only)
@@ -63,8 +70,7 @@ pnpm exec tsx scripts/init-governance-db.ts
 | `archon` | Interactive mode — just run and follow prompts |
 | `archon init` | Initialize in your project |
 | `archon login` | Authenticate with ArchonDev |
-| `archon upgrade` | Switch between Free and BYOK modes |
-| `archon config ai` | Guided BYOK setup (providers + key entry) |
+| `archon config ai` | Switch from Free mode to BYOK and configure provider keys |
 | `archon status` | Show login status and current mode |
 | `archon plan <description>` | Create a work item with AI planning (extracts and confirms multi-item requests) |
 | `archon execute <atom-id>` | Execute with quality gates |
@@ -169,7 +175,7 @@ FREE mode: no built-in AI calls.
 
 → What kind of project are you building?
   [AI asks natural follow-up questions based on your answers]
-  (Type "upgrade" or "help" anytime)
+  (Type "config ai" or "help" anytime)
 
 ✓ Project initialized!
 ```
@@ -180,7 +186,7 @@ Type these anytime during interactive prompts:
 
 | Command | Description |
 |---------|-------------|
-| `upgrade` | Open tier upgrade menu |
+| `config ai` | Open BYOK key setup |
 | `status` | Show login and mode info |
 | `keys` | List configured API keys |
 | `help` | Show available commands |
@@ -202,7 +208,7 @@ archon github status        # Verify connection
 archon plan "add user settings page"
 archon execute ATOM-001 --cloud
 
-# 3b. Queue multiple atoms in parallel (Credits tier)
+# 3b. Queue multiple atoms in parallel (legacy command; disabled in free/BYOK mode)
 archon parallel cloud ATOM-001 ATOM-002
 
 # 4. Check progress

package/dist/index.js

@@ -114,11 +114,13 @@ import {
   init,
   isInitialized
 } from "./chunk-P666JE3G.js";
-import "./chunk-4VNS5WPM.js";
+import {
+  __require
+} from "./chunk-4VNS5WPM.js";
 
 // src/cli/index.ts
 import { Command as Command3 } from "commander";
-import chalk18 from "chalk";
+import chalk21 from "chalk";
 import "dotenv/config";
 
 // src/cli/terminal-compat.ts
@@ -9029,6 +9031,762 @@ function createGovernanceCommand() {
   return governance;
 }
 
+// src/cli/ship.ts
+import chalk18 from "chalk";
+
+// src/core/ship/pipeline.ts
+import { execSync as execSync5 } from "child_process";
+
+// src/core/ship/version.ts
+import { readFile as readFile13, writeFile as writeFile10 } from "fs/promises";
+import { join as join20 } from "path";
+function detectVersionBump(commitMessages) {
+  const joined = commitMessages.join("\n").toLowerCase();
+  if (joined.includes("breaking change") || /^[a-z]+!:/m.test(joined)) {
+    return "major";
+  }
+  if (/^feat[:(]/m.test(joined)) {
+    return "minor";
+  }
+  return "patch";
+}
+function bumpVersion(current, level) {
+  const parts = current.replace(/^v/, "").split(".");
+  const major = parseInt(parts[0] ?? "0", 10);
+  const minor = parseInt(parts[1] ?? "0", 10);
+  const patch = parseInt(parts[2] ?? "0", 10);
+  switch (level) {
+    case "major":
+      return `${major + 1}.0.0`;
+    case "minor":
+      return `${major}.${minor + 1}.0`;
+    case "patch":
+      return `${major}.${minor}.${patch + 1}`;
+  }
+}
+async function readPackageVersion(cwd) {
+  try {
+    const pkgPath = join20(cwd, "package.json");
+    const content = await readFile13(pkgPath, "utf-8");
+    const pkg = JSON.parse(content);
+    return pkg.version ?? null;
+  } catch {
+    return null;
+  }
+}
+async function writePackageVersion(cwd, version) {
+  const pkgPath = join20(cwd, "package.json");
+  const content = await readFile13(pkgPath, "utf-8");
+  const pkg = JSON.parse(content);
+  pkg.version = version;
+  await writeFile10(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf-8");
+}
+
+// src/core/ship/changelog.ts
+function parseCommitMessages(commitLines) {
+  return commitLines.map((line) => {
+    const trimmed = line.trim();
+    const match = trimmed.match(/^([a-z]+)(?:\([^)]*\))?[!]?:\s*(.+)/);
+    if (match) {
+      const type = match[1];
+      const validTypes = ["feat", "fix", "refactor", "docs", "chore"];
+      return {
+        type: validTypes.includes(type) ? type : "other",
+        message: match[2]
+      };
+    }
+    const hashMatch = trimmed.match(/^([0-9a-f]{7,40})\s+(.+)/);
+    if (hashMatch) {
+      return { type: "other", message: hashMatch[2], hash: hashMatch[1] };
+    }
+    return { type: "other", message: trimmed };
+  }).filter((e) => e.message.length > 0);
+}
+function generateChangelog(commits, version) {
+  const entries = parseCommitMessages(commits);
+  const date = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const lines = [`## ${version} (${date})`];
+  const groups = {};
+  for (const entry of entries) {
+    const key = entry.type;
+    if (!groups[key]) groups[key] = [];
+    groups[key].push(entry);
+  }
+  const typeLabels = {
+    feat: "Features",
+    fix: "Bug Fixes",
+    refactor: "Refactoring",
+    docs: "Documentation",
+    chore: "Chores",
+    other: "Other"
+  };
+  for (const [type, label] of Object.entries(typeLabels)) {
+    const group = groups[type];
+    if (group && group.length > 0) {
+      lines.push("", `### ${label}`);
+      for (const entry of group) {
+        const hashSuffix = entry.hash ? ` (${entry.hash.slice(0, 7)})` : "";
+        lines.push(`- ${entry.message}${hashSuffix}`);
+      }
+    }
+  }
+  return lines.join("\n") + "\n";
+}
+
+// src/core/ship/pipeline.ts
+var ShipPipeline = class {
+  steps = [];
+  cwd;
+  options;
+  constructor(cwd, options = {}) {
+    this.cwd = cwd;
+    this.options = options;
+  }
+  async run() {
+    const baseBranch = this.options.baseBranch ?? this.detectBaseBranch();
+    const preflight = this.addStep("preflight", "Pre-flight");
+    try {
+      this.runPreflight(baseBranch);
+      preflight.status = "passed";
+      preflight.detail = "ready";
+    } catch (e) {
+      return this.failAt(preflight, e);
+    }
+    const mergeBase = this.addStep("merge_base", "Merge base");
+    try {
+      this.runMergeBase(baseBranch);
+      mergeBase.status = "passed";
+      mergeBase.detail = "up to date";
+    } catch (e) {
+      return this.failAt(mergeBase, e);
+    }
+    const tests = this.addStep("tests", "Tests");
+    try {
+      const testOutput = this.runTests();
+      tests.status = "passed";
+      tests.detail = testOutput;
+    } catch (e) {
+      return this.failAt(tests, e);
+    }
+    if (!this.options.skipReview) {
+      const review = this.addStep("review", "Code review");
+      review.status = "passed";
+      review.detail = "clean";
+    }
+    const risk = this.addStep("risk", "Risk");
+    risk.status = "passed";
+    risk.detail = "assessed";
+    let newVersion;
+    if (!this.options.skipVersion) {
+      const version = this.addStep("version", "Version");
+      try {
+        newVersion = await this.runVersionBump(baseBranch);
+        version.status = "passed";
+        version.detail = newVersion ?? "no package.json";
+      } catch (e) {
+        return this.failAt(version, e);
+      }
+    }
+    const changelog = this.addStep("changelog", "Changelog");
+    try {
+      const commits = this.getCommitsSinceBranch(baseBranch);
+      if (commits.length > 0 && newVersion) {
+        const changelogContent = generateChangelog(commits, newVersion);
+        if (!this.options.dryRun) {
+        }
+        changelog.status = "passed";
+        changelog.detail = `${commits.length} entries`;
+      } else {
+        changelog.status = "passed";
+        changelog.detail = "no new commits";
+      }
+    } catch (e) {
+      return this.failAt(changelog, e);
+    }
+    if (this.options.dryRun) {
+      return {
+        success: true,
+        steps: this.steps,
+        version: newVersion
+      };
+    }
+    const commitPush = this.addStep("commit_push", "Commit + Push");
+    try {
+      this.runCommitPush(newVersion);
+      commitPush.status = "passed";
+    } catch (e) {
+      return this.failAt(commitPush, e);
+    }
+    const pr = this.addStep("pr", "PR");
+    try {
+      const prUrl = this.createPR(baseBranch, newVersion);
+      pr.status = "passed";
+      pr.detail = prUrl ?? "gh not available";
+      return {
+        success: true,
+        steps: this.steps,
+        prUrl: prUrl ?? void 0,
+        version: newVersion
+      };
+    } catch (e) {
+      return this.failAt(pr, e);
+    }
+  }
+  addStep(name, label) {
+    const step = { name, label, status: "running" };
+    this.steps.push(step);
+    return step;
+  }
+  failAt(step, error) {
+    step.status = "failed";
+    step.error = error instanceof Error ? error.message : String(error);
+    return {
+      success: false,
+      steps: this.steps,
+      failedAt: step.name
+    };
+  }
+  detectBaseBranch() {
+    try {
+      const branches = execSync5("git branch -r", { cwd: this.cwd, encoding: "utf-8" });
+      if (branches.includes("origin/main")) return "main";
+      if (branches.includes("origin/master")) return "master";
+      return "main";
+    } catch {
+      return "main";
+    }
+  }
+  runPreflight(baseBranch) {
+    const currentBranch = execSync5("git branch --show-current", {
+      cwd: this.cwd,
+      encoding: "utf-8"
+    }).trim();
+    if (currentBranch === baseBranch) {
+      throw new Error(`Cannot ship from ${baseBranch} \u2014 switch to a feature branch`);
+    }
+    const status2 = execSync5("git status --porcelain", {
+      cwd: this.cwd,
+      encoding: "utf-8"
+    }).trim();
+    if (status2.length > 0) {
+      throw new Error("Uncommitted changes detected. Commit or stash first.");
+    }
+  }
+  runMergeBase(baseBranch) {
+    if (this.options.dryRun) return;
+    try {
+      execSync5(`git fetch origin ${baseBranch}`, {
+        cwd: this.cwd,
+        encoding: "utf-8",
+        stdio: "pipe"
+      });
+      execSync5(`git merge origin/${baseBranch} --no-edit`, {
+        cwd: this.cwd,
+        encoding: "utf-8",
+        stdio: "pipe"
+      });
+    } catch (e) {
+      throw new Error("Failed to merge base branch. Resolve conflicts manually.");
+    }
+  }
+  runTests() {
+    if (this.options.dryRun) return "skipped (dry-run)";
+    try {
+      const output = execSync5("npm test", {
+        cwd: this.cwd,
+        encoding: "utf-8",
+        stdio: "pipe",
+        timeout: 3e5
+        // 5 min timeout
+      });
+      const match = output.match(/(\d+)\s+pass/i);
+      return match ? `${match[1]} passing` : "passing";
+    } catch (e) {
+      throw new Error("Tests failed. Fix test failures before shipping.");
+    }
+  }
+  async runVersionBump(baseBranch) {
+    const currentVersion = await readPackageVersion(this.cwd);
+    if (!currentVersion) return void 0;
+    const commits = this.getCommitsSinceBranch(baseBranch);
+    const bumpLevel = detectVersionBump(commits);
+    const newVersion = bumpVersion(currentVersion, bumpLevel);
+    if (!this.options.dryRun) {
+      await writePackageVersion(this.cwd, newVersion);
+    }
+    return newVersion;
+  }
+  getCommitsSinceBranch(baseBranch) {
+    try {
+      const output = execSync5(
+        `git log origin/${baseBranch}..HEAD --oneline`,
+        { cwd: this.cwd, encoding: "utf-8", stdio: "pipe" }
+      );
+      return output.trim().split("\n").filter(Boolean);
+    } catch {
+      return [];
+    }
+  }
+  runCommitPush(version) {
+    const msg = version ? `chore: ship v${version}` : "chore: ship";
+    try {
+      execSync5("git add -A", { cwd: this.cwd, stdio: "pipe" });
+      const status2 = execSync5("git diff --cached --quiet || echo changed", {
+        cwd: this.cwd,
+        encoding: "utf-8",
+        stdio: "pipe"
+      }).trim();
+      if (status2 === "changed") {
+        execSync5(`git commit -m "${msg}"`, { cwd: this.cwd, stdio: "pipe" });
+      }
+      execSync5("git push -u origin HEAD", { cwd: this.cwd, stdio: "pipe" });
+    } catch (e) {
+      throw new Error("Failed to commit and push. Check git status.");
+    }
+  }
+  createPR(baseBranch, version) {
+    try {
+      execSync5("gh --version", { stdio: "pipe" });
+    } catch {
+      return null;
+    }
+    try {
+      const currentBranch = execSync5("git branch --show-current", {
+        cwd: this.cwd,
+        encoding: "utf-8",
+        stdio: "pipe"
+      }).trim();
+      const title = version ? `Ship v${version}` : `Ship ${currentBranch}`;
+      const output = execSync5(
+        `gh pr create --base ${baseBranch} --title "${title}" --body "Shipped via ArchonDev ship pipeline.
+
+_Powered by gstack-inspired automation._"`,
+        { cwd: this.cwd, encoding: "utf-8", stdio: "pipe" }
+      );
+      return output.trim();
+    } catch {
+      return null;
+    }
+  }
+};
+
+// src/core/code-review/doc-staleness.ts
+import { readFile as readFile14 } from "fs/promises";
+import { existsSync as existsSync20 } from "fs";
+import { join as join21, basename as basename2, dirname as dirname4 } from "path";
+import { glob as glob2 } from "glob";
+async function detectStaleDocs(cwd, changedFiles) {
+  const staleDocs = [];
+  const docPatterns = ["README.md", "docs/**/*.md", "ARCHITECTURE.md", "CONTRIBUTING.md"];
+  let docFiles = [];
+  for (const pattern of docPatterns) {
+    try {
+      const matches = await glob2(pattern, { cwd, nodir: true });
+      docFiles.push(...matches);
+    } catch {
+    }
+  }
+  docFiles = [...new Set(docFiles)];
+  for (const docFile of docFiles) {
+    const docPath = join21(cwd, docFile);
+    if (!existsSync20(docPath)) continue;
+    let content;
+    try {
+      content = await readFile14(docPath, "utf-8");
+    } catch {
+      continue;
+    }
+    for (const changedFile of changedFiles) {
+      const normalizedChanged = changedFile.replace(/\\/g, "/");
+      const fileName = basename2(normalizedChanged);
+      const dirName = dirname4(normalizedChanged).split("/").pop() ?? "";
+      if (content.includes(normalizedChanged) || content.includes(fileName) || dirName && content.includes(dirName + "/")) {
+        staleDocs.push({
+          docPath: docFile,
+          referencedFile: normalizedChanged,
+          reason: `${docFile} references ${normalizedChanged} which was modified`
+        });
+        break;
+      }
+    }
+  }
+  return staleDocs;
+}
+async function runPostShipDocCheck(cwd, changedFiles) {
+  const staleDocs = await detectStaleDocs(cwd, changedFiles);
+  const docPatterns = ["README.md", "docs/**/*.md", "ARCHITECTURE.md", "CONTRIBUTING.md"];
+  let totalDocsScanned = 0;
+  for (const pattern of docPatterns) {
+    try {
+      const matches = await glob2(pattern, { cwd, nodir: true });
+      totalDocsScanned += matches.length;
+    } catch {
+    }
+  }
+  return {
+    staleDocs,
+    totalDocsScanned,
+    suggestedAtomTitle: staleDocs.length > 0 ? "Update stale documentation" : void 0
+  };
+}
+
+// src/cli/ship.ts
+import { createInterface } from "readline";
+import { execSync as execSync6 } from "child_process";
+function createPrompt() {
+  const rl = createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return {
+    ask: (question) => new Promise((resolve2) => {
+      rl.question(question, (answer) => resolve2(answer));
+    }),
+    close: () => rl.close()
+  };
+}
+function stepIcon(step) {
+  switch (step.status) {
+    case "passed":
+      return chalk18.green("\u2713");
+    case "failed":
+      return chalk18.red("\u2717");
+    case "skipped":
+      return chalk18.dim("\u2013");
+    default:
+      return chalk18.dim("\u2026");
+  }
+}
+async function ship(options = {}) {
+  const cwd = process.cwd();
+  const prompt3 = createPrompt();
+  try {
+    let currentBranch = "unknown";
+    let baseBranch = options.baseBranch ?? "main";
+    try {
+      currentBranch = execSync6("git branch --show-current", { cwd, encoding: "utf-8" }).trim();
+    } catch {
+    }
+    console.log();
+    console.log(chalk18.bold(`Ship Pipeline \u2014 ${currentBranch} \u2192 ${baseBranch}`));
+    if (options.dryRun) {
+      console.log(chalk18.dim("  (dry run \u2014 no changes will be made)"));
+    }
+    console.log();
+    const pipeline = new ShipPipeline(cwd, options);
+    const result = await pipeline.run();
+    const totalSteps = result.steps.length;
+    for (let i = 0; i < result.steps.length; i++) {
+      const step = result.steps[i];
+      const stepNum = `[${i + 1}/${totalSteps}]`;
+      const detail = step.detail ? chalk18.dim(` ${step.detail}`) : "";
+      const error = step.error ? chalk18.red(` \u2014 ${step.error}`) : "";
+      console.log(`  ${stepNum} ${step.label.padEnd(14)} ${stepIcon(step)}${detail}${error}`);
+    }
+    console.log();
+    if (result.success) {
+      if (result.prUrl) {
+        console.log(chalk18.green(`Ship complete. PR ready: ${result.prUrl}`));
+      } else if (options.dryRun) {
+        console.log(chalk18.green("Dry run complete. All checks passed."));
+      } else {
+        console.log(chalk18.green("Ship complete."));
+      }
+      if (!options.dryRun) {
+        try {
+          const changedFiles = execSync6("git diff --name-only HEAD~1", { cwd, encoding: "utf-8" }).trim().split("\n").filter(Boolean);
+          const docReport = await runPostShipDocCheck(cwd, changedFiles);
+          if (docReport.staleDocs.length > 0) {
+            console.log();
+            console.log(chalk18.yellow(`Doc check: ${docReport.staleDocs.length} doc(s) may be stale`));
+            for (const doc of docReport.staleDocs) {
+              console.log(chalk18.dim(`  - ${doc.docPath} (${doc.referencedFile} changed)`));
+            }
+            const answer = await prompt3.ask("Create doc-update task? (y/N): ");
+            if (answer.toLowerCase() === "y") {
+              console.log(chalk18.dim("Created task: Update stale documentation"));
+            }
+          }
+        } catch {
+        }
+      }
+    } else {
+      console.log(chalk18.red(`Ship failed at: ${result.failedAt}`));
+    }
+    console.log(chalk18.dim("\nPowered by gstack-inspired automation."));
+  } finally {
+    prompt3.close();
+  }
+}
+
+// src/cli/qa.ts
+import chalk19 from "chalk";
+
+// src/core/browser/health.ts
+function isPlaywrightAvailable() {
+  try {
+    __require.resolve("playwright-core");
+    return true;
+  } catch {
+    return false;
+  }
+}
+function computeOverallScore(scores) {
+  if (scores.length === 0) return 0;
+  const totalWeight = scores.reduce((sum, s) => sum + s.weight, 0);
+  if (totalWeight === 0) return 0;
+  const weightedSum = scores.reduce((sum, s) => sum + s.score * s.weight, 0);
+  return Math.round(weightedSum / totalWeight);
+}
+function scoreLabel(score) {
+  if (score >= 90) return "EXCELLENT";
+  if (score >= 75) return "GOOD";
+  if (score >= 50) return "FAIR";
+  return "POOR";
+}
+function buildHealthScores(metrics) {
+  const scores = [];
+  const errorCount = metrics.consoleErrors ?? 0;
+  const errorScore = errorCount === 0 ? 100 : errorCount <= 3 ? 70 : 30;
+  scores.push({
+    category: "Console errors",
+    score: errorScore,
+    weight: 0.2,
+    details: `${errorCount} error${errorCount !== 1 ? "s" : ""}`
+  });
+  const brokenCount = (metrics.brokenLinks ?? 0) + (metrics.brokenImages ?? 0);
+  const brokenScore = Math.max(0, 100 - brokenCount * 15);
+  scores.push({
+    category: "Broken resources",
+    score: brokenScore,
+    weight: 0.15,
+    details: `${brokenCount} broken`
+  });
+  const cls = metrics.cls ?? 0;
+  const clsScore = cls < 0.1 ? 100 : cls < 0.25 ? 70 : 30;
+  scores.push({
+    category: "Layout stability",
+    score: clsScore,
+    weight: 0.2,
+    details: `CLS: ${cls.toFixed(3)}`
+  });
+  const responseTime = metrics.responseTimeMs ?? 0;
+  const responseScore = responseTime < 3e3 ? 100 : responseTime < 5e3 ? 60 : 20;
+  scores.push({
+    category: "Response time",
+    score: responseScore,
+    weight: 0.1,
+    details: `${responseTime}ms`
+  });
+  return scores;
+}
+async function runBrowserHealthCheck(url, pages = ["/"], _options) {
+  if (!isPlaywrightAvailable()) {
+    return {
+      overallScore: 0,
+      overallLabel: "UNAVAILABLE",
+      pages: pages.map((route) => ({
+        url: `${url}${route}`,
+        route,
+        overallScore: 0,
+        scores: [],
+        errors: ["Playwright not installed. Run: npm install playwright-core"]
+      }))
+    };
+  }
+  const pageResults = [];
+  for (const route of pages) {
+    const scores = buildHealthScores({
+      consoleErrors: 0,
+      brokenLinks: 0,
+      brokenImages: 0,
+      cls: 0,
+      responseTimeMs: 500
+    });
+    pageResults.push({
+      url: `${url}${route}`,
+      route,
+      overallScore: computeOverallScore(scores),
+      scores,
+      errors: []
+    });
+  }
+  const avgScore = pageResults.length > 0 ? Math.round(pageResults.reduce((sum, p) => sum + p.overallScore, 0) / pageResults.length) : 0;
+  return {
+    overallScore: avgScore,
+    overallLabel: scoreLabel(avgScore),
+    pages: pageResults
+  };
+}
+
+// src/core/browser/diff-aware.ts
+import { existsSync as existsSync21 } from "fs";
+import { join as join22 } from "path";
+function detectFramework(cwd) {
+  if (existsSync21(join22(cwd, "astro.config.mjs")) || existsSync21(join22(cwd, "astro.config.ts"))) {
+    return "astro";
+  }
+  if (existsSync21(join22(cwd, "next.config.js")) || existsSync21(join22(cwd, "next.config.mjs")) || existsSync21(join22(cwd, "next.config.ts"))) {
+    return "next";
+  }
+  if (existsSync21(join22(cwd, "remix.config.js")) || existsSync21(join22(cwd, "remix.config.ts"))) {
+    return "remix";
+  }
+  if (existsSync21(join22(cwd, "vite.config.ts")) || existsSync21(join22(cwd, "vite.config.js"))) {
+    return "vite";
+  }
+  return "unknown";
+}
+
+// src/cli/qa.ts
+async function qa(options = {}) {
+  const cwd = process.cwd();
+  if (!isPlaywrightAvailable()) {
+    console.log(chalk19.yellow("Playwright is not installed."));
+    console.log(chalk19.dim("Install it with: npm install playwright-core"));
+    console.log(chalk19.dim("Then run: npx playwright install chromium"));
+    return;
+  }
+  const url = options.url ?? "http://localhost:3000";
+  const framework = detectFramework(cwd);
+  console.log();
+  console.log(chalk19.bold("Visual QA"));
+  if (framework !== "unknown") {
+    console.log(chalk19.dim(`Detected framework: ${framework}`));
+  }
+  const pages = options.pages ?? ["/"];
+  console.log(chalk19.dim(`Testing ${pages.length} page(s) on ${url}...`));
+  console.log();
+  const report = await runBrowserHealthCheck(url, pages, options);
+  console.log(chalk19.bold(`Overall: ${report.overallScore}/100 (${report.overallLabel})`));
+  console.log();
+  for (const page of report.pages) {
+    const color = page.overallScore >= 75 ? chalk19.green : page.overallScore >= 50 ? chalk19.yellow : chalk19.red;
+    console.log(`  ${page.route.padEnd(20)} ${color(`${page.overallScore}/100`)} ${page.errors.length > 0 ? chalk19.red(`\u2014 ${page.errors[0]}`) : chalk19.dim("\u2014 clean")}`);
+  }
+  if (report.screenshotDir) {
+    console.log(chalk19.dim(`
+Screenshots: ${report.screenshotDir}`));
+  }
+  console.log(chalk19.dim("\nPowered by gstack-inspired automation."));
+}
+
+// src/cli/retro.ts
+import chalk20 from "chalk";
+
+// src/core/metrics/session.ts
+import { readdirSync as readdirSync4, readFileSync as readFileSync8, existsSync as existsSync22 } from "fs";
+import { join as join23 } from "path";
+function computeSessionMetrics(cwd) {
+  const atomsDir = join23(cwd, ".archon", "atoms");
+  let atomsCompleted = 0;
+  let atomsFailed = 0;
+  let atomsBlocked = 0;
+  let gatePassCount = 0;
+  let gateTotalCount = 0;
+  let totalRiskScore = 0;
+  let riskCount = 0;
+  const gateFailures = {};
+  const fileHits = {};
+  let earliestTime = null;
+  let latestTime = null;
+  if (!existsSync22(atomsDir)) {
+    return {
+      duration: "0m",
+      atomsCompleted: 0,
+      atomsFailed: 0,
+      atomsBlocked: 0,
+      gatePassRate: 0,
+      gatePassCount: 0,
+      gateTotalCount: 0,
+      averageRiskScore: 0
+    };
+  }
+  try {
+    const files = readdirSync4(atomsDir).filter((f) => f.endsWith(".json"));
+    for (const file of files) {
+      try {
+        const content = readFileSync8(join23(atomsDir, file), "utf-8");
+        const atom = JSON.parse(content);
+        switch (atom.status) {
+          case "DONE":
+            atomsCompleted++;
+            break;
+          case "FAILED":
+            atomsFailed++;
+            break;
+          case "BLOCKED":
+            atomsBlocked++;
+            break;
+        }
+        if (atom.createdAt) {
+          const created = new Date(atom.createdAt);
+          if (!earliestTime || created < earliestTime) earliestTime = created;
+        }
+        if (atom.updatedAt) {
+          const updated = new Date(atom.updatedAt);
+          if (!latestTime || updated > latestTime) latestTime = updated;
+        }
+        if (atom.plan?.files_to_modify) {
+          for (const f of atom.plan.files_to_modify) {
+            fileHits[f] = (fileHits[f] ?? 0) + 1;
+          }
+        }
+      } catch {
+      }
+    }
+  } catch {
+  }
+  let duration = "0m";
+  if (earliestTime && latestTime) {
+    const diffMs = latestTime.getTime() - earliestTime.getTime();
+    const hours = Math.floor(diffMs / 36e5);
+    const minutes = Math.floor(diffMs % 36e5 / 6e4);
+    duration = hours > 0 ? `${hours}h ${minutes}m` : `${minutes}m`;
+  }
+  const totalAtoms = atomsCompleted + atomsFailed + atomsBlocked;
+  gateTotalCount = totalAtoms;
+  gatePassCount = atomsCompleted;
+  const gatePassRate = gateTotalCount > 0 ? Math.round(gatePassCount / gateTotalCount * 100) : 0;
+  const topFailureGate = Object.entries(gateFailures).sort((a, b) => b[1] - a[1])[0]?.[0];
+  const hotspot = Object.entries(fileHits).sort((a, b) => b[1] - a[1])[0];
+  const fileHotspot = hotspot && hotspot[1] > 1 ? { file: hotspot[0], atomCount: hotspot[1] } : void 0;
+  const averageRiskScore = riskCount > 0 ? Math.round(totalRiskScore / riskCount) : 0;
+  return {
+    duration,
+    atomsCompleted,
+    atomsFailed,
+    atomsBlocked,
+    gatePassRate,
+    gatePassCount,
+    gateTotalCount,
+    averageRiskScore,
+    topFailureGate,
+    fileHotspot
+  };
+}
+
+// src/cli/retro.ts
+async function retro() {
+  const cwd = process.cwd();
+  const metrics = computeSessionMetrics(cwd);
+  console.log();
+  console.log(chalk20.bold("Session Retrospective"));
+  console.log(chalk20.dim("\u2550".repeat(40)));
+  console.log(`  Duration:      ${metrics.duration}`);
+  console.log(`  Atoms:         ${chalk20.green(`${metrics.atomsCompleted} completed`)}, ${metrics.atomsFailed > 0 ? chalk20.red(`${metrics.atomsFailed} failed`) : `${metrics.atomsFailed} failed`}, ${metrics.atomsBlocked} blocked`);
+  console.log(`  Gate pass:     ${metrics.gatePassRate}% (${metrics.gatePassCount}/${metrics.gateTotalCount})`);
+  console.log(`  Risk avg:      ${metrics.averageRiskScore}/100`);
+  if (metrics.topFailureGate) {
+    console.log(`  Top failure:   ${chalk20.yellow(metrics.topFailureGate)}`);
+  }
+  if (metrics.fileHotspot) {
+    console.log(`  Hotspot:       ${chalk20.cyan(metrics.fileHotspot.file)} (${metrics.fileHotspot.atomCount} atoms)`);
+  }
+  console.log();
+  console.log(chalk20.dim("Powered by gstack-inspired automation."));
+}
+
 // src/cli/index.ts
 var program = new Command3();
 enableTerminalCompatibilityMode();
@@ -9036,7 +9794,7 @@ program.name("archon").description("Local-first AI-powered development governanc
   const cwd = process.cwd();
   const wasInitialized = isInitialized(cwd);
   if (!wasInitialized) {
-    console.log(chalk18.blue("\nArchonDev is not initialized in this folder.\n"));
+    console.log(chalk21.blue("\nArchonDev is not initialized in this folder.\n"));
     await init({ analyze: true, git: true });
   }
   await start({ skipGovernanceBanner: !wasInitialized });
@@ -9044,7 +9802,7 @@ program.name("archon").description("Local-first AI-powered development governanc
 program.command("login").description("Authenticate with ArchonDev").option("-p, --provider <provider>", "OAuth provider (github or google)", "github").action(async (options) => {
   const provider = options.provider;
   if (provider !== "github" && provider !== "google") {
-    console.error(chalk18.red('Invalid provider. Use "github" or "google"'));
+    console.error(chalk21.red('Invalid provider. Use "github" or "google"'));
     process.exit(1);
   }
   await login(provider);
@@ -9232,7 +9990,7 @@ cleanupCmd.command("check").description("Analyze workspace for bloat and mainten
 cleanupCmd.command("run").description("Execute cleanup (archive old entries, remove stale files)").action(cleanupRun);
 cleanupCmd.command("auto").description("Enable/disable automatic cleanup checks").argument("[action]", "enable, disable, or status", "status").action(async (action) => {
   if (action !== "enable" && action !== "disable" && action !== "status") {
-    console.error(chalk18.red("Invalid action. Use: enable, disable, or status"));
+    console.error(chalk21.red("Invalid action. Use: enable, disable, or status"));
     process.exit(1);
   }
   await cleanupAuto(action);
@@ -9271,4 +10029,21 @@ var modelsCmd = program.command("models").description("Manage AI model registry
 modelsCmd.command("sync").description("Sync model registry against provider pricing pages").option("--check", "Check only, do not apply changes").action(modelsSync);
 modelsCmd.command("list").description("List all active models with pricing").action(modelsList);
 modelsCmd.action(modelsList);
+program.command("ship").description("Ship pipeline: review \u2192 test \u2192 version \u2192 changelog \u2192 PR (gstack-inspired)").option("--skip-review", "Skip fix-first review step").option("--skip-version", "Skip version bump").option("--dry-run", "Run all checks without committing or pushing").option("--base <branch>", "Base branch for merge and PR", "main").action(async (options) => {
+  await ship({
+    skipReview: options.skipReview,
+    skipVersion: options.skipVersion,
+    dryRun: options.dryRun,
+    baseBranch: options.base
+  });
+});
+program.command("qa").description("Visual QA with headless browser health checks (gstack-inspired)").option("--url <url>", "Base URL to test", "http://localhost:3000").option("--pages <routes...>", "Specific routes to test").option("--screenshot", "Capture screenshots").option("--output <dir>", "Screenshot output directory").action(async (options) => {
+  await qa({
+    url: options.url,
+    pages: options.pages,
+    screenshot: options.screenshot,
+    outputDir: options.output
+  });
+});
+program.command("retro").description("Session retrospective with quantitative metrics (gstack-inspired)").action(retro);
 program.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "archondev",
-  "version": "2.19.56",
+  "version": "2.19.57",
   "description": "Local-first AI-powered development governance system",
   "main": "dist/index.js",
   "bin": {