deuk-agent-rule 2.4.4 → 2.5.11

package/bundle/rules.d/deukrag-mcp.md

@@ -0,0 +1,31 @@
+---
+id: deukrag-mcp
+condition:
+  mcp: deukrag
+inject_target: ["AGENTS.md", "gemini.md"]
+---
+## 🧠 DeukRag Knowledge Engine & RAG-FIRST HARD LOCK
+
+- **[ABSOLUTE PRIORITY: RAG-FIRST ACTION] (하드룰)**: 
+  - 프롬프트에 응답하는 모든 액션에서 MCP(`mcp_deukrag_search_*`) 활용이 **0순위**입니다.
+  - 로컬 파일(`grep_search`, `view_file`)을 뒤지거나 코드를 수정하기 전에, **무조건** 관련된 룰, 티켓, 코드를 MCP로 먼저 검색하십시오. MCP는 당신의 주 감각 기관입니다.
+- **[CONTINUOUS RAG POLICY (하드룰)]**: 
+  - 티켓 시작(Phase 0) 시점에만 MCP를 1회 호출하고 끝내지 마십시오. 
+  - 코드를 작성하는 도중(Phase 2) 새로운 파일/클래스를 마주치거나, 빌드 에러가 발생하거나, API 스펙 확인이 필요할 때마다 **작업 중간에도 수시로** `mcp_deukrag_search_*` 도구를 적극 호출해야 합니다.
+  - **로컬 파일 검색에 의존하지 말고 RAG를 반복 호출하십시오.**
+
+## 📡 RAG Connectivity & Fallback Protocol (RAG 상태별 행동 지침)
+
+에이전트는 현재 환경의 RAG(MCP) 연결 상태에 따라 아래와 같이 행동 유형을 즉시 전환해야 합니다.
+
+### State A: RAG-Normal (Strict RAG-First)
+- **상태**: MCP 도구(`mcp_deukrag_search_*`)가 정상 작동함.
+- **행동**: 모든 분석과 코드 작성 전 반드시 RAG를 호출하십시오. 로컬 파일 검색(`grep`, `ls`)보다 RAG 결과를 우선 신뢰하십시오.
+
+### State B: RAG-Missing (Graceful Fallback)
+- **상태**: 환경에 MCP 도구가 설치되어 있지 않거나 설정되지 않음.
+- **행동**: 즉시 로컬 파일 기반 검색(`grep_search`, `list_dir`, `view_file`)으로 전환하십시오. RAG 부재를 사용자에게 불평하지 말고, 가용한 로컬 컨텍스트 내에서 최선을 다해 작업을 완수하십시오.
+
+### State C: RAG-Error (Loop Prevention)
+- **상태**: MCP 호출 시 타임아웃, 연결 오류, 또는 동일 에러가 2회 이상 반복됨.
+- **행동**: **즉시 RAG 호출을 중단**하고 State B(로컬 검색)로 강제 전환하십시오. 에러 루프에 빠져 작업 시간을 낭비하지 마십시오. 문제 상황을 `## 📜 Execution Report`에 기록하여 추후 복구 티켓을 발행할 수 있게 하십시오.

package/bundle/templates/TICKET_TEMPLATE.md

@@ -1,37 +1,52 @@
-# Task: [Task Title] | Ticket: [TICKET-XXX]
+# [Execution] Task: <%= meta.title %> | ID: <%= meta.id %>
 
-> **[CAUTION FOR AI AGENTS]** 
-> You are operating within a locked multi-module monorepo. 
+> **[CAUTION FOR AI AGENTS]**
+> You are operating within a locked multi-module monorepo.
 > 1. Restrict absolutely all analysis, file creation, and modifications to the declared **[Target Submodule]** below.
 > 2. Read the files listed in **[Context Files]** before doing ANY code generation.
 > 3. DO NOT leak configuration, logic, or dependencies from other submodules.
 
 ## 🎯 Scope Bounds
