@mainahq/core 1.0.1 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mainahq/core",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "license": "Apache-2.0",
   "description": "Maina core engines — Context, Prompt, and Verify for verification-first development",

package/src/ai/__tests__/availability.test.ts

@@ -0,0 +1,131 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { checkAIAvailability } from "../availability";
+
+describe("checkAIAvailability", () => {
+	const originalEnv = { ...process.env };
+
+	beforeEach(() => {
+		// Clear all relevant env vars before each test
+		delete process.env.MAINA_API_KEY;
+		delete process.env.OPENROUTER_API_KEY;
+		delete process.env.ANTHROPIC_API_KEY;
+		delete process.env.MAINA_HOST_MODE;
+		delete process.env.CLAUDECODE;
+		delete process.env.CLAUDE_CODE_ENTRYPOINT;
+		delete process.env.CURSOR;
+	});
+
+	afterEach(() => {
+		// Restore original env
+		for (const key of [
+			"MAINA_API_KEY",
+			"OPENROUTER_API_KEY",
+			"ANTHROPIC_API_KEY",
+			"MAINA_HOST_MODE",
+			"CLAUDECODE",
+			"CLAUDE_CODE_ENTRYPOINT",
+			"CURSOR",
+		]) {
+			if (originalEnv[key] !== undefined) {
+				process.env[key] = originalEnv[key];
+			} else {
+				delete process.env[key];
+			}
+		}
+	});
+
+	it("returns api-key method when MAINA_API_KEY is set", () => {
+		process.env.MAINA_API_KEY = "test-key-123";
+
+		const result = checkAIAvailability();
+
+		expect(result.available).toBe(true);
+		expect(result.method).toBe("api-key");
+		expect(result.reason).toBeUndefined();
+	});
+
+	it("returns api-key method when OPENROUTER_API_KEY is set", () => {
+		process.env.OPENROUTER_API_KEY = "or-key-456";
+
+		const result = checkAIAvailability();
+
+		expect(result.available).toBe(true);
+		expect(result.method).toBe("api-key");
+		expect(result.reason).toBeUndefined();
+	});
+
+	it("returns api-key method when ANTHROPIC_API_KEY is set", () => {
+		process.env.ANTHROPIC_API_KEY = "sk-ant-test";
+
+		const result = checkAIAvailability();
+
+		expect(result.available).toBe(true);
+		expect(result.method).toBe("api-key");
+		expect(result.reason).toBeUndefined();
+	});
+
+	it("returns host-delegation when CLAUDECODE env is set", () => {
+		process.env.CLAUDECODE = "1";
+
+		const result = checkAIAvailability();
+
+		expect(result.available).toBe(true);
+		expect(result.method).toBe("host-delegation");
+		expect(result.reason).toBeUndefined();
+	});
+
+	it("returns host-delegation when CLAUDE_CODE_ENTRYPOINT is set", () => {
+		process.env.CLAUDE_CODE_ENTRYPOINT = "cli";
+
+		const result = checkAIAvailability();
+
+		expect(result.available).toBe(true);
+		expect(result.method).toBe("host-delegation");
+		expect(result.reason).toBeUndefined();
+	});
+
+	it("returns host-delegation when CURSOR is set", () => {
+		process.env.CURSOR = "1";
+
+		const result = checkAIAvailability();
+
+		expect(result.available).toBe(true);
+		expect(result.method).toBe("host-delegation");
+		expect(result.reason).toBeUndefined();
+	});
+
+	it("returns host-delegation when MAINA_HOST_MODE is true", () => {
+		process.env.MAINA_HOST_MODE = "true";
+
+		const result = checkAIAvailability();
+
+		expect(result.available).toBe(true);
+		expect(result.method).toBe("host-delegation");
+		expect(result.reason).toBeUndefined();
+	});
+
+	it("returns none when no key and no host environment", () => {
+		const result = checkAIAvailability();
+
+		expect(result.available).toBe(false);
+		expect(result.method).toBe("none");
+	});
+
+	it("includes a reason message when method is none", () => {
+		const result = checkAIAvailability();
+
+		expect(result.reason).toBeDefined();
+		expect(result.reason).toContain("No API key found");
+		expect(result.reason).toContain("maina init");
+	});
+
+	it("prefers api-key over host-delegation when both available", () => {
+		process.env.MAINA_API_KEY = "test-key";
+		process.env.CLAUDECODE = "1";
+
+		const result = checkAIAvailability();
+
+		expect(result.available).toBe(true);
+		expect(result.method).toBe("api-key");
+	});
+});

package/src/ai/availability.ts

