superlab 0.1.8 → 0.1.10

package/README.md

@@ -55,6 +55,8 @@ This writes:
 - `.lab/changes/`
 - `.lab/.managed/templates/`
 - `.lab/.managed/scripts/`
+- `results/`
+- `figures/`
 
 If you prefer non-interactive use:
 
@@ -87,6 +89,14 @@ Refresh a specific project:
 superlab update --target /path/to/project
 ```
 
+Attach a user-provided LaTeX template directory without rewriting it:
+
+```bash
+superlab paper attach-template --target /path/to/project --path /path/to/template
+```
+
+This only records the template root in project config. Template files are treated as user-owned assets and may already include upstream or local modifications. `superlab` does not rewrite them by default.
+
 Refresh every registered project initialized from this user account:
 
 ```bash
@@ -133,8 +143,11 @@ superlab doctor
 
 - required `.lab` files
 - `workflow.json` schema
+- `results_root` and `figures_root` placement
 - `deliverables_root` placement
+- `paper_template_root` when configured
 - LaTeX-first paper output layout under `<deliverables_root>/paper/`
+- boundary violations such as durable run outputs stored under `.lab/changes/*/runs`
 
 ## Version
 
@@ -174,7 +187,10 @@ This installer also writes `.lab/config/workflow.json`, which is the global cont
 - `workflow_language`
 - `paper_language`
 - `paper_format`
+- `results_root`
+- `figures_root`
 - `deliverables_root`
+- `paper_template_root`
 
 Stages should follow that file rather than guess language locally.
 
@@ -189,9 +205,11 @@ Stages should follow that file rather than guess language locally.
 ## Command Set
 
 - `/lab:idea` researches an idea, critiques it, and writes the initial research framing.
+- `/lab:data` turns the approved idea into a dataset and benchmark package with years, paper usage, source audit, download plans, explicit benchmark-role rationale for classic-public, recent-strong-public, and claim-specific benchmarks, and explicit comparison rationale for canonical baselines, strong historical baselines, recent strong public methods, and closest prior work.
 - `/lab:framing` locks paper-facing method names, module names, titles, and contribution wording before drafting.
 - `/lab:spec` converts the approved idea into one `.lab/changes/<change-id>/` directory.
 - `/lab:run` executes a small-scale validation run and establishes the evaluation pipeline.
+- Durable run outputs should go under the configured `results_root`, not `.lab/changes/`.
 - `/lab:iterate` runs bounded experiment loops with fixed mission, explicit thresholds, and per-round reports.
 - `/lab:review` audits documents and results in reviewer mode.
 - `/lab:report` produces the final report from accumulated artifacts.
