sync-notes

# 同步笔记 把工作目录、远端提交和素材 authority 同步成可继续维护的状态。先遵循当前仓库 `AGENTS.md` 与私有补充；这是普通会话，不创建 Goal、自动化或其他线程。 ## 指令 | 用户说法 | 执行范围 | | --- | --- | | `同步笔记` / `sync笔记` / `pull CS-Notes and push` | 拉取远端、保留有效本地改动、对账素材，验证后提交并推送公开内容 | | `同步笔记，仅检查` | 获取远端引用并生成只读计划；不改变笔记、素材 authority、提交或推送 | | `同步笔记，提 PR` | 同步后在 `codex/` 分支提交并创建 PR；合并沿用用户另行明确的授权 | 明确的目录、材料、提交粒度或排除项优先。同步不隐含用户读完材料，不为了同步重新评分整条队列。 ## 同步路径 1. 看常用目录的分支、upstream、status、staged/unstaged diff 与未跟踪文件。对将被切换、恢复或合并的文件保存可恢复副本、原 Git revision 与 digest；临时备份及审计可以留本地，执行代码放仓库工具层。读取现有完成证据与 authority 版本。 2. `git fetch` 后，固定 `HEAD`、upstream 和 merge-base。在 pull 或刷新生成文件前运行三方素材计划： ```sh python3 note-system/materials/material_reconcile.py --repo . --upstream origin/master ``` 实际 upstream 优先，不写死切换到 master。脚本只读已获取的引用，校验完整公开卡片，输出稳定 ID 的新增/缺失/冲突与独立排名变化；不生成 lifecycle transition。若暂存版与工作副本不同，两者都核对。 3. 无冲突时 fast-forward；脏文件按共同基线逐文件或逐 hunk 合并。保留远端脱敏与修正，同时保留本地新增。既有本地提交和远端有分歧时做可审查合并，不能 force、批量 restore/reset 或以 stash 遗留掩盖内容。确有语义冲突才问不可替代的用户判断，继续独立部分。 4. 材料 authority 与 Git 是两个状态源。公开 catalog/Markdown 是投影，不能反向覆盖 authority。若项目已激活 Material Lifecycle，使用项目的 `loopx-material` 与 source adapter 对账： - `local_addition` 保留原 ID、body backing、读取范围和排序；远端缺少它不产生归档。 - 本地或远端缺条目时，先查 source disposition 与逐条用户声明；远端 PR 的笼统“读完”、助手 read_scope 或 Notes 中出现摘要均不证明用户完成。 - 已核验的用户完成声明才能通过现有 owner gate / CAS / receipt 改 lifecycle；材料级声明校验由 [共享实现](../../../note-system/materials/material_completion.py)维护。 - 远端新卡片保留真实既有读取范围，不把摘要导入说成全文阅读。独立对账 lifecycle、intake 与 ranking，保留不相关材料顺序、并发新增和全部 backing。缺材料完成证据时保留当前状态，不阻塞无关笔记同步。 5. authority 结算后重新绑定公开字段审查，执行项目入口的 prepare/apply/check，再运行： ```sh python3 note-system/materials/material_queue.py --check python3 -m unittest discover -s note-system/materials/tests -p 'test_material*.py' git diff --check ``` 未激活或公开克隆没有 source adapter 时，保留 Git 对账结果，明确无法结算的 source 操作，不创建替代 authority；合法的公开内容仍可按授权提交。 6. 阅读最终 diff，确认没有材料无依据消失、重复 ID、未审查状态泄露和私有内容。按主题只暂存明确路径，遵循 `git-split-commit-pr`。默认完整指令已授权公开内容 commit/push；不要求重复确认，不借该指令授权公司内容、凭证、内部来源或外部消息。 7. 推送前核对当前 GitHub 账号、上游与已有 fork 的权限。上游 `push=false` 或一次明确的 403 只说明该账号不能直推上游，不代表不能提 PR。用户已要求提 PR 时，检查当前账号的已有 fork 是否确为同一上游且 `push=true`；核对目标分支、远端 head 和原授权范围后，正常推送到已有 fork，再以明确的 `--repo 上游 --base 原基线 --head 当前账号:分支` 创建 PR。先查询同 head 的现有 PR，发送结果不明时先读回，不重复推送或建 PR。不覆盖 `origin`、不 force push、不切账号或扩大权限；没有合适的已授权 fork 时说明精确缺口。单纯同步请求不借此新建 fork 或改成 PR。 更新已有 PR 时，先读取其真实 `headRepository / headRefName / headRefOid`，核对该仓库权限与预期 head，再正常推到它的确切来源。主仓库存在同名分支或本地 upstream 指向主仓库，不代表该分支就是 PR 来源。推送后必须读回 PR head 与本地提交一致，才可报告更新成功或继续合并。 8. 核验远端 head 和常用 checkout 的实际状态，核验材料队列读回。完成报告包含提交链接、剩余改动或具体阻塞；不能只报告独立 worktree 干净。 同步中发现已核验的流程缺陷时，把修复落到现有 owner 的 AGENTS、skill 或工具层，并用原失误的合成反例验证。稳定规则与通用代码维护在仓库，私有配置和运行证据留本地；不要为每次同步另写本机专属脚本。