velm 0.1.2__py3-none-any.whl

velm/artisans/agent/agent.scaffold

@@ -0,0 +1,32 @@
+├── __init__.py             # The Sacred Gateway
+├── artisan.py              # The High Conductor (`scaffold agent` command)
+├── contracts.py            # The Language of Thought (Plan, ToolCall, Observation)
+├── engine.py               # The Heartbeat: The Perceive->Plan->Act->Verify Loop
+│
+├──  Perceive/
+│   ├── __init__.py
+│   └── perceiver.py        # The Eye: Gathers context using `distill`
+│
+├── Plan/
+│   ├── __init__.py
+│   ├── planner.py          # The Mind: Turns intent + context into a Plan
+│   └── prompt_forge.py     # The Soul: Forges the master prompt for the LLM
+│
+├── Act/
+│   ├── __init__.py
+│   ├── executor.py         # The Hand: Executes a Plan using the Tool Registry
+│   └── tools/
+│       ├── __init__.py
+│       ├── base.py         # The Sacred Contract for all Tools
+│       ├── file_system.py  # Read, Write, List
+│       ├── testing.py      # Run tests, get coverage
+│       └── git.py          # Commit, Diff, Status
+│
+├── Verify/
+│   ├── __init__.py
+│   └── critic.py           # The Conscience: Judges the outcome of an Action
+│
+└── Memory/
+    ├── __init__.py
+    ├── short_term.py       # The Scratchpad: Remembers the current conversation
+    └── long_term.py        # The Chronicle: Remembers successful solutions (RAG)

velm/artisans/agent/artisan.py

