From 8eb02ebdd49328fb981a743f7380de9ad8b311a1 Mon Sep 17 00:00:00 2001
From: Research Assistant <research@example.com>
Date: Tue, 19 May 2026 15:28:37 +0800
Subject: [PATCH] feat(skill): add pre-flight checklist harness to SKILL.md and
 all molecules

---
 _temp_bootstrap_vec.py                        | 85 +++++++++++++++++++
 paperforge/skills/paperforge/SKILL.md         | 12 +++
 .../molecules/capture-project-knowledge.md    |  9 ++
 .../molecules/deep-analyze-paper.md           | 10 ++-
 .../paperforge/molecules/discover-papers.md   |  9 +-
 .../molecules/find-supporting-evidence.md     | 11 ++-
 .../paperforge/molecules/read-known-paper.md  |  9 +-
 7 files changed, 137 insertions(+), 8 deletions(-)
 create mode 100644 _temp_bootstrap_vec.py

diff --git a/_temp_bootstrap_vec.py b/_temp_bootstrap_vec.py
new file mode 100644
index 00000000..7256c63f
--- /dev/null
+++ b/_temp_bootstrap_vec.py
@@ -0,0 +1,85 @@
+"""Verify bootstrap and vector availability."""
+import subprocess, json, sys
+from pathlib import Path
+
+VAULT = r"D:\L\OB\Literature-hub"
+SCRIPT = Path(r"D:\L\OB\Literature-hub\.opencode\skills\paperforge\scripts\pf_bootstrap.py")
+PYTHON = sys.executable
+
+def run(*args):
+    r = subprocess.run(args, capture_output=True, text=False, timeout=15)
+    return r.stdout.decode("utf-8", errors="replace")
+
+print("=" * 50)
+print("PHASE 0: BOOTSTRAP (SKILL.md Section 1)")
+print("=" * 50)
+
+# Run bootstrap AS AN AGENT would
+result = run(PYTHON, str(SCRIPT), "--vault", VAULT)
+print(result[:2000])
+boot = json.loads(result)
+
+print(f"\n--- Bootstrap Results ---")
+print(f"ok: {boot.get('ok')}")
+print(f"vault: {boot.get('vault_root')}")
+
+paths = boot.get('paths', {})
+for k, v in paths.items():
+    print(f"  {k}: {v}")
+
+caps = boot.get('capabilities', {})
+print(f"\n--- Capabilities ---")
+for k, v in caps.items():
+    print(f"  {k}: {v}")
+
+mem = boot.get('memory_layer', {})
+print(f"\n--- Memory Layer ---")
+for k, v in mem.items():
+    print(f"  {k}: {v}")
+
+print(f"\nDomains: {boot.get('domains')}")
+print(f"Python verified: {boot.get('python_verified')}")
+print(f"Methods: {len(boot.get('methodology_index', []))} cards")
+
+print(f"\n{'=' * 50}")
+print("PHASE 0.5: CAPABILITY AWARE ROUTING TEST")
+print("=" * 50)
+print(f"""
+Scenario: User asks "找 Piezo1 和软骨基质降解的证据"
+
+Retrieval routing decision (atoms/retrieval-routing.md):
+  semantic_enabled={caps.get('semantic_enabled')}
+  semantic_ready={caps.get('semantic_ready')}
+
+  Since this is an EVIDENCE query (not candidate expansion):
+  -> Ladder B (rg) is primary path
+  -> Ladder D (semantic) is available as supplementary only
+
+Agent decision:
+  rg available: {caps.get('rg')}
+  Agent uses Ladder B for primary evidence retrieval
+  Agent does NOT use Ladder D as primary path (correct per retrieval-routing.md)
+  Agent CAN use Ladder D for candidate expansion AFTER rg verification
+  
+Vector DB status:
+  Enabled: {caps.get('semantic_enabled')}
+  Ready: {caps.get('semantic_ready')}
+  {'Agent may use semantic for candidate expansion' if caps.get('semantic_ready') else 'Agent must not use semantic'}
+  Agent must verify all semantic hits with rg/fulltext before use
+""")
+
+print("--- runtime-health authoritative check ---")
+rh = run(PYTHON, "-m", "paperforge", "--vault", VAULT, "runtime-health", "--json")
+try:
+    rh_data = json.loads(rh)
+    vec = rh_data.get("data", {}).get("layers", {}).get("vector", {})
+    print(f"  runtime-health vector status: {vec.get('status')}")
+    print(f"  bootstrap semantic_ready: {caps.get('semantic_ready')}")
+    match = (vec.get('status') == 'ok') == (caps.get('semantic_ready') == True)
+    print(f"  {'[PASS] bootstrap and runtime-health agree' if match else '[INFO] bootstrap is convenience layer, runtime-health is authoritative'}")
+except:
+    print(f"  [INFO] could not parse runtime-health")
+
+# Clean
+if Path("_temp_bootstrap_vec.py").exists():
+    Path("_temp_bootstrap_vec.py").unlink()
diff --git a/paperforge/skills/paperforge/SKILL.md b/paperforge/skills/paperforge/SKILL.md
index 0303a829..f33d8133 100644
--- a/paperforge/skills/paperforge/SKILL.md
+++ b/paperforge/skills/paperforge/SKILL.md
@@ -40,6 +40,18 @@ python $SKILL_DIR/scripts/pf_bootstrap.py --vault "$VAULT"
 
 bootstrap 现在也返回一个 `capabilities` 块（rg, semantic, metadata 等）。
 