@@ -0,0 +1,23 @@
+import { getApiKey, isHostMode } from "../config/index";
+
+export interface AIAvailability {
+	available: boolean;
+	method: "api-key" | "host-delegation" | "none";
+	reason?: string;
+}
+
+export function checkAIAvailability(): AIAvailability {
+	const apiKey = getApiKey();
+	if (apiKey !== null) {
+		return { available: true, method: "api-key" };
+	}
+	if (isHostMode()) {
+		return { available: true, method: "host-delegation" };
+	}
+	return {
+		available: false,
+		method: "none",
+		reason:
+			"No API key found and not running inside an AI agent. Run `maina init` to set up or run inside Claude Code/Cursor.",
+	};
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 export const VERSION = "0.1.0";
 
 // AI
+export { type AIAvailability, checkAIAvailability } from "./ai/availability";
 export { generateCommitMessage } from "./ai/commit-msg";
 // AI — Delegation
 export {
@@ -99,8 +100,9 @@ export {
 	setVerificationResult,
 	trackFile,
 } from "./context/working";
-// DB (Result type)
+// DB
 export type { Result } from "./db/index";
+export { getFeedbackDb } from "./db/index";
 // Design (ADR)
 export {
 	type AdrSummary,
@@ -211,6 +213,7 @@ export {
 // Init
 export {
 	bootstrap,
+	buildMainaSection,
 	type DetectedStack,
 	type InitOptions,
 	type InitReport,

package/src/init/__tests__/init.test.ts

@@ -131,29 +131,21 @@ describe("bootstrap", () => {
 		expect(existsSync(hooksDir)).toBe(true);
 	});
 
-	test("skips existing files (no overwrite)", async () => {
+	test("skips existing non-agent files (no overwrite)", async () => {
 		// Pre-create constitution.md with custom content
 		const mainaDir = join(tmpDir, ".maina");
 		mkdirSync(mainaDir, { recursive: true });
 		const constitutionPath = join(mainaDir, "constitution.md");
 		writeFileSync(constitutionPath, "# My Custom Constitution\n");
 
-		// Pre-create AGENTS.md with custom content
-		const agentsPath = join(tmpDir, "AGENTS.md");
-		writeFileSync(agentsPath, "# My Custom Agents\n");
-
 		const result = await bootstrap(tmpDir);
 		expect(result.ok).toBe(true);
 		if (result.ok) {
 			expect(result.value.skipped).toContain(".maina/constitution.md");
-			expect(result.value.skipped).toContain("AGENTS.md");
 
 			// Content should NOT have been overwritten
 			const content = readFileSync(constitutionPath, "utf-8");
 			expect(content).toBe("# My Custom Constitution\n");
-
-			const agentsContent = readFileSync(agentsPath, "utf-8");
-			expect(agentsContent).toBe("# My Custom Agents\n");
 		}
 	});
 
@@ -195,8 +187,11 @@ describe("bootstrap", () => {
 			expect(result.value.created).toContain(".maina/prompts/review.md");
 			expect(result.value.created).toContain(".maina/prompts/commit.md");
 
-			// Total files should add up
-			const total = result.value.created.length + result.value.skipped.length;
+			// Total files should add up (created + skipped + updated)
+			const total =
+				result.value.created.length +
+				result.value.skipped.length +
+				result.value.updated.length;
 			expect(total).toBeGreaterThanOrEqual(5);
 		}
 	});
@@ -351,22 +346,89 @@ describe("bootstrap", () => {
 		expect(content).toContain("maina verify");
 	});
 
-	test("does not overwrite existing agent files", async () => {
+	test("merges maina section into existing agent files without ## Maina", async () => {
 		writeFileSync(join(tmpDir, "CLAUDE.md"), "# My Custom CLAUDE.md\n");
 		writeFileSync(join(tmpDir, "GEMINI.md"), "# My Custom GEMINI.md\n");
 		writeFileSync(join(tmpDir, ".cursorrules"), "# My Custom Rules\n");
 
+		const result = await bootstrap(tmpDir);
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.updated).toContain("CLAUDE.md");
+			expect(result.value.updated).toContain("GEMINI.md");
+			expect(result.value.updated).toContain(".cursorrules");
+			expect(result.value.skipped).not.toContain("CLAUDE.md");
+			expect(result.value.skipped).not.toContain("GEMINI.md");
+			expect(result.value.skipped).not.toContain(".cursorrules");
+		}
+
+		const claudeContent = readFileSync(join(tmpDir, "CLAUDE.md"), "utf-8");
+		expect(claudeContent).toContain("# My Custom CLAUDE.md");
+		expect(claudeContent).toContain("## Maina");
+		expect(claudeContent).toContain("constitution.md");
+		expect(claudeContent).toContain("getContext");
+
+		const geminiContent = readFileSync(join(tmpDir, "GEMINI.md"), "utf-8");
+		expect(geminiContent).toContain("# My Custom GEMINI.md");
+		expect(geminiContent).toContain("## Maina");
+
+		const cursorContent = readFileSync(join(tmpDir, ".cursorrules"), "utf-8");
+		expect(cursorContent).toContain("# My Custom Rules");
+		expect(cursorContent).toContain("## Maina");
+	});
+
+	test("skips agent files that already have ## Maina section", async () => {
+		writeFileSync(
+			join(tmpDir, "CLAUDE.md"),
+			"# My CLAUDE.md\n\n## Maina\n\nAlready configured.\n",
+		);
+		writeFileSync(
+			join(tmpDir, "GEMINI.md"),
+			"# My GEMINI.md\n\n## Maina\n\nAlready configured.\n",
+		);
+
 		const result = await bootstrap(tmpDir);
 		expect(result.ok).toBe(true);
 		if (result.ok) {
 			expect(result.value.skipped).toContain("CLAUDE.md");
 			expect(result.value.skipped).toContain("GEMINI.md");
-			expect(result.value.skipped).toContain(".cursorrules");
+			expect(result.value.updated).not.toContain("CLAUDE.md");
+			expect(result.value.updated).not.toContain("GEMINI.md");
 		}
 
-		expect(readFileSync(join(tmpDir, "CLAUDE.md"), "utf-8")).toBe(
-			"# My Custom CLAUDE.md\n",
+		// Content should not be modified
+		const claudeContent = readFileSync(join(tmpDir, "CLAUDE.md"), "utf-8");
+		expect(claudeContent).toBe(
+			"# My CLAUDE.md\n\n## Maina\n\nAlready configured.\n",
+		);
+	});
+
+	test("merges AGENTS.md with maina section", async () => {
+		writeFileSync(
+			join(tmpDir, "AGENTS.md"),
+			"# My Agents File\n\nCustom content here.\n",
 		);
+
+		const result = await bootstrap(tmpDir);
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.updated).toContain("AGENTS.md");
+		}
+
+		const content = readFileSync(join(tmpDir, "AGENTS.md"), "utf-8");
+		expect(content).toContain("# My Agents File");
+		expect(content).toContain("Custom content here.");
+		expect(content).toContain("## Maina");
+		expect(content).toContain("brainstorm");
+		expect(content).toContain("MCP Tools");
+	});
+
+	test("updated array is empty for fresh directory", async () => {
+		const result = await bootstrap(tmpDir);
+		expect(result.ok).toBe(true);
+		if (result.ok) {
+			expect(result.value.updated).toEqual([]);
+		}
 	});
 
 	// ── Workflow order in agent files ─────────────────────────────────────

package/src/init/index.ts

@@ -28,6 +28,7 @@ export interface InitOptions {
 export interface InitReport {
 	created: string[];
 	skipped: string[];
+	updated: string[];
 	directory: string;
 	detectedStack: DetectedStack;
 	detectedTools: DetectedTool[];
@@ -41,6 +42,14 @@ export interface DetectedStack {
 	testRunner: string;
 	linter: string;
 	framework: string;
+	/** package.json scripts (e.g. { test: "vitest", build: "tsc" }) */
+	scripts: Record<string, string>;
+	/** Build tool detected (e.g. "vite", "webpack", "tsup", "bunup", "esbuild") */
+	buildTool: string;
+	/** Whether this is a monorepo (workspaces detected) */
+	monorepo: boolean;
+	/** Inferred conventions from project context */
+	conventions: string[];
 }
 
 // ── Project Detection ───────────────────────────────────────────────────────
@@ -53,6 +62,10 @@ function detectStack(repoRoot: string): DetectedStack {
 		testRunner: "unknown",
 		linter: "unknown",
 		framework: "none",
+		scripts: {},
+		buildTool: "unknown",
+		monorepo: false,
+		conventions: [],
 	};
 
 	// ── Multi-language detection (file-marker based) ─────────────────────
@@ -118,6 +131,16 @@ function detectStack(repoRoot: string): DetectedStack {
 				...(pkg.devDependencies as Record<string, string> | undefined),
 				...(pkg.peerDependencies as Record<string, string> | undefined),
 			};
+
+			// Extract scripts
+			if (pkg.scripts && typeof pkg.scripts === "object") {
+				stack.scripts = pkg.scripts as Record<string, string>;
+			}
+
+			// Detect monorepo (workspaces)
+			if (pkg.workspaces) {
+				stack.monorepo = true;
+			}
 		} catch {
 			// Malformed package.json — skip
 		}
@@ -187,8 +210,108 @@ function detectStack(repoRoot: string): DetectedStack {
 		} else if (allDeps.svelte) {
 			stack.framework = "svelte";
 		}
+
+		// Build tool detection
+		if (allDeps.bunup) {
+			stack.buildTool = "bunup";
+		} else if (allDeps.tsup) {
+			stack.buildTool = "tsup";
+		} else if (allDeps.vite) {
+			stack.buildTool = "vite";
+		} else if (allDeps.webpack) {
+			stack.buildTool = "webpack";
+		} else if (allDeps.esbuild) {
+			stack.buildTool = "esbuild";
+		} else if (allDeps.rollup) {
+			stack.buildTool = "rollup";
+		} else if (allDeps.turbo) {
+			stack.buildTool = "turborepo";
+		}
+
+		// Also check for monorepo tools
+		if (
+			allDeps.turbo ||
+			allDeps.nx ||
+			allDeps.lerna ||
+			existsSync(join(repoRoot, "pnpm-workspace.yaml"))
+		) {
+			stack.monorepo = true;
+		}
+	}
+
+	// ── Infer conventions from project context ───────────────────────────
+	const conventions: string[] = [];
+
+	// Check for conventional commits
+	if (
+		existsSync(join(repoRoot, "commitlint.config.js")) ||
+		existsSync(join(repoRoot, "commitlint.config.ts")) ||
+		existsSync(join(repoRoot, ".commitlintrc.json")) ||
+		existsSync(join(repoRoot, ".commitlintrc.yml"))
+	) {
+		conventions.push("Conventional commits enforced via commitlint");
+	}
+
+	// Check for git hooks
+	if (existsSync(join(repoRoot, "lefthook.yml"))) {
+		conventions.push("Git hooks via lefthook");
+	} else if (existsSync(join(repoRoot, ".husky"))) {
+		conventions.push("Git hooks via husky");
+	}
+
+	// Check for strict TypeScript
+	if (existsSync(join(repoRoot, "tsconfig.json"))) {
+		try {
+			const tsconfig = readFileSync(join(repoRoot, "tsconfig.json"), "utf-8");
+			if (tsconfig.includes('"strict"') && tsconfig.includes("true")) {
+				conventions.push("TypeScript strict mode enabled");
+			}
+		} catch {
+			// ignore
+		}
 	}
 
+	// Check for Docker
+	if (
+		existsSync(join(repoRoot, "Dockerfile")) ||
+		existsSync(join(repoRoot, "docker-compose.yml")) ||
+		existsSync(join(repoRoot, "docker-compose.yaml"))
+	) {
+		conventions.push("Docker containerization");
+	}
+
+	// Check for CI
+	if (existsSync(join(repoRoot, ".github/workflows"))) {
+		conventions.push("GitHub Actions CI/CD");
+	} else if (existsSync(join(repoRoot, ".gitlab-ci.yml"))) {
+		conventions.push("GitLab CI/CD");
+	} else if (existsSync(join(repoRoot, ".circleci"))) {
+		conventions.push("CircleCI");
+	}
+
+	// Check for env management
+	if (existsSync(join(repoRoot, ".env.example"))) {
+		conventions.push("Environment variables documented in .env.example");
+	}
+
+	// Infer from package.json scripts
+	if (stack.scripts.lint || stack.scripts["lint:fix"]) {
+		conventions.push(
+			`Lint command: \`${stack.runtime === "bun" ? "bun" : "npm"} run lint\``,
+		);
+	}
+	if (stack.scripts.test) {
+		conventions.push(`Test command: \`${stack.scripts.test}\``);
+	}
+	if (stack.scripts.build) {
+		conventions.push(`Build command: \`${stack.scripts.build}\``);
+	}
+	if (stack.scripts.typecheck || stack.scripts["type-check"]) {
+		conventions.push("Type checking enforced");
+	}
+
+	stack.conventions = conventions;
+
 	// If no languages detected, mark as unknown
 	stack.languages = languages.length > 0 ? languages : ["unknown"];
 
@@ -237,6 +360,53 @@ function buildConstitution(stack: DetectedStack): string {
 	const frameworkLine =
 		stack.framework !== "none" ? `- Framework: ${stack.framework}\n` : "";
 
+	const buildLine =
+		stack.buildTool !== "unknown" ? `- Build: ${stack.buildTool}\n` : "";
+
+	const monorepoLine = stack.monorepo ? "- Monorepo: yes (workspaces)\n" : "";
+
+	// Build architecture section from context
+	const archLines: string[] = [];
+	if (stack.monorepo) {
+		archLines.push("- Monorepo with shared packages");
+	}
+	if (stack.framework !== "none") {
+		archLines.push(`- ${stack.framework} application`);
+	}
+	if (stack.languages.length > 1) {
+		archLines.push(`- Multi-language: ${stack.languages.join(", ")}`);
+	}
+	const archSection =
+		archLines.length > 0
+			? archLines.join("\n")
+			: "- [NEEDS CLARIFICATION] Define architectural constraints.";
+
+	// Build verification section from scripts
+	const verifyLines: string[] = [];
+	const runCmd = stack.runtime === "bun" ? "bun" : "npm";
+	if (stack.scripts.lint || stack.linter !== "unknown") {
+		verifyLines.push(
+			`- Lint: \`${stack.scripts.lint ?? `${runCmd} run lint`}\``,
+		);
+	}
+	if (stack.language === "typescript") {
+		verifyLines.push(
+			`- Typecheck: \`${stack.scripts.typecheck ?? stack.scripts["type-check"] ?? `${runCmd} run typecheck`}\``,
+		);
+	}
+	if (stack.scripts.test) {
+		verifyLines.push(`- Test: \`${stack.scripts.test}\``);
+	} else if (stack.testRunner !== "unknown") {
+		verifyLines.push(`- Test: \`${runCmd} test\``);
+	}
+	verifyLines.push("- Diff-only: only report findings on changed lines");
+
+	// Build conventions section from detected conventions
+	const conventionLines =
+		stack.conventions.length > 0
+			? stack.conventions.map((c) => `- ${c}`).join("\n")
+			: "- [NEEDS CLARIFICATION] Add project-specific conventions.";
+
 	return `# Project Constitution
 
 Non-negotiable rules. Injected into every AI call.
@@ -246,16 +416,15 @@ ${runtimeLine}
 ${langLine}
 ${lintLine}
 ${testLine}
-${frameworkLine}
+${frameworkLine}${buildLine}${monorepoLine}
 ## Architecture
-- [NEEDS CLARIFICATION] Define architectural constraints.
+${archSection}
 
 ## Verification
-- All commits pass: lint + typecheck + test
-- Diff-only: only report findings on changed lines
+${verifyLines.join("\n")}
 
 ## Conventions
-- [NEEDS CLARIFICATION] Add project-specific conventions.
+${conventionLines}
 `;
 }
 
@@ -351,6 +520,35 @@ Issues labeled \`audit\` come from maina's daily verification. Fix the specific
 `;
 }
 
+// ── Maina Section (for merging into existing agent files) ──────────────────
+
+/** Agent file names that support maina section merging */
+const MERGEABLE_AGENT_FILES = [
+	"AGENTS.md",
+	"CLAUDE.md",
+	"GEMINI.md",
+	".cursorrules",
+	".github/copilot-instructions.md",
+];
+
+/**
+ * Build a standalone "## Maina" section that can be appended to an existing
+ * agent file. Contains essential maina workflow + MCP tools info.
+ */
+export function buildMainaSection(_stack: DetectedStack): string {
+	return `## Maina
+
+This repo uses [Maina](https://mainahq.com) for verification-first development.
+Read \`.maina/constitution.md\` for project DNA.
+
+### Workflow
+\`${WORKFLOW_ORDER}\`
+
+### MCP Tools
+${MCP_TOOLS_TABLE}
+`;
+}
+
 // ── .mcp.json ───────────────────────────────────────────────────────────────
 
 function buildMcpJson(): string {
@@ -742,6 +940,7 @@ export async function bootstrap(
 	const mainaDir = join(repoRoot, ".maina");
 	const created: string[] = [];
 	const skipped: string[] = [];
+	const updated: string[] = [];
 
 	try {
 		// Detect project stack from package.json
@@ -782,7 +981,25 @@ export async function bootstrap(
 			mkdirSync(dirPath, { recursive: true });
 
 			if (existsSync(fullPath) && !force) {
-				skipped.push(entry.relativePath);
+				// Try to merge maina section for agent files
+				if (
+					MERGEABLE_AGENT_FILES.some((af) => entry.relativePath.endsWith(af))
+				) {
+					const existing = readFileSync(fullPath, "utf-8");
+					if (!existing.includes("## Maina")) {
+						const mainaSection = buildMainaSection(detectedStack);
+						writeFileSync(
+							fullPath,
+							`${existing.trimEnd()}\n\n${mainaSection}`,
+							"utf-8",
+						);
+						updated.push(entry.relativePath);
+					} else {
+						skipped.push(entry.relativePath);
+					}
+				} else {
+					skipped.push(entry.relativePath);
+				}
 			} else {
 				writeFileSync(fullPath, entry.content, "utf-8");
 				created.push(entry.relativePath);
@@ -805,6 +1022,7 @@ export async function bootstrap(
 			value: {
 				created,
 				skipped,
+				updated,
 				directory: mainaDir,
 				detectedStack,
 				detectedTools: detectedToolsList,

package/src/verify/__tests__/builtin.test.ts

@@ -0,0 +1,270 @@
+/**
+ * Tests for built-in verify checks.
+ *
+ * Each check is a pure function: (filePath, content) => Finding[].
+ * No I/O, no side effects — just string analysis.
+ */
+
+import { describe, expect, it } from "bun:test";
+import {
+	checkAnyType,
+	checkConsoleLogs,
+	checkEmptyCatch,
+	checkFileSize,
+	checkSecrets,
+	checkTodoComments,
+	checkUnusedImports,
+	runBuiltinChecks,
+} from "../builtin";
+
+// ─── checkConsoleLogs ────────────────────────────────────────────────────
+
+describe("checkConsoleLogs", () => {
+	it("detects console.log in a .ts file", () => {
+		const content = `const x = 1;\nconsole.log(x);\nconst y = 2;\n`;
+		const findings = checkConsoleLogs("src/app.ts", content);
+		expect(findings).toHaveLength(1);
+		expect(findings[0]?.line).toBe(2);
+		expect(findings[0]?.severity).toBe("warning");
+		expect(findings[0]?.ruleId).toBe("no-console-log");
+		expect(findings[0]?.tool).toBe("builtin");
+		expect(findings[0]?.file).toBe("src/app.ts");
+	});
+
+	it("skips .test.ts files", () => {
+		const content = `console.log("debug");\n`;
+		const findings = checkConsoleLogs("src/app.test.ts", content);
+		expect(findings).toHaveLength(0);
+	});
+
+	it("skips .spec.ts files", () => {
+		const content = `console.log("debug");\n`;
+		const findings = checkConsoleLogs("src/app.spec.ts", content);
+		expect(findings).toHaveLength(0);
+	});
+
+	it("skips files in __tests__ directories", () => {
+		const content = `console.log("debug");\n`;
+		const findings = checkConsoleLogs("src/__tests__/app.ts", content);
+		expect(findings).toHaveLength(0);
+	});
+
+	it("detects console.warn and console.error too", () => {
+		const content = `console.warn("w");\nconsole.error("e");\n`;
+		const findings = checkConsoleLogs("src/app.ts", content);
+		expect(findings).toHaveLength(2);
+	});
+
+	it("returns empty for clean files", () => {
+		const content = `const x = 1;\nconst y = 2;\n`;
+		const findings = checkConsoleLogs("src/app.ts", content);
+		expect(findings).toHaveLength(0);
+	});
+});
+
+// ─── checkTodoComments ───────────────────────────────────────────────────
+
+describe("checkTodoComments", () => {
+	it("detects TODO with correct line numbers", () => {
+		const content = `const x = 1;\n// TODO: fix this\nconst y = 2;\n// FIXME: broken\n`;
+		const findings = checkTodoComments("src/app.ts", content);
+		expect(findings).toHaveLength(2);
+		expect(findings[0]?.line).toBe(2);
+		expect(findings[0]?.message).toContain("TODO");
+		expect(findings[1]?.line).toBe(4);
+		expect(findings[1]?.message).toContain("FIXME");
+	});
+
+	it("detects HACK comments", () => {
+		const content = `// HACK: temporary workaround\n`;
+		const findings = checkTodoComments("src/app.ts", content);
+		expect(findings).toHaveLength(1);
+		expect(findings[0]?.ruleId).toBe("todo-comment");
+	});
+
+	it("returns empty when no markers present", () => {
+		const content = `const x = 1;\n// This is a normal comment\n`;
+		const findings = checkTodoComments("src/app.ts", content);
+		expect(findings).toHaveLength(0);
+	});
+});
+
+// ─── checkFileSize ───────────────────────────────────────────────────────
+
+describe("checkFileSize", () => {
+	it("flags files over 500 lines", () => {
+		const lines = Array.from({ length: 501 }, (_, i) => `const x${i} = ${i};`);
+		const content = lines.join("\n");
+		const findings = checkFileSize("src/big.ts", content);
+		expect(findings).toHaveLength(1);
+		expect(findings[0]?.severity).toBe("warning");
+		expect(findings[0]?.ruleId).toBe("file-too-long");
+		expect(findings[0]?.message).toContain("501");
+	});
+
+	it("does not flag files with exactly 500 lines", () => {
+		const lines = Array.from({ length: 500 }, (_, i) => `const x${i} = ${i};`);
+		const content = lines.join("\n");
+		const findings = checkFileSize("src/ok.ts", content);
+		expect(findings).toHaveLength(0);
+	});
+});
+
+// ─── checkSecrets ────────────────────────────────────────────────────────
+
+describe("checkSecrets", () => {
+	it("detects hardcoded password patterns", () => {
+		const content = `const config = {\n  password="s3cret123"\n};\n`;
+		const findings = checkSecrets("src/config.ts", content);
+		expect(findings).toHaveLength(1);
+		expect(findings[0]?.severity).toBe("error");
+		expect(findings[0]?.ruleId).toBe("hardcoded-secret");
+	});
+
+	it("detects api_key patterns", () => {
+		const content = `const api_key = "abc123def456";\n`;
+		const findings = checkSecrets("src/config.ts", content);
+		expect(findings).toHaveLength(1);
+	});
+
+	it("ignores variable references (not hardcoded)", () => {
+		const content = `const password = process.env.PASSWORD;\n`;
+		const findings = checkSecrets("src/config.ts", content);
+		expect(findings).toHaveLength(0);
+	});
+
+	it("detects token patterns", () => {
+		const content = `const token = "ghp_abc123def456";\n`;
+		const findings = checkSecrets("src/config.ts", content);
+		expect(findings).toHaveLength(1);
+	});
+
+	it("detects secret patterns", () => {
+		const content = `secret="mySecretValue123";\n`;
+		const findings = checkSecrets("src/config.ts", content);
+		expect(findings).toHaveLength(1);
+	});
+});
+
+// ─── checkEmptyCatch ─────────────────────────────────────────────────────
+
+describe("checkEmptyCatch", () => {
+	it("detects empty catch blocks", () => {
+		const content = `try {\n  doSomething();\n} catch (e) {\n}\n`;
+		const findings = checkEmptyCatch("src/app.ts", content);
+		expect(findings).toHaveLength(1);
+		expect(findings[0]?.ruleId).toBe("empty-catch");
+		expect(findings[0]?.severity).toBe("warning");
+	});
+
+	it("does not flag catch blocks with content", () => {
+		const content = `try {\n  doSomething();\n} catch (e) {\n  console.error(e);\n}\n`;
+		const findings = checkEmptyCatch("src/app.ts", content);
+		expect(findings).toHaveLength(0);
+	});
+
+	it("detects catch blocks with only whitespace", () => {
+		const content = `try {\n  doSomething();\n} catch (e) {\n  \n}\n`;
+		const findings = checkEmptyCatch("src/app.ts", content);
+		expect(findings).toHaveLength(1);
+	});
+
+	it("allows catch with a comment (intentional empty catch)", () => {
+		const content = `try {\n  doSomething();\n} catch (e) {\n  // intentionally empty\n}\n`;
+		const findings = checkEmptyCatch("src/app.ts", content);
+		expect(findings).toHaveLength(0);
+	});
+});
+
+// ─── checkAnyType ────────────────────────────────────────────────────────
+
+describe("checkAnyType", () => {
+	it("detects 'any' type annotation in .ts files", () => {
+		const content = `function foo(x: any): void {\n  return;\n}\n`;
+		const findings = checkAnyType("src/app.ts", content);
+		expect(findings).toHaveLength(1);
+		expect(findings[0]?.line).toBe(1);
+		expect(findings[0]?.ruleId).toBe("no-any-type");
+		expect(findings[0]?.severity).toBe("warning");
+	});
+
+	it("skips .d.ts files", () => {
+		const content = `declare function foo(x: any): void;\n`;
+		const findings = checkAnyType("src/types.d.ts", content);
+		expect(findings).toHaveLength(0);
+	});
+
+	it("does not flag 'any' in comments or strings", () => {
+		const content = `// any type is bad\nconst msg = "any value";\n`;
+		const findings = checkAnyType("src/app.ts", content);
+		expect(findings).toHaveLength(0);
+	});
+
+	it("detects multiple any usages", () => {
+		const content = `const x: any = 1;\nconst y: any = 2;\n`;
+		const findings = checkAnyType("src/app.ts", content);
+		expect(findings).toHaveLength(2);
+	});
+
+	it("does not flag words containing 'any' like 'many' or 'company'", () => {
+		const content = `const many = 1;\nconst company = "acme";\n`;
+		const findings = checkAnyType("src/app.ts", content);
+		expect(findings).toHaveLength(0);
+	});
+});
+
+// ─── checkUnusedImports ──────────────────────────────────────────────────
+
+describe("checkUnusedImports", () => {
+	it("detects unused named imports", () => {
+		const content = `import { foo, bar } from "./mod";\nconst x = foo();\n`;
+		const findings = checkUnusedImports("src/app.ts", content);
+		// bar is unused
+		expect(findings).toHaveLength(1);
+		expect(findings[0]?.message).toContain("bar");
+		expect(findings[0]?.ruleId).toBe("unused-import");
+	});
+
+	it("does not flag used imports", () => {
+		const content = `import { foo } from "./mod";\nconst x = foo();\n`;
+		const findings = checkUnusedImports("src/app.ts", content);
+		expect(findings).toHaveLength(0);
+	});
+
+	it("handles type imports (should not flag)", () => {
+		const content = `import type { Foo } from "./mod";\nconst x: Foo = {};\n`;
+		const findings = checkUnusedImports("src/app.ts", content);
+		expect(findings).toHaveLength(0);
+	});
+});
+
+// ─── runBuiltinChecks ────────────────────────────────────────────────────
+
+describe("runBuiltinChecks", () => {
+	it("aggregates findings from all checks", () => {
+		const content = [
+			`import { unused } from "./mod";`,
+			`console.log("bad");`,
+			`// TODO: fix later`,
+			`const x: any = 1;`,
+			`try { f(); } catch (e) {}`,
+			`password="secret123"`,
+		].join("\n");
+
+		const findings = runBuiltinChecks("src/app.ts", content);
+		// Should have findings from multiple checks
+		expect(findings.length).toBeGreaterThanOrEqual(4);
+
+		// Verify all findings have correct tool
+		for (const f of findings) {
+			expect(f.tool).toBe("builtin");
+			expect(f.file).toBe("src/app.ts");
+		}
+	});
+
+	it("returns empty for clean files", () => {
+		const content = `import { foo } from "./mod";\nconst x = foo();\n`;
+		const findings = runBuiltinChecks("src/app.ts", content);
+		expect(findings).toHaveLength(0);
+	});
+});

package/src/verify/__tests__/pipeline.test.ts

@@ -272,8 +272,8 @@ describe("VerifyPipeline", () => {
 		expect(callOrder).toContain("runTrivy");
 		expect(callOrder).toContain("runSecretlint");
 
-		// 10 tool reports (slop + semgrep + trivy + secretlint + sonarqube + stryker + diff-cover + typecheck + consistency + ai-review)
-		expect(result.tools).toHaveLength(10);
+		// 11 tool reports (slop + semgrep + trivy + secretlint + sonarqube + stryker + diff-cover + typecheck + consistency + builtin + ai-review)
+		expect(result.tools).toHaveLength(11);
 		expect(result.findings).toHaveLength(3);
 	});
 

package/src/verify/builtin.ts

@@ -0,0 +1,350 @@
+/**
+ * Built-in Verify Checks — pure-function checks that always run.
+ *
+ * These provide baseline verification without requiring external linters.
+ * Each check is a pure function: (filePath, content) => Finding[].
+ * No I/O, no side effects, no subprocess spawns.
+ */
+
+import type { Finding } from "./diff-filter";
+
+// ─── Helpers ─────────────────────────────────────────────────────────────
+
+function isTestFile(filePath: string): boolean {
+	return (
+		filePath.endsWith(".test.ts") ||
+		filePath.endsWith(".test.tsx") ||
+		filePath.endsWith(".test.js") ||
+		filePath.endsWith(".test.jsx") ||
+		filePath.endsWith(".spec.ts") ||
+		filePath.endsWith(".spec.tsx") ||
+		filePath.endsWith(".spec.js") ||
+		filePath.endsWith(".spec.jsx") ||
+		filePath.includes("__tests__/")
+	);
+}
+
+function isDeclarationFile(filePath: string): boolean {
+	return filePath.endsWith(".d.ts");
+}
+
+function isTypeScriptFile(filePath: string): boolean {
+	return (
+		filePath.endsWith(".ts") ||
+		filePath.endsWith(".tsx") ||
+		filePath.endsWith(".mts") ||
+		filePath.endsWith(".cts")
+	);
+}
+
+// ─── Check 1: console.log in non-test files ─────────────────────────────
+
+/**
+ * Detect console.log/warn/error/debug/info calls in production code.
+ * Test files are excluded since console usage is acceptable there.
+ */
+export function checkConsoleLogs(filePath: string, content: string): Finding[] {
+	if (isTestFile(filePath)) return [];
+
+	const findings: Finding[] = [];
+	const lines = content.split("\n");
+	const consolePattern = /\bconsole\.(log|warn|error|debug|info)\s*\(/;
+
+	for (const [i, line] of lines.entries()) {
+		if (consolePattern.test(line)) {
+			findings.push({
+				tool: "builtin",
+				file: filePath,
+				line: i + 1,
+				message: `console.${line.match(consolePattern)?.[1]} found in production code`,
+				severity: "warning",
+				ruleId: "no-console-log",
+			});
+		}
+	}
+
+	return findings;
+}
+
+// ─── Check 2: Unused imports ─────────────────────────────────────────────
+
+/**
+ * Best-effort regex check for unused named imports.
+ * Looks for `import { X, Y }` where identifiers don't appear
+ * elsewhere in the file. Prefers false negatives over false positives.
+ */
+export function checkUnusedImports(
+	filePath: string,
+	content: string,
+): Finding[] {
+	const findings: Finding[] = [];
+	const lines = content.split("\n");
+
+	// Match named imports: import { A, B } from "..." or import type { A } from "..."
+	const importLinePattern =
+		/^import\s+(?:type\s+)?{([^}]+)}\s+from\s+["'][^"']+["'];?\s*$/;
+
+	for (const [i, line] of lines.entries()) {
+		const match = line.match(importLinePattern);
+		if (!match) continue;
+
+		// Check if this is a type-only import (import type { ... })
+		const isTypeImport = /^import\s+type\s+\{/.test(line);
+
+		const rawNames = match[1]?.split(",") ?? [];
+		const importedNames: string[] = [];
+		for (const raw of rawNames) {
+			// Handle "X as Y" — the local name is Y
+			const parts = raw.trim().split(/\s+as\s+/);
+			const resolved = (parts.length > 1 ? parts[1] : parts[0])?.trim() ?? "";
+			if (resolved.length > 0) {
+				importedNames.push(resolved);
+			}
+		}
+
+		// Get the rest of the file content (excluding import lines)
+		const restOfFile = lines
+			.filter((l) => !importLinePattern.test(l))
+			.join("\n");
+
+		for (const name of importedNames) {
+			// Check if the identifier appears in the rest of the file
+			// Use word boundary to avoid matching substrings
+			const usagePattern = new RegExp(`\\b${escapeRegex(name)}\\b`);
+			if (!usagePattern.test(restOfFile)) {
+				findings.push({
+					tool: "builtin",
+					file: filePath,
+					line: i + 1,
+					message: `Import '${name}' appears unused${isTypeImport ? " (type import)" : ""}`,
+					severity: "warning",
+					ruleId: "unused-import",
+				});
+			}
+		}
+	}
+
+	return findings;
+}
+
+function escapeRegex(str: string): string {
+	return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+// ─── Check 3: TODO/FIXME/HACK comments ──────────────────────────────────
+
+/**
+ * Count and report TODO, FIXME, and HACK markers.
+ * These are informational — they don't block verification.
+ */
+export function checkTodoComments(
+	filePath: string,
+	content: string,
+): Finding[] {
+	const findings: Finding[] = [];
+	const lines = content.split("\n");
+	const todoPattern = /\b(TODO|FIXME|HACK)\b/;
+
+	for (const [i, line] of lines.entries()) {
+		const match = line.match(todoPattern);
+		if (match) {
+			findings.push({
+				tool: "builtin",
+				file: filePath,
+				line: i + 1,
+				message: `${match[1]} comment found: ${line.trim()}`,
+				severity: "info",
+				ruleId: "todo-comment",
+			});
+		}
+	}
+
+	return findings;
+}
+
+// ─── Check 4: File size ──────────────────────────────────────────────────
+
+/**
+ * Flag files exceeding 500 lines. Large files are harder to review
+ * and maintain — consider splitting them.
+ */
+export function checkFileSize(filePath: string, content: string): Finding[] {
+	const lineCount = content.split("\n").length;
+
+	if (lineCount > 500) {
+		return [
+			{
+				tool: "builtin",
+				file: filePath,
+				line: 1,
+				message: `File has ${lineCount} lines (exceeds 500 line limit). Consider splitting.`,
+				severity: "warning",
+				ruleId: "file-too-long",
+			},
+		];
+	}
+
+	return [];
+}
+
+// ─── Check 5: Secrets patterns ──────────────────────────────────────────
+
+/**
+ * Detect hardcoded secrets: password=, secret=, token=, api_key=
+ * followed by a quoted or literal non-empty value (not a variable reference).
+ */
+export function checkSecrets(filePath: string, content: string): Finding[] {
+	const findings: Finding[] = [];
+	const lines = content.split("\n");
+
+	// Patterns: key followed by = and a hardcoded value (quoted string or bare literal)
+	// Does NOT match variable references like process.env.X, ${VAR}, etc.
+	const secretPattern =
+		/\b(password|secret|token|api_key|apikey|api_secret|private_key|auth_token)\s*[=:]\s*["'`]([^"'`\s$]{2,})["'`]/i;
+
+	for (const [i, line] of lines.entries()) {
+		const match = line.match(secretPattern);
+		if (match) {
+			findings.push({
+				tool: "builtin",
+				file: filePath,
+				line: i + 1,
+				message: `Possible hardcoded ${match[1]} detected`,
+				severity: "error",
+				ruleId: "hardcoded-secret",
+			});
+		}
+	}
+
+	return findings;
+}
+
+// ─── Check 6: Empty catch blocks ─────────────────────────────────────────
+
+/**
+ * Detect empty catch blocks (no statements, no comments).
+ * A catch with only whitespace is still flagged.
+ * A catch with a comment is considered intentional and allowed.
+ */
+export function checkEmptyCatch(filePath: string, content: string): Finding[] {
+	const findings: Finding[] = [];
+	const lines = content.split("\n");
+
+	for (const [i, line] of lines.entries()) {
+		// Match catch on same line: catch (e) {}
+		// or catch (e) {  } (with just whitespace)
+		const inlineMatch = line.match(/\bcatch\s*\([^)]*\)\s*\{\s*\}\s*$/);
+		if (inlineMatch) {
+			findings.push({
+				tool: "builtin",
+				file: filePath,
+				line: i + 1,
+				message: "Empty catch block — errors are silently swallowed",
+				severity: "warning",
+				ruleId: "empty-catch",
+			});
+			continue;
+		}
+
+		// Multi-line catch: catch (e) { on this line, } on a later line
+		const catchOpenMatch = line.match(/\bcatch\s*\([^)]*\)\s*\{\s*$/);
+		if (catchOpenMatch) {
+			// Look ahead for the closing brace
+			let blockContent = "";
+			let closingLine = -1;
+			for (let j = i + 1; j < lines.length && j < i + 20; j++) {
+				const nextLine = lines[j] ?? "";
+				if (nextLine.trim() === "}") {
+					closingLine = j;
+					break;
+				}
+				blockContent += nextLine;
+			}
+
+			if (closingLine !== -1) {
+				const trimmed = blockContent.trim();
+				// Empty or whitespace-only is flagged
+				// Comments are intentional — not flagged
+				if (trimmed === "") {
+					findings.push({
+						tool: "builtin",
+						file: filePath,
+						line: i + 1,
+						message: "Empty catch block — errors are silently swallowed",
+						severity: "warning",
+						ruleId: "empty-catch",
+					});
+				}
+				// If it contains a comment (// or /* or *), it's intentional
+				// If it contains actual code, it's not empty
+				// Either way, no finding needed
+			}
+		}
+	}
+
+	return findings;
+}
+
+// ─── Check 7: `any` type usage ───────────────────────────────────────────
+
+/**
+ * Detect `any` type annotations in TypeScript files.
+ * Skips .d.ts files where `any` is sometimes necessary.
+ * Avoids false positives on words containing "any" (e.g., "many", "company")
+ * and on comments/strings.
+ */
+export function checkAnyType(filePath: string, content: string): Finding[] {
+	if (!isTypeScriptFile(filePath)) return [];
+	if (isDeclarationFile(filePath)) return [];
+
+	const findings: Finding[] = [];
+	const lines = content.split("\n");
+
+	// Match `: any`, `as any`, `<any>`, `any[]`, `any,`, `any)`, `any;`
+	// — basically `any` used as a type annotation, not as a substring in identifiers
+	const anyTypePattern =
+		/(?::\s*any\b|(?:as|extends|implements)\s+any\b|<any\b|any\s*[[\]>,);|&])/;
+
+	for (const [i, line] of lines.entries()) {
+		// Skip comment lines
+		const trimmed = line.trim();
+		if (trimmed.startsWith("//") || trimmed.startsWith("*")) continue;
+
+		// Skip lines where 'any' only appears in a string literal
+		// Simple heuristic: remove string contents and check again
+		const withoutStrings = line
+			.replace(/"(?:[^"\\]|\\.)*"/g, '""')
+			.replace(/'(?:[^'\\]|\\.)*'/g, "''")
+			.replace(/`(?:[^`\\]|\\.)*`/g, "``");
+
+		if (anyTypePattern.test(withoutStrings)) {
+			findings.push({
+				tool: "builtin",
+				file: filePath,
+				line: i + 1,
+				message: "Usage of 'any' type — prefer explicit types or 'unknown'",
+				severity: "warning",
+				ruleId: "no-any-type",
+			});
+		}
+	}
+
+	return findings;
+}
+
+// ─── Aggregator ──────────────────────────────────────────────────────────
+
+/**
+ * Run all built-in checks on a single file and return aggregated findings.
+ */
+export function runBuiltinChecks(filePath: string, content: string): Finding[] {
+	return [
+		...checkConsoleLogs(filePath, content),
+		...checkUnusedImports(filePath, content),
+		...checkTodoComments(filePath, content),
+		...checkFileSize(filePath, content),
+		...checkSecrets(filePath, content),
+		...checkEmptyCatch(filePath, content),
+		...checkAnyType(filePath, content),
+	];
+}

package/src/verify/pipeline.ts

@@ -5,7 +5,7 @@
  * 1. Get files to check (staged files, or provided list)
  * 2. Run syntax guard FIRST — abort immediately if it fails
  * 3. Auto-detect available tools
- * 4. Run all available tools in PARALLEL (slop, semgrep, trivy, secretlint)
+ * 4. Run all available tools in PARALLEL (slop, builtin, semgrep, trivy, secretlint)
  * 5. Collect all findings
  * 6. Apply diff-only filter (unless diffOnly === false)
  * 7. Determine pass/fail: passed = no error-severity findings
@@ -19,6 +19,7 @@ import { detectLanguages } from "../language/detect";
 import type { LanguageId } from "../language/profile";
 import { getProfile } from "../language/profile";
 import { type AIReviewResult, runAIReview } from "./ai-review";
+import { runBuiltinChecks } from "./builtin";
 import { checkConsistency } from "./consistency";
 import { runCoverage } from "./coverage";
 import type { DetectedTool } from "./detect";
@@ -240,10 +241,27 @@ export async function runPipeline(
 		}),
 	);
 
+	// Built-in checks (always run, pure functions, no external dependencies)
+	toolPromises.push(
+		runToolWithTiming("builtin", async () => {
+			const findings: Finding[] = [];
+			for (const file of files) {
+				try {
+					const fullPath = file.startsWith("/") ? file : `${cwd}/${file}`;
+					const text = await Bun.file(fullPath).text();
+					findings.push(...runBuiltinChecks(file, text));
+				} catch {
+					// File read failure should not block pipeline
+				}
+			}
+			return { findings, skipped: false };
+		}),
+	);
+
 	const toolReports = await Promise.all(toolPromises);
 
 	// ── Step 4b: Warn if all external tools were skipped ─────────────────
-	const builtInTools = new Set(["slop", "typecheck", "consistency"]);
+	const builtInTools = new Set(["slop", "typecheck", "consistency", "builtin"]);
 	const externalTools = toolReports.filter((r) => !builtInTools.has(r.tool));
 	const allExternalSkipped =
 		externalTools.length > 0 && externalTools.every((r) => r.skipped);