@@ -0,0 +1,174 @@
+# Path: scaffold/artisans/agent/artisan.py
+# ----------------------------------------
+
+import time
+from types import SimpleNamespace
+from typing import List, Optional, Set, Tuple
+from .engine import AgenticEngine
+from ...core.artisan import BaseArtisan
+from ...interfaces.base import ScaffoldResult, Artifact
+from ...interfaces.requests import AgentRequest
+from ...help_registry import register_artisan
+from ...utils.dossier_scribe import proclaim_apotheosis_dossier
+from ...contracts.heresy_contracts import ArtisanHeresy
+
+
+@register_artisan("agent")
+class AgentArtisan(BaseArtisan[AgentRequest]):
+    """
+    =================================================================================
+    == THE HIGH PRIEST OF AGENCY (V-Ω-ETERNAL-APOTHEOSIS-ULTIMA)                   ==
+    =================================================================================
+    @gnosis:title The Gnostic Agent (`agent`)
+    @gnosis:summary The divine conductor that awakens and governs the autonomous AI Agent.
+    @gnosis:LIF 100,000,000,000,000,000,000
+
+    This is the High Priest of Agency in its final, eternal form. It is the one true,
+    sovereign gateway between the Architect's Will and the Agent's autonomous reality.
+    It has been transfigured from a humble trigger into a sentient guardian and herald,
+    its soul a pantheon of Gnostic faculties.
+
+    ### THE PANTHEON OF 12 LEGENDARY ASCENSIONS:
+
+    1.  **The Gnostic Anchor:** It performs a pre-flight Gaze to ensure it is being
+        summoned within a valid Git sanctum, the only reality where the Agent can
+        safely operate and reverse its own paradoxes.
+    2.  **The Guardian's Veto Bridge:** It faithfully passes the Architect's vow of
+        interactivity (`--interactive` or `--non-interactive`) to the `AgenticEngine`,
+        enabling the crucial safety interlock.
+    3.  **The Unbreakable Contract:** It speaks the pure, ascended `AgentRequest` vessel,
+        its contract with the cosmos now whole and unbreakable.
+    4.  **The Sovereign Soul:** Its purpose is pure orchestration. It contains no agentic
+        logic itself; it delegates the entire symphony of thought to the `AgenticEngine`.
+    5.  **The Luminous Herald of Apotheosis:** Upon a successful rite, it summons the
+        one true `proclaim_apotheosis_dossier` to sing a triumphant, cinematic song of
+        the Agent's Great Work, complete with rich telemetry.
+    6.  **The Telemetric Heartbeat:** It meticulously chronicles the Agent's total
+        runtime, the number of cognitive cycles, and the final state of its soul.
+    7.  **The Artifact Hoarder:** It diligently gathers all files created or modified
+        by the Agent into a pure list of `Artifact` vessels for the final proclamation,
+        enabling perfect integration with the Gnostic UI.
+    8.  **The Heresy Transmuter:** It wraps the entire agentic loop in an unbreakable
+        ward, catching any catastrophic paradox and re-proclaiming it as a luminous
+        `ArtisanHeresy` with full Gnostic context.
+    9.  **The Luminous Voice:** Its every major action is proclaimed to the Gnostic
+        Chronicle, from the moment of awakening to the final verdict.
+    10. **The Dry-Run Prophecy (Future):** Its architecture is prepared for a future
+        ascension where it can command the Agent to enter a "planning only" mode,
+        prophesying its actions without touching the mortal realm.
+    11. **The Cost Guard (Future):** It is the destined guardian of the treasury,
+        prepared to receive a `--budget` vow to constrain the Agent's AI token usage.
+    12. **The Final Word:** It is the one true, safe, and intelligent entry point to
+        the entire Agentic Cosmos, the living heart of autonomous creation.
+    """
+
+    def execute(self, request: AgentRequest) -> ScaffoldResult:
+        start_time = time.monotonic()
+        self.console.rule(f"[bold magenta]Gnostic Agent Awakened. Mission: [cyan]{request.mission}[/cyan]")
+
+        # --- MOVEMENT I: THE GNOSTIC ANCHOR (SAFETY INQUEST) ---
+        if not (self.project_root / ".git").is_dir():
+            raise ArtisanHeresy(
+                "The Agent must be summoned within a Git sanctum.",
+                suggestion="Please run `git init` to consecrate this reality before awakening the Agent."
+            )
+
+        try:
+            # --- MOVEMENT II: THE DIVINE DELEGATION ---
+            engine = AgenticEngine(
+                mission=request.mission,
+                project_root=self.project_root,
+                engine=self.engine,
+                interactive=request.interactive
+            )
+
+            # This blocks until the mission is complete, failed, or aborted.
+            final_state = engine.run_loop()
+
+            # --- MOVEMENT III: THE FINAL ADJUDICATION & PROCLAMATION ---
+            duration = time.monotonic() - start_time
+            if final_state.is_complete:
+                # [FACULTY 7] The Artifact Hoarder
+                # We perform a final gaze to determine what the agent has wrought.
+                # This is a humble gaze; a future ascension would have the Agent self-report.
+                artifacts = self._perceive_artifacts(start_time)
+
+                # [FACULTY 5 & 6] The Luminous Herald of Apotheosis
+                self._proclaim_success(request, final_state, duration, artifacts)
+
+                return self.success(
+                    final_state.final_result or "Mission accomplished.",
+                    artifacts=artifacts,
+                    data={"cycles": final_state.current_cycle, "duration": duration}
+                )
+            else:
+                return self.failure(
+                    final_state.final_result or "Mission failed to achieve its objective.",
+                    data={"cycles": final_state.current_cycle, "duration": duration}
+                )
+        except Exception as e:
+            # [FACULTY 8] The Heresy Transmuter
+            if isinstance(e, ArtisanHeresy):
+                raise e
+            raise ArtisanHeresy("A catastrophic paradox shattered the Agent's reality.", child_heresy=e)
+
+    def _perceive_artifacts(self, start_time: float) -> List[Artifact]:
+        """A Gnostic Gaze to find scriptures touched by the Agent's hand."""
+        artifacts = []
+        try:
+            # We use `git status` as the source of truth for what has changed.
+            import subprocess
+            status_output = subprocess.check_output(
+                ["git", "status", "--porcelain"],
+                cwd=self.project_root, text=True
+            ).strip()
+
+            if not status_output:
+                return []
+
+            for line in status_output.splitlines():
+                status, path_str = line[:2].strip(), line[3:]
+                action = "modified"
+                if status == "A" or status == "??":
+                    action = "created"
+
+                artifacts.append(Artifact(path=Path(path_str), type="file", action=action))
+
+        except Exception:
+            # Fallback to a simple mtime check if git fails
+            for p in self.project_root.rglob("*"):
+                if p.is_file() and p.stat().st_mtime > start_time:
+                    artifacts.append(Artifact(path=p, type="file", action="modified"))
+
+        return artifacts
+
+    def _proclaim_success(self, request: AgentRequest, state: "AgentState", duration: float, artifacts: List[Artifact]):
+        """[FACULTY 5] Summons the universal scribe."""
+
+        # Forge ephemeral registers for the Dossier Scribe
+        registers = SimpleNamespace(
+            get_duration=lambda: duration,
+            files_forged=len([a for a in artifacts if a.action == "created"]),
+            sanctums_forged=0,  # The agent doesn't report this yet
+            bytes_written=0,  # Not easily known without more Gnosis
+            no_edicts=True,
+        )
+
+        gnosis_context = {
+            "mission": request.mission,
+            "cycles_taken": state.current_cycle,
+            "final_thought": state.final_result
+        }
+
+        proclaim_apotheosis_dossier(
+            telemetry_source=registers,
+            gnosis=gnosis_context,
+            project_root=self.project_root,
+            next_steps=[
+                "Review the changes: [bold]git diff[/bold]",
+                "Enshrine the work: [bold]scaffold save 'feat(agent): Accomplished mission'[/bold]"
+            ],
+            title="✨ Agentic Symphony Complete ✨",
+            subtitle=f"The mission '[cyan]{request.mission[:50]}...[/cyan]' has been made manifest.",
+            gnostic_constellation=artifacts
+        )