@@ -208,6 +226,7 @@ See the source command docs in [commands/codex/lab.md](/Users/zhouhao119/coding/
 - `skills/lab/` contains the shared workflow contract and reference guidance.
 - `templates/` contains durable document templates.
 - `scripts/` contains reproducibility helpers.
+- `results/` and `figures/` are the natural roots for durable experiment outputs and plots.
 - `tests/` contains minimal regression coverage for the helper scripts.
 - `examples/` contains a minimal end-to-end usage example.
 - `docs/` contains the design spec and release notes.
@@ -215,13 +234,14 @@ See the source command docs in [commands/codex/lab.md](/Users/zhouhao119/coding/
 ## Typical Flow
 
 1. Run `/lab:idea` to produce the initial idea artifact.
-2. Run `/lab:spec` to convert the idea into one self-contained lab change directory.
-3. Run `/lab:run` to verify the experiment path and register the first run.
-4. Run `/lab:iterate` to improve against fixed targets using bounded iterations.
-5. Run `/lab:review` whenever you need reviewer-grade critique.
-6. Run `/lab:report` to synthesize the final report.
-7. Run `/lab:framing` to lock naming, title, and contribution wording.
-8. Run `/lab:write` to draft paper sections from stable report evidence.
+2. Run `/lab:data` to lock the approved dataset package, source hierarchy, benchmark-class coverage, and the rationale for each comparison-method class.
+3. Run `/lab:spec` to convert the idea into one self-contained lab change directory.
+4. Run `/lab:run` to verify the experiment path and register the first run.
+5. Run `/lab:iterate` to improve against fixed targets using bounded iterations.
+6. Run `/lab:review` whenever you need reviewer-grade critique.
+7. Run `/lab:report` to synthesize the final report.
+8. Run `/lab:framing` to lock naming, title, and contribution wording.
+9. Run `/lab:write` to draft paper sections from stable report evidence.
 
 `/lab:write` writes final manuscript output under the configured `deliverables_root` (default: `docs/research`):
 
@@ -235,6 +255,14 @@ Internal writing-control artifacts stay under:
 - `.lab/writing/plan.md`
 - `.lab/writing/iterations/*.md`
 
+If `paper_template_root` is configured, `/lab:write` should inspect that template directory first and align drafting to it. If no template is configured, it falls back to the managed default LaTeX scaffold.
+
+`/lab` treats `.lab/` as the workflow-control layer only. Durable outputs should use natural project roots:
+
+- `results_root` for logs, checkpoints, and metrics
+- `figures_root` for plots and exported figures
+- `deliverables_root` for reports and paper sources
+
 ## Helper Scripts
 
 - `scripts/register_run.py` records run metadata in a JSON registry.

package/README.zh-CN.md

@@ -53,6 +53,8 @@ npx github:zhouhaoUCAS/superlab init
 - `.lab/changes/`
 - `.lab/.managed/templates/`
 - `.lab/.managed/scripts/`
+- `results/`
+- `figures/`
 
 如果你更喜欢非交互方式，也可以直接传参：
 
@@ -85,6 +87,14 @@ superlab update
 superlab update --target /path/to/project
 ```
 
+接入一个用户自己提供的 LaTeX 模板目录，但默认不改模板文件：
+
+```bash
+superlab paper attach-template --target /path/to/project --path /path/to/template
+```
+
+这个命令只会把模板目录记录进项目配置。模板目录会被视为用户资产，里面可能已经有上游或你自己的修改，`superlab` 默认不会重写它。
+
 刷新当前用户登记过的所有项目：
 
 ```bash
@@ -131,8 +141,11 @@ superlab doctor
 
 - 必需的 `.lab` 文件是否存在
 - `workflow.json` 结构是否合法
+- `results_root` 和 `figures_root` 是否放在合理位置
 - `deliverables_root` 是否放在合理位置
+- `paper_template_root` 在配置时是否合法
 - `<deliverables_root>/paper/` 下是否仍然满足 LaTeX-first 输出约束
+- 是否把长期 run 输出错误地堆在 `.lab/changes/*/runs`
 
 ## 版本查询
 
@@ -172,7 +185,10 @@ superlab init --lang en
 - `workflow_language`
 - `paper_language`
 - `paper_format`
+- `results_root`
+- `figures_root`
 - `deliverables_root`
+- `paper_template_root`
 
 后续 stage 应该按这个配置决定语言和论文格式，而不是各模板自己猜。
 
@@ -187,9 +203,11 @@ superlab init --lang en
 ## 命令集合
 
 - `/lab:idea` 调研 idea、文献、数据集、指标和 baseline，并输出初始方案。
+- `/lab:data` 把已批准的 idea 收敛成数据集与 benchmark 方案，要求记录年份、使用论文、来源审计、下载计划，并明确 classic-public、recent-strong-public、claim-specific 三类 benchmark 的纳入理由，以及 canonical baselines、strong historical baselines、recent strong public methods、closest prior work 四类对比方法的纳入理由。
 - `/lab:framing` 在正式写作前收紧方法名、模块名、论文题目和 contribution wording。
 - `/lab:spec` 把批准后的方案转换成一个统一的 `.lab/changes/<change-id>/` 目录。
 - `/lab:run` 执行最小可运行实验，并建立首版评估链路。
+- 持久 run 输出应写到 `results_root`，不要写进 `.lab/changes/`。
 - `/lab:iterate` 以固定 mission、固定阈值和最大轮次做有边界的实验迭代。
 - `/lab:review` 以审稿人模式检查方法、对照、公平性、泄漏和统计问题。
 - `/lab:report` 根据累积工件生成最终实验报告。
@@ -201,13 +219,14 @@ superlab init --lang en
 
 1. 在目标项目执行 `superlab init`。
 2. 在 Codex 或 Claude 中直接调用 `/lab:idea`。
-3. 经确认后执行 `/lab:spec`。
-4. 用 `/lab:run` 打通最小实验链路。
-5. 用 `/lab:iterate` 进行多轮迭代。
-6. 在关键节点运行 `/lab:review`。
-7. 最后用 `/lab:report` 产出总报告。
-8. 用 `/lab:framing` 收紧题目、命名和 contribution wording。
-9. 用 `/lab:write` 把稳定结果写成论文各 section。
+3. 经确认后执行 `/lab:data`，锁定数据集、下载来源、benchmark 类别覆盖，以及各类对比方法的纳入理由。
+4. 再执行 `/lab:spec`。
+5. 用 `/lab:run` 打通最小实验链路。
+6. 用 `/lab:iterate` 进行多轮迭代。
+7. 在关键节点运行 `/lab:review`。
+8. 最后用 `/lab:report` 产出总报告。
+9. 用 `/lab:framing` 收紧题目、命名和 contribution wording。
+10. 用 `/lab:write` 把稳定结果写成论文各 section。
 
 `/lab:write` 会把最终可交付物写到 `deliverables_root` 指定的目录，默认是 `docs/research`：
 
@@ -221,6 +240,14 @@ superlab init --lang en
 - `.lab/writing/plan.md`
 - `.lab/writing/iterations/*.md`
 
+如果配置了 `paper_template_root`，`/lab:write` 应先检查该模板目录并按其结构写作；如果没有配置模板，就回退到内置的默认 LaTeX scaffold。
+
+`/lab` 把 `.lab/` 视为工作流控制层，不是正式结果目录。持久输出应按自然根目录放置：
+
+- `results_root`：日志、checkpoint、metrics
+- `figures_root`：图表和导出图片
+- `deliverables_root`：报告和论文源码
+
 ## 仓库内容
 
 - `commands/` 是源码仓库里的说明文件。
@@ -228,6 +255,7 @@ superlab init --lang en
 - `skills/lab/` 是仓库开发时使用的共享 workflow 定义。
 - `templates/` 是研究工件模板。
 - `scripts/` 是运行登记、评估汇总和结果校验脚本。
+- `results/` 和 `figures/` 是默认的自然结果目录。
 - `tests/` 是脚本与安装器测试。
 - `examples/` 是最小端到端示例。
 - `docs/` 存放设计文档和发布说明。