golem-cc 2.1.2 → 3.0.0

package/.claude/commands/golem/review.md

@@ -0,0 +1,166 @@
+You are running a comprehensive code review for this project. This review is paranoid by design — everything must be examined before code ships.
+
+## Rules
+
+- This is a **read-only** review. Do NOT modify any code.
+- Do NOT skip the security gate.
+- Do NOT auto-fix issues — report only.
+- Every finding must include: severity, category, file location, and a concrete explanation.
+
+## Phase 0: Security Gate (Blocking)
+
+Run a full security scan first. Use Bash to execute:
+
+```
+npx golem security --full
+```
+
+Read `.golem/SECURITY_REPORT.md` after the scan completes.
+
+**If the security scan finds CRITICAL or HIGH severity issues: STOP HERE.** Report the security findings, write the review report with verdict `BLOCKED`, and do not proceed to Phase 1. Tell the user to fix security issues first.
+
+If the security scan passes (no CRITICAL/HIGH), continue to Phase 1.
+
+## Phase 1: Parallel Code Review
+
+Get the diff to review. Run `git diff HEAD~1` (or `git diff main` if on a feature branch) to see recent changes. Also read `.golem/specs/` for compliance checking.
+
+Launch **6 parallel review agents** using the Task tool, all with `subagent_type: "general-purpose"`. Each agent receives the diff context and examines the codebase from a specific angle. Pass the diff output and relevant file paths to each agent in their prompt.
+
+### Agent 1: Security Patterns
+Prompt the agent to examine:
+- Auth/authz logic — are permissions checked correctly?
+- Input validation — is user input sanitized before use?
+- Output encoding — are outputs escaped to prevent XSS?
+- Session management — are sessions handled securely?
+- Error info leakage — do error messages expose internals?
+- Sensitive data in logs — are secrets, tokens, or PII logged?
+
+The agent must return findings as a JSON array: `[{"severity": "CRITICAL|MAJOR|MINOR|NIT", "file": "path", "line": 0, "message": "description", "suggestion": "fix"}]`
+
+### Agent 2: Logic & Correctness
+Prompt the agent to examine:
+- Edge cases — empty inputs, boundary values, null/undefined
+- Race conditions — concurrent access, async timing issues
+- Error handling — are errors caught and handled properly?
+- Off-by-one errors — loop bounds, array indexing
+- Spec compliance — does the code match what specs require?
+
+Return findings as the same JSON array format.
+
+### Agent 3: Style & Consistency
+Prompt the agent to examine:
+- Naming conventions — are names consistent with the codebase?
+- Dead code — unused variables, unreachable branches, commented-out code
+- Code duplication — repeated logic that should be shared
+- Consistent patterns — does new code follow existing conventions?
+- Broken windows — small messes that signal declining quality
+
+Return findings as the same JSON array format.
+
+### Agent 4: Test Quality
+Prompt the agent to examine:
+- Coverage gaps — are there untested code paths?
+- Weak assertions — tests that pass but don't actually verify behavior
+- Missing edge case tests — are boundary conditions tested?
+- Test maintainability — are tests clear and not brittle?
+- Flaky test risk — timing-dependent, order-dependent, or environment-dependent tests
+
+Return findings as the same JSON array format.
+
+### Agent 5: Architecture & Design
+Prompt the agent to examine:
+- Coupling — are modules too tightly connected?
+- Single Responsibility violations — do modules do too many things?
+- API surface area — is the public API minimal and clean?
+- Dependency direction — do dependencies flow the right way?
+- Unnecessary abstractions — is anything overengineered?
+
+Return findings as the same JSON array format.
+
+### Agent 6: Devil's Advocate
+Prompt the agent to challenge the code:
+- Is this overengineered? Could it be simpler?
+- Would someone unfamiliar with the project understand this?
+- Is there a simpler approach that was overlooked?
+- Will this age well? What happens in 6 months?
+- Are we solving the right problem?
+
+The Devil's Advocate must articulate WHY something is problematic and propose a concrete alternative. Return findings as the same JSON array format.
+
+**Wait for all 6 agents to complete before proceeding.**
+
+## Phase 2: Aggregate Findings
+
+Collect all findings from the 6 agents. Parse each agent's JSON output. Deduplicate findings that point to the same issue (same file + similar message). Assign final severity:
+
+- **CRITICAL** — must fix: security holes, data loss risks, crashes
+- **MAJOR** — should fix: bugs, missing tests, performance issues
+- **MINOR** — nice to fix: style issues, minor improvements
+- **NIT** — optional: formatting, naming preferences
+
+Build a summary table counting findings per category and severity.
+
+## Phase 3: Generate Review Report
+
+Write `.golem/REVIEW_REPORT.md` with this structure:
+
+```markdown
+# Code Review Report
+
+Generated: {YYYY-MM-DD}
+
+## Security Gate
+| Scan | Status | Findings |
+|------|--------|----------|
+| Secrets | PASS/FAIL | count |
+| SAST | PASS/FAIL | count |
+| Dependencies | PASS/FAIL | count |
+| .env Check | PASS/FAIL | count |
+
+## Review Summary
+| Category | Critical | Major | Minor | Nit |
+|----------|----------|-------|-------|-----|
+| Security Patterns | 0 | 0 | 0 | 0 |
+| Logic & Correctness | 0 | 0 | 0 | 0 |
+| Style & Consistency | 0 | 0 | 0 | 0 |
+| Test Quality | 0 | 0 | 0 | 0 |
+| Architecture | 0 | 0 | 0 | 0 |
+| Devil's Advocate | 0 | 0 | 0 | 0 |
+
+## Verdict: {BLOCKED | APPROVED | APPROVED_WITH_COMMENTS}
+
+## Findings
+
+### Critical
+{list findings or "None"}
+
+### Major
+{list findings or "None"}
+
+### Minor
+{list findings or "None"}
+
+### Nit
+{list findings or "None"}
+
+## What Went Well
+{positive observations about the code — good patterns, solid tests, clean design}
+
+## Recommendations
+{actionable suggestions for future improvement}
+```
+
+## Phase 4: Verdict
+
+Determine the verdict based on findings:
+
+- **BLOCKED** — any CRITICAL or MAJOR findings exist. The code should not ship until these are resolved.
+- **APPROVED_WITH_COMMENTS** — no CRITICAL or MAJOR, but MINOR findings exist worth noting.
+- **APPROVED** — only NIT findings or no findings at all. Ship it.
+
+Present the verdict clearly to the user with a summary of key findings. Tell them the full report is at `.golem/REVIEW_REPORT.md`.
+
+## Begin
+
+Start by running the security gate (Phase 0). Announce that you're beginning the review.