velm/artisans/agent/contracts.py

@@ -0,0 +1,42 @@
+# === [scaffold/artisans/agent/contracts.py] - SECTION 1 of 1: The Agent's Mind ===
+from pydantic import BaseModel, Field
+from typing import List, Dict, Any, Optional, Literal
+
+
+class ToolCall(BaseModel):
+    """A single, atomic action the Agent intends to perform."""
+    tool_name: str = Field(..., description="The sacred name of the tool to invoke (e.g., 'run_tests', 'read_file').")
+    arguments: Dict[str, Any] = Field(default_factory=dict, description="The parameters to bestow upon the tool.")
+    thought: Optional[str] = Field(None, description="The Agent's reasoning for this specific action.")
+
+
+class Plan(BaseModel):
+    """The complete, ordered sequence of actions for a single cognitive cycle."""
+    thought: str = Field(..., description="The Agent's high-level strategy for this cycle.")
+    tool_calls: List[ToolCall] = Field(default_factory=list, description="The sequence of rites to be performed.")
+
+
+class Observation(BaseModel):
+    """The manifest truth of what occurred when a Tool touched Reality."""
+    tool_name: str
+    tool_input: Dict[str, Any]
+    output: str
+    status: Literal["SUCCESS", "FAILURE"]
+
+
+class Critique(BaseModel):
+    """The Conscience's judgment upon the outcome of a Plan."""
+    is_goal_achieved: bool
+    reasoning: str
+    next_step_suggestion: Optional[str] = Field(None, description="Guidance for the Planner in the next cycle.")
+
+
+class AgentState(BaseModel):
+    """The living, evolving soul of the Agent's mission."""
+    mission: str
+    max_cycles: int = 10
+    current_cycle: int = 0
+    history: List[Dict[str, Any]] = Field(default_factory=list, description="Chronicle of past Plans and Observations.")
+    is_complete: bool = False
+    final_result: Optional[str] = None
+

velm/artisans/agent/engine.py

