Claude/rea trace

ACKNOWLEDGEMENTS.md

@@ -44,3 +44,15 @@ and native result schema. No Shinka source, prompts or assets are copied into
 this repository. The earlier no-runtime-dependency statement describes the core;
 it does not apply when this optional extra is explicitly installed. Retain and
 review upstream license/notice material if distributing its dependency artifacts.
+
+## Design influence: REA (2026-10-14)
+
+The `trace` investigation toolkit borrows design ideas from
+[morluto/rea](https://github.com/morluto/rea) (Reverse Engineer Anything, MIT,
+reviewed at commit `9630c8ff46533fe63ec0e06212d01545070d17f0`): summary-first
+tools, three-valued results where absence is only claimed for exhaustive
+coverage, explicit authority/confidence on recovered facts, reconciliation of
+declared versus observed facts, an evidence-obligation ledger with stable
+diagnostic codes, and unpacking of bundled artifacts. No REA source code,
+prompts or assets are copied; LabWeft's implementation is independently written
+in Python for research projects rather than binaries.

README.md

@@ -67,6 +67,22 @@ Then ask your coding agent to read the project and use the Skill, for example:
 
 The scanner collects facts; **the host agent supplies research interpretation**. LabWeft does not infer a scientific map from directory names alone. The [bundled Skill protocol](research_harness/skill/research-harness/references/PROTOCOL.md) specifies how to record that interpretation. Fresh-chat automatic Skill discovery and every client/platform combination have not yet been certified.
 
