How to Enable LoopX Explore Capability for Experiment Tracking

LoopX Explore capability provides a structured, public‑safe evidence graph that records exploration history, blockers, and confirmed findings under loopx/capabilities/explore/, enabling systematic experiment tracking through two toggleable sub‑features: Explore Graph and Explore Harness.

In the huangruiteng/loopx repository, the LoopX Explore capability serves as the canonical append‑only log for experimental evidence. It maintains a machine‑readable topology of what the system has explored, why specific paths are blocked, and what hypotheses have been validated, making it essential for audit trails and reproducible research workflows.

What Is the LoopX Explore Capability?

The Explore evidence layer is a structured graph stored under loopx/capabilities/explore/ that acts as a single source of truth for experiment state. Unlike transient logs, this layer maintains a canonical append‑only log of nodes, edges, and findings that survives material refreshes and can be safely exposed to public‑facing dashboards.

According to the source code in docs/capabilities/explore/README.md, the capability is designed to answer three operational questions:

• What has the system already explored?
• Why is a specific branch blocked?
• Which findings have been confirmed with high confidence?

Explore Architecture and Sub‑Features

The capability splits into two independent optional sub‑features defined in loopx/capabilities/explore/activation.py:

Explore Graph (explore_graph.enabled)
Persists the evidence graph after every material refresh and optionally pushes projections to presentation sinks (e.g., Lark Base). This is the data persistence layer that ensures your experiment history is never lost.

Explore Harness (spawn_policy.explore_harness.enabled)
Provides a read‑only planner that builds "todo‑branch‑plans" or "worker‑branch‑plans" for subsequent experiments. It analyzes the current graph topology to suggest the next logical experiments without automatically executing them.

Both gates default to off. You can enable only the Graph for passive tracking, or activate both for active experiment planning.

Architecture Flow for Experiment Tracking

When enabled, the Explore capability follows a five‑stage pipeline as implemented in the activation layer:

1. Goal registration – LoopX stores a goal entry in the registry under goals/<goal-id>/.

2. Material refresh – Running loopx refresh-state folds the canonical Explore log into a projection named loopx_explore_result_projection_v0.

3. Graph activation – If explore_graph.enabled is true, the function sync_explore_graph_after_material_refresh writes the projection to configured sinks and records a delivery post‑condition.

4. Harness planning – If spawn_policy.explore_harness.enabled is true, the planner reads the projection and emits read‑only plans containing node references, confidence scores, and resource‑capacity hints. Note: This step does not launch workers.

5. Presentation – The loopx.extensions.lark.presentation package renders the graph into Lark boards or Mermaid diagrams, with board styles controlled by explore_visual_styles.py.

How to Enable LoopX Explore Capability

Enable the capability using the loopx configure-goal CLI or programmatically via the registry API.

Method 1: CLI Configuration

Enable the Explore Graph (and optionally the Harness) for a specific goal:

loopx configure-goal --goal-id my-goal \
  --explore-graph-enabled \
  --no-explore-harness-enabled \
  --execute

This writes the following structure to your registry:

explore_graph:
  enabled: true
spawn_policy:
  explore_harness:
    enabled: false

Method 2: Programmatic Configuration

For automation pipelines, modify the goal registry directly:

from pathlib import Path
from loopx.agent_registry import load_goal_from_registry, save_goal_to_registry

registry = Path("/path/to/registry")
goal_id = "my-goal"

goal = load_goal_from_registry(registry, goal_id) or {}
goal.setdefault("explore_graph", {})["enabled"] = True
goal.setdefault("spawn_policy", {}).setdefault("explore_harness", {})["enabled"] = False

save_goal_to_registry(registry, goal_id, goal)

Trigger the First Graph Generation

After configuration, generate your initial evidence graph:

loopx refresh-state --goal-id my-goal --execute

This triggers sync_explore_graph_after_material_refresh, which appends new events to goals/my-goal/explore-result-log.jsonl.

Configuring Presentation Sinks

To visualize the graph in Lark (Feishu), configure a presentation sink after enabling the Graph:

loopx explore feishu-visual-configure \
  --view-role canonical \
  --projection-mode canonical_full \
  --board-style auto_flow \
  --execute

The board-style parameter accepts values defined in loopx/extensions/lark/presentation/explore_visual_styles.py, including auto_flow for automatic layout or semantic_lane_columns for lane‑based grouping. This creates a local config at .loopx/lark-explore.json and registers the board with Lark.

Using the Explore Harness for Planning

Once your graph is populated, query the Harness for experiment suggestions:

loopx explore todo-branch-plan \
  --goal-id my-goal \
  --width 3

The output lists candidate todo IDs, confidence scores, and resource‑lane hints. The Harness operates as a read‑only planner; it suggests experiments but does not claim or launch workers. You must manually claim suggested todos through your standard execution pipeline.

Alternatively, request a worker‑branch plan for resource‑specific allocations:

loopx explore worker-branch-plan --goal-id my-goal --width 5

Summary

• LoopX Explore capability maintains a canonical evidence graph at loopx/capabilities/explore/ for audit‑safe experiment tracking.
• Explore Graph (explore_graph.enabled) handles persistence and optional sink integration via sync_explore_graph_after_material_refresh.
• Explore Harness (spawn_policy.explore_harness.enabled) provides read‑only planning without automatic execution.
• Enable the capability via loopx configure-goal or the registry API, then trigger updates with loopx refresh-state.
• Visualize results using Lark integration configured through loopx explore feishu-visual-configure.

Frequently Asked Questions

What is the difference between Explore Graph and Explore Harness?

Explore Graph is the data persistence layer that records the evidence topology after each material refresh, while Explore Harness is a planning layer that reads that topology to suggest next experiments. You can enable the Graph alone for passive tracking, or combine both for active experiment recommendation.

Where is the Explore evidence data physically stored?

The canonical log is stored in your registry under goals/<goal-id>/explore-result-log.jsonl. This append‑only JSONL file is the source of truth, with projections generated dynamically during loopx refresh-state operations.

Does enabling Explore Harness automatically execute experiments?

No. The Harness operates as a read‑only planner. When you run loopx explore todo-branch-plan, it emits candidate branches with confidence scores and resource hints, but does not claim todos or launch workers. Execution remains a manual or separately automated step.

How do I customize the visual layout of the Explore graph in Lark?

Board styling is controlled through the --board-style parameter in loopx explore feishu-visual-configure. Valid options include auto_flow for automatic node positioning and semantic_lane_columns for column‑based grouping, defined in loopx/extensions/lark/presentation/explore_visual_styles.py.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}