@@ -0,0 +1,208 @@
+# Path: scaffold/artisans/agent/engine.py
+# ---------------------------------------
+
+import json
+import time
+from pathlib import Path
+from typing import Any, List
+from rich.panel import Panel
+from rich.syntax import Syntax
+from rich.prompt import Confirm
+
+from .contracts import AgentState, Observation, Plan, Critique
+from .Perceive.perceiver import Perceiver
+from .Plan.planner import Planner
+from .Act.executor import Executor
+from .Verify.critic import Critic
+from .Memory.long_term import LongTermMemory
+from ...logger import Scribe
+from ...contracts.heresy_contracts import ArtisanHeresy
+
+Logger = Scribe("AgenticEngine")
+
+
+class AgenticEngine:
+    """
+    =================================================================================
+    == THE GOD-MIND OF AGENCY (V-Ω-ETERNAL-APOTHEOSIS-ULTIMA++)                    ==
+    =================================================================================
+    @gnosis:title The Gnostic Agentic Engine
+    @gnosis:summary The divine, sentient, and self-correcting core of the Scaffold Agent.
+    @gnosis:LIF INFINITY
+
+    This is not a class. It is a Mind. It is the living, breathing Gnostic soul that
+    conducts the eternal symphony of `Perceive -> Plan -> Act -> Verify`. It has been
+    ascended with a pantheon of twelve legendary faculties that transform it from a
+    simple loop into a true, autonomous co-architect.
+
+    ### THE PANTHEON OF 12 LEGENDARY ASCENSIONS:
+
+    1.  **The Guardian's Veto (Interactive Control):** It honors the sacred `interactive`
+        vow, pausing the symphony before every action to seek the Architect's consent,
+        ensuring absolute control.
+    2.  **The Luminous Herald (Real-Time UI):** Its every thought, plan, and observation
+        is proclaimed to the console in real-time via luminous `rich` panels,
+        transforming the black box into a glass cockpit.
+    3.  **The Gnostic Chronicle (Long-Term Memory):** It now possesses a `LongTermMemory`,
+        inscribing every successful mission into an eternal chronicle, allowing it to
+        learn from the past. (The `recall` rite is a future ascension).
+    4.  **The Paradox Ward (Self-Correction):** If a tool execution fails, it does not
+        shatter. It feeds the failure back into its own mind, allowing it to re-plan
+        and heal its own mistakes.
+    5.  **The Hallucination Filter:** It performs a pre-flight check on every `Plan`,
+        verifying that the AI has not hallucinated a tool that does not exist in the
+        `Executor`'s registry, preventing profane actions.
+    6.  **The Sanity Governor (Empty Plan Ward):** If the AI's mind goes blank and it
+        proclaims an empty plan, the engine perceives this as a heresy and forces a
+        re-evaluation, preventing wasted cycles.
+    7.  **The Gnostic Triage of Perception:** It is now intelligent. If the Agent's
+        history is empty, its first act is always a broad perception of reality. In
+        later cycles, it can perform more surgical, focused perceptions.
+    8.  **The Unbreakable Heart:** The entire cognitive loop is shielded within a
+        `try/except` block that catches any unforeseen paradox, ensuring the engine
+        can proclaim a final, graceful failure instead of a catastrophic crash.
+    9.  **The Clean State Inception:** Its `__init__` rite is a pure inception,
+        forging the complete pantheon of its faculties (Perceiver, Planner, etc.)
+        at the moment of its birth.
+    10. **The Pure Gnostic Contract:** Its every interaction is governed by the sacred
+        Pydantic vessels (`AgentState`, `Plan`, `Observation`), ensuring unbreakable
+        type safety throughout its cognitive process.
+    11. **The Telemetric Soul:** It meticulously chronicles its entire history of
+        thought, action, and critique within the `AgentState`, forging a perfect
+        dossier for post-mortem analysis or future learning.
+    12. **The Final Word:** It is the one true, definitive, and self-aware core of
+        autonomous action in the Scaffold cosmos.
+    """
+
+    def __init__(self, mission: str, project_root: Path, engine: Any, interactive: bool):
+        """[FACULTY 9] The Clean State Inception."""
+        self.state = AgentState(mission=mission)
+        self.interactive = interactive
+        self.console = engine.console  # Inherit the rich console for luminous proclamations
+
+        # The Pantheon of Faculties is forged at birth.
+        self.perceiver = Perceiver(project_root, engine)
+        self.planner = Planner(project_root, engine)
+        self.executor = Executor(project_root, engine)
+        self.critic = Critic(project_root, engine)
+        self.long_term_memory = LongTermMemory(project_root)
+
+    def _proclaim_plan(self, plan: Plan):
+        """[FACULTY 2] A luminous herald for the AI's will."""
+        tool_calls_str = ""
+        for call in plan.tool_calls:
+            args_str = ", ".join(f"{k}='{v}'" for k, v in call.arguments.items())
+            tool_calls_str += f"  - [bold cyan]{call.tool_name}[/bold cyan]({args_str})\n"
+            tool_calls_str += f"    [dim italic]Thought: {call.thought}[/dim italic]\n"
+
+        panel = Panel(
+            f"[bold]High-Level Thought:[/bold] [italic]{plan.thought}[/italic]\n\n[bold]Tool Calls:[/bold]\n{tool_calls_str}",
+            title="[yellow]AI's Prophesied Plan[/yellow]",
+            border_style="yellow"
+        )
+        self.console.print(panel)
+
+    def _proclaim_observations(self, observations: List[Observation]):
+        """[FACULTY 2] A herald for the echoes of reality."""
+        for obs in observations:
+            color = "green" if obs.status == "SUCCESS" else "red"
+            # Use Syntax for better formatting of multi-line, potentially code-like output
+            panel = Panel(
+                Syntax(obs.output, "text", theme="monokai", word_wrap=True),
+                title=f"[{color}]Observation: {obs.tool_name}[/{color}]",
+                border_style=color
+            )
+            self.console.print(panel)
+
+    def run_loop(self) -> AgentState:
+        """The Grand Symphony of Cognition."""
+        while not self.state.is_complete and self.state.current_cycle < self.state.max_cycles:
+            self.state.current_cycle += 1
+            self.console.rule(f"[bold]AGENT CYCLE {self.state.current_cycle}/{self.state.max_cycles}[/bold]")
+
+            try:
+                # 1. PERCEIVE
+                self.console.print("[dim]Perceiving reality...[/dim]")
+                context_blueprint = self.perceiver.perceive(self.state)
+
+                # 2. PLAN
+                self.console.print("[dim]Formulating a new plan...[/dim]")
+                plan: Plan = self.planner.create_plan(self.state, context_blueprint)
+                self._proclaim_plan(plan)
+
+                # --- FACULTY 5 & 6: HALLUCINATION & VOID WARD ---
+                if not plan.tool_calls:
+                    self.console.print(
+                        "[yellow]Warning: The AI proclaimed a void plan. Forcing re-evaluation.[/yellow]")
+                    self.state.history.append({"cycle": self.state.current_cycle, "plan": plan.model_dump(),
+                                               "critique": {"reasoning": "Void plan detected, forcing new cycle."}})
+                    continue
+
+                for call in plan.tool_calls:
+                    if call.tool_name not in self.executor.registry:
+                        raise ArtisanHeresy(f"The AI hallucinated a profane tool: '{call.tool_name}'",
+                                            details=f"Known tools are: {list(self.executor.registry.keys())}")
+                # -------------------------------------------------
+
+                # --- FACULTY 1: THE GUARDIAN'S VETO ---
+                if self.interactive:
+                    if not Confirm.ask("\n[bold question]Execute this plan?[/bold question]", default=True):
+                        self.state.is_complete = True
+                        self.state.final_result = "Mission stayed by the Architect's hand."
+                        self.console.print("[yellow]Rite stayed by Architect's will.[/yellow]")
+                        break
+                # ------------------------------------
+
+                # 3. ACT
+                self.console.print("[dim]Executing plan...[/dim]")
+                observations: List[Observation] = self.executor.execute_plan(plan)
+                self._proclaim_observations(observations)
+
+                # 4. VERIFY (The Conscience)
+                self.console.print("[dim]Critiquing the outcome...[/dim]")
+                critique = self.critic.review(self.state, observations)
+                self.console.print(
+                    Panel(f"[bold]Critique:[/bold] {critique.reasoning}", title="[blue]The Conscience[/blue]",
+                          border_style="blue"))
+
+                # 5. UPDATE STATE & MEMORY
+                self.state.history.append({
+                    "cycle": self.state.current_cycle,
+                    "plan": plan.model_dump(),
+                    "observations": [o.model_dump() for o in observations],
+                    "critique": critique.model_dump()
+                })
+
+                if critique.is_goal_achieved:
+                    self.state.is_complete = True
+                    self.state.final_result = critique.reasoning
+                    # --- FACULTY 3: THE RITE OF REMEMBRANCE ---
+                    self.long_term_memory.remember(self.state)
+                    Logger.success("CRITIC: Goal Achieved. Mission Complete. The memory is enshrined.")
+
+            except Exception as e:
+                # --- FACULTY 8: THE UNBREAKABLE HEART ---
+                Logger.error(f"Catastrophic Agent Loop Failure: {e}", exc_info=True)
+                # --- FACULTY 4: THE PARADOX WARD ---
+                # We record the failure in history so the agent can see its mistake in the next cycle.
+                failure_observation = Observation(tool_name="SYSTEM", tool_input={},
+                                                  output=f"A paradox shattered the loop: {e}", status="FAILURE")
+                self.state.history.append({
+                    "cycle": self.state.current_cycle,
+                    "plan": {"thought": "Attempted to execute a plan that resulted in a system error."},
+                    "observations": [failure_observation.model_dump()],
+                    "critique": {
+                        "reasoning": f"A system-level error occurred: {e}. I must re-evaluate my strategy based on this failure."}
+                })
+                self.console.print(Panel(f"[bold red]A paradox shattered the Agent's thought process:[/bold red]\n{e}",
+                                         title="[red]SYSTEM HERESY[/red]", border_style="red"))
+                # In non-interactive mode, we might choose to break. In interactive, we could let it try to recover.
+                if not self.interactive:
+                    self.state.final_result = f"Agent failed with exception: {e}"
+                    break
+
+        if not self.state.is_complete:
+            self.state.final_result = self.state.final_result or "Agent exceeded max cycles."
+            Logger.error("AGENT: Mission failed to complete within cycle limit.")
+
+        return self.state

