great-cto 2.3.4 → 2.4.0

package/dist/adapt.js

@@ -0,0 +1,342 @@
+// great-cto adapt — platform config generator.
+//
+// Writes platform-native config files derived from a shared core. Lets a
+// single great_cto installation work transparently with Claude Code, OpenAI
+// Codex CLI, Cursor, Aider, and Continue. AGENTS.md is the de-facto cross-
+// platform standard (used verbatim by Codex; consumed as fallback by most
+// others) so it forms the shared core.
+//
+// Usage:
+//   great-cto adapt --platform claude     CLAUDE.md
+//   great-cto adapt --platform codex      AGENTS.md
+//   great-cto adapt --platform cursor     .cursorrules + .cursor/rules/*.mdc
+//   great-cto adapt --platform aider      .aider.conf.yml + CONVENTIONS.md
+//   great-cto adapt --platform continue   .continue/rules.md
+//   great-cto adapt --platform all        all of the above
+//   great-cto adapt --dry-run             show what would be written
+//
+// Each adapter writes ONLY platform-native files. All share the AGENTS.md
+// core text via getAgentsCore(). To customize per-project, edit
+// .great_cto/PROJECT.md (archetype, owners, compliance) — adapt re-derives.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+function readProjectMeta(cwd) {
+    const projectMd = join(cwd, ".great_cto", "PROJECT.md");
+    if (!existsSync(projectMd)) {
+        return { archetype: "unknown", compliance: [], owners: "", hasGreatCto: false };
+    }
+    const text = readFileSync(projectMd, "utf8");
+    const archetype = (text.match(/^primary:\s*(\S+)/m)?.[1] ?? "unknown").trim();
+    const complianceLine = text.match(/^compliance:\s*(.+)$/m)?.[1] ?? "";
+    const compliance = complianceLine
+        .split(/[,\s]+/)
+        .map(s => s.trim())
+        .filter(Boolean);
+    const owners = (text.match(/^owners?:\s*(.+)$/m)?.[1] ?? "").trim();
+    return { archetype, compliance, owners, hasGreatCto: true };
+}
+/**
+ * Common AGENTS.md content used across platforms.
+ * Codex CLI reads this verbatim. Cursor / Aider / Claude Code embed it.
+ */
+function getAgentsCore(meta) {
+    const compliance = meta.compliance.length > 0
+        ? meta.compliance.map(c => `- ${c}`).join("\n")
+        : "_(none auto-detected — set in .great_cto/PROJECT.md)_";
+    return `# AGENTS.md
+
+> This file is the cross-tool agent contract. It is consumed by OpenAI Codex
+> CLI, Claude Code, Cursor, Aider, Continue, and any other AGENTS.md-aware
+> tooling. Generated by \`great-cto adapt\` — re-run after editing
+> \`.great_cto/PROJECT.md\`.
+
+## Project context
+
+- **Archetype:** ${meta.archetype}
+- **Compliance gates:**
+${compliance.split("\n").map(l => "  " + l).join("\n")}
+- **Owners:** ${meta.owners || "_(unset)_"}
+
+## How agents should work in this repo
+
+1. **Before touching code** — read \`.great_cto/PROJECT.md\` (archetype +
+   constraints) and \`.great_cto/lessons.md\` if present (past mistakes).
+2. **Before proposing a fix** — query \`~/.great_cto/decisions.md\` for ADRs
+   on related topics. Solved problems should stay solved.
+3. **Before merging** — run \`npx great-cto ci\` locally. Same gate as CI.
+4. **On failure / incident** — append to \`.great_cto/lessons.md\`. After 3
+   occurrences across projects, \`/crystallize\` promotes to global pattern.
+
+## Required gates (do not bypass)
+
+| Gate | When | Owner |
+|---|---|---|
+| security-officer | Any change touching auth, payments, PII | @security |
+| qa-engineer | Any feature merge | @qa |
+| performance-engineer | Any change to hot path | @perf |
+| db-migration-reviewer | Any \`migrations/\` change | @data |
+
+Override with \`/waiver\` and a written reason. Auto-expires in 14 days.
+
+## Available tools (via MCP)
+
+When this repo is opened in any MCP-capable tool, \`great-cto mcp\` exposes:
+
+- \`scan\` — OWASP LLM Top 10 + 24 rules · returns findings
+- \`list_rules\` — full rule catalogue
+- \`detect_archetype\` — archetype + compliance for any path
+- \`estimate_cost\` — LLM vs human time estimate for a task
+- \`query_decisions\` — search ADR log
+
+Configure your client to launch:
+\`\`\`bash
+npx great-cto mcp
+\`\`\`
+
+## Style + conventions
+
+- Tests **before** implementation (RED → GREEN → REFACTOR). Coverage 80%+ default.
+- Conventional commits: \`feat\` / \`fix\` / \`docs\` / \`refactor\` / \`test\` / \`chore\`.
+- One concern per PR. Refactors and behaviour changes are separate PRs.
+- No secrets in code. \`great-cto scan\` blocks ~13 patterns by default.
+
+## Out of scope
+
+Do not invent business decisions. If the spec is ambiguous, ask. Do not skip
+gates "because it's just a small change" — that's the path to incidents.
+
+---
+
+_Generated by \`great-cto@${getCliVersion()}\` adapt at ${new Date().toISOString().slice(0, 10)}_
+`;
+}
+function getCliVersion() {
+    try {
+        const here = dirname(new URL(import.meta.url).pathname);
+        const pkg = JSON.parse(readFileSync(join(here, "..", "package.json"), "utf8"));
+        return pkg.version ?? "unknown";
+    }
+    catch {
+        return "unknown";
+    }
+}
+function writeFile(path, content, dryRun) {
+    if (dryRun) {
+        console.log(`would write: ${path} (${content.length} bytes)`);
+        return false;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    const existed = existsSync(path);
+    writeFileSync(path, content);
+    console.log(`  ${existed ? "✎ updated" : "✓ wrote"}  ${path}`);
+    return true;
+}
+// ── Per-platform adapters ──────────────────────────────────────────────────
+function adaptClaude(cwd, meta, dryRun) {
+    // Claude Code reads CLAUDE.md (or AGENTS.md as fallback). We write both
+    // for maximum compat — projects with CLAUDE.md already get a top-level
+    // reference, and AGENTS.md unlocks any AGENTS.md-aware tool simultaneously.
+    const out = [];
+    const agentsBody = getAgentsCore(meta);
+    const claudeBody = `# CLAUDE.md
+
+> Project guidance for Claude Code. The full agent contract lives in
+> \`AGENTS.md\` — please read that first. This file adds Claude-Code-specific
+> overrides only.
+
+## Cross-tool contract
+
+See [AGENTS.md](./AGENTS.md) for the full project context, gates, and
+conventions. Generated by \`great-cto adapt\`.
+
+## Claude Code specifics
+
+- The great_cto plugin orchestrates 34 specialist agents — pipeline runs
+  through \`/start\`, \`/inbox\`, \`/save\`, etc.
+- Memory is layered: \`.great_cto/PROJECT.md\` (L1) → \`lessons.md\` (L3) →
+  \`~/.great_cto/decisions.md\` (L4 cross-project ADR log).
+- Run \`great-cto board\` (\`http://localhost:3141\`) for the kanban + metrics
+  + memory + agents view.
+
+## Quick links
+
+- ${"`"}/start "..."${"`"} — kick off a feature pipeline
+- ${"`"}/inbox${"`"} — see what needs your decision
+- ${"`"}/agent-review${"`"} — performance scorecard for agents
+
+`;
+    if (writeFile(join(cwd, "AGENTS.md"), agentsBody, dryRun))
+        out.push("AGENTS.md");
+    if (writeFile(join(cwd, "CLAUDE.md"), claudeBody, dryRun))
+        out.push("CLAUDE.md");
+    return out;
+}
+function adaptCodex(cwd, meta, dryRun) {
+    // OpenAI Codex CLI reads AGENTS.md. We write only that — Codex doesn't
+    // currently consume CLAUDE.md / .cursorrules.
+    const out = [];
+    if (writeFile(join(cwd, "AGENTS.md"), getAgentsCore(meta), dryRun))
+        out.push("AGENTS.md");
+    return out;
+}
+function adaptCursor(cwd, meta, dryRun) {
+    // Cursor reads .cursorrules (legacy single file) and .cursor/rules/*.mdc
+    // (modern modular). Write both for compat.
+    const out = [];
+    const rulesContent = `# Cursor rules — auto-generated by great-cto adapt
+# See AGENTS.md for the full agent contract; this file is the Cursor-native
+# subset focusing on inline-completion and chat behaviour.
+
+archetype: ${meta.archetype}
+compliance:
+${meta.compliance.map(c => `  - ${c}`).join("\n") || "  - none"}
+
+## Behaviour
+
+Before suggesting code changes:
+- Read \`AGENTS.md\` for repo-wide conventions
+- Read \`.great_cto/PROJECT.md\` for archetype constraints
+- Check \`~/.great_cto/decisions.md\` for prior ADRs on the topic
+
+## Gates that block merges (do not bypass)
+
+- security-officer: auth/payments/PII changes
+- qa-engineer: feature merges
+- db-migration-reviewer: any migrations/ change
+
+## Style
+
+- TDD: tests RED → implementation GREEN → refactor
+- Conventional commits
+- One concern per PR
+`;
+    const mdcContent = `---
+description: great_cto archetype + compliance contract
+globs: ["**/*"]
+alwaysApply: true
+---
+
+This repo is a **${meta.archetype}** project. Compliance gates:
+${meta.compliance.map(c => `- ${c}`).join("\n") || "- none"}
+
+Read \`AGENTS.md\` and \`.great_cto/PROJECT.md\` before proposing changes.
+Run \`npx great-cto ci\` before pushing.
+`;
+    if (writeFile(join(cwd, ".cursorrules"), rulesContent, dryRun))
+        out.push(".cursorrules");
+    if (writeFile(join(cwd, ".cursor", "rules", "great-cto.mdc"), mdcContent, dryRun))
+        out.push(".cursor/rules/great-cto.mdc");
+    if (writeFile(join(cwd, "AGENTS.md"), getAgentsCore(meta), dryRun))
+        out.push("AGENTS.md");
+    return out;
+}
+function adaptAider(cwd, meta, dryRun) {
+    // Aider reads .aider.conf.yml for settings and CONVENTIONS.md (or files
+    // listed in read: arrays) for context.
+    const out = [];
+    const conf = `# .aider.conf.yml — auto-generated by great-cto adapt
+# Aider config. Run aider in this dir and these settings apply.
+
+# Always include AGENTS.md and PROJECT.md as context
+read:
+  - AGENTS.md
+  - .great_cto/PROJECT.md
+
+# Auto-test after edits
+auto-test: true
+test-cmd: "npx great-cto ci --severity high"
+
+# Pretty output
+pretty: true
+
+# Conventional commits
+commit-prompt: "Use conventional commit format: feat/fix/docs/refactor/test/chore"
+
+# Archetype: ${meta.archetype}
+# Compliance: ${meta.compliance.join(", ") || "none"}
+`;
+    const conventions = `# CONVENTIONS.md
+
+> This is the Aider-native conventions file. The cross-tool agent contract
+> lives in \`AGENTS.md\` — please read that for full context.
+
+## Quick rules
+
+- **Archetype:** ${meta.archetype}
+- **Compliance gates:** ${meta.compliance.join(", ") || "_(none)_"}
+
+### Process
+1. Tests first (TDD)
+2. One concern per PR
+3. Conventional commits
+4. Run \`npx great-cto ci\` before push
+
+### Style
+- No secrets in code (\`great-cto scan\` enforces this)
+- Read \`.great_cto/PROJECT.md\` before suggesting architectural changes
+- Read \`~/.great_cto/decisions.md\` for prior ADRs
+`;
+    if (writeFile(join(cwd, ".aider.conf.yml"), conf, dryRun))
+        out.push(".aider.conf.yml");
+    if (writeFile(join(cwd, "CONVENTIONS.md"), conventions, dryRun))
+        out.push("CONVENTIONS.md");
+    if (writeFile(join(cwd, "AGENTS.md"), getAgentsCore(meta), dryRun))
+        out.push("AGENTS.md");
+    return out;
+}
+function adaptContinue(cwd, meta, dryRun) {
+    const out = [];
+    const rulesContent = `# Continue rules — generated by great-cto adapt
+
+## Project context
+
+Archetype: **${meta.archetype}**.
+Compliance: ${meta.compliance.join(", ") || "none"}.
+Read \`AGENTS.md\` for the full contract.
+
+## Behaviour
+
+- Run \`npx great-cto ci\` before pushing
+- Don't bypass gates (security / qa / db-migration)
+- Append lessons to \`.great_cto/lessons.md\` after incidents
+`;
+    if (writeFile(join(cwd, ".continue", "rules.md"), rulesContent, dryRun))
+        out.push(".continue/rules.md");
+    if (writeFile(join(cwd, "AGENTS.md"), getAgentsCore(meta), dryRun))
+        out.push("AGENTS.md");
+    return out;
+}
+// ── Main entry ─────────────────────────────────────────────────────────────
+export async function runAdapt(args) {
+    const meta = readProjectMeta(args.cwd);
+    if (!meta.hasGreatCto) {
+        console.error("FAIL: no .great_cto/PROJECT.md found.");
+        console.error("Run `npx great-cto init` first to bootstrap the project.");
+        return 1;
+    }
+    const platforms = args.platform === "all"
+        ? ["claude", "codex", "cursor", "aider", "continue"]
+        : [args.platform];
+    console.log(`great-cto adapt → ${platforms.join(", ")}${args.dryRun ? " (dry-run)" : ""}`);
+    console.log(`  archetype: ${meta.archetype}  compliance: ${meta.compliance.join(", ") || "none"}`);
+    console.log("");
+    const written = [];
+    for (const p of platforms) {
+        console.log(`▸ ${p}`);
+        const adapter = {
+            claude: adaptClaude,
+            codex: adaptCodex,
+            cursor: adaptCursor,
+            aider: adaptAider,
+            continue: adaptContinue,
+        }[p];
+        const out = adapter(args.cwd, meta, args.dryRun);
+        written.push(...out);
+    }
+    if (!args.dryRun) {
+        console.log("");
+        console.log(`✓ generated ${written.length} file(s) for ${platforms.length} platform(s).`);
+        console.log(`  Re-run after editing .great_cto/PROJECT.md to refresh.`);
+    }
+    return 0;
+}

package/dist/ci.js

@@ -0,0 +1,258 @@
+// great-cto ci — single-command CI gate.
+//
+// Runs scan + budget-check + archetype-validate with output formats matching
+// CI conventions. Designed to be the only great_cto invocation in a CI step.
+//
+// Outputs:
+//   - human-readable to stderr (always)
+//   - GitHub Actions annotations (auto when $GITHUB_ACTIONS is set, or --annotations)
+//   - SARIF 2.1.0 JSON (--sarif <path>) — uploadable to GitHub Security tab
+//   - JUnit XML (--junit <path>) — for test reporters / pipeline UIs
+//
+// Exit codes:
+//   0 = clean, all gates pass
+//   1 = findings at/above --fail-on threshold (CI should fail)
+//   2 = scan/setup error (not a finding — infrastructure problem)
+//
+// Example workflow:
+//   - run: npx great-cto@latest ci ./
+//     env:
+//       GREAT_CTO_NO_TELEMETRY: "1"
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+const SEVERITY_ORDER = {
+    info: 0,
+    low: 1,
+    medium: 2,
+    high: 3,
+    critical: 4,
+};
+function severityAtLeast(sev, threshold) {
+    return (SEVERITY_ORDER[sev] ?? 0) >= (SEVERITY_ORDER[threshold] ?? 0);
+}
+/**
+ * Emit GitHub Actions annotation lines. These appear inline on PR diffs.
+ * Format: ::error file=path,line=N,col=M,title=T::message
+ *         ::warning file=...
+ *         ::notice file=...
+ */
+function emitGitHubAnnotation(finding) {
+    const sev = finding.rule.severity;
+    const level = sev === "critical" || sev === "high" ? "error"
+        : sev === "medium" ? "warning" : "notice";
+    const file = finding.location.file;
+    const line = finding.location.line;
+    const title = `${finding.rule.id}: ${finding.rule.title}`;
+    const message = finding.rule.owasp
+        ? `${finding.rule.title} (${finding.rule.owasp})`
+        : finding.rule.title;
+    // Escape GHA-special characters
+    const escape = (s) => s.replace(/%/g, "%25").replace(/\r/g, "%0D").replace(/\n/g, "%0A");
+    console.log(`::${level} file=${escape(file)},line=${line},title=${escape(title)}::${escape(message)}`);
+}
+/**
+ * Emit JUnit XML report. One <testcase> per scanned file, fails recorded as
+ * <failure> elements. Format compatible with most CI test reporters.
+ */
+function buildJunitXml(report) {
+    const findingsByFile = new Map();
+    for (const f of report.findings) {
+        const arr = findingsByFile.get(f.location.file) || [];
+        arr.push(f);
+        findingsByFile.set(f.location.file, arr);
+    }
+    const totalTests = Math.max(report.filesScanned, findingsByFile.size);
+    const failures = report.findings.length;
+    const escape = (s) => String(s)
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+    const cases = Array.from(findingsByFile.entries())
+        .map(([file, findings]) => {
+        const failureBody = findings
+            .map(f => `      <failure type="${escape(f.rule.severity)}" message="${escape(f.rule.id + ': ' + f.rule.title)}">
+${escape(f.location.snippet || '')}
+${escape(f.rule.owasp || '')}
+      </failure>`)
+            .join("\n");
+        return `    <testcase classname="agentshield" name="${escape(file)}" time="0">
+${failureBody}
+    </testcase>`;
+    })
+        .join("\n");
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<testsuites>
+  <testsuite name="great-cto ci" tests="${totalTests}" failures="${failures}" errors="0" time="${(report.durationMs / 1000).toFixed(3)}">
+${cases}
+  </testsuite>
+</testsuites>
+`;
+}
+/**
+ * Quick archetype-detection sanity check. Fails CI if the archetype changed
+ * from what's pinned in .great_cto/PROJECT.md (signals undeclared
+ * architectural drift).
+ */
+async function archetypeCheck(cwd, quiet) {
+    const projectMd = resolve(cwd, ".great_cto", "PROJECT.md");
+    if (!existsSync(projectMd)) {
+        if (!quiet)
+            console.error("  ⊘ archetype check skipped (no .great_cto/PROJECT.md)");
+        return { ok: true, msg: "skipped" };
+    }
+    const declared = (readFileSync(projectMd, "utf8").match(/^primary:\s*(\S+)/m)?.[1] ?? "").trim();
+    if (!declared) {
+        return { ok: true, msg: "no archetype declared in PROJECT.md" };
+    }
+    try {
+        const { detect } = await import("./detect.js");
+        const { pickArchetype } = await import("./archetypes.js");
+        const detected = await detect(cwd);
+        const result = pickArchetype(detected);
+        if (result.primary !== declared) {
+            return {
+                ok: false,
+                msg: `archetype drift: declared=${declared}, detected=${result.primary} (${result.confidence})`,
+            };
+        }
+        return { ok: true, msg: `archetype confirmed: ${declared}` };
+    }
+    catch (e) {
+        return { ok: true, msg: `archetype check failed (non-fatal): ${e.message}` };
+    }
+}
+/**
+ * Quick budget sanity check. Reads monthly-budget from PROJECT.md and warns
+ * if recent burn (last 30 days) exceeds it. Non-fatal — never blocks CI.
+ * Pure observability — for fatal budget enforcement use cost-guard hook.
+ */
+function budgetCheck(cwd, quiet) {
+    const projectMd = resolve(cwd, ".great_cto", "PROJECT.md");
+    if (!existsSync(projectMd))
+        return { ok: true, msg: "no PROJECT.md" };
+    const text = readFileSync(projectMd, "utf8");
+    const budget = text.match(/monthly[-_]budget:\s*\$?(\d[\d,]+)/i)?.[1]?.replace(/,/g, "");
+    if (!budget)
+        return { ok: true, msg: "no budget set" };
+    // Very simple: just confirm budget is well-formed. Real burn calc lives in board.
+    if (!quiet)
+        console.error(`  ✓ monthly-budget: $${budget}`);
+    return { ok: true, msg: `budget configured: $${budget}` };
+}
+export async function runCi(args) {
+    const startTs = Date.now();
+    const inGitHubActions = process.env.GITHUB_ACTIONS === "true";
+    const wantAnnotations = args.annotations || inGitHubActions;
+    if (!args.quiet) {
+        console.error(`\ngreat-cto ci — gate threshold: ${args.failOn}, scan: ${args.severity}+`);
+        console.error(`  path: ${resolve(args.path)}`);
+        if (inGitHubActions)
+            console.error(`  env: GitHub Actions detected — emitting annotations`);
+        console.error("");
+    }
+    // 1. Scan
+    let scan;
+    let toSarif;
+    try {
+        ({ scan } = await import("./agentshield/scanner.js"));
+        ({ toSarif } = await import("./agentshield/sarif.js"));
+    }
+    catch (e) {
+        console.error(`ci: failed to load scanner: ${e.message}`);
+        return 2;
+    }
+    const report = scan(resolve(args.path), {
+        minSeverity: args.severity,
+    });
+    // 2. Archetype check
+    let archResult = { ok: true, msg: "skipped" };
+    if (!args.noArchetype) {
+        archResult = await archetypeCheck(args.path, args.quiet);
+    }
+    // 3. Budget check (warn-only)
+    let budgetResult = { ok: true, msg: "skipped" };
+    if (!args.noBudget) {
+        budgetResult = budgetCheck(args.path, args.quiet);
+    }
+    // 4. Emit annotations
+    if (wantAnnotations) {
+        for (const f of report.findings) {
+            if (severityAtLeast(f.rule.severity, args.failOn)) {
+                emitGitHubAnnotation(f);
+            }
+        }
+    }
+    // 5. Emit SARIF
+    if (args.sarifPath) {
+        writeFileSync(args.sarifPath, JSON.stringify(toSarif(report), null, 2));
+        if (!args.quiet)
+            console.error(`  ✓ SARIF → ${args.sarifPath}`);
+    }
+    // 6. Emit JUnit XML
+    if (args.junitPath) {
+        writeFileSync(args.junitPath, buildJunitXml(report));
+        if (!args.quiet)
+            console.error(`  ✓ JUnit XML → ${args.junitPath}`);
+    }
+    // 7. Summary
+    const blockingFindings = report.findings.filter((f) => severityAtLeast(f.rule.severity, args.failOn));
+    const passed = blockingFindings.length === 0 && archResult.ok;
+    if (!args.quiet) {
+        const dur = ((Date.now() - startTs) / 1000).toFixed(1);
+        console.error("");
+        console.error(`  scan:       ${report.findings.length} finding(s) (${blockingFindings.length} at/above ${args.failOn})`);
+        console.error(`  archetype:  ${archResult.ok ? "✓" : "✗"} ${archResult.msg}`);
+        console.error(`  budget:     ${budgetResult.msg}`);
+        console.error(`  duration:   ${dur}s`);
+        console.error("");
+        if (passed) {
+            console.error("\x1b[32m✓ great-cto ci: passed\x1b[0m");
+        }
+        else {
+            console.error("\x1b[31m✗ great-cto ci: failed\x1b[0m");
+            if (blockingFindings.length) {
+                console.error(`  ${blockingFindings.length} finding(s) at/above ${args.failOn}:`);
+                for (const f of blockingFindings.slice(0, 10)) {
+                    console.error(`    [${f.rule.severity}] ${f.rule.id} — ${f.location.file}:${f.location.line}`);
+                }
+                if (blockingFindings.length > 10) {
+                    console.error(`    ... +${blockingFindings.length - 10} more`);
+                }
+            }
+            if (!archResult.ok)
+                console.error(`  ${archResult.msg}`);
+        }
+    }
+    return passed ? 0 : 1;
+}
+/**
+ * Parse `great-cto ci` flags from raw argv.
+ */
+export function parseCiArgs(rawArgv) {
+    const flag = (n) => rawArgv.includes(`--${n}`);
+    const value = (n, def) => {
+        const i = rawArgv.indexOf(`--${n}`);
+        return i >= 0 && i < rawArgv.length - 1 ? rawArgv[i + 1] : def;
+    };
+    const ciIdx = rawArgv.indexOf("ci");
+    let path = ".";
+    for (let i = ciIdx + 1; i < rawArgv.length; i++) {
+        if (rawArgv[i] && !rawArgv[i].startsWith("--")) {
+            path = rawArgv[i];
+            break;
+        }
+    }
+    return {
+        path,
+        severity: value("severity", "high"),
+        failOn: value("fail-on", "critical"),
+        sarifPath: value("sarif") ?? null,
+        junitPath: value("junit") ?? null,
+        annotations: flag("annotations"),
+        noBudget: flag("no-budget"),
+        noArchetype: flag("no-archetype"),
+        quiet: flag("quiet"),
+    };
+}

package/dist/main.js

@@ -83,6 +83,14 @@ function parseArgs(argv) {
             args.command = "scan";
         else if (a === "list-rules")
             args.command = "list-rules";
+        else if (a === "ci")
+            args.command = "ci";
+        else if (a === "mcp")
+            args.command = "mcp";
+        else if (a === "adapt")
+            args.command = "adapt";
+        else if (a === "serve")
+            args.command = "serve";
         else if (a.startsWith("--dir="))
             args.dir = a.slice("--dir=".length);
         else if (a === "--dir")
@@ -316,6 +324,10 @@ ${bold("Usage:")}
   npx great-cto register [--dir PATH]
   npx great-cto scan [path] [--severity LVL] [--scanner NAME] [--sarif FILE]
   npx great-cto list-rules
+  npx great-cto ci [path] [--fail-on LVL] [--sarif F] [--junit F]
+  npx great-cto mcp [--sse --port N]
+  npx great-cto adapt --platform [claude|codex|cursor|aider|continue|all]
+  npx great-cto serve [--port 3142]
   npx great-cto help
   npx great-cto version
 
@@ -338,6 +350,32 @@ ${bold("Scan (AI-security):")}
   great-cto list-rules                 Print rule catalog
   ${dim("(exits 1 if findings ≥ severity threshold; CI-friendly)")}
 
+${bold("CI gate:")}
+  great-cto ci                         Single-command CI gate (scan + archetype check)
+  great-cto ci --fail-on critical      Exit 1 only on critical findings (default)
+  great-cto ci --sarif out.sarif       Emit SARIF (uploadable to GitHub Security)
+  great-cto ci --junit out.xml         Emit JUnit XML for test reporters
+  ${dim("(auto-detects \$GITHUB_ACTIONS → emits ::error:: annotations)")}
+
+${bold("MCP server (cross-platform):")}
+  great-cto mcp                        Stdio MCP server — works in Claude Desktop /
+                                       Cursor / Continue / any MCP host
+  great-cto mcp --sse --port 8765      SSE mode for remote / multi-client (TODO v2.5)
+  ${dim("Tools exposed: scan, list_rules, detect_archetype, estimate_cost, query_decisions")}
+
+${bold("Platform adapter (multi-tool support):")}
+  great-cto adapt --platform claude    Generate AGENTS.md + CLAUDE.md
+  great-cto adapt --platform codex     Generate AGENTS.md (OpenAI Codex CLI)
+  great-cto adapt --platform cursor    Generate .cursorrules + .cursor/rules/*.mdc
+  great-cto adapt --platform aider     Generate .aider.conf.yml + CONVENTIONS.md
+  great-cto adapt --platform continue  Generate .continue/rules.md
+  great-cto adapt --platform all       All of the above
+  ${dim("Idempotent — re-run after editing .great_cto/PROJECT.md")}
+
+${bold("Webhook server (preview):")}
+  great-cto serve --port 3142          Webhook receiver (logs to ~/.great_cto/webhook-events.log)
+  ${dim("Endpoints: POST /webhook/github, POST /webhook/generic, GET /events, GET /healthz")}
+
 ${bold("Options:")}
   -y, --yes              Skip confirmation prompts (non-interactive)
       --dry-run          Show what would be done without doing it
@@ -732,6 +770,67 @@ async function main() {
             process.exit(1);
         }
     }
+    if (args.command === "ci") {
+        try {
+            const { runCi, parseCiArgs } = await import("./ci.js");
+            const code = await runCi(parseCiArgs(rawArgv));
+            process.exit(code);
+        }
+        catch (e) {
+            error(e.message);
+            process.exit(2);
+        }
+    }
+    if (args.command === "mcp") {
+        try {
+            const { runMcp } = await import("./mcp.js");
+            const sse = rawArgv.includes("--sse");
+            const portArg = rawArgv.indexOf("--port");
+            const port = portArg >= 0 ? parseInt(rawArgv[portArg + 1] ?? "8765", 10) : 8765;
+            const code = await runMcp({ mode: sse ? "sse" : "stdio", port, version: getCliVersion() });
+            process.exit(code);
+        }
+        catch (e) {
+            error(e.message);
+            process.exit(2);
+        }
+    }
+    if (args.command === "adapt") {
+        try {
+            const { runAdapt } = await import("./adapt.js");
+            const platArg = rawArgv.indexOf("--platform");
+            const platform = (platArg >= 0 ? rawArgv[platArg + 1] : "all");
+            const valid = ["claude", "codex", "cursor", "aider", "continue", "all"];
+            if (!valid.includes(platform)) {
+                error(`adapt: --platform must be one of ${valid.join(", ")} (got: ${platform})`);
+                process.exit(2);
+            }
+            const code = await runAdapt({
+                platform,
+                dryRun: rawArgv.includes("--dry-run"),
+                cwd: args.dir,
+            });
+            process.exit(code);
+        }
+        catch (e) {
+            error(e.message);
+            process.exit(2);
+        }
+    }
+    if (args.command === "serve") {
+        try {
+            const { runServe } = await import("./serve.js");
+            const code = await runServe({
+                port: args.boardPort === 3141 ? 3142 : args.boardPort,
+                noLog: rawArgv.includes("--no-log"),
+            });
+            process.exit(code);
+        }
+        catch (e) {
+            error(e.message);
+            process.exit(2);
+        }
+    }
     if (args.command === "version") {
         // Version resolved in index.mjs or from package.json at runtime
         try {

package/dist/mcp.js

@@ -0,0 +1,287 @@
+// great-cto mcp — Model Context Protocol server.
+//
+// Exposes great_cto's core capabilities as MCP tools so any MCP-compatible
+// host (Claude Desktop, Cursor, Continue, Codex CLI via MCP, custom agents)
+// can call them. This is the single biggest cross-platform multiplier — one
+// implementation, all clients.
+//
+// Modes:
+//   stdio (default)  — Claude Desktop / Cursor / Continue spawn this as subprocess
+//   sse              — long-running HTTP/SSE for remote / multi-client access
+//
+// Tools exposed:
+//   scan              OWASP LLM Top 10 + 24 rules → findings
+//   list_rules        full rule catalogue
+//   detect_archetype  archetype + compliance for a path
+//   estimate_cost     LLM/human time for a task
+//   query_decisions   search ~/.great_cto/decisions.md
+//
+// Protocol: minimal MCP 2024-11-05 implementation. We hand-roll because
+// adding @modelcontextprotocol/sdk would balloon install size for what is
+// fundamentally a few JSON messages over stdio.
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+const PROTOCOL_VERSION = "2024-11-05";
+const SERVER_INFO = {
+    name: "great-cto",
+    version: "", // populated at startup
+};
+// ── Tool implementations ────────────────────────────────────────────────────
+async function toolScan(args) {
+    const { scan } = await import("./agentshield/scanner.js");
+    const path = args.path ?? ".";
+    const report = scan(resolve(path), {
+        minSeverity: (args.severity ?? "info"),
+        scanners: args.scanner,
+    });
+    return {
+        files_scanned: report.filesScanned,
+        duration_ms: report.durationMs,
+        findings: report.findings.map((f) => ({
+            rule_id: f.rule.id,
+            severity: f.rule.severity,
+            title: f.rule.title,
+            owasp: f.rule.owasp,
+            file: f.location.file,
+            line: f.location.line,
+            snippet: f.location.snippet,
+        })),
+    };
+}
+async function toolListRules() {
+    const { loadRules } = await import("./agentshield/rules-loader.js");
+    const rules = loadRules();
+    return {
+        count: rules.length,
+        rules: rules.map((r) => ({
+            id: r.id,
+            severity: r.severity,
+            scanner: r.scanner,
+            title: r.title,
+            owasp: r.owasp ?? null,
+        })),
+    };
+}
+async function toolDetectArchetype(args) {
+    const { detect } = await import("./detect.js");
+    const { pickArchetype, suggestCompliance } = await import("./archetypes.js");
+    const cwd = resolve(args.path ?? ".");
+    const detected = await detect(cwd);
+    const result = pickArchetype(detected);
+    const compliance = suggestCompliance(detected, result.primary);
+    return {
+        archetype: result.primary,
+        confidence: result.confidence,
+        rationale: result.rationale,
+        alternatives: result.alternatives,
+        compliance,
+    };
+}
+async function toolEstimateCost(args) {
+    // Rough heuristic — for production, agents call /cost feature directly.
+    // This is the LLM-host-friendly summary.
+    const scale = args.scale ?? "standard";
+    const minutesByScale = {
+        quick: 15,
+        standard: 45,
+        deep: 90,
+    };
+    const llmRatePerHr = 0.02;
+    const humanRatePerHr = 150;
+    const minutes = minutesByScale[scale] ?? 45;
+    const llmUsd = +(minutes / 60 * llmRatePerHr).toFixed(4);
+    const humanUsd = +(minutes / 60 * humanRatePerHr).toFixed(2);
+    const humanDays = +(minutes / 60 / 6).toFixed(1); // 6 productive hrs / day
+    return {
+        task: args.task_description ?? "",
+        archetype: args.archetype ?? "unknown",
+        scale,
+        llm_agent: { wall_clock_min: minutes, cost_usd: llmUsd },
+        human_team: { working_days: humanDays, cost_usd: humanUsd },
+        savings_x: Math.round(humanUsd / Math.max(llmUsd, 0.0001)),
+    };
+}
+function toolQueryDecisions(args) {
+    const decisionsPath = join(homedir(), ".great_cto", "decisions.md");
+    if (!existsSync(decisionsPath)) {
+        return { count: 0, results: [], note: "No ~/.great_cto/decisions.md found." };
+    }
+    const text = readFileSync(decisionsPath, "utf8");
+    const entries = text.split(/\n---\n/).filter(s => s.trim());
+    const q = (args.query ?? "").toLowerCase();
+    const limit = args.limit ?? 10;
+    const matches = q
+        ? entries.filter(e => e.toLowerCase().includes(q))
+        : entries.slice(-limit);
+    return {
+        count: matches.length,
+        total_decisions: entries.length,
+        results: matches.slice(0, limit).map(e => {
+            const titleMatch = e.match(/^##\s+(.+)$/m);
+            return {
+                title: titleMatch?.[1] ?? "(untitled)",
+                excerpt: e.slice(0, 400),
+            };
+        }),
+    };
+}
+// ── Tool dispatch table ────────────────────────────────────────────────────
+const TOOLS = [
+    {
+        name: "scan",
+        description: "Scan code for AI/LLM-specific security issues (OWASP LLM Top 10, 24 rules). Returns findings with severity, file, line, OWASP mapping.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "File or directory to scan (default: cwd)" },
+                severity: {
+                    type: "string",
+                    enum: ["info", "low", "medium", "high", "critical"],
+                    description: "Minimum severity to report",
+                },
+                scanner: {
+                    type: "array",
+                    items: {
+                        type: "string",
+                        enum: ["prompt-injection", "secrets-in-prompts", "ssrf-in-tools", "rag-poisoning", "cost-runaway"],
+                    },
+                    description: "Limit to specific scanner categories",
+                },
+            },
+        },
+        handler: toolScan,
+    },
+    {
+        name: "list_rules",
+        description: "List all 24 AgentShield security rules with severity and OWASP LLM Top 10 mapping.",
+        inputSchema: { type: "object", properties: {} },
+        handler: toolListRules,
+    },
+    {
+        name: "detect_archetype",
+        description: "Detect the project archetype (one of 25: fintech, healthcare, commerce, agent-product, mlops, edtech, gov-public, insurance, ...) and the compliance gates that apply.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Project root (default: cwd)" },
+            },
+        },
+        handler: toolDetectArchetype,
+    },
+    {
+        name: "estimate_cost",
+        description: "Estimate LLM-agent wall-clock time and cost vs human-team equivalent for a task. Returns LLM/human cost and savings ratio (~7500×).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                task_description: { type: "string" },
+                archetype: { type: "string" },
+                scale: { type: "string", enum: ["quick", "standard", "deep"] },
+            },
+        },
+        handler: toolEstimateCost,
+    },
+    {
+        name: "query_decisions",
+        description: "Search the cross-project ADR log at ~/.great_cto/decisions.md. Returns matching decisions for the given query string.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Search string (case-insensitive). Empty = recent decisions." },
+                limit: { type: "number", description: "Max results (default 10)" },
+            },
+        },
+        handler: toolQueryDecisions,
+    },
+];
+// ── JSON-RPC handler ───────────────────────────────────────────────────────
+async function handle(req) {
+    const { method, id = null, params } = req;
+    // Notifications (no id) get no response
+    const isNotification = id === null || id === undefined;
+    const reply = (result) => isNotification ? null : { jsonrpc: "2.0", id: id, result };
+    const fail = (code, message, data) => isNotification ? null : { jsonrpc: "2.0", id: id, error: { code, message, data } };
+    try {
+        switch (method) {
+            case "initialize":
+                return reply({
+                    protocolVersion: PROTOCOL_VERSION,
+                    capabilities: { tools: {} },
+                    serverInfo: SERVER_INFO,
+                });
+            case "initialized":
+            case "notifications/initialized":
+                return null;
+            case "tools/list":
+                return reply({
+                    tools: TOOLS.map(t => ({
+                        name: t.name,
+                        description: t.description,
+                        inputSchema: t.inputSchema,
+                    })),
+                });
+            case "tools/call": {
+                const name = params?.name;
+                const args = params?.arguments ?? {};
+                const tool = TOOLS.find(t => t.name === name);
+                if (!tool)
+                    return fail(-32601, `Unknown tool: ${name}`);
+                const result = await tool.handler(args);
+                return reply({
+                    content: [
+                        { type: "text", text: JSON.stringify(result, null, 2) },
+                    ],
+                    isError: false,
+                });
+            }
+            case "ping":
+                return reply({});
+            default:
+                return fail(-32601, `Method not found: ${method}`);
+        }
+    }
+    catch (e) {
+        return fail(-32603, `Internal error: ${e.message}`);
+    }
+}
+// ── stdio transport ────────────────────────────────────────────────────────
+async function runStdio() {
+    // Read newline-delimited JSON from stdin, write to stdout. This is the
+    // standard MCP stdio transport.
+    let buffer = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", async (chunk) => {
+        buffer += chunk;
+        let nl;
+        while ((nl = buffer.indexOf("\n")) >= 0) {
+            const line = buffer.slice(0, nl).trim();
+            buffer = buffer.slice(nl + 1);
+            if (!line)
+                continue;
+            try {
+                const req = JSON.parse(line);
+                const res = await handle(req);
+                if (res)
+                    process.stdout.write(JSON.stringify(res) + "\n");
+            }
+            catch (e) {
+                process.stderr.write(`mcp: parse error: ${e.message}\n`);
+            }
+        }
+    });
+    return new Promise(resolve => {
+        process.stdin.on("end", () => resolve(0));
+        process.stdin.on("error", () => resolve(2));
+    });
+}
+export async function runMcp(args) {
+    SERVER_INFO.version = args.version;
+    if (args.mode === "sse") {
+        process.stderr.write("great-cto mcp: SSE mode not yet implemented (use --stdio)\n");
+        return 2;
+    }
+    // Notify clients we're ready (some hosts log this)
+    process.stderr.write(`great-cto mcp v${args.version} (stdio) — ${TOOLS.length} tools\n`);
+    return runStdio();
+}

package/dist/serve.js

@@ -0,0 +1,158 @@
+// great-cto serve — webhook receiver + outbound notifier (scaffolding).
+//
+// v2.4.0 ships scaffolding + a single working endpoint (POST /webhook/github
+// → run scan, log event). Signature verification, retry/DLQ, and outbound
+// integrations land in v2.5.0.
+//
+// Usage:
+//   great-cto serve [--port 3142] [--no-log]
+//
+// Endpoints:
+//   POST /webhook/github    GitHub event receiver (pull_request.opened →
+//                           runs scan on PR head, persists summary)
+//   POST /webhook/generic   Catch-all for ad-hoc integrations. Body persisted
+//                           to ~/.great_cto/webhook-events.log (JSONL).
+//   GET  /healthz           Liveness probe
+//   GET  /events            Recent event log (last 50)
+//
+// All events are appended to ~/.great_cto/webhook-events.log as JSONL with
+// fields: ts, source, event_type, payload_summary, action_taken.
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { homedir } from "node:os";
+import { join } from "node:path";
+const EVENTS_LOG = join(homedir(), ".great_cto", "webhook-events.log");
+function logEvent(ev, noLog) {
+    if (noLog)
+        return;
+    try {
+        const dir = join(homedir(), ".great_cto");
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        appendFileSync(EVENTS_LOG, JSON.stringify(ev) + "\n");
+    }
+    catch (e) {
+        process.stderr.write(`serve: failed to log event: ${e.message}\n`);
+    }
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        let data = "";
+        req.on("data", chunk => (data += chunk));
+        req.on("end", () => resolve(data));
+        req.on("error", reject);
+    });
+}
+function json(res, status, body) {
+    res.writeHead(status, { "Content-Type": "application/json" });
+    res.end(JSON.stringify(body));
+}
+// ── Endpoint handlers ──────────────────────────────────────────────────────
+async function handleGitHub(req, res, args) {
+    const body = await readBody(req);
+    const eventType = req.headers["x-github-event"] ?? "unknown";
+    const deliveryId = req.headers["x-github-delivery"] ?? "no-id";
+    let payload;
+    try {
+        payload = JSON.parse(body);
+    }
+    catch {
+        json(res, 400, { error: "invalid JSON" });
+        return;
+    }
+    // Currently we just record the event. Scan-on-PR lands in v2.5.0 with
+    // proper signature verification and clone-and-scan flow.
+    const summary = eventType === "pull_request"
+        ? `${payload.action ?? "?"} PR #${payload.number ?? "?"} in ${payload.repository?.full_name ?? "?"}`
+        : `${eventType} delivery=${deliveryId}`;
+    const ev = {
+        ts: new Date().toISOString(),
+        source: "github",
+        event_type: eventType,
+        summary,
+        action_taken: "logged",
+        meta: { delivery_id: deliveryId, pr_number: payload.number, action: payload.action },
+    };
+    logEvent(ev, args.noLog);
+    json(res, 200, { ok: true, event_type: eventType, recorded: true });
+}
+async function handleGeneric(req, res, args) {
+    const body = await readBody(req);
+    let payload = body;
+    try {
+        payload = JSON.parse(body);
+    }
+    catch {
+        /* keep as raw string */
+    }
+    const ev = {
+        ts: new Date().toISOString(),
+        source: "generic",
+        event_type: "incoming",
+        summary: `payload ${body.length} bytes`,
+        action_taken: "logged",
+        meta: { payload_preview: String(body).slice(0, 200) },
+    };
+    logEvent(ev, args.noLog);
+    json(res, 200, { ok: true, recorded: true });
+}
+function handleEvents(_req, res) {
+    if (!existsSync(EVENTS_LOG)) {
+        json(res, 200, { events: [] });
+        return;
+    }
+    const lines = readFileSync(EVENTS_LOG, "utf8")
+        .split("\n")
+        .filter(Boolean)
+        .slice(-50);
+    const events = lines
+        .map(l => {
+        try {
+            return JSON.parse(l);
+        }
+        catch {
+            return null;
+        }
+    })
+        .filter(Boolean);
+    json(res, 200, { events });
+}
+// ── Main entry ─────────────────────────────────────────────────────────────
+export async function runServe(args) {
+    const server = createServer(async (req, res) => {
+        const url = new URL(req.url ?? "/", `http://localhost:${args.port}`);
+        const path = url.pathname;
+        // Healthz
+        if (req.method === "GET" && path === "/healthz") {
+            return json(res, 200, { ok: true, service: "great-cto serve", events_log: EVENTS_LOG });
+        }
+        if (req.method === "GET" && path === "/events") {
+            return handleEvents(req, res);
+        }
+        if (req.method === "POST" && path === "/webhook/github") {
+            return handleGitHub(req, res, args);
+        }
+        if (req.method === "POST" && path === "/webhook/generic") {
+            return handleGeneric(req, res, args);
+        }
+        json(res, 404, { error: "not found", path });
+    });
+    return new Promise(resolve => {
+        server.listen(args.port, "127.0.0.1", () => {
+            console.error(`great-cto serve → http://localhost:${args.port}`);
+            console.error(`  POST /webhook/github    GitHub event receiver`);
+            console.error(`  POST /webhook/generic   Catch-all`);
+            console.error(`  GET  /events            Recent event log`);
+            console.error(`  GET  /healthz           Liveness probe`);
+            console.error(`  log: ${EVENTS_LOG}`);
+        });
+        process.on("SIGINT", () => {
+            server.close();
+            resolve(0);
+        });
+        process.on("SIGTERM", () => {
+            server.close();
+            resolve(0);
+        });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "great-cto",
-  "version": "2.3.4",
+  "version": "2.4.0",
   "description": "One command install for the great_cto Claude Code plugin. Auto-detects your stack, picks the right archetype, bootstraps PROJECT.md.",
   "keywords": [
     "claude-code",