@su-record/vibe 2.8.23 → 2.8.25

package/hooks/scripts/context-save.js

@@ -24,6 +24,43 @@ const summaryMap = {
 // Debounce: track last reflection level per session to avoid duplicates
 let lastReflectionLevel = null;
 
+// Guard against recursive reflection and rapid threshold crossings
+let reflectionInProgress = false;
+const DEBOUNCE_LOCKFILE = path.join(
+  process.env.HOME || process.env.USERPROFILE || '/tmp',
+  '.claude', '.vibe-hud', '.context-save-lock'
+);
+const DEBOUNCE_INTERVAL_MS = 30000; // 30 seconds between saves at same urgency
+
+/**
+ * Check if a recent save at the same urgency already happened (cross-process debounce)
+ */
+function isDebounceLocked(level) {
+  try {
+    const lockFile = `${DEBOUNCE_LOCKFILE}-${level}`;
+    if (fs.existsSync(lockFile)) {
+      const stat = fs.statSync(lockFile);
+      const ageMs = Date.now() - stat.mtimeMs;
+      if (ageMs < DEBOUNCE_INTERVAL_MS) return true;
+    }
+  } catch { /* ignore */ }
+  return false;
+}
+
+/**
+ * Set debounce lock for a given urgency level
+ */
+function setDebounceLock(level) {
+  try {
+    const lockFile = `${DEBOUNCE_LOCKFILE}-${level}`;
+    const lockDir = path.dirname(lockFile);
+    if (!fs.existsSync(lockDir)) {
+      fs.mkdirSync(lockDir, { recursive: true });
+    }
+    fs.writeFileSync(lockFile, String(Date.now()));
+  } catch { /* ignore */ }
+}
+
 /**
  * 프로젝트 환경에서 구조적 메타데이터를 추출.
  * 실패 시 빈 객체 반환 (non-blocking).
@@ -102,6 +139,11 @@ function buildStructuredSummary(baseMessage, metadata) {
 }
 
 async function main() {
+  // Cross-process debounce: skip if recently saved at same urgency
+  if (isDebounceLocked(urgency)) {
+    return;
+  }
+
   try {
     const metadata = extractStructuredMetadata();
     const baseMessage = summaryMap[urgency] || summaryMap.medium;
@@ -117,6 +159,9 @@ async function main() {
     const percent = urgency === 'critical' ? '95' : urgency === 'high' ? '90' : '80';
     console.log(`[CONTEXT ${percent}%]`, result.content[0].text);
 
+    // Mark this urgency level as recently saved
+    setDebounceLock(urgency);
+
     // Sync TokenBudgetTracker with current context usage
     try {
       const { TokenBudgetTracker } = await import(`${LIB_URL}TokenBudgetTracker.js`);
@@ -132,14 +177,20 @@ async function main() {
     // 무시
   }
 
+  // Guard against recursive reflection (setImmediate can re-enter)
+  if (reflectionInProgress) return;
+
   // Minor Reflection (80% = medium): 컨텍스트 압력 시 자동 성찰
   if (urgency === 'medium' && lastReflectionLevel !== 'medium') {
     lastReflectionLevel = 'medium';
+    reflectionInProgress = true;
     // Fire-and-forget: 기존 context-save에 영향 없음
     setImmediate(() => {
-      triggerMinorReflection().catch(e => {
-        process.stderr.write(`[REFLECTION] minor reflection failed: ${e.message}\n`);
-      });
+      triggerMinorReflection()
+        .catch(e => {
+          process.stderr.write(`[REFLECTION] minor reflection failed: ${e.message}\n`);
+        })
+        .finally(() => { reflectionInProgress = false; });
     });
   }
 
@@ -165,10 +216,13 @@ async function main() {
     // Major Reflection: 세션 종료 시 전체 성찰
     if (lastReflectionLevel !== 'critical') {
       lastReflectionLevel = 'critical';
+      reflectionInProgress = true;
       setImmediate(() => {
-        triggerMajorReflection().catch(e => {
-          process.stderr.write(`[REFLECTION] major reflection failed: ${e.message}\n`);
-        });
+        triggerMajorReflection()
+          .catch(e => {
+            process.stderr.write(`[REFLECTION] major reflection failed: ${e.message}\n`);
+          })
+          .finally(() => { reflectionInProgress = false; });
       });
     }
   }

package/hooks/scripts/hud-status.js

@@ -12,6 +12,11 @@ import os from 'os';
 const STATE_DIR = path.join(os.homedir(), '.claude', '.vibe-hud');
 const STATE_FILE = path.join(STATE_DIR, 'state.json');
 
+// Write debounce configuration
+const WRITE_DEBOUNCE_MS = 500;
+let pendingState = null;
+let writeTimer = null;
+
 // 기본 상태
 const DEFAULT_STATE = {
   mode: 'idle',           // idle | ultrawork | spec | review
@@ -65,14 +70,31 @@ function loadState() {
 }
 
 /**
- * 상태 저장
+ * 상태를 디스크에 즉시 기록
  */
-function saveState(state) {
+function flushState(state) {
   ensureStateDir();
   state.lastUpdate = new Date().toISOString();
   fs.writeFileSync(STATE_FILE, JSON.stringify(state, null, 2));
 }
 
+/**
+ * 상태 저장 (debounced - 빈번한 호출을 병합)
+ * CLI 종료 전 pending write가 있으면 flush 됨
+ */
+function saveState(state) {
+  state.lastUpdate = new Date().toISOString();
+  pendingState = state;
+  if (writeTimer) clearTimeout(writeTimer);
+  writeTimer = setTimeout(() => {
+    if (pendingState) {
+      flushState(pendingState);
+      pendingState = null;
+      writeTimer = null;
+    }
+  }, WRITE_DEBOUNCE_MS);
+}
+
 /**
  * 상태 업데이트
  */
@@ -286,6 +308,14 @@ Examples:
   }
 }
 