+## Reverse-engineer a large or remote project (trace)
+
+Reading a research folder is reverse engineering: the tree records where files were saved, not what was studied. Inspired by [REA](https://github.com/morluto/rea), `trace` runs a read-only probe next to the data (stdlib only, Python 3.8+, over SSH on the host that mounts your NAS) and gives the agent coverage-aware, three-valued (found / not_found / unknown) investigation tools:
+
+```sh
+python labweft.py trace collect ./ws --source PROJ --root /mnt/nas/PROJ --host my-server --remote-dir /data/scratch
+python labweft.py trace outline ./ws --source PROJ --format text      # experiments grouped by what was varied x measured, across folders
+python labweft.py trace reconcile ./ws --source PROJ --path REPORT.md  # every printed number -> raw value / mean±SD (with SD convention) / same-line difference
+python labweft.py trace fetch ./ws --source PROJ --study STUDY --sync  # mirror only the cited files, hash-checked
+python labweft.py trace propose ./ws --source PROJ --study STUDY --out draft.json   # draft Cells/Runs with locators filled in
+python labweft.py trace obligations ./ws                               # evidence-obligation ledger for claims and runs
+python labweft.py mcp ./ws                                             # the same tools as a stdio MCP server
+```
+
+Files are classified by content, not name; controlled factors, replicate seeds and one-factor comparisons are recovered from configs, table columns and hyperparameters encoded in run names (e.g. `aw0.1_lw0.1_rh1_s7`); one experiment spread over summary tables, raw results, figure data and legacy copies is one experiment with several evidence locations; text inside tar/zip bundles is parsed. See [the investigation guide](research_harness/skill/research-harness/references/TRACE.md).
+
 ## Keep it local, share deliberately
 
 ```sh

README.zh-CN.md

@@ -67,6 +67,22 @@ Bootstrap 安装一个控制工作流程的 Skill，并完成初步事实扫描
 
 扫描器采集事实，**研究语义由当前 agent 理解后写入**。LabWeft 不会仅靠文件夹名称推断科学地图。[随包 Skill 协议](research_harness/skill/research-harness/references/PROTOCOL.md) 规定了这种理解的记录方式。新聊天自动发现 Skill、所有客户端及平台组合仍未逐一验证。
 
+## 逆向拆解大型或远程项目（trace）
+
+读一个科研文件夹本质上是逆向工程：目录记录的是文件存在哪，而不是研究了什么。受 [REA](https://github.com/morluto/rea) 启发，`trace` 在数据旁边运行一个只读探针（仅标准库，Python 3.8+，可通过 SSH 跑在挂载 NAS 的服务器上），再在本地给 agent 提供一组带覆盖率、三值结果（found / not_found / unknown）的调查工具：
+
+```sh
+python labweft.py trace collect ./ws --source PROJ --root /mnt/nas/PROJ --host my-server --remote-dir /data/scratch
+python labweft.py trace outline ./ws --source PROJ --format text      # 按“改了什么 × 测了什么”跨文件夹归并实验
+python labweft.py trace reconcile ./ws --source PROJ --path REPORT.md  # 报告里每个数字追到原始值 / 均值±SD（含口径）/ 同行差值
+python labweft.py trace fetch ./ws --source PROJ --study STUDY --sync  # 只拉取被引用的文件并校验哈希
+python labweft.py trace propose ./ws --source PROJ --study STUDY --out draft.json   # 自动填好定位符的 Cell/Run 草案
+python labweft.py trace obligations ./ws                               # 每条结论 / Run 的证据义务账本
+python labweft.py mcp ./ws                                             # 同一套工具的 stdio MCP 服务
+```
+
+它按内容（而不是文件名）判断配置、结果表、日志、启动脚本、报告；从配置、表格列和编码在 run 名里的超参（如 `aw0.1_lw0.1_rh1_s7`）恢复受控因子、重复 seed 与一因子对照；同一实验散落在汇总表、原始结果、画图数据、历史副本中时归为一个实验的多个证据位置；压缩包内的文本也会被解析。详见 [调查流程](research_harness/skill/research-harness/references/TRACE.md)。
+
 ## 本地使用，按需分享
 
 ```sh

research_harness/cli.py

@@ -119,6 +119,8 @@ def parser() -> argparse.ArgumentParser:
     sub = p.add_subparsers(dest="command", required=True)
     from .autoresearch import add_cli
     add_cli(sub)
+    from .trace.cli import add_cli as add_trace_cli
+    add_trace_cli(sub)
     s = sub.add_parser("init", help="Create a persistent research workspace, without moving source files")
     s.add_argument("workspace", nargs="?", default=".")
     s.add_argument("--name")
@@ -191,6 +193,12 @@ def main(argv: list[str] | None = None) -> int:
             from .autoresearch import dispatch
             emit(dispatch(args))
             return 0
+        if args.command in ("trace", "mcp"):
+            from .trace.cli import dispatch as trace_dispatch
+            out = trace_dispatch(args)
+            if out is not None:
+                emit(out)
+            return 0
         if args.command == "install-skill":
             emit(install_skill(args.agent, args.project, args.user))
             return 0
@@ -272,7 +280,7 @@ def main(argv: list[str] | None = None) -> int:
             if args.open:
                 serve(store, args.port, True)
         return 0
-    except (HarnessError, OSError, ValueError) as exc:
+    except (HarnessError, OSError, ValueError, KeyError) as exc:
         print(json.dumps({"error": str(exc)}, ensure_ascii=False), file=sys.stderr)
         return 2
 

research_harness/server.py

@@ -18,7 +18,14 @@
 
 def presentation(store: Store) -> dict:
     state = store.load()
-    return {**state, "comparison": compare(state), "drift": drift(state), "organization": organization(state), "mode": "live"}
+    out = {**state, "comparison": compare(state), "drift": drift(state), "organization": organization(state), "mode": "live"}
+    sem = store.root / "semantic_map.json"
+    if sem.is_file():  # paper view published by `labweft trace publish-map`
+        try:
+            out["semantic"] = json.loads(sem.read_text(encoding="utf-8"))
+        except ValueError:
+            pass
+    return out
 
 
 def export_html(store: Store, output: Path, *, include_evidence: bool = False,

research_harness/skill/research-harness/SKILL.md

@@ -28,6 +28,11 @@ Use `labweft` if installed, or the exact command prefix in
 can run `python /absolute/path/to/labweft.py` without pip installation. The commands
 below use legacy `rh` as shorthand for that same CLI. Quote all paths.
 
+For a large, remote (NAS/SSH) or custom-format project, investigate it first with
+[trace](references/TRACE.md): it recovers experiments by what was varied and
+measured, traces printed numbers to sources and drafts evidence-linked Cells/Runs,
+so you do not hand-write per-project parsing scripts.
+
 ## Non-negotiable boundaries
 
 - Read user/project constraints and persisted state before making a new plan.
@@ -67,6 +72,10 @@ below use legacy `rh` as shorthand for that same CLI. Quote all paths.
    reconciling it. If review establishes the new primary result is valid, submit
    a versioned patch for the run's status, evidence and transition marker, then
    sync again. Do not relabel an older fallback result as the current one.
+   **Large, remote or unfamiliar trees:** investigate first with `rh trace`
+   ([INVESTIGATE.md](references/INVESTIGATE.md)): collect next to the data,
+   read `overview`/`outline`, recover experiments and reconcile report numbers,
+   then `trace fetch --sync` only the evidence the map will cite.
 3. **Read necessary evidence.** Run `rh files WORKSPACE --offset 0 --limit 50`;
    follow `next_offset`. Read snapshots using `rh evidence WORKSPACE --sha HASH`;
    follow `next_start_line` when needed. Inspect the actual implementation path,