superlab 0.1.9 → 0.1.11

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,33 @@ 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`
+
+## Auto Mode
+
+First fill `.lab/context/auto-mode.md` with the bounded contract, the per-stage commands, and the policy check commands for the campaign, then arm it for the current project:
+
+```bash
+superlab auto start
+```
+
+Inspect the live auto-mode state:
+
+```bash
+superlab auto status
+```
+
+Stop the current auto-mode run:
+
+```bash
+superlab auto stop
+```
+
+`/lab:auto` is an orchestration mode layered on top of approved execution stages. It reuses `run`, `iterate`, `review`, `report`, and optional `write` inside the limits defined by `.lab/context/auto-mode.md` and `.lab/context/auto-status.md`. `superlab auto start` runs the configured stage commands in the foreground, polls for completion, enforces `success/stop/promotion` check commands, and guards the configured frozen core. It does not replace manual `idea`, `data`, `framing`, or `spec` decisions.
 
 ## Version
 
@@ -174,7 +209,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 +227,12 @@ 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:auto` orchestrates approved `run`, `iterate`, `review`, `report`, and optional `write` stages inside a bounded contract and can promote exploratory additions to the primary package when the promotion policy is satisfied.
 - `/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 +249,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 +257,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 +278,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,33 @@ superlab doctor
 
 - 必需的 `.lab` 文件是否存在
 - `workflow.json` 结构是否合法
+- `results_root` 和 `figures_root` 是否放在合理位置
 - `deliverables_root` 是否放在合理位置
+- `paper_template_root` 在配置时是否合法
 - `<deliverables_root>/paper/` 下是否仍然满足 LaTeX-first 输出约束
+- 是否把长期 run 输出错误地堆在 `.lab/changes/*/runs`
+
+## 自动模式
+
+先填写 `.lab/context/auto-mode.md`，明确本次自治执行的边界契约、各阶段命令，以及 success/stop/promotion 的检查命令，再启动当前项目的自动模式：
+
+```bash
+superlab auto start
+```
+
+查看自动模式当前状态：
+
+```bash
+superlab auto status
+```
+
+停止当前自动模式：
+
+```bash
+superlab auto stop
+```
+
+`/lab:auto` 是叠加在现有执行阶段之上的编排模式。它会在 `.lab/context/auto-mode.md` 和 `.lab/context/auto-status.md` 的约束下，复用 `run`、`iterate`、`review`、`report`，以及可选的 `write`。`superlab auto start` 会在前台执行这些已配置阶段命令、轮询完成情况，并真正执行 success/stop/promotion 检查命令，同时保护已声明的 frozen core。它不会替代手动的 `idea`、`data`、`framing`、`spec` 决策。
 
 ## 版本查询
 
@@ -172,7 +207,10 @@ superlab init --lang en
 - `workflow_language`
 - `paper_language`
 - `paper_format`
+- `results_root`
+- `figures_root`
 - `deliverables_root`
+- `paper_template_root`
 
 后续 stage 应该按这个配置决定语言和论文格式，而不是各模板自己猜。
 
@@ -187,9 +225,12 @@ 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:auto` 在已批准边界内编排 `run`、`iterate`、`review`、`report` 和可选 `write`，并在升格策略满足时允许把 exploratory additions 自动升级为 primary package。
 - `/lab:spec` 把批准后的方案转换成一个统一的 `.lab/changes/<change-id>/` 目录。
 - `/lab:run` 执行最小可运行实验，并建立首版评估链路。
+- 持久 run 输出应写到 `results_root`，不要写进 `.lab/changes/`。
 - `/lab:iterate` 以固定 mission、固定阈值和最大轮次做有边界的实验迭代。
 - `/lab:review` 以审稿人模式检查方法、对照、公平性、泄漏和统计问题。
 - `/lab:report` 根据累积工件生成最终实验报告。
@@ -201,13 +242,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 +263,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 +278,7 @@ superlab init --lang en
 - `skills/lab/` 是仓库开发时使用的共享 workflow 定义。
 - `templates/` 是研究工件模板。
 - `scripts/` 是运行登记、评估汇总和结果校验脚本。
+- `results/` 和 `figures/` 是默认的自然结果目录。
 - `tests/` 是脚本与安装器测试。
 - `examples/` 是最小端到端示例。
 - `docs/` 存放设计文档和发布说明。