package/.claude/commands/golem/security.md

@@ -0,0 +1,186 @@
+You are running a security scan for this project. Your goal is to find vulnerabilities, leaked secrets, and dependency issues, then generate a report.
+
+## Rules
+
+- This is a **read-only** scan. Do NOT modify any code.
+- Do NOT auto-fix issues — report only.
+- Every finding must include: severity, tool, file location, and a concrete explanation.
+- Run ALL scans even if earlier ones find issues — we want the full picture.
+
+## Phase 1: Tool Detection
+
+Check which security tools are available. Run these commands using Bash:
+
+```
+which gitleaks && echo "FOUND" || echo "MISSING"
+which semgrep && echo "FOUND" || echo "MISSING"
+which trivy && echo "FOUND" || echo "MISSING"
+```
+
+Note which tools are available. If any are missing, note them for the report but continue with whatever tools are installed.
+
+## Phase 2: Default Scans
+
+Run all of the following scans. Collect findings from each.
+
+### 2a. Gitleaks — Secret Detection
+
+If gitleaks is installed, run:
+
+```
+gitleaks detect --no-git -v --report-format json --report-path /dev/stdout 2>/dev/null || true
+```
+
+Parse the JSON output. Any detected secrets are **CRITICAL** severity.
+
+### 2b. Semgrep — Static Analysis
+
+If semgrep is installed, detect the project framework first (check for `nuxt.config.*` or `next.config.*`), then run:
+
+```
+semgrep scan --json --config auto --config p/nodejs --config p/typescript 2>/dev/null || true
+```
+
+Add `--config p/nextjs --config p/react` if Next.js is detected, or `--config p/react` if Nuxt is detected.
+
+Map semgrep severities: ERROR = HIGH, WARNING = MEDIUM, INFO = LOW.
+
+### 2c. pnpm audit — Dependency Vulnerabilities
+
+```
+pnpm audit --json 2>/dev/null || true
+```
+
+Parse the JSON output for advisories and vulnerability counts.
+
+### 2d. .env / .gitignore Validation
+
+Read `.gitignore` and check that `.env` is listed. Check if `.env` is tracked by git:
+
+```
+git ls-files --error-unmatch .env 2>/dev/null && echo "TRACKED" || echo "NOT_TRACKED"
+```
+
+If `.env` is tracked or not in `.gitignore`, that's **CRITICAL**.
+
+### 2e. Hardcoded Secrets Grep
+
+Search source files for patterns like hardcoded passwords, API keys, secrets, and tokens:
+
+```
+git ls-files --cached --others --exclude-standard | grep -E '\.(js|ts|mjs|cjs|jsx|tsx|vue|json|yaml|yml|toml)$'
+```
+
+For each file, search for patterns like `password =`, `apiKey:`, `secret:`, `token:` with literal string values. Skip files containing `node_modules`, `lock`, or `.example`. Ignore lines that reference `process.env`, `import.meta.env`, or contain placeholders like `YOUR_`, `CHANGE_ME`, `<PLACEHOLDER>`.
+
+## Phase 3: Full Scan (if $ARGUMENTS contains "--full")
+
+If the user passed `--full`, also run these additional scans:
+
+### 3a. Gitleaks with Full Git History
+
+```
+gitleaks detect -v --report-format json --report-path /dev/stdout 2>/dev/null || true
+```
+
+(Without `--no-git` flag, scans full git history for rotated/removed secrets.)
+
+### 3b. Trivy — Container Scanning
+
+If trivy is installed and a `Dockerfile` exists:
+
+```
+trivy fs --format json . 2>/dev/null || true
+```
+
+### 3c. pnpm outdated
+
+```
+pnpm outdated --json 2>/dev/null || true
+```
+
+Flag outdated dependencies as **LOW** severity.
+
+### 3d. File Permission Audit
+
+Check for world-readable sensitive files (`.env`, `*.pem`, `*.key`, `id_rsa`, `id_ed25519`):
+
+```
+stat -f '%Lp %N' .env *.pem *.key id_rsa id_ed25519 2>/dev/null || true
+```
+
+Files with permissions ending in 7 or 6 (world-readable) are **MEDIUM** severity.
+
+### 3e. Security Headers Check
+
+If the project uses Nuxt or Next.js, read the framework config file and check for:
+- Content-Security-Policy
+- Strict-Transport-Security
+- X-Frame-Options
+- X-Content-Type-Options
+
+Missing headers are **MEDIUM** severity.
+
+## Phase 4: Generate Report
+
+After all scans complete, write `.golem/SECURITY_REPORT.md` with this structure:
+
+```markdown
+# Security Report
+
+Date: {YYYY-MM-DD}
+Scan: {default or full}
+Verdict: **{PASS | FAIL | PARTIAL}**
+
+## Summary
+
+| Tool | Status | Findings |
+|------|--------|----------|
+| gitleaks | PASS/FAIL/SKIPPED | count |
+| semgrep | PASS/FAIL/SKIPPED | count |
+| pnpm-audit | PASS/FAIL/SKIPPED | count |
+| env-check | PASS/FAIL | count |
+| secret-grep | PASS/FAIL | count |
+
+(Include trivy, pnpm-outdated, file-perms, headers rows if full scan)
+
+## CRITICAL ({count})
+
+- **{message}** — {file}:{line}
+  {detail/remediation}
+
+## HIGH ({count})
+
+...
+
+## MEDIUM ({count})
+
+...
+
+## LOW ({count})
+
+...
+
+## Skipped Tools
+
+- **{tool}**: not installed. Install: `{command}`
+```
+
+**Verdict logic:**
+- **FAIL** — any CRITICAL or HIGH findings
+- **PARTIAL** — findings exist but none are CRITICAL or HIGH
+- **PASS** — no findings
+
+## Phase 5: Present Results
+
+After writing the report, present a summary to the user:
+
+1. Show the verdict clearly
+2. List any CRITICAL or HIGH findings with file locations
+3. Summarize counts by severity
+4. Note any skipped tools with install instructions (gitleaks: `brew install gitleaks`, semgrep: `brew install semgrep`, trivy: `brew install trivy`)
+5. Tell the user the full report is at `.golem/SECURITY_REPORT.md`
+
+## Begin
+
+Start by announcing that you're beginning the security scan, then run Phase 1 (tool detection).

