update/fmt docs, lineage_writes_for_frame

2026-05-24 23:22:58 +07:00
parent e48656c165
commit 2214746a54
50 changed files with 555 additions and 221 deletions
@@ -3,17 +3,20 @@
 `lda-workflow-as-struct` is a Python 3.14 prototype for `lda.chat`: an AI-assisted workflow system where an LLM plans structured workflows and a deterministic executor validates/runs them.

 Main packages live under `src/`:
+
 - `wf_core`: workflow model, validation, runtime semantics, frames, trace, interrupts, foreach, async execution.
 - `wf_authoring`: ergonomic authoring layer including `@node`, `NodeSpec`, `WorkflowBuilder`, conditions, paths, and subgraph wrapping.
 - `wf_mcp`: MCP broker/proxy layer for managing multiple backend MCP connections, transparent FastMCP proxying, live config/admin tools, hot reload, tool introspection, discovery/catalog snapshots, and eventual workflow build/run integration.

 Important docs:
+
 - `readme.md`: running design notes and architecture.
 - `authoring_sketch.md`: authoring API direction.
 - `wf_mcp_plan.md`: MCP proxy/broker/workflow integration plan.
 - `scratchpad.md`: rough design history.

 Current MCP direction:
+
 - Transparent proxy mode is the main product path.
 - Old broker mode remains useful for debugging/admin/catalog operations.
 - Protocol-native FastMCP proxying exposes upstream tools/resources/prompts as first-class MCP capabilities.
@@ -21,6 +24,7 @@ Current MCP direction:
 - Direct Serena is configured outside `wf_mcp` and should be preferred for code navigation/editing because it does not reset when `wf-mcp` hot-reloads.

 Recent `wf_mcp` capabilities:
+
 - Pydantic config boundary in `config_models.py`.
 - Config mutation boundary in `config_manager.py`.
 - Proxy validation in `proxy_validation.py`.
@@ -29,4 +33,4 @@ Recent `wf_mcp` capabilities:
 - Opaque cursor pagination helpers in `pagination.py`.
 - Admin tools under `wf.mcp_*`: list/get config, add/update/enable/disable/remove connection, reload config, list/get proxy tools.
 - `wf.mcp_list_proxy_tools` supports `connection_id`, `query`, `limit`, and `cursor`; returns `{tools, nextCursor, total}`.
- `wf.mcp_get_proxy_tool` returns one detailed proxied tool row with schema where available.
+- `wf.mcp_get_proxy_tool` returns one detailed proxied tool row with schema where available.
@@ -1,6 +1,7 @@
 # Style And Conventions

 General:
+
 - Python 3.14, `src/` layout, Pydantic v2 where external/boundary validation is useful.
 - Prefer explicit dataclasses for runtime/internal models and Pydantic for config/wire-ish boundary validation.
 - Async-first for MCP calls and workflow runtime interactions.
@@ -8,6 +9,7 @@ General:
 - Do not leak workflow-only fields into MCP `tools/list`.

 MCP/proxy conventions:
+
 - Transparent proxy mode is the product path; old broker mode is secondary/debug/admin-oriented.
 - Admin tools live under the reserved namespace `wf.mcp_*`.
 - Upstream FastMCP names use Namespace behavior: `<connection_id>_<local_tool_name>`, e.g. `everything.default_echo`.
@@ -17,6 +19,7 @@ MCP/proxy conventions:
 - `wf_mcp.config.json` is user-owned live config. Do not edit/revert it unless explicitly asked.

 Code style:
+
 - Use precise type hints and modern Python collection syntax (`list[str]`, `dict[str, Any]`).
 - Keep modules layered by responsibility; avoid stuffing everything into service/runtime files.
 - Prefer small helper modules when behavior becomes a boundary (`config_models.py`, `config_manager.py`, `proxy_validation.py`, `names.py`, `pagination.py`).
@@ -25,6 +28,7 @@ Code style:
 - For MCP client `CallToolResult.structured_content`, guard for `None` in tests before subscripting; use helper assertions where useful.

 Editing rules from repo collaboration:
+
 - Use `apply_patch` for manual code edits.
 - Do not revert user-owned changes.
- Direct Serena MCP is available and can be used for semantic navigation/editing; onboarding is already complete.
+- Direct Serena MCP is available and can be used for semantic navigation/editing; onboarding is already complete.
@@ -3,24 +3,29 @@
 Use PowerShell on Windows from the repo root.

 Testing:
+
 - `uv run --with pytest pytest -q`
 - Focused MCP proxy tests: `uv run --with pytest pytest tests/test_wf_mcp_transparent_proxy.py -q`
 - Focused names/pagination examples: `uv run --with pytest pytest tests/test_wf_mcp_names.py tests/test_wf_mcp_transparent_proxy.py -q`

 Lint/type checks:
+
 - `uv run ruff check src/wf_mcp tests`
 - Focused basedpyright example: `uv run basedpyright src/wf_mcp/transparent_proxy.py src/wf_mcp/pagination.py --level error`

 Formatting:
+
 - `uv run ruff format`

 CLI / MCP server:
+
 - `uv run wf-mcp --config wf_mcp.config.json serve`
 - Transparent proxy mode is default.
 - Old broker mode: `uv run wf-mcp --config wf_mcp.config.json serve --mode broker`
 - Optional compatibility/search flags: `--resources-as-tools`, `--prompts-as-tools`, `--search-tools`

 Useful live MCP admin tools exposed by `wf-mcp`:
+
 - `wf.mcp_list_connections`
 - `wf.mcp_get_config`
 - `wf.mcp_add_connection`
@@ -33,8 +38,9 @@ Useful live MCP admin tools exposed by `wf-mcp`:
 - `wf.mcp_get_proxy_tool`

 Useful Windows shell commands:
+
 - Fast search: `rg "pattern" path`
 - List files: `Get-ChildItem -Force`
 - Read file: `Get-Content -Path path`
 - Git status: `git status --short`
- Diff: `git diff -- path`
+- Diff: `git diff -- path`
@@ -1,6 +1,7 @@
 # Task Completion Checklist

 Before considering a code task done:
+
 - Run focused tests for the touched area.
 - Run full tests when the change affects shared behavior: `uv run --with pytest pytest -q`.
 - Run ruff on touched source/tests, usually `uv run ruff check src/wf_mcp tests` for MCP work.
@@ -10,8 +11,10 @@ Before considering a code task done:
 - Summarize functional changes and verification results concisely.

 Recent known-good full-suite count after proxy tool pagination/detail work:
+
 - `48 passed, 1 skipped`

 Known environment notes:
+
 - Windows sandbox may block commands with `CreateProcessAsUserW failed: 5`; retry important commands with escalation rather than working around via unsafe shell tricks.
- Codex/native MCP tool schemas may not refresh dynamically after `wf-mcp` hot reload. A fresh client/session may be needed to see newly added MCP tools.
+- Codex/native MCP tool schemas may not refresh dynamically after `wf-mcp` hot reload. A fresh client/session may be needed to see newly added MCP tools.