superlab 0.1.25 → 0.1.27

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (26) hide show
  1. package/README.md +6 -1
  2. package/README.zh-CN.md +6 -2
  3. package/lib/i18n.cjs +78 -3
  4. package/package-assets/claude/commands/lab-write.md +1 -1
  5. package/package-assets/claude/commands/lab.md +3 -1
  6. package/package-assets/codex/prompts/lab-write.md +1 -1
  7. package/package-assets/codex/prompts/lab.md +3 -1
  8. package/package-assets/shared/lab/.managed/scripts/validate_manuscript_delivery.py +175 -0
  9. package/package-assets/shared/lab/.managed/scripts/validate_paper_plan.py +228 -0
  10. package/package-assets/shared/lab/.managed/templates/paper-figure.tex +6 -0
  11. package/package-assets/shared/lab/.managed/templates/paper-plan.md +54 -0
  12. package/package-assets/shared/lab/.managed/templates/paper-references.bib +9 -0
  13. package/package-assets/shared/lab/.managed/templates/paper-table.tex +13 -0
  14. package/package-assets/shared/skills/lab/SKILL.md +9 -4
  15. package/package-assets/shared/skills/lab/references/paper-writing/examples/conclusion/conservative-claim-boundary.md +27 -0
  16. package/package-assets/shared/skills/lab/references/paper-writing/examples/conclusion-examples.md +16 -0
  17. package/package-assets/shared/skills/lab/references/paper-writing/examples/experiments/figure-placeholder-and-discussion.md +44 -0
  18. package/package-assets/shared/skills/lab/references/paper-writing/examples/experiments/main-results-and-ablation-latex.md +83 -0
  19. package/package-assets/shared/skills/lab/references/paper-writing/examples/experiments-examples.md +17 -0
  20. package/package-assets/shared/skills/lab/references/paper-writing/examples/index.md +12 -3
  21. package/package-assets/shared/skills/lab/references/paper-writing/examples/related-work/closest-prior-gap-template.md +20 -0
  22. package/package-assets/shared/skills/lab/references/paper-writing/examples/related-work/topic-comparison-template.md +24 -0
  23. package/package-assets/shared/skills/lab/references/paper-writing/examples/related-work-examples.md +17 -0
  24. package/package-assets/shared/skills/lab/references/paper-writing-integration.md +19 -10
  25. package/package-assets/shared/skills/lab/stages/write.md +37 -1
  26. package/package.json +1 -1
package/README.md CHANGED
@@ -255,7 +255,7 @@ Stages should follow that file rather than guess language locally.
255
255
  - Python 3.10+
256
256
  - Git
257
257
 
258
- `/lab:write` ships with vendored paper-writing references and the upstream example bank for `abstract`, `introduction`, and `method` under the installed `lab` skill, so it does not depend on an extra runtime skill installation.
258
+ `/lab:write` ships with vendored paper-writing references, the upstream example bank for `abstract`, `introduction`, and `method`, and local manuscript-delivery examples for `related work`, `experiments`, and `conclusion` under the installed `lab` skill, so it does not depend on an extra runtime skill installation.
259
259
 
260
260
  ## Command Set
261
261
 