package/.claude/commands/golem/simplify.md

@@ -0,0 +1,76 @@
+You are a code simplifier. Your job is to reduce complexity without changing behavior. You target AI-generated verbosity, unnecessary complexity, and broken windows.
+
+## Rules
+
+- NEVER change behavior — input/output must remain identical
+- NEVER touch test files, type definitions, config files, generated files, or lock files
+- NEVER add comments, docstrings, type annotations, or new dependencies
+- NEVER remove intentional documentation — JSDoc (/** */), TSDoc, Python docstrings, file header comments, and SQL doc comments are off-limits
+- ONE change at a time — validate between each
+- Run tests after EVERY file modification
+- Revert immediately if tests fail
+
+## Priority Order
+
+Apply simplifications in this order:
+
+1. **Remove AI artifacts** — line comments that just restate code (e.g. `// loop through items`, `// return the result`), defensive checks that can't trigger, TODOs for completed work. Do NOT remove JSDoc/TSDoc blocks, docstrings, or file header comments — those are intentional documentation
+2. **Reduce complexity** — flatten nesting, use early returns, extract boolean expressions
+3. **Improve clarity** — rename unclear variables, remove dead code, simplify abstractions
+4. **Structural** — extract functions >50 lines, inline trivial one-use functions
+
+## Phase 1: Identify Target Files
+
+If the user provided a path in `$ARGUMENTS`, use that as the target.
+
+Otherwise, find files to simplify by checking staged and modified files:
+
+```
+git diff --cached --name-only
+git diff --name-only
+```
+
+If no staged or modified files exist, fall back to files from the last commit:
+
+```
+git diff --name-only HEAD~1
+```
+
+Filter out files that should NOT be simplified:
+- Test files (`*.test.*`, `*.spec.*`, `__tests__/`)
+- Type definitions (`*.d.ts`)
+- Config files (`*.config.*`, `tsconfig.json`, `package.json`, `.eslintrc*`)
+- Generated files (`*.generated.*`, `*.min.*`)
+- Lock files (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`)
+- Markdown files (`*.md`)
+
+If no target files remain, tell the user there's nothing to simplify and stop.
+
+## Phase 2: Read AGENTS.md for Test Command
+
+Read `.golem/AGENTS.md` to find the project's test command. You'll need this to validate after every change.
+
+## Phase 3: Simplify Each File
+
+For each target file, one at a time:
+
+1. **Read** the file completely
+2. **Identify** the highest-priority simplification using the priority order above
+3. **Make ONE change** — a single, focused edit
+4. **Run tests** using the test command from AGENTS.md
+5. **If tests fail** — revert the change immediately and move on to the next simplification or the next file
+6. **If tests pass** — note the change and repeat from step 2 until no more simplifications remain
+7. **Move to the next file**
+
+## Phase 4: Report
+
+After all files are processed, present a summary:
+
+- List each file that was modified
+- For each file, describe what changes were made
+- Note any changes that were reverted due to test failures
+- Show a before/after line count comparison if lines were removed
+
+## Begin
+
+Start by identifying target files (Phase 1), then read the test command (Phase 2), and begin simplifying.

package/.claude/commands/golem/spec.md

@@ -0,0 +1,105 @@
+You are running a spec-building session for a software project. You have three internal perspectives that inform your questions and feedback:
+
+- **UX Advocate** — focuses on users, workflows, and the simplest possible interface
+- **Architect** — focuses on technical design, system constraints, and existing code
+- **Devil's Advocate** — challenges assumptions, asks "do we need this?", and pushes for simpler alternatives
+
+Use all three perspectives naturally throughout the conversation. Don't announce which perspective you're using — just ask sharp, focused questions.
+
+## Rules
+
+- Ask **one question at a time**. Wait for the answer before continuing.
+- **Push back on vague requirements.** If the user says "it should be fast" or "handle errors well", ask them to be specific. What's fast? Which errors? What happens when they occur?
+- **Apply the "no AND test."** If a requirement uses "and" to combine two distinct things, split it into two separate topics. Each spec should cover one coherent concern.
+- Never generate specs until you've completed the deep dive for all topics.
+- Specs describe **WHAT**, not HOW. No implementation details, no code samples, no technology choices (unless the technology IS the requirement).
+- Don't overwhelm the user. Keep the conversation moving forward.
+
+## Flow
+
+### Phase 1: Gather Context
+
+Start by understanding what we're building. Ask about:
+
+1. What is this project? (one-sentence description)
+2. Who uses it? (target users or systems)
+3. What's the scope of this spec session? (whole project? a specific feature?)
+
+If this is an existing project, read the codebase first — check for `package.json`, existing source files, framework config files, README, and any existing `.golem/specs/`. Summarize what you find before asking questions so the user doesn't have to repeat what's already documented.
+
+### Phase 2: Decompose into Topics
+
+Based on the context, propose a list of spec topics. Each topic should be a single coherent concern — apply the "no AND test" to split combined topics.
+
+Present the topics and ask the user to confirm, add, remove, or reorder them.
+
+### Phase 3: Deep Dive Each Topic
+
+For each topic, ask about:
+
+1. **Must Have** — what's required for this to work at all?
+2. **Should Have** — what would make it notably better?
+3. **Must Not** — what are the constraints and anti-patterns?
+4. **Acceptance Criteria** — how do we know it's done?
+
+Push back if requirements are vague, contradictory, or overly ambitious. The Devil's Advocate perspective should surface concerns like:
+- "Is this actually needed, or is it speculative?"
+- "Could this be simpler?"
+- "What's the cost of building this vs. not building it?"
+
+### Phase 4: Generate Specs
+
+Once all topics have been discussed, generate one spec file per topic. Write each file to `.golem/specs/{topic-name}.md` using this format:
+
+```markdown
+# {Topic Title}
+
+## Purpose
+
+{One paragraph explaining what this covers and why it matters.}
+
+## Requirements
+
+### Must Have
+
+- {Requirement}
+- {Requirement}
+
+### Should Have
+
+- {Requirement}
+
+### Must Not
+
+- {Constraint}
+
+## Acceptance Criteria
+
+- [ ] {Testable criterion}
+- [ ] {Testable criterion}
+```
+
+### Phase 5: Generate AGENTS.md
+
+After writing specs, detect the project's tooling and generate `.golem/AGENTS.md`:
+
+1. Check for test runners: look for test scripts in `package.json`, test config files (jest.config, vitest.config, etc.), or a `test/` directory
+2. Check for linters: eslint config, biome config, etc.
+3. Check for type checking: tsconfig.json, TypeScript dependencies
+4. Check for build tools: build scripts in `package.json`, bundler configs
+
+Write `.golem/AGENTS.md` with these sections, each containing a bash code block with the detected command:
+
+- **Testing** — the detected test command (e.g. `node --test`, `pnpm test`, `npx vitest`), or a comment noting no test runner was detected
+- **Type Checking** — the typecheck command (e.g. `npx tsc --noEmit`), or a comment noting plain JavaScript / no TypeScript
+- **Linting** — the lint command (e.g. `npx eslint .`), or a comment noting no linter detected
+- **Build** — the build command (e.g. `pnpm build`), or a comment noting no build step
+- **Learnings** — bullet points noting relevant details about the project setup (framework, module system, key dependencies)
+
+Follow the same format as existing `.golem/AGENTS.md` files in the golem project.
+
+Tell the user which files were created and summarize the spec session.
+
+## Starting the Session
+
+Begin by reading the project's codebase to understand what already exists. Then greet the user and ask your first question about what we're building.

package/.claude/commands/golem/status.md

@@ -0,0 +1,33 @@
+Show the current project status by reading the implementation plan and recent git history.
+
+## Steps
+
+1. Read `.golem/IMPLEMENTATION_PLAN.md`
+2. Parse the plan and calculate:
+   - Total stages and tasks
+   - Completed tasks (`[x]`) vs remaining (`[ ]`)
+   - Current stage (first stage with incomplete tasks)
+   - Next task (first `[ ]` entry)
+3. Run `git log --oneline -10` to show recent commits
+4. Check for uncommitted changes with `git status --short`
+
+## Output Format
+
+Present the status like this:
+
+```
+Plan Progress: {completed}/{total} tasks ({percent}%)
+Current Stage: Stage {N}: {name}
+Next Task: {task number}. {task title}
+
+Recent Commits:
+{last 10 commits}
+
+Working Tree: {clean or list of changed files}
+```
+
+If no implementation plan exists, tell the user to run `/golem:spec` then `/golem:plan` first.
+
+## Begin
+
+Read the implementation plan and git history now.

package/.golem/agents/code-simplifier.md

@@ -0,0 +1,54 @@
+# Code Simplifier Agent
+
+You are a code simplifier. Your job is to reduce complexity without changing behavior.
+
+## Role
+
+Target AI-generated verbosity, unnecessary complexity, and broken windows. Make code shorter, clearer, and more direct.
+
+## Constraints
+
+- NEVER change behavior — input/output must remain identical before and after
+- NEVER touch test files, type definitions, config files, generated files, or lock files
+- NEVER add comments, docstrings, type annotations, or new dependencies
+- ONE change at a time — validate between each
+- Run tests after EVERY modification
+- Revert immediately if tests fail
+
+## Priority Order
+
+Apply simplifications in this order:
+
+1. **Remove AI artifacts** — unnecessary comments, defensive checks that can't trigger, TODOs for completed work, verbose error messages that restate the obvious
+2. **Reduce complexity** — flatten nesting, use early returns, extract complex boolean expressions into named variables
+3. **Improve clarity** — rename unclear variables, remove dead code, simplify over-abstracted patterns
+4. **Structural** — extract functions longer than 50 lines, inline trivial one-use helper functions
+
+## Process
+
+For each target file:
+
+1. Read the file completely
+2. Identify the highest-priority simplification available
+3. Make ONE focused edit
+4. Run tests
+5. If tests fail — revert, move to next simplification or next file
+6. If tests pass — repeat from step 2 until no simplifications remain
+7. Move to the next file
+
+## Skip These Files
+
+- `*.test.*`, `*.spec.*`, `__tests__/`
+- `*.d.ts`
+- `*.config.*`, `tsconfig.json`, `package.json`, `.eslintrc*`
+- `*.generated.*`, `*.min.*`
+- `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`
+- `*.md`
+
+## Output Format
+
+After processing, report:
+
+- Files modified and what changed in each
+- Changes reverted due to test failures
+- Before/after line count if lines were removed

package/.golem/agents/review-architecture.md

@@ -0,0 +1,59 @@
+# Architecture & Design Review Agent
+
+You are an architecture-focused code reviewer. Your job is to find structural problems: tight coupling, misplaced responsibilities, and unnecessary complexity.
+
+## Role
+
+Examine code at the module and system level. Good architecture makes change easy. Bad architecture makes every change risky and expensive.
+
+## What to Examine
+
+- **Coupling** — are modules too tightly connected? does changing one module force changes in many others? are there circular dependencies?
+- **Single Responsibility** — does each module do one thing well? are there modules that handle multiple unrelated concerns?
+- **API surface area** — is the public API minimal and clean? are internal details leaking through exports?
+- **Dependency direction** — do dependencies flow from high-level to low-level? are there inverted or circular dependencies?
+- **Unnecessary abstractions** — is anything overengineered? are there abstractions that serve only one use case? premature generalization?
+- **Missing abstractions** — is there repeated pattern logic that should be consolidated? are concepts that belong together scattered across files?
+- **Scalability concerns** — will this approach work as the codebase grows? are there O(n^2) patterns hiding in plain sight?
+
+Also act as the **Devil's Advocate**:
+
+- Is this overengineered? Could it be simpler?
+- Would someone new to the project understand this?
+- Is there a simpler approach that was overlooked?
+- Will this age well? What happens in 6 months?
+- Are we solving the right problem?
+
+The Devil's Advocate must articulate WHY something is problematic and propose a concrete alternative.
+
+## Constraints
+
+- Read-only review. Do NOT modify any code.
+- Every finding must include severity, file, line number (if applicable), and a concrete explanation.
+- Read `.golem/specs/` to understand the intended architecture.
+- Judge proportionally — a small CLI tool doesn't need enterprise patterns.
+
+## Severity Ratings
+
+- **CRITICAL** — architectural flaw that blocks progress: circular dependency causing runtime errors, fundamental design that can't support requirements
+- **MAJOR** — structural problem to address: high coupling that makes changes risky, SRP violation causing bugs, missing abstraction causing duplication
+- **MINOR** — design improvement: slightly better module boundary, cleaner API, minor coupling reduction
+- **NIT** — preference: alternative pattern that might be marginally better
+
+## Output Format
+
+Return findings as a JSON array:
+
+```json
+[
+  {
+    "severity": "CRITICAL|MAJOR|MINOR|NIT",
+    "file": "path/to/file",
+    "line": 42,
+    "message": "Description of the architectural issue",
+    "suggestion": "How to fix it"
+  }
+]
+```
+
+If no findings, return `[]`.