# How LoopX Projects Public-Safe Evidence Through the Lark Kanban Adapter

> Discover how LoopX leverages its .loopx/ source of truth and the Lark Kanban adapter to project public-safe evidence. Learn about sanitizing and syncing project state securely.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: how-to-guide
- Published: 2026-09-02

---

**LoopX uses the hidden `.loopx/` directory as its source of truth for project state, then sanitizes all evidence through `_public_safe_text()` before projecting it to Lark Kanban boards via the `sync_loopx_todos_to_lark_kanban()` adapter.**

The huangruiteng/loopx repository implements a secure evidence-projection pipeline that keeps sensitive data local while sharing sanitized progress updates. By treating `.loopx/` as the authoritative store and applying redaction rules before network transmission, LoopX ensures that public Kanban boards contain only safe, non-sensitive information.

## The Source of Truth: The `.loopx/` Directory

LoopX designates the **`.loopx/`** directory at the project root as the single source of truth for all configuration, state files, and local evidence. This hidden directory contains:

- **Kanban configuration** ([`lark-kanban.json`](https://github.com/huangruiteng/loopx/blob/main/lark-kanban.json)) storing base tokens, table IDs, and view mappings
- **Todo state files** tracking user and agent task progress
- **Local record mappings** that tie LoopX internal IDs to Lark record IDs for incremental syncs

Because this directory remains on the local filesystem and never transmits to external services, it can safely store file paths, internal URLs, and credential references that would otherwise pose security risks.

## How the Lark Kanban Adapter Syncs Evidence

The evidence-projection flow in [`loopx/extensions/lark/presentation/kanban.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/extensions/lark/presentation/kanban.py) follows a six-step pipeline that guarantees public-safety at every network boundary.

### Step 1: Resolving the State File

The `sync_loopx_todos_to_lark_kanban()` function begins by calling `resolve_todo_state_path()` to locate the state file under the project's `.loopx/` directory. This function accepts an optional custom path but defaults to the standard hidden directory structure (lines 21,726–21,734).

```python
from loopx.extensions.lark.presentation.kanban import (
    resolve_todo_state_path,
    sync_loopx_todos_to_lark_kanban
)

# Resolves to .loopx/todos.json by default

state_path = resolve_todo_state_path(registry_path, goal_id="my-goal")

```

### Step 2: Loading Raw Todos

Once located, the adapter reads the state file and extracts todo blocks for both "user" and "agent" sections. The parsing loop filters out completed items unless the caller explicitly sets `include_done=True` (lines 21,740–21,766).

### Step 3: Public-Safe Transformation

Before any data leaves the local machine, each string field passes through `_public_safe_text()`. This sanitizer, implemented at lines 21,94–21,104, **redacts** local file paths, private URLs, internal IDs, and credential references.

The helper `_lark_record_from_todo_block()` invokes this transformation via `_public_safe_lark_values()` (lines 21,123–21,128), ensuring the resulting JSON payload contains only public-safe evidence:

```python
from loopx.extensions.lark.presentation.kanban import _public_safe_lark_values

raw_evidence = "See file:///home/user/.ssh/id_rsa for details"
safe_payload = _public_safe_lark_values({"Evidence": raw_evidence})

# Result: {"Evidence": "[local-path-redacted]"}

```

### Step 4: Projecting Issue-Fix Outcomes

The adapter also handles structured issue-fix outcomes generated by the `issue_fix` capability. The `_lark_record_from_projection_block()` function transforms these outcomes into Lark rows while again applying the public-safe sanitizer (lines 22,26–22,44 and 21,123–21,128).

### Step 5: Writing to Lark

For each sanitized row, the adapter builds a `lark-cli` record-upsert command via `build_record_upsert_command()` (lines 21,558–21,574). The command contains the redacted JSON payload, ensuring only public-safe evidence reaches the remote Kanban board. Execution occurs at lines 21,106–21,112, or runs in simulation mode if `execute=False`.

### Step 6: Persisting the Local Mapping

After a successful upsert, the local mapping (`record_map`) that ties LoopX todo IDs to Lark record IDs writes back into `.loopx/` via `write_lark_kanban_local_config()` (lines 21,336–21,345). This persistence (lines 21,138–21,144) maintains the source of truth locally and enables subsequent incremental syncs without re-creating remote records.

## Code Examples

### Syncing Todos to Lark

Execute a live sync that reads from `.loopx/` and pushes sanitized data to your Lark Kanban board:

```python
from pathlib import Path
from loopx.extensions.lark.presentation.kanban import (
    LarkKanbanConfig,
    default_lark_kanban_config_path,
    sync_loopx_todos_to_lark_kanban,
)

# Load the local Kanban config stored in .loopx

config = LarkKanbanConfig(
    base_token="my_base_token",
    table_id="tbl_12345",
    view_id="vew_kanban",
)

# Sync todos for a specific goal

result = sync_loopx_todos_to_lark_kanban(
    config,
    registry_path=Path.cwd(),
    goal_id="my-goal",
    agent_id="codex-kanban-worker",
    execute=True,  # Actually push to Lark

)

print(f"{result['successful_write_count']} rows written to Lark")

```

### Inspecting the Sanitization

Preview how sensitive data gets redacted before transmission:

```python
from loopx.extensions.lark.presentation.kanban import _public_safe_lark_values

raw_evidence = "Internal server at http://192.168.1.50:8080 failed"
safe_payload = _public_safe_lark_values({"Evidence": raw_evidence})
print(safe_payload["Evidence"])

# Output: "[url-redacted]"

```

### Reading Local Configuration

Access the Kanban configuration stored in your source-of-truth directory:

```python
from pathlib import Path
from loopx.extensions.lark.presentation.kanban import read_lark_kanban_local_config

cfg = read_lark_kanban_local_config(Path(".loopx/lark-kanban.json"))
print(cfg["board"]["base_token"])  # Local copy, never fetched from Lark

```

## Summary

- LoopX treats **`.loopx/`** as the authoritative source of truth for all project state, configurations, and todo mappings.
- The `sync_loopx_todos_to_lark_kanban()` function in [`loopx/extensions/lark/presentation/kanban.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/extensions/lark/presentation/kanban.py) orchestrates the projection workflow.
- Every piece of evidence passes through **`_public_safe_text()`** before network transmission, redacting file paths, private URLs, and credentials.
- Issue-fix outcomes undergo the same sanitization via `_lark_record_from_projection_block()`.
- Local-to-remote ID mappings persist back into `.loopx/` via `write_lark_kanban_local_config()`, maintaining incremental sync capability while keeping sensitive metadata local.
- The `lark-cli` integration executes only after sanitization completes, ensuring the Kanban board receives exclusively public-safe evidence.

## Frequently Asked Questions

### What is the `.loopx/` directory used for in LoopX?

The `.loopx/` directory serves as the project's hidden source of truth, storing todo state files, Kanban configuration ([`lark-kanban.json`](https://github.com/huangruiteng/loopx/blob/main/lark-kanban.json)), and local ID mappings. Because it remains on the local filesystem, it safely contains sensitive paths and credentials that should never reach external APIs.

### How does LoopX ensure sensitive data isn't exposed to Lark?

LoopX implements a public-safe sanitization layer via `_public_safe_text()` and `_public_safe_lark_values()` in [`kanban.py`](https://github.com/huangruiteng/loopx/blob/main/kanban.py). These functions intercept all string data before transmission and replace local file paths, private IP addresses, internal URLs, and credential references with redacted tokens like `[local-path-redacted]`.

### Can I preview the sanitized data before sending it to Lark?

Yes. Set `execute=False` when calling `sync_loopx_todos_to_lark_kanban()` to run in simulation mode. The function will build and log the `lark-cli` commands without executing them, allowing inspection of the sanitized JSON payloads. You can also call `_public_safe_lark_values()` directly on your evidence strings to preview the redaction.

### Where does LoopX store the mapping between local todos and Lark records?

LoopX persists these mappings in [`.loopx/lark-kanban.json`](https://github.com/huangruiteng/loopx/blob/main/.loopx/lark-kanban.json) via the `write_lark_kanban_local_config()` function. This local storage strategy maintains the association between LoopX internal IDs and remote Lark record IDs, enabling efficient incremental updates without requiring state queries from the Lark API.