-
-- **Target Submodule:** `[e.g., DeukUI | DeukPack | DeukNavigation]`
+- **Target Submodule:** `<%- meta.submodule || '[e.g., DeukUI | DeukPack | DeukNavigation]' %>`
 - **Context Files:** 
   - `[e.g., DeukAgentRules/templates/MODULE_RULE_TEMPLATE.md]`
   - `[e.g., path/to/your/specific/rules.md]`
 
 ## 📁 Files to Modify
 - `path/from/root/to/target1`: [Specific instructions. Don't write 'refactor', describe WHAT to refactor.]
-- `path/from/root/to/target2`: [Instructions...]
 
-## 🏗️ Design Decisions (For Context)
-- [Why are we doing this? E.g., "To isolate the IR Layout bindings from DOM events"]
-- [What pattern to use?]
+## 🏗️ Design Decisions (Refer to Plan)
+- **Plan Reference**: <%- meta.planLink %>
+- [Briefly restate critical decisions if necessary]
 
 ## 🛑 Strict Constraints (Rules to never break)
-- [e.g., Do NOT remove existing @ts-nocheck headers]
-- [e.g., MUST retain C# [SerializeField] directives]
-- [e.g., Do NOT import Vue logic into DeukPack]
+- [e.g., No hotpath LINQ, Async Safety, No Raw Pointers]
 
 ## 🔄 Phased Execution Steps
-> Agent: Do NOT attempt to do Phase 3 before Phase 1 is fully tested. Use separate chat messages per phase if the task is large.
+> Agent: Do NOT attempt to do Phase 3 before Phase 1 is fully tested. 
+
+0. [Phase 0> RAG Research (MCP)]
+   - [ ] `mcp_deukrag_search_rules` 기반 규약 검토 완료
+   - [ ] `mcp_deukrag_search_tickets` 과거 유사 티켓 이력 열람 완료
+   - [ ] (필수 작성) 검색된 핵심 컨텍스트 요약: 
+0.5 [Phase 0.5> Deep Analysis (Optional)]
+   - [ ] 복잡한 아키텍처 변경 시 별도 분석 아티팩트 작성 및 승인 완료
 1. [Phase 1> Setup / Parsing]
 2. [Phase 2> Core Logic Change]
+   - [ ] (CONTINUOUS RAG) 새로운 함수/클래스 수정 전 `mcp_deukrag_search_code` 및 `search_rules`로 관련 패턴 수시 검색
 3. [Phase 3> Cleanup / Verification]
+   - [ ] (VERIFY RAG) 디버깅 및 에러 발생 시 로그 덤프 전 `mcp_deukrag_search_tickets` 로 과거 해결책 우선 탐색
+   - [ ] **Potential Issue Table**:
+     | 이슈 | 심각도 | 설명 | 조치 계획 |
+     |---|---|---|---|
+     | | | | |
+4. [Phase 4> Follow-up Chaining (MANDATORY if issues exist)]
+   - [ ] 위 표에서 즉시 해결 불가능한 항목에 대해 별도 티켓 발행 완료
+     > CLI Command Example: `deuk-agent-rule ticket create --topic 048-F1-fix-issue --title "Fix the issue" --group <group>`
+   - [ ] (필수 작성) 발행된 후속 티켓 번호 리스트:
 
 ## ✅ Verification / QA
-- [e.g., Check CLI command output `npm run test`]
-- [e.g., Validate Inspector mounts properly in Figma]
+- [ ] **Deep Analysis Verification**: Phase 0.5에서 도출된 핵심 설계 및 구조적 결정사항이 코드에 모두 올바르게 반영되었는지 확인.
+- [ ] **Potential Issues Check**: [Identify side effects, edge cases, or performance impacts]
+- [ ] **Strict Constraints Audit**: [No hotpath LINQ, Async Safety, No Raw Pointers, etc.]
+- [ ] `npm run test` 또는 관련 검증 명령 실행 결과 확인

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deuk-agent-rule",
-  "version": "2.4.4",
+  "version": "2.5.11",
   "description": "DeukAgentRules: generic AGENTS.md + .cursor rule templates with init/merge CLI (npm name: deuk-agent-rule).",
   "keywords": [
     "agents-md",
@@ -39,9 +39,7 @@
   "engines": {
     "node": ">=18"
   },
-  "bin": {
-    "deuk-agent-rule": "./scripts/cli.mjs"
-  },
+  "bin": {},
   "dependencies": {
     "ejs": "^5.0.2",
     "yaml": "^2.8.3"

package/scripts/cli-args.mjs

@@ -38,6 +38,7 @@ export function parseArgs(argv) {
     else if (a === "--backup") out.backup = true;
     else if (a === "--non-interactive") out.nonInteractive = true;
     else if (a === "--interactive") out.interactive = true;
+    else if (a === "--clean") out.clean = true;
     else if (a === "--tag") out.tag = argv[++i];
     else if (a === "--marker-begin") out.markerBegin = argv[++i];
     else if (a === "--marker-end") out.markerEnd = argv[++i];

package/scripts/cli-init-commands.mjs

@@ -1,20 +1,101 @@
-import { join } from "path";
-import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, readdirSync } from "fs";
+import { join, dirname, basename } from "path";
+import { existsSync, readFileSync, writeFileSync, mkdirSync, copyFileSync, readdirSync, unlinkSync, rmSync, renameSync } from "fs";
 import { resolveMarkers, resolveCursorrulesMarkers, applyAgents, applyRules, applyCursorrules, readBundleAgents } from "./merge-logic.mjs";
 import { ensureTicketDirAndGitignore } from "./cli-init-logic.mjs";
+import { normalizeTicketPaths } from "./cli-ticket-logic.mjs";
+import { compileDynamicRules } from "./cli-rule-compiler.mjs";
 import { loadInitConfig, writeInitConfig } from "./cli-utils.mjs";
 import { runInteractive } from "./cli-prompts.mjs";
 
+import { AGENT_ROOT_DIR, TICKET_SUBDIR, TEMPLATE_SUBDIR, RULES_SUBDIR, discoverAllSubmodules } from "./cli-utils.mjs";
+
+function migrateLegacyStructure(cwd, dryRun) {
+  const recursiveMerge = (src, dest) => {
+    if (!existsSync(src)) return;
+    if (!existsSync(dest)) {
+      if (!dryRun) {
+        mkdirSync(dirname(dest), { recursive: true });
+        renameSync(src, dest);
+      }
+      return;
+    }
+    // Both exist, merge contents
+    const entries = readdirSync(src, { withFileTypes: true });
+    for (const ent of entries) {
+      const sPath = join(src, ent.name);
+      const dPath = join(dest, ent.name);
+      if (ent.isDirectory()) {
+        recursiveMerge(sPath, dPath);
+      } else {
+        if (!existsSync(dPath)) {
+          if (!dryRun) renameSync(sPath, dPath);
+        } else {
+          // If destination exists, we could overwrite or skip. 
+          // For tickets, we skip to avoid data loss, but log it.
+          if (basename(sPath) !== "INDEX.json" && basename(sPath) !== "TICKET_LIST.md") {
+             // console.warn(`[MIGRATE] Skipping existing file: ${dPath}`);
+          }
+          if (!dryRun) unlinkSync(sPath); // Remove migrated/redundant file
+        }
+      }
+    }
+    // Clean up src if empty
+    try {
+      if (!dryRun && readdirSync(src).length === 0) rmSync(src, { recursive: true });
+    } catch {}
+  };
+
+  const legacyTemplates = join(cwd, ".deuk-agent-templates");
+  const newTemplates = join(cwd, AGENT_ROOT_DIR, TEMPLATE_SUBDIR);
+  if (existsSync(legacyTemplates)) {
+    console.log(`[MIGRATE] Merging legacy templates into ${AGENT_ROOT_DIR}/${TEMPLATE_SUBDIR}`);
+    recursiveMerge(legacyTemplates, newTemplates);
+  }
+
+  const legacyTickets = join(cwd, ".deuk-agent-ticket");
+  const legacyTicketsPlural = join(cwd, ".deuk-agent-tickets");
+  const newTickets = join(cwd, AGENT_ROOT_DIR, TICKET_SUBDIR);
+
+  if (existsSync(legacyTickets)) {
+    console.log(`[MIGRATE] Merging legacy singular ticket directory into ${AGENT_ROOT_DIR}/${TICKET_SUBDIR}`);
+    recursiveMerge(legacyTickets, newTickets);
+  }
+  if (existsSync(legacyTicketsPlural)) {
+    console.log(`[MIGRATE] Merging legacy plural tickets directory into ${AGENT_ROOT_DIR}/${TICKET_SUBDIR}`);
+    recursiveMerge(legacyTicketsPlural, newTickets);
+  }
+
+  const legacyConfig = join(cwd, ".deuk-agent-rule.config.json");
+  const newConfig = join(cwd, AGENT_ROOT_DIR, "config.json");
+  if (existsSync(legacyConfig) && !existsSync(newConfig)) {
+    console.log(`[MIGRATE] Moving legacy config to ${AGENT_ROOT_DIR}/config.json`);
+    if (!dryRun) {
+      mkdirSync(join(cwd, AGENT_ROOT_DIR), { recursive: true });
+      renameSync(legacyConfig, newConfig);
+    }
+  }
+
+  // 3. Clean up redundant legacy pointer files from the target directory
+  if (existsSync(newTickets)) {
+    for (const file of ["ACTIVE_TICKET.md", "ACTIVE_TICKET.json", "LATEST.md"]) {
+      const p = join(newTickets, file);
+      if (existsSync(p)) {
+        console.log(`[MIGRATE] Removing redundant pointer file: ${file}`);
+        if (!dryRun) unlinkSync(p);
+      }
+    }
+  }
+}
+
 function syncTemplates(cwd, bundleRoot, dryRun) {
   const tplSrcDir = join(bundleRoot, "templates");
-  const tplDestDir = join(cwd, ".deuk-agent-templates");
+  const tplDestDir = join(cwd, AGENT_ROOT_DIR, TEMPLATE_SUBDIR);
   if (!existsSync(tplSrcDir)) return;
   if (!dryRun) mkdirSync(tplDestDir, { recursive: true });
 
   const srcFiles = readdirSync(tplSrcDir).filter(n => n.endsWith(".md"));
   const destFiles = existsSync(tplDestDir) ? readdirSync(tplDestDir).filter(n => n.endsWith(".md")) : [];
 
-  // 1. Copy/Update new templates
   for (const name of srcFiles) {
     const src = join(tplSrcDir, name);
     const dest = join(tplDestDir, name);
@@ -22,51 +103,177 @@ function syncTemplates(cwd, bundleRoot, dryRun) {
     console.log(`template synced: ${dest}`);
   }
 
-  // 2. Cleanup obsolete templates (Migration)
   for (const name of destFiles) {
     if (!srcFiles.includes(name)) {
       const obsolete = join(tplDestDir, name);
-      if (!dryRun) {
-        import("fs").then(fs => fs.unlinkSync(obsolete));
-      }
+      if (!dryRun) unlinkSync(obsolete);
       console.log(`template removed (obsolete): ${obsolete}`);
     }
   }
 }
 
+const SPOKE_REGISTRY = [
+  {
+    id: "cursor",
+    detect: (cwd) => existsSync(join(cwd, ".cursor")),
+    legacy: ".cursorrules",
+    target: ".cursor/rules/deuk-agent.mdc",
+    format: "mdc",
+  },
+  {
+    id: "claude",
+    detect: (cwd) => existsSync(join(cwd, "CLAUDE.md")) || existsSync(join(cwd, ".claude")),
+    legacy: null,
+    target: "CLAUDE.md",
+    format: "markdown",
+  },
+  {
+    id: "copilot",
+    detect: (cwd) => existsSync(join(cwd, ".github")),
+    legacy: null,
+    target: ".github/copilot-instructions.md",
+    format: "markdown",
+  },
+  {
+    id: "windsurf",
+    detect: (cwd) => existsSync(join(cwd, ".windsurf")),
+    legacy: ".windsurfrules",
+    target: ".windsurf/rules/deuk-agent.md",
+    format: "markdown",
+  },
+  {
+    id: "jetbrains",
+    detect: (cwd) => existsSync(join(cwd, ".aiassistant")) || existsSync(join(cwd, ".idea")),
+    legacy: null,
+    target: ".aiassistant/rules/deuk-agent.md",
+    format: "markdown",
+  },
+  {
+    id: "antigravity",
+    detect: (cwd) => existsSync(join(cwd, "gemini.md")) || existsSync(join(cwd, ".gemini")),
+    legacy: null,
+    target: "gemini.md",
+    format: "markdown",
+  },
+];
+
+function generateSpokeContent(spoke) {
+  const commonContent = `# Deuk Agent Rules
+
+This project follows the Deuk Agent Rules framework.
+- Read the full rules: [AGENTS.md](../../AGENTS.md)
+- Module-specific rules: [.deuk-agent/rules/](../../.deuk-agent/rules/)
+
+## Critical Rules
+- Use \`.deuk-agent/templates/TICKET_TEMPLATE.md\` for multi-step tasks.
+- RAG-First: Use MCP tools before local file search when available.
+- Error Loop Prevention: Stop after 2 repeated errors, create a ticket.
+`;
+
+  if (spoke.format === "mdc") {
+    return `---
+description: "Deuk Agent Rules - Project conventions and ticket workflow"
+globs: ["**/*"]
+alwaysApply: true
+---
+${commonContent}`;
+  }
+  return `<!-- deuk-agent-rule:begin -->\n${commonContent}\n<!-- deuk-agent-rule:end -->\n`;
+}
+
+function generateLegacyDeprecationNotice(spoke) {
+  return `<!-- deuk-agent-rule:deprecated -->
+This file is deprecated. Rules have moved to:
+- Target: ${spoke.target}
+- All agents: AGENTS.md
+<!-- deuk-agent-rule:deprecated:end -->
+`;
+}
+
+function deploySpokePointers(cwd, dryRun) {
+  for (const spoke of SPOKE_REGISTRY) {
+    if (!spoke.detect(cwd)) continue;
+    
+    const targetPath = join(cwd, spoke.target);
+    const targetDir = dirname(targetPath);
+    
+    if (!dryRun) {
+      mkdirSync(targetDir, { recursive: true });
+      writeFileSync(targetPath, generateSpokeContent(spoke), "utf8");
+    }
+    console.log(`spoke synced: ${spoke.target} (${spoke.id})`);
+    
+    // Deprecate legacy file if it exists
+    if (spoke.legacy) {
+      const legacyPath = join(cwd, spoke.legacy);
+      if (existsSync(legacyPath)) {
+        if (!dryRun) writeFileSync(legacyPath, generateLegacyDeprecationNotice(spoke), "utf8");
+        console.log(`spoke deprecated: ${spoke.legacy} -> ${spoke.target}`);
+      }
+    }
+  }
+}
 
 export async function runInit(opts, bundleRoot) {
+  const submodules = discoverAllSubmodules(opts.cwd);
+  if (!submodules.includes(opts.cwd)) submodules.push(opts.cwd);
+
   const markers = resolveMarkers(opts);
-  const agentsResult = applyAgents({
-    targetPath: join(opts.cwd, "AGENTS.md"),
-    bundleContent: readBundleAgents(bundleRoot),
-    markers, flavor: "init",
-    appendIfNoMarkers: opts.appendIfNoMarkers,
-    dryRun: opts.dryRun, backup: opts.backup,
-    agentsMode: opts.agents || "inject"
-  });
-  console.log(`AGENTS.md: ${agentsResult.action} (${agentsResult.mode || ""})`);
+  const bundleAgents = readBundleAgents(bundleRoot);
 
-  const ruleActions = applyRules({
-    bundleRulesDir: join(bundleRoot, "rules"),
-    targetRulesDir: join(opts.cwd, ".cursor", "rules"),
-    rulesMode: opts.rules || "prefix",
-    dryRun: opts.dryRun, backup: opts.backup
-  });
-  ruleActions.forEach(r => console.log(`rule ${r.action}: ${r.dest || r.src}`));
+  for (const subCwd of submodules) {
+    console.log(`\nInitializing ${basename(subCwd)}...`);
+    
+    // 1. Migration & Directory Setup
+    migrateLegacyStructure(subCwd, opts.dryRun);
+    ensureTicketDirAndGitignore({ ...opts, cwd: subCwd });
+    
+    // 2. Normalize INDEX.json paths (fix stale paths)
+    normalizeTicketPaths(subCwd, { silent: false });
 
-  const crResult = applyCursorrules({
-    bundleRoot, cwd: opts.cwd,
-    markers: resolveCursorrulesMarkers({}),
-    cursorrulesMode: opts.cursorrules || "inject",
-    dryRun: opts.dryRun, backup: opts.backup
-  });
-  console.log(`.cursorrules: ${crResult.action} (${crResult.mode || ""})`);
+    // 3. Spoke Pointers (e.g. .cursor/rules/deuk-agent.mdc)
+    deploySpokePointers(subCwd, opts.dryRun);
 
-  ensureTicketDirAndGitignore(opts);
-  syncTemplates(opts.cwd, bundleRoot, opts.dryRun);
+    // 4. Agents Setup (AGENTS.md)
+    const compiledAgentsAdditions = compileDynamicRules(subCwd, bundleRoot, "AGENTS.md");
+    const fullBundleAgents = bundleAgents + "\n\n" + compiledAgentsAdditions;
+
+    const agentsResult = applyAgents({
+      targetPath: join(subCwd, "AGENTS.md"),
+      bundleContent: fullBundleAgents,
+      markers, flavor: "init",
+      appendIfNoMarkers: opts.appendIfNoMarkers,
+      dryRun: opts.dryRun, backup: opts.backup,
+      agentsMode: opts.agents || "inject"
+    });
+    console.log(`AGENTS.md: ${agentsResult.action}`);
+
+    // 5. Hub Rules Sync (.deuk-agent/rules/)
+    const hubRulesDir = join(subCwd, AGENT_ROOT_DIR, RULES_SUBDIR);
+    if (!opts.dryRun) mkdirSync(hubRulesDir, { recursive: true });
+    applyRules({
+      bundleRulesDir: join(bundleRoot, "rules"),
+      targetRulesDir: hubRulesDir,
+      rulesMode: opts.rules || "overwrite",
+      dryRun: opts.dryRun, backup: opts.backup
+    });
+
+    // 6. Gemini Rule Sync (root rule)
+    const geminiBundle = join(bundleRoot, "gemini.md");
+    const geminiDest = join(subCwd, "gemini.md");
+    if (existsSync(geminiBundle)) {
+      const baseGemini = readFileSync(geminiBundle, "utf8");
+      const compiledGeminiAdditions = compileDynamicRules(subCwd, bundleRoot, "gemini.md");
+      if (!opts.dryRun) {
+        writeFileSync(geminiDest, baseGemini + "\n\n" + compiledGeminiAdditions, "utf8");
+      }
+      console.log(`gemini.md: synced with dynamic rules`);
+    }
+
+    // 7. Templates Sync (.deuk-agent/templates/)
+    syncTemplates(subCwd, bundleRoot, opts.dryRun);
+  }
 
-  // If no config exists, save the derived/default config to ensure persistency
   if (!loadInitConfig(opts.cwd)) {
     writeInitConfig(opts.cwd, opts);
   }
@@ -84,21 +291,14 @@ export function runMerge(opts, bundleRoot) {
   });
   console.log(`AGENTS.md: ${agentsResult.action} (${agentsResult.mode || ""})`);
 
+  const hubRulesDir = join(opts.cwd, AGENT_ROOT_DIR, RULES_SUBDIR);
   const ruleActions = applyRules({
     bundleRulesDir: join(bundleRoot, "rules"),
-    targetRulesDir: join(opts.cwd, ".cursor", "rules"),
+    targetRulesDir: hubRulesDir,
     rulesMode: opts.rules || "skip",
     dryRun: opts.dryRun, backup: opts.backup
   });
-  ruleActions.forEach(r => console.log(`rule ${r.action}: ${r.dest || r.src}`));
-
-  const crResult = applyCursorrules({
-    bundleRoot, cwd: opts.cwd,
-    markers: resolveCursorrulesMarkers({}),
-    cursorrulesMode: opts.cursorrules || "inject",
-    dryRun: opts.dryRun, backup: opts.backup
-  });
-  console.log(`.cursorrules: ${crResult.action} (${crResult.mode || ""})`);
+  ruleActions.forEach(r => console.log(`hub rule ${r.action}: ${r.dest || r.src}`));
 
   syncTemplates(opts.cwd, bundleRoot, opts.dryRun);
 }

package/scripts/cli-init-logic.mjs

@@ -1,25 +1,46 @@
 import { existsSync, appendFileSync, writeFileSync, mkdirSync, readFileSync } from "fs";
 import { join } from "path";
-import { TICKET_DIR_NAME } from "./cli-ticket-logic.mjs";
+import { AGENT_ROOT_DIR, TICKET_DIR_NAME } from "./cli-utils.mjs";
 
-const GITIGNORE_TICKET_MARKER = "# deuk-agent-rule: ticket directory (local, not committed by default)";
+const GITIGNORE_AGENT_MARKER = "# deuk-agent-rule: agent hub directory (local, not committed by default)";
 
 export function ensureTicketDirAndGitignore(opts) {
   const ticketPath = join(opts.cwd, TICKET_DIR_NAME);
   const gitignorePath = join(opts.cwd, ".gitignore");
-  const ignoreLine = TICKET_DIR_NAME + "/";
+  const ignoreLine = AGENT_ROOT_DIR + "/";
 
   if (opts.dryRun) return;
 
   mkdirSync(ticketPath, { recursive: true });
   if (opts.shareTickets) {
-    console.log(`[INIT] Ticket sharing enabled. Skipping .gitignore entry for ${TICKET_DIR_NAME}/`);
+    console.log(`[INIT] Ticket sharing enabled. Skipping .gitignore entry for ${AGENT_ROOT_DIR}/`);
     return;
   }
 
   let gi = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf8") : "";
-  if (!gi.includes(ignoreLine)) {
-    const block = "\n" + GITIGNORE_TICKET_MARKER + "\n" + ignoreLine + "\n";
+  
+  // 1. Create document directories
+  const docsPath = join(opts.cwd, AGENT_ROOT_DIR, "docs");
+  mkdirSync(join(docsPath, "plans"), { recursive: true });
+  mkdirSync(join(docsPath, "walkthroughs"), { recursive: true });
+  mkdirSync(join(docsPath, "scratch"), { recursive: true });
+
+  // 2. Ignore docs/scratch/ always
+  const scratchIgnoreLine = `${AGENT_ROOT_DIR}/docs/scratch/`;
+  if (!gi.includes(scratchIgnoreLine)) {
+    appendFileSync(gitignorePath, "\n" + scratchIgnoreLine + "\n", "utf8");
+    console.log(`[INIT] Added ${scratchIgnoreLine} to .gitignore`);
+    gi += "\n" + scratchIgnoreLine + "\n";
+  }
+
+  // Also check for legacy ignore lines to clean up or at least check presence
+  const legacyIgnore1 = ".deuk-agent-ticket/";
+  const legacyIgnore2 = ".deuk-agent-tickets/";
+  const legacyIgnore3 = ".deuk-agent/tickets/";
+
+  if (!gi.includes(ignoreLine) && !opts.shareTickets) {
+    const block = "\n" + GITIGNORE_AGENT_MARKER + "\n" + ignoreLine + "\n";
     appendFileSync(gitignorePath, block, "utf8");
+    console.log(`[INIT] Added ${ignoreLine} to .gitignore`);
   }
 }

package/scripts/cli-rule-compiler.mjs

@@ -0,0 +1,102 @@
+import { join, basename, resolve, dirname } from "path";
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { parseFrontMatter, AGENT_ROOT_DIR } from "./cli-utils.mjs";
+import YAML from "yaml";
+
+/**
+ * Scans directories for rule markdown files, evaluates their Frontmatter conditions,
+ * and compiles a single rule string for injection.
+ */
+export function compileDynamicRules(cwd, bundleRoot, targetFileName) {
+  const bundleRulesDir = join(bundleRoot, "rules.d");
+  const localRulesDir = join(cwd, AGENT_ROOT_DIR, "domain-rules");
+  
+  const allRuleFiles = [];
+  
+  // 1. Gather global rules
+  if (existsSync(bundleRulesDir)) {
+    readdirSync(bundleRulesDir).forEach(f => {
+      if (f.endsWith(".md")) allRuleFiles.push(join(bundleRulesDir, f));
+    });
+  }
+  
+  // 2. Gather local domain rules
+  if (existsSync(localRulesDir)) {
+    readdirSync(localRulesDir).forEach(f => {
+      if (f.endsWith(".md")) allRuleFiles.push(join(localRulesDir, f));
+    });
+  }
+
+  let compiledContent = "";
+
+  for (const filePath of allRuleFiles) {
+    const rawContent = readFileSync(filePath, "utf8");
+    const { meta, content } = parseFrontMatter(rawContent);
+    
+    // Check if this rule is intended for the current target file (e.g., AGENTS.md)
+    if (meta.inject_target && !meta.inject_target.includes(targetFileName)) {
+      continue;
+    }
+
+    // Evaluate conditions
+    let shouldInclude = true;
+    if (meta.condition) {
+      shouldInclude = evaluateCondition(meta.condition, cwd);
+    }
+    
+    if (shouldInclude) {
+      const sourceId = meta.id || basename(filePath);
+      compiledContent += `\n<!-- RULE MODULE: ${sourceId} -->\n`;
+      compiledContent += content.trim() + "\n";
+    }
+  }
+
+  return compiledContent.trim();
+}
+
+/**
+ * Attempts to locate and parse the DeukRag config.yaml from the workspace root.
+ */
+function resolveDeukRagConfig(cwd) {
+  // Go up directories until we find a sibling DeukRag folder, or hit root
+  let current = resolve(cwd);
+  while (current && current !== "/") {
+    const candidatePath = join(current, "DeukRag", ".local", "config.yaml");
+    if (existsSync(candidatePath)) {
+      try {
+        const raw = readFileSync(candidatePath, "utf8");
+        return YAML.parse(raw);
+      } catch (e) {
+        console.error("Failed to parse DeukRag config.yaml:", e);
+        return null;
+      }
+    }
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+
+/**
+ * Evaluates Frontmatter conditions to determine if a rule should be included.
+ */
+function evaluateCondition(condition, cwd) {
+  if (!condition) return true;
+
+  // Example: condition: { mcp: "deukrag" }
+  if (condition.mcp === "deukrag") {
+    const ragConfig = resolveDeukRagConfig(cwd);
+    if (!ragConfig || !ragConfig.projects) return false;
+
+    // Check if the current cwd is managed by DeukRag
+    const isManaged = ragConfig.projects.some(p => {
+      // If the project path is a prefix of cwd, it's managed
+      return cwd.startsWith(p.path);
+    });
+    
+    return isManaged;
+  }
+
+  return true;
+}