+// Flush pending state on process exit to avoid data loss
+process.on('exit', () => {
+  if (pendingState) {
+    flushState(pendingState);
+    pendingState = null;
+  }
+});
+
 // 메인 실행
 const args = process.argv.slice(2);
 handleCommand(args);

package/hooks/scripts/llm-orchestrate.js

@@ -39,10 +39,65 @@ const DEFAULT_SYSTEM_PROMPT = 'You are a helpful assistant.';
 const provider = process.argv[2] || 'gemini';
 const mode = process.argv[3] || 'orchestrate';
 
-// Retry configuration
+// WHY 3 retries: Enough to ride out brief 503/overload blips (typically 1-2
+// consecutive), but not so many that a genuinely down provider delays the
+// fallback chain for minutes.
 const MAX_RETRIES = 3;
+// WHY 2000ms initial delay: LLM rate-limit windows are typically 1-5s;
+// starting at 2s with exponential backoff (2s, 4s, 8s) covers most reset intervals.
 const INITIAL_DELAY_MS = 2000;
 
+// ============================================
+// Response Cache (TTL-based, in-memory)
+// ============================================
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const CACHE_MAX_ENTRIES = 50;
+const responseCache = new Map();
+
+function getCacheKey(providerName, prompt, sysPrompt, jsonMode) {
+  const hash = crypto.createHash('sha256')
+    .update(`${providerName}|${sysPrompt}|${prompt}|${jsonMode}`)
+    .digest('hex')
+    .slice(0, 16);
+  return hash;
+}
+
+function getCachedResponse(key) {
+  const entry = responseCache.get(key);
+  if (!entry) return null;
+  if (Date.now() - entry.timestamp > CACHE_TTL_MS) {
+    responseCache.delete(key);
+    return null;
+  }
+  return entry.result;
+}
+
+function setCachedResponse(key, result) {
+  // Evict oldest entries when cache is full
+  if (responseCache.size >= CACHE_MAX_ENTRIES) {
+    const oldestKey = responseCache.keys().next().value;
+    responseCache.delete(oldestKey);
+  }
+  responseCache.set(key, { result, timestamp: Date.now() });
+}
+
+// ============================================
+// Simple Prompt Detection (early exit)
+// WHY skip orchestration for simple prompts: Sending greetings/acks to an
+// external LLM wastes latency and tokens — Claude handles these natively.
+// ============================================
+const SIMPLE_PROMPT_MAX_LEN = 20;
+const SIMPLE_PROMPT_PATTERNS = [
+  /^(hi|hello|hey|thanks|thank you|ok|yes|no|y|n)\.?$/i,
+  /^(help|version|status)$/i,
+];
+
+function isSimplePrompt(prompt) {
+  const trimmed = prompt.trim();
+  if (trimmed.length > SIMPLE_PROMPT_MAX_LEN) return false;
+  return SIMPLE_PROMPT_PATTERNS.some(p => p.test(trimmed));
+}
+
 // Errors that should skip retry and go to fallback immediately
 const SKIP_RETRY_PATTERNS = [
   /rate.?limit/i,
@@ -123,7 +178,8 @@ function parseAnalyzeImageArgs(args) {
 // CLI Provider Functions
 // ============================================
 
-const CLI_TIMEOUT_MS = 120000;
+const CLI_TIMEOUT_MS = 60000;
+const CLI_FALLBACK_TIMEOUT_MS = 30000;
 const IS_WINDOWS = os.platform() === 'win32';
 
 function spawnCli(cmd, args, options) {
@@ -145,7 +201,7 @@ function buildCliPrompt(prompt, sysPrompt, jsonMode) {
 }
 
 
-function callCodexCli(prompt, sysPrompt, jsonMode, model) {
+function callCodexCli(prompt, sysPrompt, jsonMode, model, timeoutMs) {
   const fullPrompt = buildCliPrompt(prompt, sysPrompt, jsonMode);
   const outputFile = path.join(os.tmpdir(), `vibe-codex-${crypto.randomUUID()}.txt`);
   // stdin pipe로 프롬프트 전달 (shell escaping 이슈 회피)
@@ -155,11 +211,12 @@ function callCodexCli(prompt, sysPrompt, jsonMode, model) {
   const vibeConfig = readVibeConfig();
   const apiKey = vibeConfig.credentials?.gpt?.apiKey || process.env.OPENAI_API_KEY;
   const env = apiKey ? { ...process.env, OPENAI_API_KEY: apiKey } : process.env;
+  const effectiveTimeout = timeoutMs || CLI_TIMEOUT_MS;
 
   return new Promise((resolve, reject) => {
     const proc = spawnCli('codex', args, {
       stdio: ['pipe', 'pipe', 'pipe'],
-      timeout: CLI_TIMEOUT_MS,
+      timeout: effectiveTimeout,
       env,
     });
     proc.stdin.write(fullPrompt);
@@ -186,16 +243,17 @@ function callCodexCli(prompt, sysPrompt, jsonMode, model) {
   });
 }
 
-function callGeminiCli(prompt, sysPrompt, jsonMode, model) {
+function callGeminiCli(prompt, sysPrompt, jsonMode, model, timeoutMs) {
   const fullPrompt = buildCliPrompt(prompt, sysPrompt, jsonMode);
   // -p 로 headless 모드, stdin으로 프롬프트 전달 (stdin is appended to -p value)
   const args = ['-p', '.', '-o', 'text'];
   if (model) args.push('-m', model);
+  const effectiveTimeout = timeoutMs || CLI_TIMEOUT_MS;
 
   return new Promise((resolve, reject) => {
     const proc = spawnCli('gemini', args, {
       stdio: ['pipe', 'pipe', 'pipe'],
-      timeout: CLI_TIMEOUT_MS,
+      timeout: effectiveTimeout,
     });
     proc.stdin.write(fullPrompt);
     proc.stdin.end();
@@ -219,7 +277,7 @@ function callGeminiCli(prompt, sysPrompt, jsonMode, model) {
   });
 }
 
-async function callProvider(providerName, prompt, sysPrompt, jsonMode) {
+async function callProvider(providerName, prompt, sysPrompt, jsonMode, timeoutMs) {
   const vibeConfig = readVibeConfig();
 
   if (providerName === 'gpt' || providerName === 'gpt-codex' || providerName === 'gpt-spark') {
@@ -231,23 +289,23 @@ async function callProvider(providerName, prompt, sysPrompt, jsonMode) {
     } else {
       model = vibeConfig.models?.gpt || process.env.GPT_MODEL || 'gpt-5.4';
     }
-    return await callCodexCli(prompt, sysPrompt, jsonMode, model);
+    return await callCodexCli(prompt, sysPrompt, jsonMode, model, timeoutMs);
   }
 
   if (providerName === 'gemini') {
     const model = vibeConfig.models?.gemini || process.env.GEMINI_MODEL || 'gemini-3.1-pro-preview';
-    return await callGeminiCli(prompt, sysPrompt, jsonMode, model);
+    return await callGeminiCli(prompt, sysPrompt, jsonMode, model, timeoutMs);
   }
 
   throw new Error(`Unknown provider: ${providerName}`);
 }
 
-async function callWithRetry(providerName, prompt, sysPrompt, jsonMode) {
+async function callWithRetry(providerName, prompt, sysPrompt, jsonMode, timeoutMs) {
   let lastError;
 
   for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
     try {
-      return { success: true, result: await callProvider(providerName, prompt, sysPrompt, jsonMode) };
+      return { success: true, result: await callProvider(providerName, prompt, sysPrompt, jsonMode, timeoutMs) };
     } catch (e) {
       lastError = e;
       const errorMsg = e.message || String(e);
@@ -447,26 +505,46 @@ async function main() {
   const cleanPrompt = prompt.replace(prefixPatterns[provider] || /^/, '').trim();
   const jsonMode = mode === 'orchestrate-json';
 
+  // Early exit: simple prompts don't need LLM orchestration
+  if (isSimplePrompt(cleanPrompt)) {
+    return;
+  }
+
+  // Check cache for identical prompts
+  const cacheKey = getCacheKey(provider, cleanPrompt, systemPrompt, jsonMode);
+  const cached = getCachedResponse(cacheKey);
+  if (cached) {
+    console.log(cached);
+    return;
+  }
+
   // Provider chain: primary → cross fallback
-  // gpt-codex fallback: gpt-codex → gemini (codex는 full gpt로 fallback하지 않음)
+  // WHY GPT → Gemini (not reverse): GPT is the primary code/reasoning model;
+  // Gemini serves as cross-vendor fallback so a single vendor outage never
+  // blocks the user. When Gemini is primary (e.g. web-search), GPT is fallback.
   const providerLabels = { gpt: 'GPT', 'gpt-codex': 'GPT Codex', gemini: 'Gemini' };
   const isGpt = provider === 'gpt' || provider === 'gpt-codex';
   const providerChain = isGpt
     ? [provider, 'gemini']
     : ['gemini', 'gpt'];
 
-  for (const currentProvider of providerChain) {
+  for (let i = 0; i < providerChain.length; i++) {
+    const currentProvider = providerChain[i];
     const label = providerLabels[currentProvider] || currentProvider.toUpperCase();
-    const result = await callWithRetry(currentProvider, cleanPrompt, systemPrompt, jsonMode);
+    // Use shorter timeout for fallback providers
+    const timeoutMs = i === 0 ? CLI_TIMEOUT_MS : CLI_FALLBACK_TIMEOUT_MS;
+    const result = await callWithRetry(currentProvider, cleanPrompt, systemPrompt, jsonMode, timeoutMs);
 
     if (result.success) {
-      console.log(`${label} response: ${result.result}`);
+      const output = `${label} response: ${result.result}`;
+      setCachedResponse(cacheKey, output);
+      console.log(output);
       return;
     }
 
     // Log failure and try fallback
-    if (currentProvider !== providerChain[providerChain.length - 1]) {
-      const nextProvider = providerChain[providerChain.indexOf(currentProvider) + 1];
+    if (i < providerChain.length - 1) {
+      const nextProvider = providerChain[i + 1];
       const nextLabel = providerLabels[nextProvider] || nextProvider.toUpperCase();
       console.error(`[${currentProvider.toUpperCase()}] Failed: ${result.error}. Falling back to ${nextLabel}...`);
     } else {

package/hooks/scripts/pr-test-gate.js

@@ -0,0 +1,52 @@
+/**
+ * PreToolUse Hook - PR 생성 전 테스트 게이트
+ *
+ * mcp__github__create_pull_request 호출 시 테스트가 통과해야만 PR 생성 허용.
+ * exit 2 = 차단, exit 0 = 통과
+ */
+import { execSync } from 'child_process';
+import { PROJECT_DIR } from './utils.js';
+import { existsSync, readFileSync } from 'fs';
+import path from 'path';
+
+function detectTestCommand() {
+  const pkgPath = path.join(PROJECT_DIR, 'package.json');
+  if (existsSync(pkgPath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+      if (pkg.scripts?.test && pkg.scripts.test !== 'echo "Error: no test specified" && exit 1') {
+        return 'npm test';
+      }
+    } catch { /* ignore */ }
+  }
+  // Python
+  if (existsSync(path.join(PROJECT_DIR, 'pytest.ini')) || existsSync(path.join(PROJECT_DIR, 'pyproject.toml'))) {
+    return 'python -m pytest --tb=short -q';
+  }
+  // Go
+  if (existsSync(path.join(PROJECT_DIR, 'go.mod'))) {
+    return 'go test ./...';
+  }
+  return null;
+}
+
+try {
+  const testCmd = detectTestCommand();
+  if (!testCmd) {
+    // No test command detected — allow PR
+    process.exit(0);
+  }
+
+  console.log(`[PR-GATE] Running tests before PR creation: ${testCmd}`);
+  execSync(testCmd, {
+    cwd: PROJECT_DIR,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: 120000,
+  });
+  console.log('[PR-GATE] Tests passed — PR creation allowed');
+  process.exit(0);
+} catch (err) {
+  const output = err.stdout ? err.stdout.toString().split('\n').slice(-5).join('\n') : '';
+  console.log(`[PR-GATE] Tests failed — PR creation blocked\n${output}`);
+  process.exit(2);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@su-record/vibe",
-  "version": "2.8.23",
+  "version": "2.8.25",
   "description": "AI Coding Framework for Claude Code — 49 agents, 41+ tools, multi-LLM orchestration",
   "type": "module",
   "main": "dist/cli/index.js",

package/skills/agents-md/rubrics/what-to-keep.md

@@ -0,0 +1,49 @@
+# What to Keep vs Remove in AGENTS.md
+
+## The One-Line Test
+
+> "Can the agent discover this by reading the code?" → Yes = delete.
+
+## Keep (Non-discoverable Gotchas)
+
+| Type | Example | Why Keep |
+|------|---------|----------|
+| Runtime trap | "Bun runtime, not Node" | Not visible in package.json |
+| Forbidden pattern | "Never use `require()` — ESM only" | Agent will default to CJS without this |
+| SSOT location | "Edit only `constants.ts` for stack mapping" | Agent will create duplicates |
+| Ordering invariant | "Build before test — always" | Violating silently breaks things |
+| Non-standard convention | "Exports need `.js` extension" | Counterintuitive in TS projects |
+| Tool choice | "Zod only — no joi or yup" | Agent picks any validation lib |
+| Boundary | "Never edit `dist/` directly" | Agent may "fix" generated files |
+| Response directive | "Respond in Korean" | Claude-specific, not in code |
+
+## Remove (Discoverable)
+
+| Type | Why Remove | Where to Find Instead |
+|------|------------|----------------------|
+| Directory structure | `ls` or Glob reveals it | The repo itself |
+| Tech stack list | Listed in `package.json` | `package.json` |
+| Build/test commands | Listed in `scripts` | `package.json` |
+| Phase progress tables | Historical record, not actionable | Git history |
+| API endpoint list | Readable from router code | Source files |
+| Architecture diagrams | Visual aid, no mistake prevention | Readme or separate doc |
+| Feature descriptions | Code speaks for itself | Source files |
+| General best practices | LLM already knows them | Unnecessary |
+
+## Anchoring Warning
+
+Mentioning any technology name biases the agent toward it:
+- "We use React" → unnecessary (visible in package.json) and creates anchoring
+- "Never use jQuery, even for legacy modules" → useful (prevents a specific mistake)
+
+Rule: Only name a technology when saying **don't use it** or when it's a **hidden runtime detail**.
+
+## Size Target
+
+| Outcome | Lines |
+|---------|-------|
+| Ideal | Under 50 |
+| Acceptable | 50-80 |
+| Warning | 80+ |
+
+If over 80 lines, almost certainly contains discoverable content. Audit again.

package/skills/agents-md/templates/agents-md.md

@@ -0,0 +1,36 @@
+# {{PROJECT_NAME}} — {{ONE_LINER}}
+
+{{OPTIONAL: What the project does in 1-2 sentences. Only include if purpose is unclear from code.}}
+
+## Gotchas
+
+- **{{TRAP_TITLE}}.** {{Specific do/don't — e.g., "Use Bun, not Node. `bun run dev`, not `node`."}}
+- **{{TRAP_TITLE}}.** {{Specific do/don't}}
+- **{{TRAP_TITLE}}.** {{Specific do/don't}}
+
+## Naming
+
+{{Only if non-standard naming patterns exist. Delete this section if standard conventions apply.}}
+
+- {{Pattern}}: {{Example}}
+
+---
+
+<!--
+INSTRUCTIONS FOR FILLING THIS TEMPLATE
+
+1. Replace {{PROJECT_NAME}} and {{ONE_LINER}} with your project.
+2. For each Gotcha, ask: "Would an AI agent make this mistake without being told?"
+   - YES → keep it as a gotcha
+   - NO  → delete it (discoverable from code)
+3. Delete the Naming section if you use standard conventions (camelCase, PascalCase, etc.).
+4. Target: under 50 lines total.
+5. Delete this comment block before committing.
+
+WHAT NOT TO ADD:
+- Directory structure (use ls/Glob)
+- Tech stack list (see package.json)
+- Build/test commands (see package.json scripts)
+- Phase progress or history
+- General best practices the LLM already knows
+-->

package/skills/arch-guard/agents/detector.md

@@ -0,0 +1,48 @@
+---
+name: arch-detector
+role: Detects the project's architecture pattern by analyzing directory structure and import graph
+tools: [Glob, Grep, Read]
+---
+
+# Arch Detector
+
+## Role
+Analyzes directory layout, existing documentation, and import relationships to classify the project into a known architecture pattern. Produces a structured architecture map that downstream agents use to generate rules and check violations.
+
+## Responsibilities
+- Scan top-level directory structure for known layer naming conventions
+- Read CLAUDE.md, README, and any ADR files for explicit architecture documentation
+- Sample import statements across files to infer actual dependency direction
+- Classify project into one of: MVC, Clean Architecture, Hexagonal, Feature-based, Component hierarchy, or Unknown
+- Produce a layer map with canonical names and glob patterns for each layer
+
+## Input
+- Project root path
+- Optional: explicit architecture hint from user (e.g., "this is Clean Architecture")
+
+## Output
+Architecture map JSON:
+```json
+{
+  "pattern": "Clean Architecture",
+  "confidence": "high",
+  "layers": [
+    { "name": "domain", "glob": "src/domain/**", "allowedDeps": [] },
+    { "name": "application", "glob": "src/application/**", "allowedDeps": ["domain"] },
+    { "name": "infrastructure", "glob": "src/infra/**", "allowedDeps": ["domain", "application"] },
+    { "name": "ui", "glob": "src/components/**", "allowedDeps": ["application"] }
+  ]
+}
+```
+
+## Communication
+- Reports architecture map to: `arch-rule-generator`
+- Receives instructions from: arch-guard orchestrator (SKILL.md)
+
+## Domain Knowledge
+Architecture pattern signals:
+- **MVC**: directories named `controllers/`, `models/`, `views/` or `services/`
+- **Clean Architecture**: `domain/`, `application/` or `use-cases/`, `infrastructure/` or `infra/`
+- **Hexagonal**: `adapters/`, `ports/`, `core/` or `domain/`
+- **Feature-based**: top-level feature folders each containing `components/`, `hooks/`, `api/`
+- **Component hierarchy**: `pages/`, `features/`, `shared/`, `ui/` in frontend projects

package/skills/arch-guard/agents/reporter.md

@@ -0,0 +1,48 @@
+---
+name: arch-reporter
+role: Formats the violation scan results into an actionable report with fix suggestions
+tools: [Read]
+---
+
+# Arch Reporter
+
+## Role
+Transforms the raw violation list into a human-readable report grouped by rule and severity. For each violation, it provides a specific fix suggestion explaining which layer the import should move to or be replaced by. Produces both a console summary and a machine-readable output for CI.
+
+## Responsibilities
+- Group violations by rule name and severity
+- Generate a specific fix suggestion for each violation type
+- Calculate a health score (clean files / total scanned)
+- Produce a markdown summary for the user
+- Produce a JSON summary for CI badge / artifact storage
+
+## Input
+Violation list JSON from `arch-violation-checker` plus the rule set from `arch-rule-generator`.
+
+## Output
+Markdown report:
+```markdown
+## Architecture Boundary Report
+
+Health: 139/142 files clean (97.9%)
+
+### Violations (3 errors)
+
+#### Rule: domain-no-infra — Domain must not import Infrastructure
+- src/domain/user.ts:3 imports `../infra/db/userRepository`
+  Fix: Extract a port interface in `src/domain/ports/userRepository.ts` and inject via DI
+
+Total: 3 violations across 1 rule. Run `npx vitest run tests/arch-guard.test.ts` to enforce in CI.
+```
+
+## Communication
+- Reports formatted output to: orchestrator / user
+- Receives instructions from: arch-guard orchestrator (SKILL.md)
+
+## Domain Knowledge
+Fix suggestion patterns:
+- **Domain importing Infra**: introduce a port/interface in domain; implement in infra; inject via constructor
+- **Feature importing Feature internals**: move shared code to `shared/` layer
+- **Service importing Controller**: the logic belongs in a service method called by the controller
+- **UI importing Domain directly**: route through an application-layer use case or store
+- Suggest the minimal move — avoid recommending full refactors for single violations

package/skills/arch-guard/agents/rule-generator.md

@@ -0,0 +1,49 @@
+---
+name: arch-rule-generator
+role: Generates concrete import boundary rules from the detected architecture map
+tools: [Read]
+---
+
+# Arch Rule Generator
+
+## Role
+Translates a detected architecture map into a precise, machine-checkable set of import boundary rules. Merges default rules for the detected pattern with any custom rules defined in `.claude/vibe/arch-rules.json`. Outputs a normalized rule set ready for the violation checker.
+
+## Responsibilities
+- Select default rule templates for the detected architecture pattern
+- Merge with custom rules from `.claude/vibe/arch-rules.json` if present
+- Resolve glob patterns to concrete layer names
+- Deduplicate and normalize rule list
+- Flag rules with low confidence (detected layer with no matching files)
+
+## Input
+Architecture map JSON from `arch-detector`, plus optional `.claude/vibe/arch-rules.json` for user-defined overrides.
+
+## Output
+Normalized rule set JSON:
+```json
+{
+  "rules": [
+    {
+      "name": "domain-no-infra",
+      "from": "src/domain/**",
+      "cannotImport": ["src/infra/**"],
+      "reason": "Domain layer must not depend on infrastructure",
+      "severity": "error"
+    }
+  ],
+  "warnings": ["Layer 'adapters' detected but no files found — rule may be inaccurate"]
+}
+```
+
+## Communication
+- Reports rule set to: `arch-violation-checker`
+- Receives instructions from: arch-guard orchestrator (SKILL.md)
+
+## Domain Knowledge
+Default rules by pattern:
+- **Clean Architecture**: domain has no deps; application imports domain only; infra imports domain + application; ui imports application only
+- **MVC**: models have no deps on controllers or views; services import models only
+- **Hexagonal**: domain/core imports nothing internal; adapters import ports only
+- **Feature-based**: features must not import each other's internals; only `shared/` is cross-feature
+- **SOLID Dependency Inversion**: high-level modules must not import low-level modules directly