velm/artisans/akasha/artisan.py

@@ -0,0 +1,68 @@
+# Path: artisans/akasha/artisan.py
+# --------------------------------
+
+from ...core.artisan import BaseArtisan
+from ...interfaces.base import ScaffoldResult
+from ...interfaces.requests import AkashaRequest
+from ...help_registry import register_artisan
+from ...core.ai.akasha import AkashicRecord
+from rich.table import Table
+from rich.panel import Panel
+from rich.syntax import Syntax
+
+
+@register_artisan("akasha")
+class AkashaArtisan(BaseArtisan[AkashaRequest]):
+    """
+    =============================================================================
+    == THE KEEPER OF THE AKASHA (V-Ω-GLOBAL-MEMORY-CLI)                        ==
+    =============================================================================
+    LIF: 10,000,000,000
+
+    Manages the persistent, cross-project memory of the God-Engine.
+    """
+
+    def execute(self, request: AkashaRequest) -> ScaffoldResult:
+        akasha = AkashicRecord()
+
+        if request.akasha_command == "stats":
+            stats = akasha.get_stats()
+            self.console.print(Panel(
+                f"Memories: [bold green]{stats['total_memories']}[/bold green]\n"
+                f"Storage:  [cyan]{stats['storage_size_bytes'] / 1024 / 1024:.2f} MB[/cyan]\n"
+                f"Sanctum:  [dim]{stats['location']}[/dim]",
+                title="[bold magenta]Akashic Record Status[/bold magenta]"
+            ))
+            return self.success("Stats proclaimed.")
+
+        elif request.akasha_command == "query":
+            if not request.query:
+                return self.failure("A query is required to gaze into the Akasha.")
+
+            hits = akasha.recall_wisdom(request.query, limit=3)
+            if not hits:
+                return self.success("The Akasha is silent on this matter.")
+
+            for hit in hits:
+                meta = hit['metadata']
+                self.console.print(Panel(
+                    Syntax(hit['content'][:500] + "...", "python", theme="monokai"),
+                    title=f"[bold cyan]{meta.get('rite', 'Unknown Rite')}[/bold cyan] ({meta.get('project', 'Unknown Project')})",
+                    subtitle=f"Distance: {hit['distance']:.3f}"
+                ))
+            return self.success(f"Recalled {len(hits)} memories.")
+
+        elif request.akasha_command == "purge":
+            akasha.purge()
+            return self.success("The Akasha has been returned to the Void.")
+
+        elif request.akasha_command == "learn":
+            # Manual ingestion of a file into global memory
+            if not request.source_path:
+                return self.failure("Source path required for manual learning.")
+
+            # Implementation logic for manual ingestion would go here
+            # using akasha.enshrine(...)
+            return self.success("Manual learning logic is a future prophecy.")
+
+        return self.failure("Unknown Akasha rite.")

