great-cto 1.0.167 → 1.0.169

package/dist/bootstrap.js

@@ -59,6 +59,18 @@ compliance: [${complianceLine}]
 > \`compliance:\` list drives which checklists security-officer runs.
 > See ARCHETYPES.md "Parameter Values" for supported keys.
 
+## Memory & Query Rule
+
+> Before reading source files, agents should query memory layers in this order:
+> 1. **\`.great_cto/lessons.md\`** — project-specific lessons learned
+> 2. **\`~/.great_cto/decisions.md\`** — global decisions log (ADR-style, all projects)
+> 3. **\`~/.great_cto/verdicts/\`** — past agent verdicts (APPROVED/BLOCKED with rationale)
+> 4. Only then read source files for the actual implementation
+>
+> This prevents re-deriving solved problems and surfaces "we decided this last
+> sprint" insights. Agents update these layers via gate approvals (auto) and
+> by appending to \`lessons.md\` after retrospectives.
+
 ## Goals
 
 - <add your primary goal here>

package/dist/llm-fallback.js

@@ -0,0 +1,178 @@
+// LLM fallback for low-confidence archetype detection.
+//
+// When pickArchetype() returns confidence: "low", we optionally call
+// Anthropic Haiku with the README (first ~2KB) + dependency list and
+// ask for a structured archetype suggestion. Cost: ~$0.001 per call.
+//
+// Privacy:
+//   - Only sends: README first 2KB + dep names (no versions) + stack list.
+//   - Never sends: source code, paths, file names, env vars, repo name.
+//   - User opts in via:
+//       1. ANTHROPIC_API_KEY env var present (implicit), OR
+//       2. --use-llm CLI flag (explicit override even on high confidence)
+//   - Skipped when --no-llm flag, GREATCTO_NO_LLM=1, or no API key.
+//
+// Zero deps: uses native fetch (Node 18+). No @anthropic-ai/sdk import.
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const ANTHROPIC_API = "https://api.anthropic.com/v1/messages";
+const MODEL = "claude-haiku-4-5"; // cheap + fast; ~$1/M in, $5/M out
+const MAX_README_BYTES = 2048;
+const TIMEOUT_MS = 8000;
+const ALLOWED_ARCHETYPES = [
+    "web-service", "mobile-app", "ai-system", "agent-product",
+    "data-platform", "infra", "library", "cli-tool",
+    "commerce", "fintech", "healthcare", "web3",
+    "iot-embedded", "regulated", "devtools", "browser-extension", "game",
+];
+/**
+ * Whether LLM fallback is available and should be tried for this run.
+ * Returns false silently if no API key, opted out, or running offline.
+ */
+export function shouldUseLlmFallback(opts) {
+    if (opts.forceSkip)
+        return { use: false, reason: "--no-llm flag set" };
+    if (process.env.GREATCTO_NO_LLM === "1")
+        return { use: false, reason: "GREATCTO_NO_LLM=1" };
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey)
+        return { use: false, reason: "no ANTHROPIC_API_KEY" };
+    if (opts.forceUse)
+        return { use: true, reason: "--use-llm flag" };
+    if (opts.heuristicConfidence === "low")
+        return { use: true, reason: "low heuristic confidence" };
+    return { use: false, reason: "heuristic confidence is high/medium" };
+}
+/**
+ * Build the prompt sent to the LLM. Kept as a pure function for testing.
+ */
+export function buildPrompt(opts) {
+    const archList = ALLOWED_ARCHETYPES.join(" | ");
+    const readme = opts.readme.slice(0, MAX_README_BYTES).trim() || "(no README)";
+    const stack = opts.stack.length ? opts.stack.join(", ") : "(no detected stack)";
+    const hints = opts.readmeKeywords.length ? opts.readmeKeywords.join(", ") : "(none)";
+    return `You are classifying a software project into one of these archetypes:
+${archList}
+
+DETECTED STACK: ${stack}
+README KEYWORDS: ${hints}
+
+README EXCERPT (first 2KB):
+"""
+${readme}
+"""
+
+Respond with ONLY a JSON object matching this schema (no prose, no markdown):
+{
+  "archetype": "<one value from the list above>",
+  "confidence": "<high|medium|low>",
+  "rationale": "<one sentence, ≤120 chars, explaining the choice>"
+}
+
+Rules:
+- Choose the most specific archetype. fintech beats commerce when banking/ACH is present.
+- agent-product = autonomous LLM agents (LangGraph/CrewAI/MCP), not just a wrapper around an LLM API.
+- ai-system = an app that calls an LLM but is not itself agentic.
+- cli-tool = primary distribution is a command-line binary.
+- library = published as a reusable package, no app shell.
+- If unsure between two, pick the more domain-specific one and use confidence: medium.`;
+}
+/**
+ * Validate the model response and coerce to LlmSuggestion shape.
+ * Returns null if the response is malformed or the archetype is invalid.
+ */
+export function parseLlmResponse(raw) {
+    // Strip code fences if model added them despite instructions
+    const cleaned = raw.trim()
+        .replace(/^```(?:json)?\s*/i, "")
+        .replace(/```\s*$/i, "")
+        .trim();
+    let obj;
+    try {
+        obj = JSON.parse(cleaned);
+    }
+    catch {
+        return null;
+    }
+    if (typeof obj !== "object" || obj === null)
+        return null;
+    const o = obj;
+    const arch = o.archetype;
+    const conf = o.confidence;
+    const rat = o.rationale;
+    if (typeof arch !== "string" || typeof conf !== "string" || typeof rat !== "string")
+        return null;
+    if (!ALLOWED_ARCHETYPES.includes(arch))
+        return null;
+    if (!["high", "medium", "low"].includes(conf))
+        return null;
+    return {
+        archetype: arch,
+        confidence: conf,
+        rationale: rat.slice(0, 200),
+    };
+}
+function readReadme(dir) {
+    const candidates = ["README.md", "readme.md", "README", "README.rst"];
+    for (const f of candidates) {
+        const p = join(dir, f);
+        if (existsSync(p)) {
+            try {
+                return readFileSync(p, "utf-8");
+            }
+            catch {
+                return "";
+            }
+        }
+    }
+    return "";
+}
+/**
+ * Best-effort LLM call. Returns null if anything fails (network, parse,
+ * timeout, rate limit). Never throws — caller is expected to fall back
+ * to the heuristic result silently.
+ */
+export async function suggestArchetypeFromLlm(opts) {
+    const readme = readReadme(opts.dir);
+    const prompt = buildPrompt({
+        readme,
+        stack: opts.detection.stack,
+        readmeKeywords: opts.detection.readmeKeywords,
+    });
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), TIMEOUT_MS);
+    try {
+        const res = await fetch(ANTHROPIC_API, {
+            method: "POST",
+            headers: {
+                "x-api-key": opts.apiKey,
+                "anthropic-version": "2023-06-01",
+                "content-type": "application/json",
+            },
+            body: JSON.stringify({
+                model: MODEL,
+                max_tokens: 256,
+                temperature: 0,
+                messages: [{ role: "user", content: prompt }],
+            }),
+            signal: ctrl.signal,
+        });
+        clearTimeout(timer);
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        const text = body.content?.find((c) => c.type === "text")?.text;
+        if (!text)
+            return null;
+        const parsed = parseLlmResponse(text);
+        if (!parsed)
+            return null;
+        return {
+            ...parsed,
+            conflictsWithHeuristic: parsed.archetype !== opts.heuristicArchetype,
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/main.js

@@ -17,6 +17,7 @@ import { install, findInstalledVersions } from "./installer.js";
 import { enableGreatCto } from "./settings.js";
 import { bootstrap } from "./bootstrap.js";
 import { resolveTelemetryConsent, sendInstallPing } from "./telemetry.js";
+import { shouldUseLlmFallback, suggestArchetypeFromLlm } from "./llm-fallback.js";
 import { readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -44,6 +45,8 @@ function parseArgs(argv) {
         archetype: null,
         version: null,
         noTelemetry: false,
+        useLlm: false,
+        noLlm: false,
     };
     const rest = [];
     for (let i = 0; i < argv.length; i++) {
@@ -68,6 +71,10 @@ function parseArgs(argv) {
             args.boardNoOpen = true;
         else if (a === "--no-telemetry")
             args.noTelemetry = true;
+        else if (a === "--use-llm")
+            args.useLlm = true;
+        else if (a === "--no-llm")
+            args.noLlm = true;
         else if (a === "board")
             args.command = "board";
         else if (a === "register")
@@ -191,11 +198,17 @@ ${bold("Options:")}
       --dry-run          Show what would be done without doing it
       --force            Reinstall even if already present
       --archetype NAME   Override detected archetype
-                         (${cyan("web-service|mobile-app|ai-system|agent-product|commerce|web3|")}
-                          ${cyan("data-platform|infra|library|iot-embedded|regulated|")}
-                          ${cyan("devtools|browser-extension|game")})
+                         (${cyan("web-service|mobile-app|ai-system|agent-product|commerce|fintech|")}
+                          ${cyan("healthcare|web3|data-platform|infra|library|cli-tool|")}
+                          ${cyan("iot-embedded|regulated|devtools|browser-extension|game")})
       --version-tag VER  Pin to specific great_cto version (default: latest)
       --dir PATH         Run against a different directory (default: cwd)
+      --use-llm          Force LLM (Anthropic Haiku) archetype suggestion
+                         even when heuristic confidence is high
+      --no-llm           Skip LLM suggestion (run heuristic only)
+                         Or set ${cyan("GREATCTO_NO_LLM=1")}
+      --no-telemetry     Skip anonymous install ping
+                         Or set ${cyan("GREATCTO_NO_TELEMETRY=1")}
   -h, --help             Show this help
   -v, --version          Show great-cto CLI version
 
@@ -254,6 +267,61 @@ async function runInit(args) {
         alternatives = pick.alternatives;
         confidence = pick.confidence;
     }
+    // ── 2b. LLM fallback for low-confidence detections (Wave 4) ──────
+    if (!args.archetype) {
+        const llmDecision = shouldUseLlmFallback({
+            heuristicConfidence: confidence,
+            forceUse: args.useLlm,
+            forceSkip: args.noLlm,
+        });
+        if (llmDecision.use) {
+            const apiKey = process.env.ANTHROPIC_API_KEY;
+            if (apiKey) {
+                log(`  ${dim("→ low confidence — asking Anthropic Haiku for second opinion...")}`);
+                const llm = await suggestArchetypeFromLlm({
+                    dir: args.dir,
+                    detection,
+                    heuristicArchetype: archetype,
+                    apiKey,
+                });
+                if (llm) {
+                    if (llm.conflictsWithHeuristic) {
+                        log("");
+                        log(`  ${bold("AI suggests:")} ${cyan(llm.archetype)} ${dim(`(${llm.confidence})`)}`);
+                        log(`  ${dim("AI rationale:")} ${llm.rationale}`);
+                        log(`  ${bold("Heuristic says:")} ${cyan(archetype)} ${dim(`(${confidence})`)}`);
+                        if (!args.yes) {
+                            const accept = await confirm(`Use AI suggestion ${cyan(llm.archetype)} instead of ${cyan(archetype)}?`, true);
+                            if (accept) {
+                                archetype = llm.archetype;
+                                rationale = `(AI) ${llm.rationale}`;
+                                confidence = llm.confidence;
+                                if (!alternatives.includes(archetype)) {
+                                    alternatives = [archetype, ...alternatives.filter((a) => a !== archetype)].slice(0, 3);
+                                }
+                            }
+                        }
+                        else {
+                            // --yes: silently take AI suggestion only if it bumps confidence
+                            if (llm.confidence !== "low") {
+                                archetype = llm.archetype;
+                                rationale = `(AI) ${llm.rationale}`;
+                                confidence = llm.confidence;
+                            }
+                        }
+                    }
+                    else if (llm.confidence !== "low") {
+                        // AI agrees → bump confidence, refine rationale
+                        confidence = llm.confidence;
+                        rationale = `${rationale} (AI confirmed: ${llm.rationale})`;
+                    }
+                }
+                else {
+                    log(`  ${dim("(LLM call failed, keeping heuristic)")}`);
+                }
+            }
+        }
+    }
     const compliance = suggestCompliance(detection, archetype);
     log(`  ${dim("archetype:")} ${cyan(archetype)} ${dim(`(confidence: ${confidence})`)}`);
     log(`  ${dim("rationale:")} ${rationale}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "great-cto",
-  "version": "1.0.167",
+  "version": "1.0.169",
   "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",