obs-auto-moc

name	obs-auto-moc
description	建立 review-first 的 Obsidian MOC manifest、proposal 與 preview。預設不改 live MOC，只有明確要求時才 apply。

Obs Auto MOC Skill

當使用者要檢查、重建、預覽或套用 Obsidian MOC.md 時，使用這個 skill。

固定路徑

• project root: /home/haman/custom-claw-tools/obs-auto-moc
• repo skill copy: /home/haman/custom-claw-tools/obs-auto-moc/SKILL.md
• live skill path: /home/haman/.picoclaw/workspace/skills/obs-auto-moc/SKILL.md
• live wrapper path: /home/haman/.picoclaw/workspace/bin/obs-auto-moc
• artifacts root: /home/haman/.picoclaw/workspace/notes/claw/moc
• proposal root: /home/haman/.picoclaw/workspace/notes/claw/moc/proposals
• manifest path: /home/haman/.picoclaw/workspace/notes/claw/moc/index-manifest.jsonl
• preview path: /home/haman/.picoclaw/workspace/notes/claw/moc/MOC.preview.md
• status path: /home/haman/.picoclaw/workspace/notes/claw/moc/last-run.json
• live MOC path: /home/haman/.picoclaw/workspace/notes/MOC.md
• sync config root: /home/haman/.config/obsidian-headless/sync

何時使用這個 skill

當任務符合以下情況時，使用 obs-auto-moc：

• 想先 review 再決定是否更新 MOC.md
• 想檢查哪些筆記是 orphan、哪些 frontmatter 不完整
• 想看新的 MOC.preview.md
• 想在 PicoClaw 內安全觸發 MOC 重建
• 想在不直接覆寫 live MOC 的前提下產出 proposal artifact

不要用在這些情況

• 不要在未經使用者明確確認前直接套用 --apply
• 不要假裝 frontmatter 永遠完整或格式正確
• 不要在 proposal mode 寫入大量筆記
• 不要繞過 sync config 去硬編碼不可信的 vault path

角色分工

PicoClaw

• 判斷使用者是要 preview、stats，還是 explicit apply
• 透過 exec 呼叫 live wrapper
• 讀回 proposal、preview 或 stats
• 誠實回報 malformed notes、缺欄位與 unresolved links

obs-auto-moc

• 從 sync config 解出 vault path
• 只處理 root-note、TechVault、WorkVault、PersonalVault
• 掃描 Markdown、Frontmatter 與 wikilinks
• 產出 manifest、proposal 與 preview
• 只有在 --apply 時才原子更新 live MOC.md
• 支援 metadata-only Decayed 狀態；agent search / read / 引用可喚醒筆記並重算 last_resonated_at

必要流程

1. 預設先跑 preview build

   • 使用：
     • /home/haman/.picoclaw/workspace/bin/obs-auto-moc build
   • 這一步會更新 manifest、proposal 與 MOC.preview.md
   • 這一步不會改寫 live MOC.md

2. 先讀結果

   • 讀 last-run.json
   • 讀最新 proposal
   • 必要時讀 MOC.preview.md

3. 只有在使用者明確要求「套用」時，才執行：

   • /home/haman/.picoclaw/workspace/bin/obs-auto-moc build --apply

4. 回覆要精簡

   • 說明這次是否只是 preview
   • 列出 proposal / preview 路徑
   • 列出最重要的 warning
   • 若有 apply，明確說 live MOC.md 已更新

root-note pipeline scaffold

目前 repo 內已加入第一版 script-side scaffold，對應 root-note -> PicoClaw -> destination MOC 流程：

