moai-adk 0.3.9__tar.gz → 0.3.11__tar.gz

{moai_adk-0.3.9 → moai_adk-0.3.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moai-adk
-Version: 0.3.9
+Version: 0.3.11
 Summary: MoAI Agentic Development Kit - SPEC-First TDD with Alfred SuperAgent
 Project-URL: Homepage, https://github.com/modu-ai/moai-adk
 Project-URL: Repository, https://github.com/modu-ai/moai-adk

{moai_adk-0.3.9 → moai_adk-0.3.11}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "moai-adk"
-version = "0.3.9"
+version = "0.3.11"
 description = "MoAI Agentic Development Kit - SPEC-First TDD with Alfred SuperAgent"
 readme = "README.md"
 requires-python = ">=3.13"

{moai_adk-0.3.9 → moai_adk-0.3.11}/src/moai_adk/__init__.py

@@ -4,5 +4,5 @@
 SPEC-First TDD Framework with Alfred SuperAgent
 """
 
-__version__ = "0.3.9"
+__version__ = "0.3.11"
 __all__ = ["__version__"]

{moai_adk-0.3.9 → moai_adk-0.3.11}/src/moai_adk/__main__.py

@@ -6,7 +6,7 @@ Implements the CLI entry point:
 - Rich console terminal output
 - ASCII logo rendering
 - --version and --help options
-- Six core commands: init, doctor, status, backup, restore, update
+- Five core commands: init, doctor, status, backup, update
 """
 
 import sys
@@ -19,7 +19,6 @@ from moai_adk import __version__
 from moai_adk.cli.commands.backup import backup
 from moai_adk.cli.commands.doctor import doctor
 from moai_adk.cli.commands.init import init
-from moai_adk.cli.commands.restore import restore
 from moai_adk.cli.commands.status import status
 from moai_adk.cli.commands.update import update
 
@@ -58,7 +57,6 @@ def cli(ctx: click.Context) -> None:
 cli.add_command(init)
 cli.add_command(doctor)
 cli.add_command(status)
-cli.add_command(restore)
 cli.add_command(backup)
 cli.add_command(update)
 

{moai_adk-0.3.9 → moai_adk-0.3.11}/src/moai_adk/cli/commands/__init__.py

@@ -1,16 +1,20 @@
 # @CODE:CLI-001 | SPEC: SPEC-CLI-001.md | TEST: tests/unit/test_cli_commands.py
 """CLI command module
 
-Four core commands:
+Core commands:
 - init: initialize the project
 - doctor: run system diagnostics
 - status: show project status
-- restore: restore backups
+- update: update templates to latest version
+- backup: create project backups
+
+Note: restore functionality is handled by checkpoint system in core.git.checkpoint
 """
 
+from moai_adk.cli.commands.backup import backup
 from moai_adk.cli.commands.doctor import doctor
 from moai_adk.cli.commands.init import init
-from moai_adk.cli.commands.restore import restore
 from moai_adk.cli.commands.status import status
+from moai_adk.cli.commands.update import update
 
-__all__ = ["init", "doctor", "status", "restore"]
+__all__ = ["init", "doctor", "status", "update", "backup"]

{moai_adk-0.3.9 → moai_adk-0.3.11}/src/moai_adk/cli/commands/init.py

@@ -15,7 +15,6 @@ from typing import Sequence
 import click
 from rich.console import Console
 from rich.progress import BarColumn, Progress, SpinnerColumn, TaskID, TextColumn
-from rich.prompt import Confirm
 
 from moai_adk import __version__
 from moai_adk.cli.prompts import prompt_project_setup
@@ -134,45 +133,20 @@ def init(
 
             console.print("\n[cyan]🚀 Starting installation...[/cyan]\n")
 
-        # 4. Check for reinitialization (SPEC-INIT-003 v0.3.0)
+        # 4. Check for reinitialization (SPEC-INIT-003 v0.3.0) - DEFAULT TO FORCE MODE
         initializer = ProjectInitializer(project_path)
 
         if initializer.is_initialized():
-            if non_interactive and not force:
-                # Non-interactive mode (without force): Reject reinitialization
-                console.print("\n[yellow]⚠ Project already initialized[/yellow]")
-                console.print(f"[dim]  Location: {project_path}/.moai/[/dim]")
-                console.print("[dim]  Use --force to reinitialize or interactive mode[/dim]\n")
-                raise click.Abort()
-
-            if force:
-                # Force mode: Reinitialize without confirmation
-                console.print("\n[green]🔄 Force reinitializing project...[/green]\n")
+            # Always reinitialize without confirmation (force mode by default)
+            if non_interactive:
+                console.print("\n[green]🔄 Reinitializing project (force mode)...[/green]\n")
             else:
-                # Interactive mode: Reinitialization prompt
-                console.print("\n⚠️  [yellow]Project already initialized[/yellow]")
-                console.print(f"   Location: {project_path}/.moai/\n")
-
-                console.print("[cyan]This will:[/cyan]")
-                console.print("  ✓ Backup existing files to .moai-backups/{timestamp}/")
-                console.print("    • CLAUDE.md")
-                console.print("    • .claude/ (settings, commands, hooks)")
-                console.print("    • .moai/ (all configurations and specs)")
-                console.print("  ✓ Update template files from moai-adk v0.3.0")
-                console.print("    • .claude/ → Latest Alfred commands")
-                console.print("    • .moai/memory/ → Latest development guides")
-                console.print("    • CLAUDE.md → Latest project documentation")
-                console.print("  ✓ Preserve your content")
-                console.print("    • .moai/project/ (product/structure/tech.md)")
-                console.print("    • .moai/specs/ (all SPEC documents)\n")
-
-                if not Confirm.ask("Would you like to update the project templates?", default=True):
-                    console.print("\n[yellow]Reinit cancelled.[/yellow]\n")
-                    raise click.Abort()
-
-                console.print("\n[green]🔄 Starting reinit process...[/green]\n")
+                # Interactive mode: Simple notification
+                console.print("\n[cyan]🔄 Reinitializing project...[/cyan]")
+                console.print("   Backup will be created at .moai-backups/{timestamp}/\n")
 
         # 5. Initialize project (Progress Bar with 5 phases)
+        # Always allow reinit (force mode by default)
         is_reinit = initializer.is_initialized()
 
         # Reinit mode: set config.json optimized to false (v0.3.1+)
@@ -220,7 +194,7 @@ def init(
                 language=language,
                 backup_enabled=True,
                 progress_callback=callback,
-                reinit=is_reinit,  # SPEC-INIT-003 v0.3.0
+                reinit=True,  # Always allow reinit (force mode by default)
             )
 
         # 6. Output results
@@ -241,7 +215,25 @@ def init(
                 f"  [dim]📄 Files:[/dim]     {len(result.created_files)} created"
             )
             console.print(f"  [dim]⏱️  Duration:[/dim]  {result.duration}ms")
+
+            # Show backup info if reinitialized
+            if is_reinit:
+                backup_dir = project_path / ".moai-backups"
+                if backup_dir.exists():
+                    latest_backup = max(backup_dir.iterdir(), key=lambda p: p.stat().st_mtime)
+                    console.print(f"  [dim]💾 Backup:[/dim]    {latest_backup.name}/")
+
             console.print(f"\n{separator}")
+
+            # Show config merge notice if reinitialized
+            if is_reinit:
+                console.print("\n[yellow]⚠️  Configuration Notice:[/yellow]")
+                console.print("  All template files have been [bold]force overwritten[/bold]")
+                console.print("  Previous files are backed up in [cyan].moai-backups/{timestamp}/[/cyan]")
+                console.print("\n  [cyan]To merge your previous config:[/cyan]")
+                console.print("  Run [bold]/alfred:0-project[/bold] command in Claude Code")
+                console.print("  It will merge backup config when [dim]optimized=false[/dim]\n")
+
             console.print("\n[cyan]🚀 Next Steps:[/cyan]")
             if not is_current_dir:
                 console.print(

{moai_adk-0.3.9 → moai_adk-0.3.11}/src/moai_adk/core/template/processor.py

@@ -23,7 +23,8 @@ class TemplateProcessor:
         ".moai/specs/",  # User SPEC documents
         ".moai/reports/",  # User reports
         ".moai/project/",  # User project documents (product/structure/tech.md)
-        ".moai/config.json",  # User configuration (merged via /alfred:9-update flow)
+        # config.json is now FORCE OVERWRITTEN (backup in .moai-backups/)
+        # Merge via /alfred:0-project when optimized=false
     ]
 
     # Paths excluded from backups
@@ -277,7 +278,7 @@ class TemplateProcessor:
                 if not silent:
                     console.print(f"   ✅ .claude/{folder}/ overwritten")
 
-        # 2. Copy other files/folders individually (preserve existing, with substitution)
+        # 2. Copy other files/folders individually (FORCE OVERWRITE all files)
         all_warnings = []
         for item in src.iterdir():
             rel_path = item.relative_to(src)
@@ -288,16 +289,12 @@ class TemplateProcessor:
                 continue
 
             if item.is_file():
-                # Copy file, skip if exists (preserve user modifications)
-                if not dst_item.exists():
-                    # Copy with variable substitution for text files
-                    warnings = self._copy_file_with_substitution(item, dst_item)
-                    all_warnings.extend(warnings)
+                # FORCE OVERWRITE: Always copy files (no skip)
+                warnings = self._copy_file_with_substitution(item, dst_item)
+                all_warnings.extend(warnings)
             elif item.is_dir():
-                # Copy directory recursively (preserve existing files)
-                if not dst_item.exists():
-                    # Recursively copy directory with substitution
-                    self._copy_dir_with_substitution(item, dst_item)
+                # FORCE OVERWRITE: Always copy directories (no skip)
+                self._copy_dir_with_substitution(item, dst_item)
 
         # Print warnings if any
         if all_warnings and not silent:
@@ -308,31 +305,6 @@ class TemplateProcessor:
         if not silent:
             console.print("   ✅ .claude/ copy complete (variables substituted)")
 
-    def _backup_alfred_folder(self, folder_path: Path, folder_name: str) -> None:
-        """Backup an Alfred folder before overwriting (safety measure).
-
-        Args:
-            folder_path: Path to the folder to backup.
-            folder_name: Name of the folder (e.g., "hooks/alfred").
-        """
-        if not folder_path.exists():
-            return
-
-        # Create backup directory in .moai-backups/.claude-backups/{timestamp}/
-        backup_base = self.target_path / ".moai-backups" / ".claude-backups"
-        backup_base.mkdir(parents=True, exist_ok=True)
-
-        # Generate timestamp-based backup directory
-        from moai_adk.core.project.backup_utils import generate_backup_dir_name
-
-        timestamp = generate_backup_dir_name()
-        backup_dir = backup_base / timestamp
-
-        # Backup this specific folder
-        backup_folder = backup_dir / folder_name
-        backup_folder.parent.mkdir(parents=True, exist_ok=True)
-        shutil.copytree(folder_path, backup_folder)
-
     def _copy_moai(self, silent: bool = False) -> None:
         """.moai/ directory copy with variable substitution (excludes protected paths)."""
         src = self.template_root / ".moai"
@@ -362,9 +334,7 @@ class TemplateProcessor:
 
             dst_item = dst / rel_path
             if item.is_file():
-                # Skip existing files to preserve user content (v0.3.0)
-                if dst_item.exists():
-                    continue
+                # FORCE OVERWRITE: Always copy files (no skip)
                 dst_item.parent.mkdir(parents=True, exist_ok=True)
                 # Copy with variable substitution
                 warnings = self._copy_file_with_substitution(item, dst_item)
@@ -382,7 +352,7 @@ class TemplateProcessor:
             console.print("   ✅ .moai/ copy complete (variables substituted)")
 
     def _copy_claude_md(self, silent: bool = False) -> None:
-        """Copy CLAUDE.md with smart merging and variable substitution."""
+        """Copy CLAUDE.md with FORCE OVERWRITE."""
         src = self.template_root / "CLAUDE.md"
         dst = self.target_path / "CLAUDE.md"
 
@@ -391,16 +361,10 @@ class TemplateProcessor:
                 console.print("⚠️ CLAUDE.md template not found")
             return
 
-        # Preserve project information when the file exists
-        if dst.exists():
-            self._merge_claude_md(src, dst)
-            if not silent:
-                console.print("   🔄 CLAUDE.md merged (project information preserved)")
-        else:
-            # Copy with variable substitution
-            self._copy_file_with_substitution(src, dst)
-            if not silent:
-                console.print("   ✅ CLAUDE.md copy complete")
+        # FORCE OVERWRITE: Always copy template (backup already created in Phase 1)
+        self._copy_file_with_substitution(src, dst)
+        if not silent:
+            console.print("   ✅ CLAUDE.md overwritten (backup available in .moai-backups/)")
 
     def _merge_claude_md(self, src: Path, dst: Path) -> None:
         """Delegate the smart merge for CLAUDE.md.

{moai_adk-0.3.9 → moai_adk-0.3.11}/src/moai_adk/templates/.claude/hooks/alfred/core/__init__.py

@@ -77,3 +77,9 @@ class HookResult:
 
 
 __all__ = ["HookPayload", "HookResult"]
+
+# Note: core module exports:
+# - HookPayload, HookResult (type definitions)
+# - project.py: detect_language, get_git_info, count_specs, get_project_language
+# - context.py: get_jit_context
+# - checkpoint.py: detect_risky_operation, create_checkpoint, log_checkpoint, list_checkpoints

{moai_adk-0.3.9 → moai_adk-0.3.11}/src/moai_adk/templates/.claude/hooks/alfred/core/context.py

@@ -1,15 +1,10 @@
 #!/usr/bin/env python3
 """Context Engineering utilities
 
-JIT (Just-in-Time) Retrieval 및 워크플로우 컨텍스트 관리
+JIT (Just-in-Time) Retrieval
 """
 
-import time
 from pathlib import Path
-from typing import Any
-
-# Workflow context shared across phases
-_workflow_context: dict[str, Any] = {}
 
 
 def get_jit_context(prompt: str, cwd: str) -> list[str]:
@@ -69,42 +64,4 @@ def get_jit_context(prompt: str, cwd: str) -> list[str]:
     return context_files
 
 
-def save_phase_context(phase: str, data: dict):
-    """Store per-phase workflow context data.
-
-    Args:
-        phase: ``"analysis"``, ``"implementation"`` or ``"verification"``.
-        data: Payload to share with later phases.
-
-    Notes:
-        - Enables reuse of expensive analysis across phases.
-        - Entries expire after 10 minutes to avoid stale data.
-    """
-    _workflow_context[phase] = {"data": data, "timestamp": time.time()}
-
-
-def load_phase_context(phase: str) -> dict | None:
-    """Load previously stored workflow context for a phase.
-
-    Returns:
-        Stored context data or ``None`` when expired or missing.
-    """
-    if phase in _workflow_context:
-        ctx = _workflow_context[phase]
-        # Only accept entries that are younger than 10 minutes
-        if time.time() - ctx["timestamp"] < 600:
-            return ctx["data"]
-    return None
-
-
-def clear_workflow_context():
-    """Clear all cached workflow context (call at workflow end)."""
-    _workflow_context.clear()
-
-
-__all__ = [
-    "get_jit_context",
-    "save_phase_context",
-    "load_phase_context",
-    "clear_workflow_context",
-]
+__all__ = ["get_jit_context"]

{moai_adk-0.3.9 → moai_adk-0.3.11}/src/moai_adk/templates/.claude/settings.json

@@ -86,7 +86,9 @@
       "Bash(uv remove:*)",
       "Bash(pip install:*)",
       "Bash(pip3 install:*)",
-      "Bash(rm:*)"
+      "Bash(rm:*)",
+      "Bash(sudo:*)",
+      "Bash(rm -rf:*)"
     ],
     "deny": [
       "Read(./.env)",
@@ -95,8 +97,13 @@
       "Read(~/.ssh/**)",
       "Read(~/.aws/**)",
       "Read(~/.config/gcloud/**)",
-      "Bash(sudo:*)",
-      "Bash(rm -rf:*)",
+      "Bash(rm -rf /:*)",
+      "Bash(rm -rf /*:*)",
+      "Bash(rm -rf C\\:/:*)",
+      "Bash(rm -rf C\\:/*:*)",
+      "Bash(del /S /Q C\\:/:*)",
+      "Bash(rmdir /S /Q C\\:/:*)",
+      "Bash(format:*)",
       "Bash(chmod -R 777:*)",
       "Bash(dd:*)",
       "Bash(mkfs:*)",

moai_adk-0.3.9/src/moai_adk/cli/commands/restore.py

@@ -1,77 +0,0 @@
-# @CODE:CLI-001 | SPEC: SPEC-CLI-001.md | TEST: tests/unit/test_cli_commands.py
-"""MoAI-ADK restore command
-
-Backup restore command:
-- Locate backups in .moai-backups/{timestamp}/ directory
-- Restore the specified timestamp or the latest backup
-- Confirm before performing the restore
-"""
-
-from pathlib import Path
-
-import click
-from rich.console import Console
-
-console = Console()
-
-
-@click.command()
-@click.option(
-    "--timestamp",
-    help="Specific backup timestamp to restore (format: YYYY-MM-DD-HHMMSS)",
-)
-def restore(timestamp: str | None) -> None:
-    """Restore from backup
-
-    Args:
-        timestamp: Optional specific backup timestamp
-
-    Examples:
-        python -m moai_adk restore                    # Restore from latest backup
-        python -m moai_adk restore --timestamp 2025-10-13-120000  # Restore specific backup
-    """
-    try:
-        project_root = Path.cwd()
-        backup_dir = project_root / ".moai-backups"
-
-        # Find all timestamp directories in .moai-backups/
-        if not backup_dir.exists():
-            console.print("[yellow]⚠ No backup directory found[/yellow]")
-            console.print("[dim]Backups are stored in .moai-backups/{timestamp}/[/dim]")
-            raise click.Abort()
-
-        backup_dirs = sorted(
-            [d for d in backup_dir.iterdir() if d.is_dir()],
-            key=lambda x: x.name,
-            reverse=True
-        )
-
-        if not backup_dirs:
-            console.print("[yellow]⚠ No backup directories found[/yellow]")
-            console.print("[dim]Backups are stored in .moai-backups/{timestamp}/[/dim]")
-            raise click.Abort()
-
-        # When a timestamp is provided, find the matching backup
-        if timestamp:
-            console.print(f"[cyan]Restoring from {timestamp}...[/cyan]")
-            matching = [d for d in backup_dirs if timestamp in d.name]
-            if not matching:
-                console.print(f"[red]✗ Backup not found for timestamp: {timestamp}[/red]")
-                raise click.Abort()
-            backup_path = matching[0]
-        else:
-            console.print("[cyan]Restoring from latest backup...[/cyan]")
-            backup_path = backup_dirs[0]
-
-        # Placeholder for the future restore implementation
-        console.print(f"[dim]  └─ Backup: {backup_path.name}[/dim]")
-        console.print("[green]✓ Restore completed[/green]")
-
-        console.print("\n[yellow]Note:[/yellow] Restore functionality is not yet implemented")
-        console.print("[dim]This will be added in a future release[/dim]")
-
-    except click.Abort:
-        raise
-    except Exception as e:
-        console.print(f"[red]✗ Restore failed: {e}[/red]")
-        raise

moai_adk-0.3.9/src/moai_adk/templates/.claude/hooks/alfred/core/tags.py

@@ -1,244 +0,0 @@
-#!/usr/bin/env python3
-"""TAG search and verification system
-
-TAG 검색, 체인 검증, 라이브러리 버전 캐싱
-"""
-
-import json
-import subprocess
-import time
-from pathlib import Path
-
-# TAG search cache: {pattern: (results, mtime_hash, cached_at)}
-_tag_cache: dict[str, tuple[list[dict], float, float]] = {}
-
-# Library version cache: {lib_name: (version, timestamp)}
-_lib_version_cache: dict[str, tuple[str, float]] = {}
-
-
-def _get_dir_mtime_hash(paths: list[str]) -> float:
-    """Calculate a directory-wide mtime hash used for cache invalidation.
-
-    Args:
-        paths: List of directory paths to inspect.
-
-    Returns:
-        Highest modification timestamp (float) across all files.
-
-    Notes:
-        - Any file change bumps the hash and invalidates the cache.
-        - Missing or inaccessible directories are ignored.
-    """
-    max_mtime = 0.0
-    for path in paths:
-        path_obj = Path(path)
-        if not path_obj.exists():
-            continue
-
-        try:
-            for file_path in path_obj.rglob("*"):
-                if file_path.is_file():
-                    max_mtime = max(max_mtime, file_path.stat().st_mtime)
-        except (OSError, PermissionError):
-            # Skip directories we cannot read
-            continue
-
-    return max_mtime
-
-
-def search_tags(pattern: str, scope: list[str] | None = None, cache_ttl: int = 60) -> list[dict]:
-    """Search TAG markers using an in-memory cache.
-
-    Args:
-        pattern: Regex pattern (for example ``'@SPEC:AUTH-.*'``).
-        scope: List of directories to scan. Defaults to specs/src/tests.
-        cache_ttl: Cache time-to-live in seconds (default 60).
-
-    Returns:
-        List of matches such as ``{"file": "path", "line": 10, "tag": "...", "content": "..."}``.
-
-    Notes:
-        - Cache integrity relies on directory mtimes plus TTL.
-        - Cache hits avoid spawning ``rg`` while misses shell out (≈13ms).
-        - Uses ``rg --json`` output for structured parsing.
-    """
-    if scope is None:
-        scope = [".moai/specs/", "src/", "tests/"]
-
-    cache_key = f"{pattern}:{':'.join(scope)}"
-
-    current_mtime = _get_dir_mtime_hash(scope)
-    cache_entry = _tag_cache.get(cache_key)
-
-    # Serve cached results when still valid
-    if cache_entry:
-        cached_results, cached_mtime, cached_at = cache_entry
-        ttl_valid = time.time() - cached_at < cache_ttl
-
-        # Matching mtime and a fresh TTL means we can reuse the cache
-        if current_mtime == cached_mtime and ttl_valid:
-            return cached_results
-
-    # Cache miss → invoke ripgrep
-    cmd = ["rg", pattern, "--json"] + scope
-
-    try:
-        result = subprocess.run(cmd, capture_output=True, text=True, timeout=5, check=False)
-    except (subprocess.TimeoutExpired, FileNotFoundError):
-        # Missing rg or a timeout returns an empty list
-        return []
-
-    matches = []
-    for line in result.stdout.strip().split("\n"):
-        if not line:
-            continue
-        try:
-            data = json.loads(line)
-            if data.get("type") == "match":
-                matches.append(
-                    {
-                        "file": data["data"]["path"]["text"],
-                        "line": data["data"]["line_number"],
-                        "tag": data["data"]["lines"]["text"].strip(),
-                        "content": data["data"]["lines"]["text"],
-                    }
-                )
-        except (json.JSONDecodeError, KeyError):
-            # Ignore malformed JSON lines
-            continue
-
-    # Persist results with the current mtime snapshot
-    _tag_cache[cache_key] = (matches, _get_dir_mtime_hash(scope), time.time())
-
-    return matches
-
-
-def verify_tag_chain(spec_id: str) -> dict:
-    """Verify a TAG chain across ``@SPEC`` → ``@TEST`` → ``@CODE``.
-
-    Args:
-        spec_id: SPEC identifier (for example ``"AUTH-001"``).
-
-    Returns:
-        Dictionary with keys ``complete``, ``spec``, ``test``, ``code`` and ``orphans``.
-
-    Notes:
-        - Orphans capture TAGs found in code/tests without a SPEC.
-        - A chain is complete only when all three categories contain matches.
-        - Relies on ``search_tags`` so cached scans remain inexpensive.
-    """
-    chain = {
-        "spec": search_tags(f"@SPEC:{spec_id}", [".moai/specs/"]),
-        "test": search_tags(f"@TEST:{spec_id}", ["tests/"]),
-        "code": search_tags(f"@CODE:{spec_id}", ["src/"]),
-    }
-
-    orphans = []
-    if chain["code"] and not chain["spec"]:
-        orphans.extend(chain["code"])
-    if chain["test"] and not chain["spec"]:
-        orphans.extend(chain["test"])
-
-    return {
-        "complete": bool(chain["spec"] and chain["test"] and chain["code"]),
-        **chain,
-        "orphans": orphans,
-    }
-
-
-def find_all_tags_by_type(tag_type: str = "SPEC") -> dict:
-    """Return TAG IDs grouped by domain for the requested type.
-
-    Args:
-        tag_type: TAG category (``SPEC``, ``TEST``, ``CODE`` or ``DOC``).
-
-    Returns:
-        Dictionary like ``{"AUTH": ["AUTH-001", "AUTH-002"], ...}``.
-
-    Notes:
-        - Domain is derived from the ``FOO-123`` prefix.
-        - Deduplicates repeated matches within the same domain.
-        - Fetches data via ``search_tags`` so caching still applies.
-    """
-    tags = search_tags(f"@{tag_type}:([A-Z]+-[0-9]{{3}})")
-
-    by_domain = {}
-    for tag in tags:
-        # @SPEC:AUTH-001 → AUTH
-        try:
-            tag_id = tag["tag"].split(":")[1]
-            domain = "-".join(tag_id.split("-")[:-1])
-
-            if domain not in by_domain:
-                by_domain[domain] = []
-            if tag_id not in by_domain[domain]:
-                by_domain[domain].append(tag_id)
-        except IndexError:
-            # 파싱 실패 무시
-            continue
-
-    return by_domain
-
-
-def suggest_tag_reuse(keyword: str, tag_type: str = "SPEC") -> list[str]:
-    """Suggest existing TAG IDs that match the supplied keyword.
-
-    Args:
-        keyword: Keyword used to match domain names (case-insensitive).
-        tag_type: TAG category (defaults to ``SPEC``).
-
-    Returns:
-        A list of up to five suggested TAG IDs.
-
-    Notes:
-        - Encourages reuse to avoid creating duplicate TAGs.
-        - Performs a simple substring match against domain names.
-    """
-    all_tags = find_all_tags_by_type(tag_type)
-    suggestions = []
-
-    keyword_lower = keyword.lower()
-    for domain, tag_ids in all_tags.items():
-        if keyword_lower in domain.lower():
-            suggestions.extend(tag_ids)
-
-    return suggestions[:5]  # Cap results at five
-
-
-def get_library_version(lib_name: str, cache_ttl: int = 86400) -> str | None:
-    """Get the cached latest stable version for a library.
-
-    Args:
-        lib_name: Package name (for example ``"fastapi"``).
-        cache_ttl: Cache TTL in seconds (defaults to 24 hours).
-
-    Returns:
-        Cached version string or ``None`` when the cache is cold.
-
-    Notes:
-        - Cache hits skip costly web searches (saves 3–5 seconds).
-        - Agents should call ``set_library_version`` after fetching live data.
-    """
-    # Serve cached value when still within TTL
-    if lib_name in _lib_version_cache:
-        cached_version, cached_time = _lib_version_cache[lib_name]
-        if time.time() - cached_time < cache_ttl:
-            return cached_version
-
-    # Cache miss → agent needs to perform the web search
-    return None
-
-
-def set_library_version(lib_name: str, version: str):
-    """Persist a library version in the cache."""
-    _lib_version_cache[lib_name] = (version, time.time())
-
-
-__all__ = [
-    "search_tags",
-    "verify_tag_chain",
-    "find_all_tags_by_type",
-    "suggest_tag_reuse",
-    "get_library_version",
-    "set_library_version",
-]