@@ -311,7 +311,10 @@ See the source command docs in [commands/codex/lab.md](/Users/zhouhao119/coding/
311
311
  - `docs/research/main-tables.md`
312
312
  - `docs/research/artifact-status.md`
313
313
  - `docs/research/paper/main.tex`
314
+ - `docs/research/paper/references.bib`
314
315
  - `docs/research/paper/sections/*.tex`
316
+ - `docs/research/paper/tables/*.tex`
317
+ - `docs/research/paper/figures/*.tex`
315
318
 
316
319
  Internal writing-control artifacts stay under:
317
320
 
@@ -323,6 +326,7 @@ If `paper_template_root` is configured, `/lab:write` should inspect that templat
323
326
  If no template is configured, the first manuscript-writing round should ask once whether to continue with the managed default LaTeX scaffold or attach a template directory first.
324
327
  If the user approves the default scaffold, persist that choice in `.lab/config/workflow.json` and stop asking on ordinary rounds.
325
328
  At the final export or final-draft boundary, if the project is still on the default scaffold and no attached template exists, ask one final reminder question before finalizing.
329
+ For final-draft or export rounds, `/lab:write` should materialize real LaTeX tables, figure placeholders with figure intent, a non-empty `references.bib`, and pass `.lab/.managed/scripts/validate_manuscript_delivery.py --paper-dir <deliverables_root>/paper` before stopping.
326
330
 
327
331
  `/lab` treats `.lab/` as the workflow-control layer only. Durable outputs should use natural project roots:
328
332
 
@@ -336,6 +340,7 @@ At the final export or final-draft boundary, if the project is still on the defa
336
340
  - `scripts/eval_report.py` normalizes metrics into a comparable summary.
337
341
  - `scripts/summarize_iterations.py` rolls multiple iteration summaries into one file.
338
342
  - `scripts/validate_results.py` verifies required report fields before publication.
343
+ - `scripts/validate_manuscript_delivery.py` verifies that the paper deliverable contains basic manuscript-ready tables, figures, citations, and bibliography.
339
344
 
340
345
  ## Packaging
341
346
 
package/README.zh-CN.md CHANGED
@@ -253,7 +253,7 @@ superlab init --lang en
253
253
  - Python 3.10+
254
254
  - Git
255
255
 
256
- `/lab:write` 自带 vendored 的 paper-writing 章节参考,以及 `abstract`、`introduction`、`method` 对应的 upstream example bank,不再依赖额外安装一个运行时写作 skill。
256
+ `/lab:write` 自带 vendored 的 paper-writing 章节参考、`abstract`、`introduction`、`method` 对应的 upstream example bank,以及为 `related work`、`experiments`、`conclusion` 补齐的 manuscript-delivery examples,不再依赖额外安装一个运行时写作 skill。
257
257
 
258
258
  ## 命令集合
259
259
 
@@ -296,7 +296,10 @@ Codex 和 Claude 的命令入口不一样:
296
296
  - `docs/research/main-tables.md`
297
297
  - `docs/research/artifact-status.md`
298
298
  - `docs/research/paper/main.tex`
299
+ - `docs/research/paper/references.bib`
299
300
  - `docs/research/paper/sections/*.tex`
301
+ - `docs/research/paper/tables/*.tex`
302
+ - `docs/research/paper/figures/*.tex`
300
303
 
301
304
  内部写作控制工件放在:
302
305
 
@@ -308,6 +311,7 @@ Codex 和 Claude 的命令入口不一样:
308
311
  如果没有配置模板,第一次进入论文 `.tex` 写作时应先追问一次:继续使用内置默认 LaTeX scaffold,还是先接入模板目录。
309
312
  如果用户确认先用默认 scaffold,就把这个决定持久化到 `.lab/config/workflow.json`,后续普通轮次不再重复追问。
310
313
  但在最终导出或最终定稿节点,如果项目仍在使用默认 scaffold 且没有接入模板,应再提醒一次,给用户最后切换模板的机会。
314
+ 在最终定稿或导出轮次里,`/lab:write` 还应物化真正的 LaTeX 表格、带图意图的 figure placeholders、非空的 `references.bib`,并在停止前通过 `.lab/.managed/scripts/validate_manuscript_delivery.py --paper-dir <deliverables_root>/paper`。
311
315
 
312
316
  `/lab` 把 `.lab/` 视为工作流控制层,不是正式结果目录。持久输出应按自然根目录放置:
313
317
 
@@ -321,7 +325,7 @@ Codex 和 Claude 的命令入口不一样:
321
325
  - `package-assets/` 是 npm 安装时真正分发到目标项目的命令与 skill 资产。
322
326
  - `skills/lab/` 是仓库开发时使用的共享 workflow 定义。
323
327
  - `templates/` 是研究工件模板。
324
- - `scripts/` 是运行登记、评估汇总和结果校验脚本。
328
+ - `scripts/` 是运行登记、评估汇总和结果校验脚本,其中也包括论文交付校验器。
325
329
  - `results/` 和 `figures/` 是默认的自然结果目录。
326
330
  - `tests/` 是脚本与安装器测试。
327
331
  - `examples/` 是最小端到端示例。
package/lib/i18n.cjs CHANGED
@@ -60,7 +60,7 @@ const ZH_CONTENT = {
60
60
  [path.join(".codex", "prompts", "lab-write.md")]: codexPrompt(
61
61
  "把验证过的研究工件转成论文 section,并按小步方式修订",
62
62
  "section or writing target",
63
- "使用已安装的 `lab` 技能:`.codex/skills/lab/SKILL.md`。\n\n立刻针对用户当前给出的参数执行 `/lab:write`,不要只推荐别的 `/lab` 阶段。只有在缺少阻塞性前提时,才明确指出缺什么,并且一次最多追问一个问题。\n\n本命令运行 `/lab:write` 阶段。它必须先有来自 `/lab:framing` 的已批准 framing artifact,再读取 `.codex/skills/lab/references/paper-writing/` 下与当前 section 对应的参考文件;如果当前是 `abstract`、`introduction` `method`,还必须继续读取 `.codex/skills/lab/references/paper-writing/examples/index.md`、对应的 examples index,以及 1-2 个具体 example 文件。然后结合 `paper-review.md` 与 `does-my-writing-flow-source.md`,先写 mini-outline,再只修改一个 section。第一次进入会产出论文 `.tex` 的路径时,如果 `paper_template_root` 为空,必须先问一次:继续使用默认 LaTeX scaffold,还是先接入模板目录。"
63
+ "使用已安装的 `lab` 技能:`.codex/skills/lab/SKILL.md`。\n\n立刻针对用户当前给出的参数执行 `/lab:write`,不要只推荐别的 `/lab` 阶段。只有在缺少阻塞性前提时,才明确指出缺什么,并且一次最多追问一个问题。\n\n本命令运行 `/lab:write` 阶段。它必须先有来自 `/lab:framing` 的已批准 framing artifact,再读取 `.codex/skills/lab/references/paper-writing/` 下与当前 section 对应的参考文件;如果当前 section bundled example bank,还必须继续读取 `.codex/skills/lab/references/paper-writing/examples/index.md`、对应的 examples index,以及 1-2 个具体 example 文件。然后结合 `paper-review.md` 与 `does-my-writing-flow-source.md`,先写 mini-outline,先规划该 section 需要的表、图和 citation,再只修改一个 section。在起草 `method`、`experiments`、`related work` 或 `conclusion` 之前,必须先运行 `.lab/.managed/scripts/validate_paper_plan.py --paper-plan .lab/writing/plan.md`。最终定稿或导出轮次必须运行 `.lab/.managed/scripts/validate_manuscript_delivery.py --paper-dir <deliverables_root>/paper`。第一次进入会产出论文 `.tex` 的路径时,如果 `paper_template_root` 为空,必须先问一次:继续使用默认 LaTeX scaffold,还是先接入模板目录。"
64
64
  ),
65
65
  [path.join(".claude", "commands", "lab-idea.md")]: claudeCommand(
66
66
  "lab-idea",
@@ -925,9 +925,10 @@ const ZH_SKILL_FILES = {
925
925
 
926
926
  ## 目标
927
927
 
928
- - Venue or audience:
929
- - Paper status:
928
+ - 目标会议或读者:
929
+ - 论文状态:
930
930
  - 一句话主线:
931
+ - 已批准 framing artifact:
931
932
  - Terminology lock:
932
933
 
933
934
  ## Section 状态
@@ -946,6 +947,60 @@ const ZH_SKILL_FILES = {
946
947
  - Limitation sources:
947
948
  - 哪些 claim 还缺证据:
948
949
 
950
+ ## 表计划
951
+
952
+ - 主结果表:
953
+ - 资产文件:
954
+ - 作用章节:
955
+ - 作用:
956
+ - 证据:
957
+ - 状态:
958
+ - 消融表:
959
+ - 资产文件:
960
+ - 作用章节:
961
+ - 作用:
962
+ - 证据:
963
+ - 状态:
964
+
965
+ ## 图计划
966
+
967
+ - 方法总览图:
968
+ - 资产文件:
969
+ - 作用章节:
970
+ - 图意图:
971
+ - 证据:
972
+ - 状态:
973
+ - 结果总览图:
974
+ - 资产文件:
975
+ - 作用章节:
976
+ - 图意图:
977
+ - 证据:
978
+ - 状态:
979
+
980
+ ## 引用计划
981
+
982
+ - 背景锚点:
983
+ - 引用或来源锚点:
984
+ - 作用章节:
985
+ - 为什么重要:
986
+ - 状态:
987
+ - 最接近前作:
988
+ - 引用或来源锚点:
989
+ - 作用章节:
990
+ - 为什么重要:
991
+ - 状态:
992
+ - 指标或 benchmark 来源:
993
+ - 引用或来源锚点:
994
+ - 作用章节:
995
+ - 为什么重要:
996
+ - 状态:
997
+
998
+ ## 章节到资产映射
999
+
1000
+ - 方法:
1001
+ - 实验:
1002
+ - 相关工作:
1003
+
949
1004
  ## 写作顺序
950
1005
 
951
1006
  1. 第一优先 section:
@@ -1583,8 +1638,23 @@ ZH_CONTENT[path.join(".codex", "skills", "lab", "stages", "write.md")] = `# \`/l
1583
1638
  - 如果用户在最终提醒里仍确认继续使用默认 scaffold,就把 \`paper_template_final_reminder_acknowledged\` 持久化为 \`true\`。
1584
1639
  - 只加载当前 section guide,不要一次加载全部章节参考。
1585
1640
  - 如果当前 section 是 \`abstract\`、\`introduction\` 或 \`method\`,还必须继续读取本地 example bank:\`references/paper-writing/examples/index.md\`、对应的 examples index,以及 1-2 个具体 example 文件。
1641
+ - 如果当前 section 是 \`related work\`、\`experiments\` 或 \`conclusion\`,也要读取对应的本地 example bank:\`references/paper-writing/examples/index.md\`、对应的 examples index,以及 1-2 个具体 example 文件。
1586
1642
  - 例子只能复用结构、段落角色和句法逻辑,不能直接复用原句。
1587
1643
  - 先写 mini-outline 再写 prose。
1644
+ - 如果当前 section 带方法、实验、相关工作或结论 claim,先规划需要的表格、figure placeholders 和 citations,再写 prose。
1645
+ - 在起草 \`method\`、\`experiments\`、\`related work\` 或 \`conclusion\` 之前,必须先运行 \`.lab/.managed/scripts/validate_paper_plan.py --paper-plan .lab/writing/plan.md\`。
1646
+ - 如果 \`paper-plan\` 校验失败,就先补 \`.lab/writing/plan.md\`,不能直接跳去写 prose。
1647
+ - 最终定稿或导出轮次里,必须维护非空的 \`references.bib\`,并把关键实验结果物化成真正的 LaTeX 表格:
1648
+ - \`<deliverables_root>/paper/tables/main-results.tex\`
1649
+ - \`<deliverables_root>/paper/tables/ablations.tex\`
1650
+ - 方法或实验章节还必须物化带 caption、label 和图意图的 figure placeholders:
1651
+ - \`<deliverables_root>/paper/figures/method-overview.tex\`
1652
+ - \`<deliverables_root>/paper/figures/results-overview.tex\`
1653
+ - 只要论文资产发生变化,就同步更新 \`.lab/writing/plan.md\` 里的表计划、图计划、引用计划和章节到资产映射。
1654
+ - 不要把纯 prose section 当成论文交付完成。
1655
+ - 论文源码里不要出现绝对本地路径、workflow provenance、shell 日志或 \`+/-\` 这类工程记法;应改成 paper-facing LaTeX 表达。
1656
+ - 在最终定稿或导出轮次结束前,必须运行 \`.lab/.managed/scripts/validate_manuscript_delivery.py --paper-dir <deliverables_root>/paper\`;如果失败,就继续补表、图、引用和正文。
1657
+ - 如果本地有 LaTeX 工具链,就再跑一次 compile smoke test;如果没有,也要在 write iteration artifact 里记录该限制。
1588
1658
  - 如果缺少 framing artifact,不要继续写作,直接回到 \`/lab:framing\`。
1589
1659
  - 如果某个 claim 没有证据支撑,就削弱或删除。
1590
1660
 
@@ -1594,7 +1664,12 @@ ZH_CONTENT[path.join(".codex", "skills", "lab", "stages", "write.md")] = `# \`/l
1594
1664
  - \`.lab/writing/plan.md\`
1595
1665
  - \`.lab/writing/iterations/<n>.md\`
1596
1666
  - \`<deliverables_root>/paper/main.tex\`
1667
+ - \`<deliverables_root>/paper/references.bib\`
1597
1668
  - \`<deliverables_root>/paper/sections/<section>.tex\`
1669
+ - \`<deliverables_root>/paper/tables/main-results.tex\`
1670
+ - \`<deliverables_root>/paper/tables/ablations.tex\`
1671
+ - \`<deliverables_root>/paper/figures/method-overview.tex\`
1672
+ - \`<deliverables_root>/paper/figures/results-overview.tex\`
1598
1673
  `;
1599
1674
 
1600
1675
  ZH_CONTENT[path.join(".claude", "skills", "lab", "stages", "write.md")] =
@@ -7,4 +7,4 @@ argument-hint: section or writing target
7
7
  Use the installed `lab` skill at `.claude/skills/lab/SKILL.md`.
8
8
 
9
9
  Execute the requested `/lab-write` command against the user's argument now. Do not only recommend another lab stage. If a blocking prerequisite is missing, say exactly what is missing and ask at most one clarifying question.
10
- This command runs the `write` stage of the lab workflow. It requires an approved framing artifact from the `framing` stage, must read the matching section reference from `.claude/skills/lab/references/paper-writing/`, and for `abstract`, `introduction`, or `method` it must also read `.claude/skills/lab/references/paper-writing/examples/index.md` plus the matching examples index and 1-2 concrete example files. Then it should run `paper-review.md` and `does-my-writing-flow-source.md`, build a mini-outline, and revise only one section.
10
+ This command runs the `write` stage of the lab workflow. It requires an approved framing artifact from the `framing` stage, must read the matching section reference from `.claude/skills/lab/references/paper-writing/`, and for any section with a bundled example bank it must also read `.claude/skills/lab/references/paper-writing/examples/index.md` plus the matching examples index and 1-2 concrete example files. Then it should run `paper-review.md` and `does-my-writing-flow-source.md`, build a mini-outline, plan the section's paper-facing tables/figures/citations, and revise only one section. Before drafting `method`, `experiments`, `related work`, or `conclusion`, it must run `.lab/.managed/scripts/validate_paper_plan.py --paper-plan .lab/writing/plan.md`. Final-draft or export rounds must run `.lab/.managed/scripts/validate_manuscript_delivery.py --paper-dir <deliverables_root>/paper` before stopping.
@@ -58,7 +58,9 @@ Use the same repository artifacts and stage boundaries every time.
58
58
  - `iterate` requires a normalized summary from `scripts/eval_report.py`.
59
59
  - `run`, `iterate`, `auto`, and `report` should all follow `.lab/context/eval-protocol.md`, including its recorded sources for metrics and comparison implementations.
60
60
  - `write` requires an approved framing artifact from the `framing` stage.
61
- - `write` requires stable report artifacts, a mini-outline, the active section guide, `paper-review.md`, and `does-my-writing-flow-source.md`, and should only change one section per round.
61
+ - `write` requires stable report artifacts, a mini-outline, the active section guide, the matching bundled examples when available, `paper-review.md`, and `does-my-writing-flow-source.md`, and should only change one section per round.
62
+ - Before drafting `method`, `experiments`, `related work`, or `conclusion`, `write` should validate `.lab/writing/plan.md` with `.lab/.managed/scripts/validate_paper_plan.py --paper-plan .lab/writing/plan.md`.
63
+ - Final-draft or export rounds in `write` should materialize paper-facing tables, figure placeholders, a non-empty `references.bib`, and pass `.lab/.managed/scripts/validate_manuscript_delivery.py --paper-dir <deliverables_root>/paper`.
62
64
 
63
65
  ## How to Ask for `/lab auto`
64
66
 
@@ -6,4 +6,4 @@ argument-hint: section or writing target
6
6
  Use the installed `lab` skill at `.codex/skills/lab/SKILL.md`.
7
7
 
8
8
  Execute the requested `/lab:write` stage against the user's argument now. Do not only recommend another lab stage. If a blocking prerequisite is missing, say exactly what is missing and ask at most one clarifying question.
9
- This command runs the `/lab:write` stage. It requires an approved framing artifact from `/lab:framing`, must read the matching section reference from `.codex/skills/lab/references/paper-writing/`, and for `abstract`, `introduction`, or `method` it must also read `.codex/skills/lab/references/paper-writing/examples/index.md` plus the matching examples index and 1-2 concrete example files. Then it should run `paper-review.md` and `does-my-writing-flow-source.md`, build a mini-outline, and revise only one section.
9
+ This command runs the `/lab:write` stage. It requires an approved framing artifact from `/lab:framing`, must read the matching section reference from `.codex/skills/lab/references/paper-writing/`, and for any section with a bundled example bank it must also read `.codex/skills/lab/references/paper-writing/examples/index.md` plus the matching examples index and 1-2 concrete example files. Then it should run `paper-review.md` and `does-my-writing-flow-source.md`, build a mini-outline, plan the section's paper-facing tables/figures/citations, and revise only one section. Before drafting `method`, `experiments`, `related work`, or `conclusion`, it must run `.lab/.managed/scripts/validate_paper_plan.py --paper-plan .lab/writing/plan.md`. Final-draft or export rounds must run `.lab/.managed/scripts/validate_manuscript_delivery.py --paper-dir <deliverables_root>/paper` before stopping.
@@ -52,7 +52,9 @@ argument-hint: workflow question or stage choice
52
52
  - `/lab:iterate` requires a normalized summary from `scripts/eval_report.py`.
53
53
  - `/lab:run`, `/lab:iterate`, `/lab:auto`, and `/lab:report` should all follow `.lab/context/eval-protocol.md`, including its recorded sources for metrics and comparison implementations.
54
54
  - `/lab:write` requires an approved framing artifact from `/lab:framing`.
55
- - `/lab:write` requires stable report artifacts, a mini-outline, the active section guide, `paper-review.md`, and `does-my-writing-flow-source.md`, and should only change one section per round.
55
+ - `/lab:write` requires stable report artifacts, a mini-outline, the active section guide, the matching bundled examples when available, `paper-review.md`, and `does-my-writing-flow-source.md`, and should only change one section per round.
56
+ - Before drafting `method`, `experiments`, `related work`, or `conclusion`, `/lab:write` should validate `.lab/writing/plan.md` with `.lab/.managed/scripts/validate_paper_plan.py --paper-plan .lab/writing/plan.md`.
57
+ - Final-draft or export rounds in `/lab:write` should materialize paper-facing tables, figure placeholders, a non-empty `references.bib`, and pass `.lab/.managed/scripts/validate_manuscript_delivery.py --paper-dir <deliverables_root>/paper`.
56
58
 
57
59
  ## How to Ask for `/lab:auto`
58
60
 
@@ -0,0 +1,175 @@
1
+ #!/usr/bin/env python3
2
+ import argparse
3
+ import re
4
+ import sys
5
+ from pathlib import Path
6
+
7
+
8
+ ABSOLUTE_PATH_MARKERS = ("/Users/", "/home/", "/tmp/", "/private/tmp/")
9
+ REQUIRED_TABLE_FILES = ("main-results.tex", "ablations.tex")
10
+ REQUIRED_FIGURE_FILES = ("method-overview.tex", "results-overview.tex")
11
+
12
+
13
+ def parse_args():
14
+ parser = argparse.ArgumentParser(
15
+ description="Validate that a paper delivery contains basic manuscript-ready assets."
16
+ )
17
+ parser.add_argument("--paper-dir", required=True, help="Path to the paper deliverable root")
18
+ return parser.parse_args()
19
+
20
+
21
+ def read_text(path: Path) -> str:
22
+ return path.read_text(encoding="utf-8")
23
+
24
+
25
+ def check_exists(path: Path, issues: list[str], label: str):
26
+ if not path.exists():
27
+ issues.append(f"missing required file: {label} ({path})")
28
+
29
+
30
+ def check_bibliography(paper_dir: Path, issues: list[str]):
31
+ bib_path = paper_dir / "references.bib"
32
+ check_exists(bib_path, issues, "references.bib")
33
+ if not bib_path.exists():
34
+ return
35
+ text = read_text(bib_path)
36
+ if "TODO" in text or "todo" in text or "Add bibliography entries" in text or "@" not in text:
37
+ issues.append("missing a non-empty references.bib")
38
+
39
+
40
+ def check_global_tex(paper_dir: Path, issues: list[str]):
41
+ tex_files = sorted(paper_dir.rglob("*.tex"))
42
+ combined = "\n".join(read_text(path) for path in tex_files)
43
+
44
+ if r"\cite{" not in combined:
45
+ issues.append("missing citation commands in manuscript tex files")
46
+ if "+/-" in combined:
47
+ issues.append("replace '+/-' with LaTeX \\pm formatting")
48
+ if any(marker in combined for marker in ABSOLUTE_PATH_MARKERS):
49
+ issues.append("manuscript tex files must not contain absolute local paths")
50
+
51
+
52
+ def check_table_file(path: Path, issues: list[str], label: str):
53
+ if not path.exists():
54
+ if label == "tables/main-results.tex":
55
+ issues.append("missing a main results table")
56
+ elif label == "tables/ablations.tex":
57
+ issues.append("missing an ablation table")
58
+ else:
59
+ issues.append(f"missing required file: {label} ({path})")
60
+ return
61
+ text = read_text(path)
62
+ if r"\begin{table}" not in text:
63
+ issues.append(f"{label} must contain a table environment")
64
+ if r"\caption{" not in text or r"\label{" not in text:
65
+ issues.append(f"{label} must contain both caption and label")
66
+ if not all(token in text for token in (r"\toprule", r"\midrule", r"\bottomrule")):
67
+ issues.append(f"{label} must use booktabs structure")
68
+
69
+
70
+ def check_figure_file(path: Path, issues: list[str], label: str):
71
+ if not path.exists():
72
+ if label == "figures/method-overview.tex":
73
+ issues.append("missing a method figure placeholder")
74
+ elif label == "figures/results-overview.tex":
75
+ issues.append("missing an experiments figure placeholder")
76
+ else:
77
+ issues.append(f"missing required file: {label} ({path})")
78
+ return
79
+ text = read_text(path)
80
+ if r"\begin{figure}" not in text:
81
+ issues.append(f"{label} must contain a figure environment")
82
+ if r"\caption{" not in text or r"\label{" not in text:
83
+ issues.append(f"{label} must contain both caption and label")
84
+ if "Figure intent:" not in text and "图意图:" not in text:
85
+ issues.append(f"{label} must explain figure intent")
86
+
87
+
88
+ def check_experiments_section(paper_dir: Path, issues: list[str]):
89
+ experiments = paper_dir / "sections" / "experiments.tex"
90
+ check_exists(experiments, issues, "sections/experiments.tex")
91
+ if not experiments.exists():
92
+ return
93
+ text = read_text(experiments)
94
+ has_table = any(
95
+ token in text
96
+ for token in (
97
+ r"\input{tables/main-results}",
98
+ r"\input{tables/ablations}",
99
+ r"\begin{table}",
100
+ )
101
+ )
102
+ has_figure = any(
103
+ token in text
104
+ for token in (
105
+ r"\input{figures/results-overview}",
106
+ r"\begin{figure}",
107
+ )
108
+ )
109
+ if not has_table:
110
+ issues.append("experiments section is missing a main results table")
111
+ if not has_figure:
112
+ issues.append("experiments section is missing an experiments figure placeholder")
113
+
114
+
115
+ def check_method_section(paper_dir: Path, issues: list[str]):
116
+ method = paper_dir / "sections" / "method.tex"
117
+ check_exists(method, issues, "sections/method.tex")
118
+ if not method.exists():
119
+ return
120
+ text = read_text(method)
121
+ has_figure = any(
122
+ token in text
123
+ for token in (
124
+ r"\input{figures/method-overview}",
125
+ r"\begin{figure}",
126
+ )
127
+ )
128
+ if not has_figure:
129
+ issues.append("method section is missing a method figure placeholder")
130
+
131
+
132
+ def check_main_tex(paper_dir: Path, issues: list[str]):
133
+ main_tex = paper_dir / "main.tex"
134
+ check_exists(main_tex, issues, "main.tex")
135
+ if not main_tex.exists():
136
+ return
137
+ text = read_text(main_tex)
138
+ if r"\bibliography{references}" not in text:
139
+ issues.append("main.tex must include the references bibliography")
140
+
141
+
142
+ def main():
143
+ args = parse_args()
144
+ paper_dir = Path(args.paper_dir)
145
+ issues: list[str] = []
146
+
147
+ if not paper_dir.exists():
148
+ print(f"paper directory does not exist: {paper_dir}", file=sys.stderr)
149
+ return 1
150
+
151
+ check_main_tex(paper_dir, issues)
152
+ check_bibliography(paper_dir, issues)
153
+ check_global_tex(paper_dir, issues)
154
+ check_method_section(paper_dir, issues)
155
+ check_experiments_section(paper_dir, issues)
156
+
157
+ tables_dir = paper_dir / "tables"
158
+ check_table_file(tables_dir / REQUIRED_TABLE_FILES[0], issues, "tables/main-results.tex")
159
+ check_table_file(tables_dir / REQUIRED_TABLE_FILES[1], issues, "tables/ablations.tex")
160
+
161
+ figures_dir = paper_dir / "figures"
162
+ check_figure_file(figures_dir / REQUIRED_FIGURE_FILES[0], issues, "figures/method-overview.tex")
163
+ check_figure_file(figures_dir / REQUIRED_FIGURE_FILES[1], issues, "figures/results-overview.tex")
164
+
165
+ if issues:
166
+ for issue in issues:
167
+ print(issue, file=sys.stderr)
168
+ return 1
169
+
170
+ print("manuscript delivery artifacts are valid")
171
+ return 0
172
+
173
+
174
+ if __name__ == "__main__":
175
+ raise SystemExit(main())
@@ -0,0 +1,228 @@
1
+ #!/usr/bin/env python3
2
+ import argparse
3
+ import re
4
+ import sys
5
+ from pathlib import Path
6
+
7
+
8
+ REQUIRED_SECTIONS = {
9
+ "Target": [r"^##\s+Target\s*$", r"^##\s+目标\s*$"],
10
+ "Section Status": [r"^##\s+Section Status\s*$", r"^##\s+Section 状态\s*$"],
11
+ "Evidence Map": [r"^##\s+Evidence Map\s*$", r"^##\s+证据地图\s*$"],
12
+ "Table Plan": [r"^##\s+Table Plan\s*$", r"^##\s+表计划\s*$"],
13
+ "Figure Plan": [r"^##\s+Figure Plan\s*$", r"^##\s+图计划\s*$"],
14
+ "Citation Plan": [r"^##\s+Citation Plan\s*$", r"^##\s+引用计划\s*$"],
15
+ "Section-to-Asset Map": [r"^##\s+Section-to-Asset Map\s*$", r"^##\s+章节到资产映射\s*$"],
16
+ "Writing Order": [r"^##\s+Writing Order\s*$", r"^##\s+写作顺序\s*$"],
17
+ "Five-Dimension Self-Review Status": [
18
+ r"^##\s+Five-Dimension Self-Review Status\s*$",
19
+ r"^##\s+五维自评状态\s*$",
20
+ ],
21
+ }
22
+
23
+ TARGET_FIELDS = (
24
+ "Venue or audience",
25
+ "Paper status",
26
+ "Core story in one sentence",
27
+ "Approved framing artifact",
28
+ "Terminology lock",
29
+ "目标会议或读者",
30
+ "论文状态",
31
+ "一句话主线",
32
+ "已批准 framing artifact",
33
+ "术语锁",
34
+ )
35
+
36
+ SECTION_STATUS_FIELDS = (
37
+ "Abstract",
38
+ "Introduction",
39
+ "Related Work",
40
+ "Method",
41
+ "Experiments",
42
+ "Conclusion",
43
+ )
44
+
45
+ EVIDENCE_FIELDS = (
46
+ "Main result sources",
47
+ "Ablation sources",
48
+ "Limitation sources",
49
+ "Claims that still need more evidence",
50
+ "主结果来源",
51
+ "消融来源",
52
+ "限制来源",
53
+ "还缺更多证据的 claim",
54
+ )
55
+
56
+ TABLE_DETAIL_FIELDS = (
57
+ "Asset file",
58
+ "Section",
59
+ "Message",
60
+ "Evidence",
61
+ "Status",
62
+ "资产文件",
63
+ "作用章节",
64
+ "作用",
65
+ "证据",
66
+ "状态",
67
+ )
68
+ FIGURE_DETAIL_FIELDS = (
69
+ "Asset file",
70
+ "Section",
71
+ "Figure intent",
72
+ "Evidence",
73
+ "Status",
74
+ "资产文件",
75
+ "作用章节",
76
+ "图意图",
77
+ "证据",
78
+ "状态",
79
+ )
80
+ CITATION_DETAIL_FIELDS = (
81
+ "Citation or source anchor",
82
+ "Section",
83
+ "Why it matters",
84
+ "Status",
85
+ "引用或来源锚点",
86
+ "作用章节",
87
+ "为什么重要",
88
+ "状态",
89
+ )
90
+ SECTION_MAP_FIELDS = ("Method", "Experiments", "Related Work", "方法", "实验", "相关工作")
91
+ WRITING_ORDER_FIELDS = (
92
+ "First section target",
93
+ "Second section target",
94
+ "Deferred sections",
95
+ "第一优先 section",
96
+ "第二优先 section",
97
+ "延后 section",
98
+ )
99
+ SELF_REVIEW_FIELDS = (
100
+ "Contribution",
101
+ "Writing clarity",
102
+ "Experimental strength",
103
+ "Evaluation completeness",
104
+ "Method design soundness",
105
+ )
106
+
107
+
108
+ def parse_args():
109
+ parser = argparse.ArgumentParser(
110
+ description="Validate that the managed paper plan contains concrete asset planning before prose drafting."
111
+ )
112
+ parser.add_argument("--paper-plan", required=True, help="Path to .lab/writing/plan.md")
113
+ return parser.parse_args()
114
+
115
+
116
+ def read_text(path: Path) -> str:
117
+ return path.read_text(encoding="utf-8")
118
+
119
+
120
+ def extract_section_body(text: str, patterns: list[str]) -> str:
121
+ for pattern in patterns:
122
+ match = re.search(pattern, text, flags=re.MULTILINE)
123
+ if not match:
124
+ continue
125
+ start = match.end()
126
+ next_heading = re.search(r"^##\s+", text[start:], flags=re.MULTILINE)
127
+ end = start + next_heading.start() if next_heading else len(text)
128
+ return text[start:end].strip()
129
+ return ""
130
+
131
+
132
+ def missing_sections(text: str) -> list[str]:
133
+ missing = []
134
+ for section_name, patterns in REQUIRED_SECTIONS.items():
135
+ if not any(re.search(pattern, text, flags=re.MULTILINE) for pattern in patterns):
136
+ missing.append(section_name)
137
+ return missing
138
+
139
+
140
+ def has_filled_field(body: str, field_labels: tuple[str, ...]) -> bool:
141
+ for label in field_labels:
142
+ pattern = re.compile(rf"^\s*(?:-|\d+\.)\s*{re.escape(label)}:[ \t]*([^\n]+?)\s*$", flags=re.MULTILINE)
143
+ for match in pattern.finditer(body):
144
+ value = match.group(1).strip()
145
+ if value and value not in {"TBD", "TODO", "待补", "待定"}:
146
+ return True
147
+ return False
148
+
149
+
150
+ def count_filled_fields(body: str, field_labels: tuple[str, ...]) -> int:
151
+ count = 0
152
+ for label in field_labels:
153
+ pattern = re.compile(rf"^\s*(?:-|\d+\.)\s*{re.escape(label)}:[ \t]*([^\n]+?)\s*$", flags=re.MULTILINE)
154
+ for match in pattern.finditer(body):
155
+ value = match.group(1).strip()
156
+ if value and value not in {"TBD", "TODO", "待补", "待定"}:
157
+ count += 1
158
+ return count
159
+
160
+
161
+ def validate_filled_fields(text: str) -> list[str]:
162
+ issues: list[str] = []
163
+
164
+ target_body = extract_section_body(text, REQUIRED_SECTIONS["Target"])
165
+ if not has_filled_field(target_body, TARGET_FIELDS):
166
+ issues.append("paper plan is missing filled target fields")
167
+
168
+ section_status_body = extract_section_body(text, REQUIRED_SECTIONS["Section Status"])
169
+ if count_filled_fields(section_status_body, SECTION_STATUS_FIELDS) < 6:
170
+ issues.append("paper plan is missing filled section-status entries")
171
+
172
+ evidence_body = extract_section_body(text, REQUIRED_SECTIONS["Evidence Map"])
173
+ if not has_filled_field(evidence_body, EVIDENCE_FIELDS):
174
+ issues.append("paper plan is missing filled evidence-map entries")
175
+
176
+ table_body = extract_section_body(text, REQUIRED_SECTIONS["Table Plan"])
177
+ if count_filled_fields(table_body, TABLE_DETAIL_FIELDS) < 10:
178
+ issues.append("paper plan must fill both required table-asset blocks")
179
+
180
+ figure_body = extract_section_body(text, REQUIRED_SECTIONS["Figure Plan"])
181
+ if count_filled_fields(figure_body, FIGURE_DETAIL_FIELDS) < 10:
182
+ issues.append("paper plan must fill both required figure-asset blocks")
183
+
184
+ citation_body = extract_section_body(text, REQUIRED_SECTIONS["Citation Plan"])
185
+ if count_filled_fields(citation_body, CITATION_DETAIL_FIELDS) < 12:
186
+ issues.append("paper plan must fill all required citation-plan blocks")
187
+
188
+ section_map_body = extract_section_body(text, REQUIRED_SECTIONS["Section-to-Asset Map"])
189
+ if not has_filled_field(section_map_body, SECTION_MAP_FIELDS):
190
+ issues.append("paper plan is missing filled section-to-asset mappings")
191
+
192
+ writing_order_body = extract_section_body(text, REQUIRED_SECTIONS["Writing Order"])
193
+ if count_filled_fields(writing_order_body, WRITING_ORDER_FIELDS) < 3:
194
+ issues.append("paper plan is missing filled writing-order entries")
195
+
196
+ self_review_body = extract_section_body(text, REQUIRED_SECTIONS["Five-Dimension Self-Review Status"])
197
+ if count_filled_fields(self_review_body, SELF_REVIEW_FIELDS) < 5:
198
+ issues.append("paper plan is missing filled self-review status entries")
199
+
200
+ return issues
201
+
202
+
203
+ def main():
204
+ args = parse_args()
205
+ plan_path = Path(args.paper_plan)
206
+ if not plan_path.exists():
207
+ print(f"paper plan does not exist: {plan_path}", file=sys.stderr)
208
+ return 1
209
+
210
+ text = read_text(plan_path)
211
+ issues = []
212
+
213
+ missing = missing_sections(text)
214
+ if missing:
215
+ issues.append(f"paper plan is missing required sections: {', '.join(missing)}")
216
+ issues.extend(validate_filled_fields(text))
217
+
218
+ if issues:
219
+ for issue in issues:
220
+ print(issue, file=sys.stderr)
221
+ return 1
222
+
223
+ print("paper plan is valid")
224
+ return 0
225
+
226
+
227
+ if __name__ == "__main__":
228
+ raise SystemExit(main())
@@ -0,0 +1,6 @@
1
+ \begin{figure}[t]
2
+ \centering
3
+ \fbox{\rule{0pt}{1.2in}\rule{0.9\linewidth}{0pt}}
4
+ \caption{Figure title. Figure intent: explain what this figure should show and why the reader needs it.}
5
+ \label{fig:placeholder}
6
+ \end{figure}
@@ -24,6 +24,60 @@
24
24
  - Limitation sources:
25
25
  - Claims that still need more evidence:
26
26
 
27
+ ## Table Plan
28
+
29
+ - Main results table:
30
+ - Asset file:
31
+ - Section:
32
+ - Message:
33
+ - Evidence:
34
+ - Status:
35
+ - Ablation table:
36
+ - Asset file:
37
+ - Section:
38
+ - Message:
39
+ - Evidence:
40
+ - Status:
41
+
42
+ ## Figure Plan
43
+
44
+ - Method overview figure:
45
+ - Asset file:
46
+ - Section:
47
+ - Figure intent:
48
+ - Evidence:
49
+ - Status:
50
+ - Results overview figure:
51
+ - Asset file:
52
+ - Section:
53
+ - Figure intent:
54
+ - Evidence:
55
+ - Status:
56
+
57
+ ## Citation Plan
58
+
59
+ - Background anchor:
60
+ - Citation or source anchor:
61
+ - Section:
62
+ - Why it matters:
63
+ - Status:
64
+ - Closest prior work:
65
+ - Citation or source anchor:
66
+ - Section:
67
+ - Why it matters:
68
+ - Status:
69
+ - Metric or benchmark source:
70
+ - Citation or source anchor:
71
+ - Section:
72
+ - Why it matters:
73
+ - Status:
74
+
75
+ ## Section-to-Asset Map
76
+
77
+ - Method:
78
+ - Experiments:
79
+ - Related Work:
80
+
27
81
  ## Writing Order
28
82
 
29
83
  1. First section target:
@@ -0,0 +1,9 @@
1
+ % Add paper-facing bibliography entries here.
2
+ % Keep keys stable with the manuscript's \cite{...} usage.
3
+
4
+ @article{placeholder2026,
5
+ title = {Replace with a real cited work before finalizing},
6
+ author = {Placeholder, Example},
7
+ journal = {Placeholder Venue},
8
+ year = {2026}
9
+ }
@@ -0,0 +1,13 @@
1
+ \begin{table}[t]
2
+ \caption{One-sentence message of the table and the evaluation protocol.}
3
+ \label{tab:placeholder}
4
+ \centering
5
+ \begin{tabular}{lcc}
6
+ \toprule
7
+ Method & Metric 1 $\uparrow$ & Metric 2 $\uparrow$ \\
8
+ \midrule
9
+ Ours & 0.0000 & 0.0000 \\
10
+ Baseline & 0.0000 & 0.0000 \\
11
+ \bottomrule
12
+ \end{tabular}
13
+ \end{table}
@@ -172,14 +172,19 @@ Use this skill when the user invokes `/lab:*` or asks for the structured researc
172
172
  - Write one paper section or one explicit subproblem per round.
173
173
  - Bind each claim to evidence from `report`, iteration reports, or normalized summaries.
174
174
  - Write planning artifacts with `.lab/.managed/templates/paper-plan.md`, `.lab/.managed/templates/paper-section.md`, and `.lab/.managed/templates/write-iteration.md`.
175
- - Write final manuscript artifacts with `.lab/.managed/templates/paper.tex` and `.lab/.managed/templates/paper-section.tex`.
175
+ - Write final manuscript artifacts with `.lab/.managed/templates/paper.tex`, `.lab/.managed/templates/paper-section.tex`, `.lab/.managed/templates/paper-table.tex`, `.lab/.managed/templates/paper-figure.tex`, and `.lab/.managed/templates/paper-references.bib`.
176
176
  - Use the vendored paper-writing references under `skills/lab/references/paper-writing/`.
177
- - For `abstract`, `introduction`, and `method`, also use the vendored example-bank files under `skills/lab/references/paper-writing/examples/`.
177
+ - For any section with a bundled example bank, also use the vendored example-bank files under `skills/lab/references/paper-writing/examples/`.
178
178
  - Load only the current section guide, the matching examples index when one exists, 1-2 matching concrete example files, plus `paper-review.md` and `does-my-writing-flow-source.md`.
179
179
  - Build a compact mini-outline before prose.
180
+ - Build the paper asset plan before prose when the section carries method or experiments claims.
180
181
  - For each subsection, explicitly cover motivation, design, and technical advantage when applicable.
181
182
  - Keep terminology stable across rounds and sections.
182
183
  - If a claim is not supported by evidence, weaken or remove it.
184
+ - Treat tables, figures, citations, and bibliography as core manuscript content rather than optional polish.
185
+ - Keep paper-facing LaTeX free of absolute local paths, rerun ids, shell transcripts, and internal workflow provenance.
186
+ - Materialize real LaTeX tables and figure placeholders instead of leaving all evidence inside prose paragraphs.
187
+ - Run `.lab/.managed/scripts/validate_manuscript_delivery.py --paper-dir <deliverables_root>/paper` before accepting a final-draft or export round.
183
188
  - Before finalizing a round, append and answer the five-dimension self-review checklist and revise unresolved items.
184
189
  - Apply paper-writing discipline without changing experimental truth.
185
190
  - If the evidence is insufficient, stop and route back to `review` or `iterate`.
@@ -194,7 +199,7 @@ Use this skill when the user invokes `/lab:*` or asks for the structured researc
194
199
  - No unconstrained auto mode. Every `/lab:auto` campaign must declare allowed stages, stop conditions, and a promotion policy in `.lab/context/auto-mode.md`.
195
200
  - No auto start without an explicit autonomy level and `Approval status: approved`.
196
201
  - No final report without validated normalized results.
197
- - No paper-writing round without stable report artifacts, an approved framing artifact, evidence links, and LaTeX manuscript output.
202
+ - No paper-writing round without stable report artifacts, an approved framing artifact, evidence links, LaTeX manuscript output, and a passing manuscript-delivery validation for final-draft or export rounds.
198
203
 
199
204
  ## References
200
205
 
@@ -212,7 +217,7 @@ Use this skill when the user invokes `/lab:*` or asks for the structured researc
212
217
  - Write stage guide: `.codex/skills/lab/stages/write.md` or `.claude/skills/lab/stages/write.md`
213
218
  - Paper-writing integration: `.codex/skills/lab/references/paper-writing-integration.md` or `.claude/skills/lab/references/paper-writing-integration.md`
214
219
  - Vendored paper-writing references: `.codex/skills/lab/references/paper-writing/{abstract,introduction,related-work,method,experiments,conclusion,paper-review,does-my-writing-flow-source}.md` or `.claude/skills/lab/references/paper-writing/{abstract,introduction,related-work,method,experiments,conclusion,paper-review,does-my-writing-flow-source}.md`
215
- - Vendored paper-writing example bank: `.codex/skills/lab/references/paper-writing/examples/{index,abstract-examples,introduction-examples,method-examples}.md` or `.claude/skills/lab/references/paper-writing/examples/{index,abstract-examples,introduction-examples,method-examples}.md`, plus the matching section subdirectories
220
+ - Vendored paper-writing example bank: `.codex/skills/lab/references/paper-writing/examples/{index,abstract-examples,introduction-examples,method-examples,related-work-examples,experiments-examples,conclusion-examples}.md` or `.claude/skills/lab/references/paper-writing/examples/{index,abstract-examples,introduction-examples,method-examples,related-work-examples,experiments-examples,conclusion-examples}.md`, plus the matching section subdirectories
216
221
  - Command adapters: the installed `/lab:*` command assets
217
222
  - Shared workflow config: `.lab/config/workflow.json`
218
223
  - Shared project context: `.lab/context/{mission,state,decisions,evidence-index,open-questions,data-decisions,eval-protocol,auto-mode,auto-status}.md`
@@ -0,0 +1,27 @@
1
+ # Conservative Claim-Boundary LaTeX Example
2
+
3
+ Use this example to close with the strongest supported claim while keeping the
4
+ boundary explicit.
5
+
6
+ ```tex
7
+ \section{Conclusion}
8
+
9
+ This paper shows that adding a structured ranking backbone together with a
10
+ post-hoc calibration stage improves uplift ranking under the frozen benchmark
11
+ protocol. Across the three benchmark families used in this work, the full model
12
+ consistently matches or exceeds the strongest baselines and remains stronger
13
+ than the key ablated variants. This makes the main claim narrower than a
14
+ universal superiority claim but stronger than a single-dataset win.
15
+
16
+ We do not claim that the current method solves uplift modeling in every domain
17
+ or that every design choice helps equally on every benchmark. In particular, the
18
+ calibration stage appears beneficial on some datasets and neutral on others,
19
+ which means its value should be interpreted as setting-dependent rather than as
20
+ a guaranteed gain. That boundary is consistent with recent benchmarking
21
+ practice, which argues for claim discipline and protocol-specific interpretation
22
+ rather than broad overgeneralization~\cite{carlini2019evaluating}.
23
+
24
+ The most useful next step is to extend the evaluation to a broader set of
25
+ benchmark slices and to test whether the same ranking-versus-calibration split
26
+ remains useful when the label distribution shifts more aggressively.
27
+ ```
@@ -0,0 +1,16 @@
1
+ # Conclusion Example Patterns
2
+
3
+ Use these examples to end with a bounded claim, not a marketing recap. The
4
+ referenced file is a complete LaTeX conclusion example with explicit claim
5
+ boundary language.
6
+
7
+ ## Recommended Pattern
8
+
9
+ 1. Restate the narrow supported claim.
10
+ 2. Restate the strongest evidence in one compact sentence.
11
+ 3. State the main limitation or boundary.
12
+ 4. End with the next concrete direction, not generic future work.
13
+
14
+ ## Example Files
15
+
16
+ - `examples/conclusion/conservative-claim-boundary.md`
@@ -0,0 +1,44 @@
1
+ # Figure Placeholder and Discussion Example
2
+
3
+ Use complete figure placeholders when the visual asset is not finalized yet but
4
+ the manuscript already needs a stable figure slot, caption, label, and prose
5
+ attachment.
6
+
7
+ ## Method Figure Placeholder
8
+
9
+ ```tex
10
+ \begin{figure}[t]
11
+ \centering
12
+ \fbox{\rule{0pt}{1.55in}\rule{0.92\linewidth}{0pt}}
13
+ \caption{Method overview. Figure intent: show the full pipeline, highlight the
14
+ boundary between the structured scoring module and the post-hoc calibration
15
+ stage, and make the train-time versus inference-time data flow easy to inspect.}
16
+ \label{fig:method-overview}
17
+ \end{figure}
18
+ ```
19
+
20
+ ## Results Figure Placeholder
21
+
22
+ ```tex
23
+ \begin{figure}[t]
24
+ \centering
25
+ \fbox{\rule{0pt}{1.55in}\rule{0.92\linewidth}{0pt}}
26
+ \caption{Benchmark-level results overview. Figure intent: summarize the trend
27
+ across datasets, show error bars or confidence intervals, and reveal whether the
28
+ main gain is stable or dominated by one benchmark.}
29
+ \label{fig:results-overview}
30
+ \end{figure}
31
+ ```
32
+
33
+ ## Discussion Example
34
+
35
+ ```tex
36
+ Figure~\ref{fig:method-overview} gives the reader the shortest path to the
37
+ method's logic before the section moves into module details. The figure should
38
+ make it obvious which component produces the structured signal and where the
39
+ post-hoc calibration step changes the final ranking.
40
+
41
+ Figure~\ref{fig:results-overview} should then complement the tables rather than
42
+ repeat them. Its job is to show whether the gain is stable across datasets and
43
+ seeds, not to claim a new effect that the tables do not already support.
44
+ ```
@@ -0,0 +1,83 @@
1
+ # Main Results and Ablation LaTeX Example
2
+
3
+ This file is a complete paper-facing LaTeX example for the experiments section.
4
+ Reuse the structure, caption logic, and prose-to-table linkage. Replace the
5
+ placeholder methods, metrics, and values with the current project's evidence.
6
+
7
+ Source inspiration:
8
+ - full table/figure organization examples from
9
+ `guanyingc/latex_paper_writing_tips`
10
+ - full paper-source organization from
11
+ `evaluating-adversarial-robustness/adv-eval-paper`
12
+
13
+ ## Main Results Table
14
+
15
+ ```tex
16
+ \begin{table}[t]
17
+ \caption{Main benchmark results under the frozen evaluation protocol. Higher is better on all metrics.}
18
+ \label{tab:main-results}
19
+ \centering
20
+ \resizebox{0.92\linewidth}{!}{
21
+ \begin{tabular}{lccc}
22
+ \toprule
23
+ Method & AUUC $\uparrow$ & Qini $\uparrow$ & Calibration Error $\downarrow$ \\
24
+ \midrule
25
+ Strongest baseline & 0.1421 & 0.0873 & 0.0612 \\
26
+ Closest prior work & 0.1488 & 0.0915 & 0.0544 \\
27
+ Ours & \textbf{0.1564} & \textbf{0.0987} & \textbf{0.0418} \\
28
+ \bottomrule
29
+ \end{tabular}
30
+ }
31
+ \end{table}
32
+ ```
33
+
34
+ Table message:
35
+ - `Does the proposed method beat the strongest baselines under the frozen protocol?`
36
+
37
+ ## Ablation Table
38
+
39
+ ```tex
40
+ \begin{table}[t]
41
+ \caption{Ablations that isolate which design choices create the gain.}
42
+ \label{tab:ablations}
43
+ \centering
44
+ \begin{tabular}{lc}
45
+ \toprule
46
+ Variant & AUUC $\uparrow$ \\
47
+ \midrule
48
+ Ours & \textbf{0.1564} \\
49
+ w/o structure module & 0.1497 \\
50
+ w/o calibration stage & 0.1510 \\
51
+ w/ shuffled auxiliary signal & 0.1458 \\
52
+ \bottomrule
53
+ \end{tabular}
54
+ \end{table}
55
+ ```
56
+
57
+ Table message:
58
+ - `Which design choices create the gain, and which ones are neutral?`
59
+
60
+ ## Experiments Section Stitching Example
61
+
62
+ ```tex
63
+ \section{Experiments}
64
+ \label{sec:experiments}
65
+
66
+ Table~\ref{tab:main-results} answers the main ranking question: whether the full
67
+ method remains stronger than the closest prior work and the strongest practical
68
+ baseline under the frozen protocol. Our method achieves the best AUUC and Qini
69
+ while also reducing calibration error, which means the gain is not coming from
70
+ trading ranking quality against stability.
71
+
72
+ Table~\ref{tab:ablations} then asks a narrower mechanism question. Removing the
73
+ structure module causes the largest drop, so the main gain is tied to structured
74
+ signal modeling rather than to a generic increase in capacity. Removing the
75
+ calibration stage leads to a smaller but still visible drop, which supports the
76
+ claim that calibration improves final ranking quality without being the sole
77
+ driver of the result. The shuffled-signal variant acts as a negative control and
78
+ shows that the gain does not survive when the auxiliary information is broken.
79
+
80
+ One caveat is that the calibration gain may remain neutral on some benchmarks,
81
+ so the paper should not overclaim that every component helps equally on every
82
+ dataset.
83
+ ```
@@ -0,0 +1,17 @@
1
+ # Experiments Example Patterns
2
+
3
+ Use these examples when turning validated results into paper-facing LaTeX assets.
4
+ The referenced files contain complete LaTeX environments and section-level prose
5
+ glue, not just checklists.
6
+
7
+ ## Required Asset Pattern
8
+
9
+ 1. Main results should live in a real `table` environment.
10
+ 2. Ablations should live in a separate `table` environment.
11
+ 3. Method and experiments should each have at least one figure placeholder with an explicit `Figure intent`.
12
+ 4. Captions should explain the table or figure message briefly; longer interpretation belongs in prose.
13
+
14
+ ## Example Files
15
+
16
+ - `examples/experiments/main-results-and-ablation-latex.md`
17
+ - `examples/experiments/figure-placeholder-and-discussion.md`
@@ -1,6 +1,7 @@
1
1
  # Example Bank Index
2
2
 
3
- Use this folder for concrete writing patterns and locally organized cite targets.
3
+ Use this folder for concrete writing patterns, complete LaTeX snippets, and
4
+ locally organized cite targets.
4
5
 
5
6
  ## Files
6
7
 
@@ -12,10 +13,18 @@ Use this folder for concrete writing patterns and locally organized cite targets
12
13
  6. Introduction pipeline files: `references/examples/introduction/pipeline-version-1-one-contribution-multi-advantages.md`, `references/examples/introduction/pipeline-version-2-two-contributions.md`, `references/examples/introduction/pipeline-version-3-new-module-on-existing-pipeline.md`, `references/examples/introduction/pipeline-version-4-observation-driven.md`, `references/examples/introduction/pipeline-not-recommended-abstract-only.md`
13
14
  7. Method examples index: `references/examples/method-examples.md`
14
15
  8. Method detail files: `references/examples/method/pre-writing-questions.md`, `references/examples/method/module-triad-neural-body.md`, `references/examples/method/neural-body-annotated-figure-text.md`, `references/examples/method/module-design-instant-ngp.md`, `references/examples/method/module-motivation-patterns.md`, `references/examples/method/section-skeleton.md`, `references/examples/method/overview-template.md`, `references/examples/method/example-of-the-three-elements.md`, `references/examples/method/method-writing-common-issues-note.md`
16
+ 9. Related work examples index: `references/examples/related-work-examples.md`
17
+ 10. Related work files: `references/examples/related-work/closest-prior-gap-template.md`, `references/examples/related-work/topic-comparison-template.md`
18
+ 11. Experiments examples index: `references/examples/experiments-examples.md`
19
+ 12. Experiments files: `references/examples/experiments/main-results-and-ablation-latex.md`, `references/examples/experiments/figure-placeholder-and-discussion.md`
20
+ 13. Conclusion examples index: `references/examples/conclusion-examples.md`
21
+ 14. Conclusion files: `references/examples/conclusion/conservative-claim-boundary.md`
15
22
 
16
23
  ## Usage
17
24
 
18
25
  1. Pick one template from a section guide.
19
26
  2. Open the matching examples file.
20
- 3. Reuse the sentence logic, not exact wording.
21
- 4. Keep citation links in your notes for traceability.
27
+ 3. Prefer the complete LaTeX examples when the section needs tables, figures,
28
+ citations, or section-level stitching.
29
+ 4. Reuse the structure and command patterns, not exact wording.
30
+ 5. Keep citation links in your notes for traceability.
@@ -0,0 +1,20 @@
1
+ # Closest Prior Then Gap LaTeX Example
2
+
3
+ Use this example when one family of papers is the closest technical anchor and
4
+ the paragraph needs to explain the gap precisely.
5
+
6
+ ```tex
7
+ \paragraph{Closest prior work.}
8
+ The closest prior line improves uplift ranking by sharpening the treatment-aware
9
+ scoring objective rather than by changing the final decision rule
10
+ itself~\cite{lee2021uplift,wang2022counterfactual}. These methods are strong
11
+ references because they already optimize for ranking quality and outperform
12
+ simple pointwise baselines on standard benchmarks. However, they still assume
13
+ that the learned score can be used directly as the final ranking signal across
14
+ datasets with different calibration behavior. That assumption is limiting in our
15
+ setting, where the raw score often contains useful relative information but is
16
+ not always aligned with the final protocol-level target. Our method keeps the
17
+ ranking-focused backbone but changes the final stage by inserting a post-hoc
18
+ calibration module, so the method can preserve the stronger internal signal
19
+ while adapting the exposed score to the benchmark-specific decision scale.
20
+ ```
@@ -0,0 +1,24 @@
1
+ # Topic Comparison LaTeX Example
2
+
3
+ Use this example when the related-work section needs a compact, citation-driven
4
+ comparison paragraph rather than a bullet list of papers.
5
+
6
+ ```tex
7
+ \paragraph{Structure-aware ranking methods.}
8
+ A second line of work improves ranking by injecting structured inductive bias
9
+ into the scoring function~\cite{smith2021structured,lee2022pairwise}. These
10
+ methods are attractive because they often stabilize training and can exploit
11
+ known relationships among samples or treatment groups. However, they typically
12
+ assume that the structured module alone is sufficient to produce well-calibrated
13
+ scores at evaluation time. In our setting, that assumption is too strong: the
14
+ raw ranking signal remains useful, but it is not always aligned with the final
15
+ decision scale required by the frozen protocol. We therefore keep the
16
+ structure-aware backbone but add a separate calibration stage, which lets us
17
+ reuse the stronger signal while correcting its final score mapping.
18
+ ```
19
+
20
+ What this paragraph does:
21
+ 1. groups one literature line by topic
22
+ 2. states why the line is attractive
23
+ 3. identifies the exact limitation that matters here
24
+ 4. positions the current method as a narrower, testable change
@@ -0,0 +1,17 @@
1
+ # Related Work Example Patterns
2
+
3
+ Use these examples to structure `related work` around technical gaps instead of
4
+ citation dumping. The referenced files are complete citation-driven LaTeX
5
+ paragraph examples.
6
+
7
+ ## Recommended Pattern
8
+
9
+ 1. Open with the topic line.
10
+ 2. Summarize 2-4 representative methods compactly.
11
+ 3. State the exact limitation that matters for the current problem.
12
+ 4. End with a transition sentence that positions the current method.
13
+
14
+ ## Example Files
15
+
16
+ - `examples/related-work/closest-prior-gap-template.md`
17
+ - `examples/related-work/topic-comparison-template.md`
@@ -2,13 +2,13 @@
2
2
 
3
3
  `/lab:write` vendors the paper-writing references directly into `skills/lab/references/paper-writing/`.
4
4
  The goal is to keep the upstream writing discipline while removing brittle runtime dependence on a separately installed skill.
5
- It also vendors the upstream example bank for the sections that currently have curated examples, so drafting can reuse concrete structure rather than only abstract guidance.
5
+ It also vendors the upstream example bank for the sections that currently have curated examples, and adds local manuscript-delivery examples for missing sections, so drafting can reuse concrete structure rather than only abstract guidance.
6
6
 
7
7
  ## Role Split
8
8
 
9
9
  - `lab` controls stage boundaries, evidence discipline, and durable artifacts.
10
10
  - the vendored paper-writing references control section structure, paragraph logic, and reviewer-facing polish.
11
- - the vendored example bank controls example-driven structure selection for `abstract`, `introduction`, and `method`.
11
+ - the vendored example bank controls example-driven structure selection for section prose and paper-facing LaTeX assets.
12
12
  - `/lab:write` links evidence-backed research outputs to paper-ready text.
13
13
 
14
14
  ## Required Shared Constraints
@@ -41,26 +41,35 @@ It also vendors the upstream example bank for the sections that currently have c
41
41
  - `paper-writing/examples/abstract-examples.md`
42
42
  - `paper-writing/examples/introduction-examples.md`
43
43
  - `paper-writing/examples/method-examples.md`
44
+ - `paper-writing/examples/related-work-examples.md`
45
+ - `paper-writing/examples/experiments-examples.md`
46
+ - `paper-writing/examples/conclusion-examples.md`
44
47
  - `paper-writing/examples/abstract/*`
45
48
  - `paper-writing/examples/introduction/*`
46
49
  - `paper-writing/examples/method/*`
50
+ - `paper-writing/examples/related-work/*`
51
+ - `paper-writing/examples/experiments/*`
52
+ - `paper-writing/examples/conclusion/*`
47
53
 
48
54
  ## Write-Time Rule
49
55
 
50
- For `abstract`, `introduction`, and `method`:
56
+ For `abstract`, `introduction`, `method`, `related work`, `experiments`, and `conclusion`:
51
57
 
52
58
  1. read the section guide first
53
- 2. read the matching examples index
59
+ 2. if the section has a bundled examples index, read it
54
60
  3. read 1-2 concrete example files that match the intended structure
55
- 4. reuse structure and sentence logic without copying wording
56
-
57
- For `related work`, `experiments`, and `conclusion`:
58
-
59
- 1. use the section guide directly
60
- 2. do not invent non-existent example-bank files
61
+ 4. reuse structure, sentence logic, and LaTeX asset patterns without copying wording
61
62
 
62
63
  ## Attribution
63
64
 
64
65
  These references are adapted from:
65
66
 
66
67
  - `https://github.com/Master-cai/Research-Paper-Writing-Skills/tree/main/research-paper-writing/references`
68
+
69
+ The local manuscript-delivery examples for missing sections are additionally informed by public LaTeX guidance and real paper-source repositories, including:
70
+
71
+ - `https://github.com/guanyingc/latex_paper_writing_tips`
72
+ - `https://github.com/evaluating-adversarial-robustness/adv-eval-paper`
73
+ - `https://github.com/lightningnetwork/paper`
74
+
75
+ These sources are used as structure references for complete LaTeX snippets, table/figure organization, and manuscript assembly patterns, so `/lab:write` can enforce tables, figure placeholders, and bibliography-ready drafts rather than prose-only section text.
@@ -45,6 +45,9 @@ When the current target has a bundled example bank, load the examples index and
45
45
  - abstract -> `skills/lab/references/paper-writing/examples/index.md`, `skills/lab/references/paper-writing/examples/abstract-examples.md`, plus one matching file under `skills/lab/references/paper-writing/examples/abstract/`
46
46
  - introduction -> `skills/lab/references/paper-writing/examples/index.md`, `skills/lab/references/paper-writing/examples/introduction-examples.md`, plus 1-2 matching files under `skills/lab/references/paper-writing/examples/introduction/`
47
47
  - method -> `skills/lab/references/paper-writing/examples/index.md`, `skills/lab/references/paper-writing/examples/method-examples.md`, plus 1-2 matching files under `skills/lab/references/paper-writing/examples/method/`
48
+ - related work -> `skills/lab/references/paper-writing/examples/index.md`, `skills/lab/references/paper-writing/examples/related-work-examples.md`, plus 1-2 matching files under `skills/lab/references/paper-writing/examples/related-work/`
49
+ - experiments -> `skills/lab/references/paper-writing/examples/index.md`, `skills/lab/references/paper-writing/examples/experiments-examples.md`, plus 1-2 matching files under `skills/lab/references/paper-writing/examples/experiments/`
50
+ - conclusion -> `skills/lab/references/paper-writing/examples/index.md`, `skills/lab/references/paper-writing/examples/conclusion-examples.md`, plus 1-2 matching files under `skills/lab/references/paper-writing/examples/conclusion/`
48
51
 
49
52
  Run these on every round:
50
53
 
@@ -61,17 +64,45 @@ Run these on every round:
61
64
  - If the user chooses the default scaffold, persist that choice in `.lab/config/workflow.json` by setting `paper_template_decision` to `default-scaffold`.
62
65
  - If the user chooses to attach a template, stop the drafting loop and route to `superlab paper attach-template --path <dir>` instead of silently falling back.
63
66
  - If `paper_template_decision` is `default-scaffold`, use the managed default LaTeX scaffold under the deliverable paper directory.
67
+ - When using the managed default scaffold, use the managed paper asset templates as the starting point for new manuscript assets:
68
+ - `.lab/.managed/templates/paper.tex`
69
+ - `.lab/.managed/templates/paper-section.tex`
70
+ - `.lab/.managed/templates/paper-table.tex`
71
+ - `.lab/.managed/templates/paper-figure.tex`
72
+ - `.lab/.managed/templates/paper-references.bib`
64
73
  - If the current round is a final manuscript export or final-draft pass, `paper_template_root` is still empty, `paper_template_decision` is `default-scaffold`, and `paper_template_final_reminder_acknowledged` is `false`, ask one final reminder question about switching to a template before finalizing.
65
74
  - If the user confirms staying on the default scaffold at that final reminder, persist `paper_template_final_reminder_acknowledged: true`.
66
75
  - Load only the current section guide. Do not load every section guide at once.
67
- - Reuse example-bank structure, paragraph roles, and sentence logic when examples are bundled, but never copy wording verbatim.
76
+ - Reuse example-bank structure, paragraph roles, sentence logic, and paper-facing LaTeX asset patterns when examples are bundled, but never copy wording verbatim.
68
77
  - Treat example cites and example file names as writing references, not as evidence for the current paper.
69
78
  - Build a compact mini-outline before prose.
79
+ - Build the paper asset plan before prose when the section carries experimental, method, related-work, or conclusion claims:
80
+ - record which table asset files the section needs, what each table should show, and which evidence supports it
81
+ - record which figure placeholder files the section needs, what each figure should show, and why the reader needs it
82
+ - record which citation anchors must appear in the section and why each anchor matters
83
+ - Before drafting `method`, `experiments`, `related work`, or `conclusion`, run `.lab/.managed/scripts/validate_paper_plan.py --paper-plan .lab/writing/plan.md`.
84
+ - If the paper-plan validator fails, stop and fill `.lab/writing/plan.md` first instead of drafting prose.
70
85
  - For each subsection, explicitly include motivation, design, and technical advantage when applicable.
71
86
  - Avoid a writing style that reads like incremental patching of a naive baseline.
72
87
  - Keep terminology stable across the full paper.
73
88
  - Tie every new or revised claim to explicit evidence.
74
89
  - If a claim cannot be supported by results, weaken or remove it.
90
+ - Do not treat section prose alone as a completed manuscript round.
91
+ - For paper-facing final drafts, maintain a non-empty `references.bib` with real citation keys instead of TODO placeholders.
92
+ - Keep paper-facing LaTeX free of absolute local paths, shell logs, rerun ids, and workflow-only provenance.
93
+ - Replace raw engineering notation such as `+/-` with proper LaTeX formatting such as `\pm`.
94
+ - If the current paper contains experimental claims, materialize real LaTeX table assets instead of leaving all results in prose:
95
+ - `<deliverables_root>/paper/tables/main-results.tex`
96
+ - `<deliverables_root>/paper/tables/ablations.tex`
97
+ - If the current paper contains method or experiments claims, materialize figure placeholders with captions, labels, and explicit figure intent:
98
+ - `<deliverables_root>/paper/figures/method-overview.tex`
99
+ - `<deliverables_root>/paper/figures/results-overview.tex`
100
+ - Table assets must use paper-facing LaTeX structure with `booktabs`, caption, label, and consistent precision.
101
+ - Figure placeholders must explain what the final figure should show and why the reader needs it.
102
+ - Keep `.lab/writing/plan.md` synchronized with the current table plan, figure plan, citation plan, and section-to-asset map whenever manuscript assets change.
103
+ - Run `.lab/.managed/scripts/validate_manuscript_delivery.py --paper-dir <deliverables_root>/paper` before accepting a final-draft or export round.
104
+ - If the manuscript validator fails, keep editing and asset generation until it passes; do not stop at prose-only completion.
105
+ - Run a LaTeX compile smoke test when a local LaTeX toolchain is available; if not available, record the missing verification in the write iteration artifact.
75
106
  - Record what changed and why in a write-iteration artifact.
76
107
  - Return paragraph-level roles for the revised prose when drafting.
77
108
  - Run the five-dimension self-review checklist before accepting a round.
@@ -85,7 +116,12 @@ Run these on every round:
85
116
  - `.lab/writing/plan.md`
86
117
  - `.lab/writing/iterations/<n>.md`
87
118
  - `<deliverables_root>/paper/main.tex`
119
+ - `<deliverables_root>/paper/references.bib`
88
120
  - `<deliverables_root>/paper/sections/<section>.tex`
121
+ - `<deliverables_root>/paper/tables/main-results.tex`
122
+ - `<deliverables_root>/paper/tables/ablations.tex`
123
+ - `<deliverables_root>/paper/figures/method-overview.tex`
124
+ - `<deliverables_root>/paper/figures/results-overview.tex`
89
125
 
90
126
  ## Stop Conditions
91
127
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "superlab",
3
- "version": "0.1.25",
3
+ "version": "0.1.27",
4
4
  "description": "Strict /lab research workflow installer for Codex and Claude",
5
5
  "keywords": [
6
6
  "codex",