• monitor-root-note：掃描 root-note/，只對變更檔案產出 PicoClaw handoff artifact
• apply-picoclaw-report --report <file>：吃結構化 PicoClaw 完成回報，更新 pipeline state，並刷新 touched destination MOC
• queue-picoclaw-report --report <file> [--run-pipeline]：驗證回報後先放入 report inbox，必要時立刻跑一輪 pipeline
• record-agent-reference --note-path <path>...：記錄 agent reference batch，解除 Decayed，重算 last_resonated_at，並重建 touched note set 的 related
• refresh-destination-mocs：直接重建 TechVault / WorkVault / PersonalVault 的 MOC.md
• dispatch-picoclaw-handoff --handoff <file>：把 handoff job 直接交給 live PicoClaw，擷取結構化 report，再餵回 pipeline
• run-pipeline-once：先吃 report inbox 裡的 PicoClaw 完成回報，再從 root-note/ 產出下一個 handoff job；若 auto-dispatch 開啟，會立刻把 handoff 送進 live PicoClaw
• 若 queued PicoClaw report 是壞的或無法套用，run-pipeline-once 會把它隔離到 pipeline/picoclaw-report-failures/，並讓受影響的 root-note 項目回到可重試狀態
• 若 live PicoClaw auto-dispatch 自己回了壞 output 或沒回合法 report block，run-pipeline-once 也只會把受影響項目標成可重試，不會再整條卡死在 handed_off_to_picoclaw
• 若 live PicoClaw 只回部分 entries，缺的 handoff 項目會自動補成 failed 後重試，不會再殘留成假性的 handed_off_to_picoclaw
• 若 live PicoClaw 回了 stale job / 假的 processed output（目的筆記根本沒落地），dispatcher 會直接走本機 fallback，把 source root-note 複製到選定的 destination vault 後再回灌有效 report
• listen --host 127.0.0.1 --port 45460 --run-pipeline：提供 loopback GET /health、POST /picoclaw-report 與 POST /agent-reference callback ingestion
• handoff artifact 的 callback_contract.endpoint 預設會指向 http://127.0.0.1:45460/picoclaw-report
• handoff artifact 會附上 vault_path 與 destination root paths，讓 PicoClaw 在回報前先建立目的筆記

注意：

• Stage 2 agent 由 live PicoClaw 執行，不是在 obs-auto-moc 內執行
• Stage 2 規則入口已對齊到 pi3 notes 內的 ObsToolsVault/README.md，更細的遷移規則在 ObsToolsVault/specs/
• pi3 上的建議部署是 obs-auto-moc-listener.service + obs-auto-moc-pipeline.path + obs-auto-moc-pipeline.timer
• bin/obs-auto-moc-runner 預設會開 OBS_AUTO_MOC_AUTO_DISPATCH=1，並使用 cron:obs-auto-moc:<job_id> 這種 job-scoped session 自動把 handoff 送進 PicoClaw，避免沿用舊對話上下文
• bin/obs-auto-moc-listen / bin/obs-auto-moc-runner 支援 OBS_AUTO_MOC_SYNC_ROOT、OBS_AUTO_MOC_VAULT_PATH、OBS_AUTO_MOC_AUTO_DISPATCH、OBS_AUTO_MOC_PICOCLAW_SESSION、OBS_AUTO_MOC_STALE_HANDOFF_SECONDS 等環境覆寫；其中 OBS_AUTO_MOC_PICOCLAW_SESSION 會被當成 session prefix，dispatcher 會自動附上 :<job_id>，也可自行放 {job_id} placeholder

常用指令

Preview build

/home/haman/.picoclaw/workspace/bin/obs-auto-moc build

Stats

/home/haman/.picoclaw/workspace/bin/obs-auto-moc stats

Apply

/home/haman/.picoclaw/workspace/bin/obs-auto-moc build --apply

Guardrails

• 預設是 review-first，不是 auto-apply。
• 若 last-run.json 顯示 parse errors、missing schema fields 或 unresolved links，要誠實說明。
• 若 sync config 缺失或有多份 config，直接回報錯誤，不要猜路徑。
• 除了 notes/MOC.md 的 explicit apply 之外，不要改寫 vault 內其他筆記。
• notes/claw/moc 是 artifact root；preview/proposal 都先寫這裡。