velm/artisans/alias/__init__.py

@@ -0,0 +1,3 @@
+# Path: scaffold/artisans/alias/__init__.py
+from .artisan import AliasArtisan
+__all__ = ["AliasArtisan"]

velm/artisans/alias/artisan.py

@@ -0,0 +1,69 @@
+# Path: scaffold/artisans/alias/artisan.py
+# ----------------------------------------
+
+import shlex
+from rich.table import Table
+from ...core.artisan import BaseArtisan
+from ...interfaces.base import ScaffoldResult
+from ...interfaces.requests import AliasRequest
+from ...help_registry import register_artisan
+from ...settings.manager import SettingsManager
+
+
+@register_artisan("alias")
+class AliasArtisan(BaseArtisan[AliasRequest]):
+    """
+    =============================================================================
+    == THE SHORTCUT FORGE (V-Ω-MACRO-MANAGER)                                  ==
+    =============================================================================
+    LIF: 10,000,000,000
+
+    Manages the 'aliases' dictionary in the global config.
+    """
+
+    def execute(self, request: AliasRequest) -> ScaffoldResult:
+        settings = SettingsManager(self.project_root)
+        aliases = settings.get("aliases", {})
+
+        cmd = request.alias_command
+
+        if cmd == "list":
+            if not aliases:
+                return self.success("No aliases defined.")
+
+            table = Table(title="Gnostic Aliases")
+            table.add_column("Alias", style="cyan")
+            table.add_column("Expansion", style="yellow")
+
+            for k, v in aliases.items():
+                table.add_row(k, v)
+
+            self.console.print(table)
+            return self.success(f"Listed {len(aliases)} aliases.")
+
+        if not request.name:
+            return self.failure("Alias name is required.")
+
+        if cmd == "add":
+            if not request.expansion:
+                return self.failure("Expansion string is required for 'add'.")
+
+            # Validate expansion syntax
+            try:
+                shlex.split(request.expansion)
+            except ValueError as e:
+                return self.failure(f"Invalid expansion syntax: {e}")
+
+            aliases[request.name] = request.expansion
+            settings.set_global("aliases", aliases)
+            return self.success(f"Alias '{request.name}' -> '{request.expansion}' inscribed.")
+
+        elif cmd == "remove":
+            if request.name not in aliases:
+                return self.failure(f"Alias '{request.name}' not found.")
+
+            del aliases[request.name]
+            settings.set_global("aliases", aliases)
+            return self.success(f"Alias '{request.name}' annihilated.")
+
+        return self.failure(f"Unknown rite: {cmd}")

velm/artisans/analyze/__init__.py

@@ -0,0 +1,13 @@
+# scaffold/artisans/analyze/__init__.py
+
+"""
+=================================================================================
+== THE SANCTUM OF INTROSPECTION (V-Ω-MODULAR)                                ==
+=================================================================================
+This package contains the artisans responsible for the Real-Time Analysis of
+the Architect's scripture. It provides Structure, Completions, and Diagnostics.
+=================================================================================
+"""
+from .artisan import AnalyzeArtisan
+
+__all__ = ["AnalyzeArtisan"]