project-sync

用途

project-sync 是一个用于机器学习研究项目的手动工作流，作用是把代码仓库或代码 worktree 中产生的新实验结果，记录到论文仓库的 daily_experiments.tex 文件中。

当你有新的实验结果需要沉淀为「面向论文的证据」时使用它。它是人工触发的，由你在希望为结果建立检查点（checkpoint）时主动运行。

当被记录的结果还需要更新证据、论断（claims）、风险、行动或论文状态时，可将本技能与 research-project-memory 配合使用。

主要能力与工作流程

Step 1 — 定位项目

自动检测项目结构，运行命令：

# Find the git root of the current repo
git rev-parse --show-toplevel 2>/dev/null

检查当前处于 code/ 还是 paper/，并查找同级目录：

ls "$(git rev-parse --show-toplevel)/../"

需要确定：

$CODE_ROOT：代码仓库根目录或活动代码 worktree 根目录
$PAPER_ROOT：论文仓库根目录
$PROJECT_ROOT：项目控制根目录（若存在）

在 project-init 项目中，paper/ 和 code/ 是项目控制根目录下的组件仓库，代码 worktree 通常位于 code-worktrees/ 下。若无法推断论文仓库，则询问用户：

"Where is the paper repo? Please provide its path."

Step 2 — 收集新结果

在一条消息中向用户询问：

Date：实验日期（默认今天，YYYY-MM-DD）
Short title：该批实验的简短标签（例如 "Baseline on CIFAR-10"、"Ablation: remove attention layer"）
Setup：所用的方法变体 / 配置 / 数据集
Results：关键数字（指标、准确率、损失等）
Observation：结果意味着什么，哪些有效、哪些无效
Next：计划中的后续实验

可选地，检查是否已有可提取的结果文件：

# Stable code-side evidence
find "$CODE_ROOT/docs/results" "$CODE_ROOT/docs/reports" "$CODE_ROOT/docs/runs" -maxdepth 2 -type f 2>/dev/null | sort | tail -20

# Raw or ignored outputs, if present
find "$CODE_ROOT/outputs" "$CODE_ROOT/logs" "$CODE_ROOT/checkpoints" -maxdepth 2 -type f 2>/dev/null | sort | tail -20

若存在相关的结果摘要或报告，读取并预填答案供用户确认。原始日志应视为支撑材料，而非面向论文的证据，除非用户确认其中的数字。

Step 3 — 预览条目

组织并展示 LaTeX 条目供用户审阅：

\subsection*{<DATE> — <SHORT TITLE>}
\textbf{Setup:} <setup>\\
\textbf{Result:} <results>\\
\textbf{Observation:} <observation>\\
\textbf{Next:} <next>

询问："Does this look correct? Should I add it to the paper?" 等待确认。

Step 4 — 插入 daily_experiments.tex

读取 $PAPER_ROOT/sections/daily_experiments.tex 的当前内容，将新条目插入顶部（注释头之下），使日志按时间倒序（最新在前）。插入后向用户展示文件顶部以确认。

Step 5 — 提交到论文仓库（可选）

询问是否要提交到 paper repo 的 Git。若同意：

git -C "$PAPER_ROOT" add sections/daily_experiments.tex
git -C "$PAPER_ROOT" commit -m "exp: add <DATE> — <SHORT TITLE>"

若不同意，告知用户文件已保存，可稍后提交。

Step 6 — 确认

报告：

Experiment logged:
  Date:   <DATE>
  Title:  <SHORT TITLE>
  File:   <PAPER_ROOT>/sections/daily_experiments.tex

To view all logged experiments:
  cat <PAPER_ROOT>/sections/daily_experiments.tex

Step 7 — 存在时更新项目记忆

若父项目有 memory/，更新：

memory/evidence-board.md：将记录的结果添加为 EVD-### 或链接到已有的 EXP-###
memory/provenance-board.md：记录来源路径、确认状态，以及 daily-log / 面向论文的消费路径
memory/claim-board.md：将受影响的论断移动为 supported、weakened、provisional 或 evidence-needed
memory/risk-board.md：添加或关闭该结果暴露的风险
memory/action-board.md：从日志条目添加下一个实验 / 报告 / 写作行动
memory/handoff-board.md：当同步结果需要被论文消费时，创建到 paper-evidence-board、paper-result-asset-builder 或 experiment-story-writer 的 handoff
memory/phase-dashboard.md：若本次同步改变了项目就绪度，更新活动的证据或起草门控
paper/.agent/paper-status.md：注明 sections/daily_experiments.tex 现已包含该结果
code/.agent/ 或 <code-worktree>/.agent/worktree-status.md：标记该结果已被提升为面向论文的证据

只有当数字有来源链接或经用户确认时，才将每日实验日志视为证据；否则将确定性标记为 user-stated 或 needs-verification。

适用场景

代码仓库中产生了新的实验结果，希望记录到论文中
已有日志、报告、运行文档或用户确认的指标，需要成为面向论文的证据
需要为实验结果建立检查点（checkpoint）并保持论文与代码同步

限制与注意事项

这是人工触发的工作流，不会自动运行。
原始日志属于支撑材料，除非用户确认，否则不作为面向论文的证据。
若无法推断论文仓库位置，需用户提供路径。
提交到 Git 为可选项，需要用户明确同意。