+## 1a. Pre-flight Checklist
+
+**进入任何 molecule 之前，必须完成以下检查。标记为 `[x]` 后才可前进。**
+
+- [ ] **bootstrap completed**：`$VAULT`、`$PYTHON`、`$LIT_DIR`、`$SKILL_DIR` 已定义
+- [ ] **capabilities**：已读取 `capabilities` 块中的 `rg`、`metadata_search`、`paper_context`、`semantic_enabled`、`semantic_ready`
+- [ ] **runtime-health passed**：`safe_read`、`safe_write` 已知，vector 状态已知
+- [ ] **intent identified**：用户意图已映射到一个顶层 research intent
+- [ ] **molecule selected**：已路由到对应的 `molecules/<intent>.md`
+
+如果任一检查未通过，先执行对应的步骤，**不跳过**。
+
 ---
 
 ## 2. Agent Context — bootstrap 成功后执行
diff --git a/paperforge/skills/paperforge/molecules/capture-project-knowledge.md b/paperforge/skills/paperforge/molecules/capture-project-knowledge.md
index f6c57c69..0d72835e 100644
--- a/paperforge/skills/paperforge/molecules/capture-project-knowledge.md
+++ b/paperforge/skills/paperforge/molecules/capture-project-knowledge.md
@@ -2,6 +2,15 @@
 
 捕获和持久化从阅读中获得的知识到项目记忆。
 
+## Pre-flight Checklist
+
+- [ ] SKILL.md Section 1a Pre-flight 全部通过
+- [ ] `$VAULT`、`$PYTHON` 已从 bootstrap 获取
+- [ ] 待保存的内容已就绪（证据/讨论/方法论）
+- [ ] intent 已确定为 `capture_project_knowledge`
+
+ 或作为 post-action（在其他 molecule 输出后用户要求保存）
+
 ---
 
 ## 触发模式
diff --git a/paperforge/skills/paperforge/molecules/deep-analyze-paper.md b/paperforge/skills/paperforge/molecules/deep-analyze-paper.md
index 05139914..17b7ad8a 100644
--- a/paperforge/skills/paperforge/molecules/deep-analyze-paper.md
+++ b/paperforge/skills/paperforge/molecules/deep-analyze-paper.md
@@ -13,7 +13,15 @@ Keshav 三阶段精读。在 formal note 中写入结构化的 `## 精读` 区
 
 ---
 
-## 前置检查
+## Pre-flight Checklist
+
+- [ ] SKILL.md Section 1a Pre-flight 全部通过
+- [ ] `$VAULT`、`$PYTHON` 已从 bootstrap 获取
+- [ ] 已确定唯一 paper（zotero_key）
+- [ ] OCR status 为 `done`（否则无法精读）
+- [ ] intent 已确定为 `deep_analyze_paper`
+
+---
 
 ### Step 0: paper-context（必须）
 
diff --git a/paperforge/skills/paperforge/molecules/discover-papers.md b/paperforge/skills/paperforge/molecules/discover-papers.md
index 520586f2..6a539210 100644
--- a/paperforge/skills/paperforge/molecules/discover-papers.md
+++ b/paperforge/skills/paperforge/molecules/discover-papers.md
@@ -4,9 +4,14 @@
 
 ---
 
-## 前置条件
+## Pre-flight Checklist
 
-- bootstrap 已完成（有 `$VAULT`、`$PYTHON`、`$LIT_DIR`）
+进入此 molecule 前，确认以下检查已完成。每项完成后标记 `[x]`：
+
+- [ ] SKILL.md Section 1a Pre-flight 全部通过
+- [ ] `$VAULT`、`$PYTHON`、`$LIT_DIR` 已从 bootstrap 获取
+- [ ] `capabilities` 已读取（至少确认 `metadata_search` 可用）
+- [ ] intent 已确定为 `discover_papers`
 
 ---
 
diff --git a/paperforge/skills/paperforge/molecules/find-supporting-evidence.md b/paperforge/skills/paperforge/molecules/find-supporting-evidence.md
index 9d750104..6dba40a6 100644
--- a/paperforge/skills/paperforge/molecules/find-supporting-evidence.md
+++ b/paperforge/skills/paperforge/molecules/find-supporting-evidence.md
@@ -4,10 +4,15 @@
 
 ---
 
-## 前置条件
+## Pre-flight Checklist
 
-- bootstrap 已完成（有 `$VAULT`、`$PYTHON`、`$LIT_DIR`）
-- `atoms/retrieval-routing.md` 已就绪（提供检索梯级选择）
+进入此 molecule 前，确认以下检查已完成：
+
+- [ ] SKILL.md Section 1a Pre-flight 全部通过
+- [ ] `$VAULT`、`$PYTHON`、`$LIT_DIR` 已从 bootstrap 获取
+- [ ] `capabilities` 已读取（关键：`rg`、`semantic_enabled`、`semantic_ready`）
+- [ ] `atoms/retrieval-routing.md` 已就绪（提供检索梯级选择）
+- [ ] intent 已确定为 `find_supporting_evidence`
 
 ---
 
diff --git a/paperforge/skills/paperforge/molecules/read-known-paper.md b/paperforge/skills/paperforge/molecules/read-known-paper.md
index bb3ac427..d3fc3248 100644
--- a/paperforge/skills/paperforge/molecules/read-known-paper.md
+++ b/paperforge/skills/paperforge/molecules/read-known-paper.md
@@ -10,9 +10,14 @@
 
 ---
 
-## 前置条件
+## Pre-flight Checklist
 
-- bootstrap 已完成（有 `$VAULT`、`$PYTHON`）
+进入此 molecule 前，确认以下检查已完成：
+
+- [ ] SKILL.md Section 1a Pre-flight 全部通过
+- [ ] `$VAULT`、`$PYTHON` 已从 bootstrap 获取
+- [ ] 已确定唯一 paper（zotero_key / DOI / 标题）
+- [ ] intent 已确定为 `read_known_paper`
 
 ---