tuner-testkit 4.2.0__tar.gz → 4.3.0__tar.gz

{tuner_testkit-4.2.0/tuner_testkit.egg-info → tuner_testkit-4.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tuner-testkit
-Version: 4.2.0
+Version: 4.3.0
 Summary: Shared test runtime, recorders, and DNA overlay for SUT test repos
 Author: tuner-testkit contributors
 License-Expression: MIT
@@ -138,10 +138,10 @@ uv tool upgrade tuner-testkit
 
 ```bash
 # 钉到某一发行版（推荐，和团队 lock 一致）
-uv add "tuner-testkit[db,api]==4.2.0"
+uv add "tuner-testkit[db,api]==4.3.0"
 
 # 或只抬下限，让解析器选允许范围内的最新
-# uv add "tuner-testkit[db,api]>=4.2.0"
+# uv add "tuner-testkit[db,api]>=4.3.0"
 
 uv sync
 ```
@@ -210,4 +210,4 @@ uv sync --extra all
 
 `uv sync --extra dev` 与 `--extra all` 等价（`dev` 只是引用 `[all]`）。
 
-4.2.0 发行说明见 [`docs/changelog/TEMPLATE-4.2.0.md`](docs/changelog/TEMPLATE-4.2.0.md)；3.x → 4.x 迁移见 [`TEMPLATE-4.0.0.md`](docs/changelog/TEMPLATE-4.0.0.md)。平台能力地图见 [`INDEX.md`](INDEX.md)。
+4.3.0 发行说明见 [`docs/changelog/TEMPLATE-4.3.0.md`](docs/changelog/TEMPLATE-4.3.0.md)；4.2.0 见 [`TEMPLATE-4.2.0.md`](docs/changelog/TEMPLATE-4.2.0.md)；3.x → 4.x 迁移见 [`TEMPLATE-4.0.0.md`](docs/changelog/TEMPLATE-4.0.0.md)。平台能力地图见 [`INDEX.md`](INDEX.md)。

{tuner_testkit-4.2.0 → tuner_testkit-4.3.0}/README.md

@@ -93,10 +93,10 @@ uv tool upgrade tuner-testkit
 
 ```bash
 # 钉到某一发行版（推荐，和团队 lock 一致）
-uv add "tuner-testkit[db,api]==4.2.0"
+uv add "tuner-testkit[db,api]==4.3.0"
 
 # 或只抬下限，让解析器选允许范围内的最新
-# uv add "tuner-testkit[db,api]>=4.2.0"
+# uv add "tuner-testkit[db,api]>=4.3.0"
 
 uv sync
 ```
@@ -165,4 +165,4 @@ uv sync --extra all
 
 `uv sync --extra dev` 与 `--extra all` 等价（`dev` 只是引用 `[all]`）。
 
-4.2.0 发行说明见 [`docs/changelog/TEMPLATE-4.2.0.md`](docs/changelog/TEMPLATE-4.2.0.md)；3.x → 4.x 迁移见 [`TEMPLATE-4.0.0.md`](docs/changelog/TEMPLATE-4.0.0.md)。平台能力地图见 [`INDEX.md`](INDEX.md)。
+4.3.0 发行说明见 [`docs/changelog/TEMPLATE-4.3.0.md`](docs/changelog/TEMPLATE-4.3.0.md)；4.2.0 见 [`TEMPLATE-4.2.0.md`](docs/changelog/TEMPLATE-4.2.0.md)；3.x → 4.x 迁移见 [`TEMPLATE-4.0.0.md`](docs/changelog/TEMPLATE-4.0.0.md)。平台能力地图见 [`INDEX.md`](INDEX.md)。

{tuner_testkit-4.2.0 → tuner_testkit-4.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tuner-testkit"
-version = "4.2.0"
+version = "4.3.0"
 description = "Shared test runtime, recorders, and DNA overlay for SUT test repos"
 readme = "README.md"
 license = "MIT"
@@ -73,6 +73,7 @@ tuner-index-platform = "tuner_testkit.apps.index_platform.__main__:main"
 tuner-fake = "tuner_testkit.fake.cli:main"
 tuner-page-test = "tuner_testkit.page_test.__main__:main"
 tuner-action-words = "tuner_testkit.action_words.__main__:main"
+tuner-evidence = "tuner_testkit.apps.evidence.cli:main"
 
 [build-system]
 requires = ["setuptools>=77", "wheel"]

{tuner_testkit-4.2.0 → tuner_testkit-4.3.0}/tuner_testkit/__init__.py

@@ -2,4 +2,4 @@
 
 from __future__ import annotations
 
-__version__ = "4.2.0"
+__version__ = "4.3.0"

{tuner_testkit-4.2.0 → tuner_testkit-4.3.0}/tuner_testkit/api_test/__init__.py

@@ -6,7 +6,13 @@ Primary entrypoints:
 """
 
 from .client import ApiClient
-from .model import APIModel, ApiResponse, AssertOperation, ExtractVariableOperation
+from .model import (
+    APIModel,
+    ApiResponse,
+    AssertOperation,
+    ExtractVariableOperation,
+    interpolate_path,
+)
 
 __all__ = [
     "APIModel",
@@ -14,5 +20,5 @@ __all__ = [
     "AssertOperation",
     "ExtractVariableOperation",
     "ApiClient",
+    "interpolate_path",
 ]
-

{tuner_testkit-4.2.0 → tuner_testkit-4.3.0}/tuner_testkit/api_test/model.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import re
 from dataclasses import dataclass, field, replace
 from typing import Any, Dict, Iterable, List, Mapping, MutableMapping, Optional
 
@@ -102,6 +103,22 @@ def _required_file_fields(schema: Mapping[str, Any]) -> list[str]:
     return out
 
 
+_PATH_PLACEHOLDER_RE = re.compile(r"\{([A-Za-z_][A-Za-z0-9_]*)\}")
+
+
+def interpolate_path(path: str, params: Mapping[str, Any]) -> str:
+    """Replace ``{name}`` segments. Raises if any named placeholder remains."""
+    out = path
+    for key, value in params.items():
+        out = out.replace("{" + str(key) + "}", str(value))
+    leftover = _PATH_PLACEHOLDER_RE.findall(out)
+    if leftover:
+        raise SchemaValidationError(
+            f"path still has placeholders {leftover}; pass them via set_path"
+        )
+    return out
+
+
 @dataclass(frozen=True)
 class APIModel:
     # Identity
@@ -156,6 +173,9 @@ class APIModel:
     def set_headers(self, values: Optional[Mapping[str, Any]] = None) -> "APIInvocation":
         return APIInvocation(self).set_headers(values)
 
+    def set_path(self, values: Optional[Mapping[str, Any]] = None) -> "APIInvocation":
+        return APIInvocation(self).set_path(values)
+
     def override_query(self, values: Optional[Mapping[str, Any]] = None) -> "APIInvocation":
         return APIInvocation(self).override_query(values)
 
@@ -181,6 +201,7 @@ class APIInvocation:
     _set_json: Dict[str, Any] = field(default_factory=dict)
     _set_files: Dict[str, Any] = field(default_factory=dict)
     _set_headers: Dict[str, Any] = field(default_factory=dict)
+    _path_params: Dict[str, Any] = field(default_factory=dict)
     _override_query: Optional[Dict[str, Any]] = None
     _override_json: Any = None
     _override_json_set: bool = False
@@ -237,6 +258,10 @@ class APIInvocation:
         checked = _enforce_headers_policy(headers=values, allowlist=allowlist, forbidden=forbidden)
         return replace(self, _set_headers=_merge_shallow(self._set_headers, checked))
 
+    def set_path(self, values: Optional[Mapping[str, Any]] = None) -> "APIInvocation":
+        values = {str(k): v for k, v in dict(values or {}).items()}
+        return replace(self, _path_params=_merge_shallow(self._path_params, values))
+
     def override_query(self, values: Optional[Mapping[str, Any]] = None) -> "APIInvocation":
         values = dict(values or {})
         # override still must respect schema; allow autofill via set_query if needed
@@ -308,6 +333,8 @@ class APIInvocation:
         from .client import ApiClient  # local import to avoid cycles
 
         m = self._effective_model()
+        if self._path_params:
+            m = replace(m, path=interpolate_path(m.path, self._path_params))
         use_client = client or m._client or ApiClient.default()
         files = self._final_files()
         self._validate_required_files(m, files)

tuner_testkit-4.3.0/tuner_testkit/apps/dna/dna_payload/.cursor/agents/sut-source-to-design.md

@@ -0,0 +1,33 @@
+---
+name: sut-source-to-design
+version: 1.0.0
+description: Walk SUT backend source (Django models/views/serializers, or equivalent) plus assets/ddl to draft assets/design/<app>/<route-slug>.md. Use when the engineer points at a source tree. Do not invent tables. Complements derive-design-knowledge; this agent is the source-channel playbook.
+---
+
+# SUT source → design knowledge
+
+## Purpose
+
+Highest-quality `writes` / `noise` / `reads` often come from **models.save / views**, not from MCP bodies. Plane dogfood: `Issue.save` showed `issue_sequences` + `_ensure_default_state` before any DB diff existed.
+
+## Inputs
+
+- Source root the user named (e.g. `C:\dev\repo\plane\apps\api`)
+- Matching `assets/ddl/<datasource>/` if present (dump missing tables rather than hallucinate)
+- Optional `artifacts/evidence/<run_id>/` to fill `api_object_ref` / `page_ref`
+
+## Workflow
+
+1. Locate the route: urls.py / router → view/serializer.
+2. Locate the model `.save()` / service function for that write.
+3. List INSERT/UPDATE/DELETE tables. Audit / `*_activities` / operation_log → `noise`.
+4. If a table is named in source but missing from DDL, run `tuner-dump-ddl <table> --datasource …` then continue. Do not skip the table.
+5. Write one `assets/design/<app>/<route-slug>.md` per **route** (not per button) using `docs/spec/design-knowledge-syntax.md` v0.1.
+6. Record schema gaps under `## notes` (conditional writes, defaulted FKs, dual identity). Do **not** invent new top-level keys yet.
+
+## Hard rules
+
+- Table/column names must appear in DDL or source. No guessed identifiers.
+- `confidence: inferred` for source-only; `observed` only with DB/log evidence.
+- No secrets.
+- Do not generate action words here.

tuner_testkit-4.3.0/tuner_testkit/apps/dna/dna_payload/.cursor/skills/analyze-mcp-network/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: analyze-mcp-network
+version: 1.0.0
+description: Turn a persisted artifacts/evidence/<run_id>/network.jsonl into a unique method+path route table (JSON) for freeze-api-objects. Prefer tuner-evidence routes (deterministic). Use after explore-sut or run-feature-playwright-mcp. Do not invent routes that are not in the JSONL.
+---
+
+# Analyze MCP network evidence
+
+## Scope
+
+- **Primary goal**: list freeze candidates from on-disk evidence.
+- **Write scope**: none (read-only). Optionally paste the JSON into the freeze handoff.
+- **Must follow**: `docs/spec/bdd-run-gherkin-in-playwrightMCP.md` sanitizer — if the JSONL still contains Cookie/Authorization, stop and re-run `tuner-evidence persist`.
+
+## Steps
+
+1. Confirm `artifacts/evidence/<run_id>/network.jsonl` exists.
+2. Run (stdout is JSON):
+
+```bash
+uv run python -m tuner_testkit.apps.evidence routes --run-id <run_id>
+```
+
+3. Hand the `routes[]` list to `freeze-api-objects`. Skip static/HTML. Skip `POST /api/sign-in/` (password body) unless the user explicitly wants a login API asset **without** persisting credentials.
+4. For slug paths that `normalize_path` left as literals (e.g. `/api/workspaces/tuner/...`), freeze with `{workspace_slug}` and tell callers to `set_path`.
+
+## Hard rules
+
+- Do not re-fetch live traffic here.
+- Do not write api_objects in this skill.

{tuner_testkit-4.2.0 → tuner_testkit-4.3.0}/tuner_testkit/apps/dna/dna_payload/.cursor/skills/derive-design-knowledge/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: derive-design-knowledge
-version: 0.1.0
+version: 0.2.0
 description: Compile assets/design/<app>/<route-slug>.md from open evidence channels (MCP network, DDL, SUT source, optional logs). Schema is docs/spec/design-knowledge-syntax.md v0.1 (draft). Use after an explore session or API freeze when DB effects must ground assertions. Do not invent tables that are not in DDL or source.
 ---
 
@@ -19,9 +19,10 @@ description: Compile assets/design/<app>/<route-slug>.md from open evidence chan
 2. For each captured **non-static mutating** route (POST/PUT/PATCH/DELETE):
    - Draft front-matter (`confidence`: `observed` only if DB/log proved it; else `inferred`).
    - Fill `writes` / `noise` / `reads` from the **highest quality channel available**:
-     1. source (models/views/serializers)
-     2. SQL logs / DB diff
-     3. inference from response body + DDL names
+   1. source (models/views/serializers) — see `.cursor/agents/sut-source-to-design.md`
+   2. SQL logs / DB diff
+   3. inference from response body + DDL names
+   - If source names a table that is not in `assets/ddl`, dump it (`tuner-dump-ddl`) before writing `writes`.
    - Skip `operation_log` / `*_activities` / audit tables as `noise` unless the user says they are the assertion target.
 3. Every `writes` row must cite evidence or a source path in `## notes`.
 4. If the v0.1 schema cannot express something (multi-API button, external side effects), write it under `## notes` and do **not** invent new top-level keys yet — the draft must be stress-tested first.

{tuner_testkit-4.2.0 → tuner_testkit-4.3.0}/tuner_testkit/apps/dna/dna_payload/.cursor/skills/explore-sut/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: explore-sut
-version: 1.0.0
+version: 1.1.0
 description: Explore-first Playwright MCP session against a live SUT. Produces sanitized artifacts/evidence/<run_id>/ plus assets/explore capability notes. Use when learning a web SUT, mapping pages/buttons, or gathering evidence before any .feature exists. Do NOT use when the user already has a feature to implement — use run-feature-playwright-mcp instead.
 ---
 
@@ -25,7 +25,17 @@ description: Explore-first Playwright MCP session against a live SUT. Produces s
 1. Read `INDEX.md` and `INDEX.project.md` if present. Note base URLs from `config`.
 2. Pick a **vertical slice** (e.g. workspace → project → issue), not a full-site crawl.
 3. Navigate with Playwright MCP. After each meaningful action, dump network + snapshot.
-4. Persist:
+4. Persist with **`tuner-evidence persist`** (do not leave captures only in chat):
+
+```bash
+uv run python -m tuner_testkit.apps.evidence persist \
+  --run-id YYYYMMDDTHHMMSSZ-<slice> \
+  --scenario explore:<intent> \
+  --network captures.jsonl \
+  --intent "short vertical-slice intent"
+```
+
+   Manual fallback (same files):
    - `artifacts/evidence/<run_id>/run_summary.md`
    - `artifacts/evidence/<run_id>/network.jsonl` (sanitized)
    - optional `actions.jsonl` / `snapshots/`
@@ -35,11 +45,11 @@ description: Explore-first Playwright MCP session against a live SUT. Produces s
    - primary actions (button labels)
    - APIs observed (method + path only)
    - blockers / i18n / env notes
-6. Stop. Do **not** freeze objects in this skill — tell the caller which run_id to freeze.
+6. Stop. Next: `tuner-evidence routes --run-id …` then freeze / derive-design / author feature.
 
 ## Output checklist
 
 - `run_id` and evidence directory exist.
 - Sanitizer applied statement in `run_summary.md`.
 - Explore note cites `evidence`.
-- Next-step suggestion: freeze / derive-design / author feature.
+- Next-step: `tuner-evidence routes` then freeze / derive-design / author feature.

{tuner_testkit-4.2.0 → tuner_testkit-4.3.0}/tuner_testkit/apps/dna/dna_payload/.cursor/skills/freeze-api-objects/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: freeze-api-objects
-version: 1.0.0
+version: 1.1.0
 description: Freezes sanitized Playwright MCP network captures into route-aligned, deduped API Objects under packages/api_objects/ following api-objects-syntax.md and bdd-run-gherkin-in-playwrightMCP.md. Use when creating/updating APIModel assets.
 ---
 
@@ -72,4 +72,5 @@ description: Freezes sanitized Playwright MCP network captures into route-aligne
 - No forbidden header keys or raw tokens in file content.
 - No host in APIModel path/url.
 - No scenario-specific constants asserted in APIModel.
-- File path follows route-tree naming and versioning: `<METHOD>.v<MAJOR>.py`.
+- Skip `POST /api/sign-in/` (and password-bearing login routes) unless explicitly required; never persist the password body.
+- If the path contains a workspace/org **slug**, freeze `{workspace_slug}` (not the live slug) and document `set_path`..

{tuner_testkit-4.2.0 → tuner_testkit-4.3.0}/tuner_testkit/apps/dna/dna_payload/.cursor/skills/run-feature-playwright-mcp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: run-feature-playwright-mcp
-version: 1.1.0
+version: 1.2.0
 description: Runs behave Gherkin scenarios (or records an explore session) via Playwright MCP with Run→Capture→Freeze workflow and strict sanitization. Evidence always lands under artifacts/evidence/<run_id>/. Do NOT require this skill when the user explicitly requests pytest-only work with no MCP capture need.
 ---
 
@@ -49,6 +49,7 @@ description: Runs behave Gherkin scenarios (or records an explore session) via P
   - sanitizer applied statement
 - **`artifacts/evidence/<run_id>/network.jsonl`** (required, sanitized):
   - one capture per request (see spec minimum fields)
+  - Prefer writing it via `tuner-evidence persist --network captures.jsonl` so the sanitizer is deterministic.
 - **`artifacts/evidence/<run_id>/actions.jsonl`** / `snapshots/` (optional)
 
 ## Verification checklist (must include in result)

{tuner_testkit-4.2.0 → tuner_testkit-4.3.0}/tuner_testkit/apps/dna/dna_payload/MANIFEST.txt

@@ -1,5 +1,5 @@
 {
-  "files": 47,
+  "files": 49,
   "paths": [
     ".cursor/rules",
     ".cursor/skills",

{tuner_testkit-4.2.0 → tuner_testkit-4.3.0}/tuner_testkit/apps/dna/dna_payload/docs/spec/api-objects-syntax.md

@@ -56,7 +56,9 @@ APIModel 的字段被分为三类：**Identity**、**Contract**、**Operations**
 - `name`: string（可中文）
 - `description`: string（允许 Markdown，建议结构化）
 - `method`: string（GET/POST/PUT/DELETE/…）
-- `path`: string（只允许 path，不允许写 host）
+- `path`: string（只允许 path，不允许写 host）。动态段写成 `{workspace_slug}` /
+  `{project_id}` / `{uuid}` 等；调用时用 **`set_path({...})`** 替换（4.3.0）。
+  `normalize_path` 只自动识别 uuid 与纯数字，**slug 不会被工具改写**，冻结时请手写占位名。
 
 ### 2) Contract（弱 schema 也可，但必须可约束）
 

{tuner_testkit-4.2.0 → tuner_testkit-4.3.0}/tuner_testkit/apps/dna/dna_payload/docs/spec/design-knowledge-syntax.md

@@ -94,9 +94,19 @@ page_ref:
   标成 `observed`。
 - 更新文档必须 bump `version`。
 
-## 6. 实践待决（dogfood 回来改）
+## 6. 实践待决（Plane dogfood 2026-09-13 回来改）
 
-- 要不要按「一次用户动作」而不是「一条路由」成文（一个按钮打出多条 API）？
-- `page_ref` 一个文档是否允许多个 trigger？
-- `writes` 是否需要 `where` 条件模板（UPDATE 场景）？
-- 要不要独立的 `externals:`（发邮件 / 写 S3 / 调 webhook）？
+已用 workspace→project→issue 切片压过 v0.1。**本版不升 schema**，只把缺口记在这里，待积累第二条切片再升 v0.2。
+
+| 缺口 | 实践 |
+| --- | --- |
+| 按路由还是按用户动作成文？ | **继续按路由**。本切片 Save=1 POST；登录是多条 PATCH。动作视图可写在 `assets/explore`，design 保持一路由一文。 |
+| `page_ref` 多个 trigger | 需要。工具栏 `Add work item` 与侧栏 `New work item` 打同一 POST。v0.2 考虑 `triggers: []`。 |
+| `writes` 的 `when:` | 需要。`issue_assignees` 仅当 `assignee_ids` 非空。 |
+| 默认值 / 空 body → DB 有值 | `state_id=""` → `_ensure_default_state`。`correlate` 表达不了。 |
+| 业务 identity 双键 | UUID `id` + UI `TUNER-{sequence_id}`。考虑 `business_identity`。 |
+| slug 占位 | `normalize_path` 不替换非 uuid slug；冻结时手写 `{workspace_slug}`，运行时 `set_path`。 |
+| `externals:` | 本切片未遇到（无邮件/S3）。仍待决。 |
+| 源码表先于 DDL | 允许：先从 models 写 design，再 `tuner-dump-ddl` 补表。 |
+
+样本：下游 dogfood `assets/design/web/post-api-workspaces-projects-issues.md`。

{tuner_testkit-4.2.0 → tuner_testkit-4.3.0}/tuner_testkit/apps/dna/dna_payload/docs/spec/sut-self-learning.md

@@ -82,10 +82,10 @@ artifacts/evidence/<run_id>/     ← 统一落盘（强制）
 
 ## 5. 分阶段路线图
 
-- **阶段 0（本版）**：契约先行——本文件 + design schema v0.1 + gates/路径/分诊树纠偏。
-- **阶段 1 证据落盘**：`artifacts/evidence/<run_id>/` 约定（本版已写入 MCP spec）；后续可加 `tuner_testkit.evidence` 包与 `explore-sut` skill。
-- **阶段 2 design 闭环**：`derive-design-knowledge` skill；可选 `tuner-db-diff`；`create-app` 引导证据工具。
-- **阶段 3 双路汇合**：`derive-feature-sets`；bdd-asset-pipeline 下半程（本版已改定位）。
+- **阶段 0（4.2.0）**：契约先行——本文件 + design schema v0.1 + gates/路径/分诊树纠偏。
+- **阶段 1 证据落盘（4.3.0）**：`tuner-evidence persist|routes`；`explore-sut` 强制走 CLI；PageModel `url_path` 占位插值；API `set_path`。
+- **阶段 2 design 闭环**：`derive-design-knowledge` + `sut-source-to-design` agent；schema 仍为 v0.1（Plane 切片缺口记在 design spec §6）。
+- **阶段 3 双路汇合**：`derive-feature-sets`；bdd-asset-pipeline 下半程。
 - **阶段 4 知识自治**：knowledge-curator；确定性 `secret-scan` hook。
 
 内循环用 `uv tool install --from <platform-repo>`；阶段收口才打 tag 发 PyPI。

tuner_testkit-4.3.0/tuner_testkit/apps/evidence/__init__.py

@@ -0,0 +1,5 @@
+"""Evidence persist CLI."""
+
+from .cli import main
+
+__all__ = ["main"]

tuner_testkit-4.3.0/tuner_testkit/apps/evidence/__main__.py

@@ -0,0 +1,4 @@
+from tuner_testkit.apps.evidence.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tuner_testkit-4.3.0/tuner_testkit/apps/evidence/cli.py

@@ -0,0 +1,89 @@
+"""CLI: persist / list sanitized MCP evidence under artifacts/evidence/<run_id>/.
+
+    python -m tuner_testkit.apps.evidence persist --run-id ID --scenario explore:x --network captures.jsonl
+    python -m tuner_testkit.apps.evidence routes --run-id ID
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from tuner_testkit.logging import log_error
+from tuner_testkit.project import ensure_project_on_path, project_root
+
+from .persist import load_jsonl, load_run, persist
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m tuner_testkit.apps.evidence",
+        description=(
+            "Sanitize Playwright MCP / network dumps and persist them under "
+            "artifacts/evidence/<run_id>/ as JSON (LLM-consumable)."
+        ),
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    persist_p = sub.add_parser("persist", help="write sanitized evidence for one run")
+    persist_p.add_argument("--run-id", required=True, help="ASCII run id, e.g. 20260913T134137Z-issue-slice")
+    persist_p.add_argument("--scenario", required=True, help="scenario_id or explore:<intent>")
+    persist_p.add_argument("--network", required=True, type=Path, help="JSONL of captures (one object per line)")
+    persist_p.add_argument("--actions", type=Path, default=None, help="optional actions JSONL")
+    persist_p.add_argument("--intent", default="", help="short intent blurb for generated run_summary.md")
+    persist_p.add_argument("--summary", type=Path, default=None, help="optional run_summary.md to copy")
+    persist_p.add_argument(
+        "--root",
+        type=Path,
+        default=None,
+        help="project root (default: tuner project_root())",
+    )
+
+    routes_p = sub.add_parser("routes", help="print unique method+path from an existing run")
+    routes_p.add_argument("--run-id", required=True)
+    routes_p.add_argument("--root", type=Path, default=None)
+    return parser
+
+
+def _print_json(payload: object) -> None:
+    sys.stdout.write(json.dumps(payload, ensure_ascii=False, default=str))
+    sys.stdout.write("\n")
+
+
+def main(argv: list[str] | None = None) -> int:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8")
+    ns = build_parser().parse_args(argv)
+    root = ns.root
+    if root is None:
+        ensure_project_on_path()
+        root = project_root()
+    try:
+        if ns.cmd == "persist":
+            captures = load_jsonl(ns.network)
+            actions = load_jsonl(ns.actions) if ns.actions else None
+            summary = ns.summary.read_text(encoding="utf-8") if ns.summary else None
+            payload = persist(
+                run_id=ns.run_id,
+                scenario_id=ns.scenario,
+                captures=captures,
+                actions=actions,
+                intent=ns.intent,
+                summary_text=summary,
+                root=root,
+            )
+            _print_json(payload)
+            return 0
+        if ns.cmd == "routes":
+            _print_json(load_run(ns.run_id, root=root))
+            return 0
+    except (OSError, ValueError, json.JSONDecodeError) as exc:
+        log_error("evidence cli failed", error=f"{type(exc).__name__}: {exc}")
+        return 1
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())