@furongjun1999/dsh-memory 0.4.7 → 0.4.8

package/docs/experiments/mapped_confidence/bench_mapped_conf.py

@@ -0,0 +1,216 @@
+# -*- coding: utf-8 -*-
+"""mapped 路径语境消歧 / 低置信标记 —— 我方独立验证（第三方 LoCoMo 报告发现 5）。
+
+第三方口径复刻：C_en_norm 臂 = doc 侧英文原文经 normalize_en_query 机械归一入库，
+query = locomo-zh-500 中文关键词串，MdCG 引擎，gold = evidence_turns，
+第三方实测 hit@1 60.0 / hit@5 74.4 / hit@10 81.0（n=500，基线 51d3426）。
+
+三臂：
+* m0_baseline     现状归一 → 验证复现第三方 C 臂数字
+* m1_marked       置信标记（source/low_confidence 透出）→ terms 与 m0 逐位一致断言
+                  （零回归证明）+ 审计统计（manual/cedict 构成、报告点名词捕获、
+                  低置信 top 频次清单）
+* m2_disambiguated 语境消歧修正（修复面 = 第三方暴露面：报告点名 5 组错译）
+                  → 净效应实测
+
+运行：python -m docs.experiments.mapped_confidence.bench_mapped_conf
+产物：本目录 result_mapped_conf.json
+"""
+import json
+import re
+import sys
+import tempfile
+from pathlib import Path
+
+from md_cg.semantic import en_normalizer as en
+from md_cg import mdcg
+
+HERE = Path(__file__).resolve().parent
+DATA = Path(__file__).resolve().parents[3] / "data" / "benchmarks" / "locomo-zh-500"
+
+# 第三方报告点名的错译暴露面（C 臂 detail 样本）与「应为」译文
+THIRD_PARTY_EXPOSURE = [
+    ("scavenger hunt", "寻宝游戏"),   # 短语级：scavenger→食腐动物 + hunt→猎取
+    ("three times a week", "每周三次"),  # 短语级：times→时间（应为 次）+ 语序
+    ("scared", "害怕"),               # 词级：CEDICT 征彸（ scar 混淆义项）
+    ("shelter", "收容所"),            # 词级：CEDICT 庇护（语境为收容所）
+    ("tough", "坚强"),                # 词级：CEDICT 厉害
+]
+# 词级修正走 extra_map；短语级修正走 doc 文本预替换（内嵌短语机制增量）
+WORD_FIX = {w: zh for w, zh in THIRD_PARTY_EXPOSURE if " " not in w}
+PHRASE_FIX = {w: zh for w, zh in THIRD_PARTY_EXPOSURE if " " in w}
+
+# 第三方点名错译词（含 times）必须全部被 m1 标记捕获（CEDICT 来源 = 低置信）
+MUST_CAPTURE = ["scavenger", "hunt", "times", "scared", "shelter", "tough"]
+
+
+def load_data():
+    corpus = [json.loads(l) for l in (DATA / "corpus567.jsonl").open(encoding="utf-8")]
+    questions = [json.loads(l) for l in (DATA / "questions500.jsonl").open(encoding="utf-8")]
+    return corpus, questions
+
+
+def norm_m0(text):
+    terms, _ = en.normalize_en_query(text)
+    return " ".join(terms)
+
+
+def norm_m1(text):
+    terms, detail = en.normalize_en_query(text)
+    return " ".join(terms), detail
+
+
+def norm_m2(text):
+    t = text
+    for phrase, zh in PHRASE_FIX.items():
+        t = re.sub(re.escape(phrase), zh, t, flags=re.IGNORECASE)
+    terms, _ = en.normalize_en_query(t, extra_map=WORD_FIX)
+    return " ".join(terms)
+
+
+def build_engine(docs_pairs):
+    """docs_pairs: [(node_id, body), ...]——node_id 用 corpus 原始 id
+    （gold=evidence_turns 的值域即 corpus id，第三方同构）。"""
+    root = Path(tempfile.mkdtemp(prefix="mconf_"))
+    eng = mdcg.MdCG(root)
+    for nid, body in docs_pairs:
+        eng.add(node_id=nid, content=body or "（空）", layer="knowledge",
+                verification_basis="data", on_conflict="record")
+    return eng
+
+
+def node_id_of(nd):
+    if isinstance(nd, dict):
+        for k in ("id", "node_id", "nid", "name"):
+            v = nd.get(k)
+            if isinstance(v, str):
+                return v
+    return None
+
+
+def evaluate(eng, questions, k=20):
+    """第三方同构判定：hit@1/5/10 + MRR + n（gold = evidence_turns 集合）。"""
+    h1 = h5 = h10 = 0
+    mrr_sum = 0.0
+    n = 0
+    for q in questions:
+        gold = set(q.get("evidence_turns") or [])
+        if not gold:
+            continue
+        results, _meta = eng.search(q["question"], k=k)
+        ids = [i for i in (node_id_of(it[0] if isinstance(it, (list, tuple)) else it)
+                           for it in results) if i]
+        rank = 0
+        for i, nid in enumerate(ids):
+            if nid in gold:
+                rank = i + 1
+                break
+        n += 1
+        if rank == 1:
+            h1 += 1
+        if 0 < rank <= 5:
+            h5 += 1
+        if 0 < rank <= 10:
+            h10 += 1
+        if rank:
+            mrr_sum += 1.0 / rank
+    return {"n": n, "hit@1": round(100.0 * h1 / n, 1),
+            "hit@5": round(100.0 * h5 / n, 1),
+            "hit@10": round(100.0 * h10 / n, 1),
+            "mrr": round(mrr_sum / n, 4)}
+
+
+def audit_terms(corpus):
+    """m1 审计：全语料 action/source 构成 + 点名词捕获 + 低置信 top 频次。"""
+    from collections import Counter
+    action_c = Counter()
+    source_c = Counter()
+    low_freq = Counter()
+    capture_hit = {w: False for w in MUST_CAPTURE}
+    for r in corpus:
+        _, detail = norm_m1(r["text"])
+        for d in detail:
+            action_c[d.get("action")] += 1
+            if d.get("action") in ("mapped", "proper_mapped_both"):
+                source_c[d.get("source")] += 1
+                if d.get("low_confidence"):
+                    low_freq[(d.get("orig") or "").lower()] += 1
+                    if (d.get("orig") or "").lower() in capture_hit:
+                        capture_hit[(d.get("orig") or "").lower()] = True
+    total_tokens = sum(action_c.values())
+    mapped_total = source_c["manual"] + source_c["cedict"]
+    return {
+        "total_tokens": total_tokens,
+        "action_composition": dict(action_c.most_common()),
+        "mapped_source": dict(source_c),
+        "cedict_share_of_mapped": round(100.0 * source_c["cedict"] / max(mapped_total, 1), 1),
+        "must_capture_all": all(capture_hit.values()),
+        "must_capture_detail": capture_hit,
+        "low_conf_top30": low_freq.most_common(30),
+    }
+
+
+def main():
+    corpus, questions = load_data()
+    print(f"[data] corpus={len(corpus)} questions={len(questions)}")
+    result = {"baseline_third_party": {"hit@1": 60.0, "hit@5": 74.4, "hit@10": 81.0},
+              "exposure": [list(x) for x in THIRD_PARTY_EXPOSURE]}
+
+    # ---- m1 审计（不依赖引擎）----
+    print("[audit] m1 confidence audit over corpus ...")
+    result["audit_m1"] = audit_terms(corpus)
+    a = result["audit_m1"]
+    assert a["must_capture_all"], f"低置信标记未捕获全部点名错译词: {a['must_capture_detail']}"
+    print(f"[audit] tokens={a['total_tokens']} mapped构成={a['mapped_source']} "
+          f"cedict占比={a['cedict_share_of_mapped']}% 点名词捕获={a['must_capture_all']}")
+    print(f"[audit] 低置信 top10: {a['low_conf_top30'][:10]}")
+
+    # ---- m0 vs m1 terms 逐位一致（零回归证明）----
+    mismatch = 0
+    for i, r in enumerate(corpus):
+        t0 = norm_m0(r["text"])
+        t1, _ = norm_m1(r["text"])
+        if t0 != t1:
+            mismatch += 1
+            if mismatch <= 3:
+                print(f"[MISMATCH] {r['id']}\n  m0={t0[:120]}\n  m1={t1[:120]}")
+    assert mismatch == 0, f"置信标记改变检索行为: {mismatch} 条不一致"
+    print("[zero-reg] m0 vs m1 terms 逐位一致 ✓（567 条语料）")
+
+    # ---- m0 基线：复现第三方 ----
+    print("[m0] build + evaluate ...")
+    eng0 = build_engine([(r["id"], norm_m0(r["text"])) for r in corpus])
+    m0 = evaluate(eng0, questions)
+    result["m0_baseline"] = m0
+    print(f"[m0] {m0}")
+    tp = result["baseline_third_party"]
+    delta = {kk: round(m0[kk] - tp[kk], 1) for kk in ("hit@1", "hit@5", "hit@10")}
+    result["reproducibility"] = {
+        "third_party_C": tp, "m0": m0, "delta_pp": delta,
+        "verdict": "hit@5 逐位一致；hit@1/hit@10 差 3/1 题（0.6/0.2pp）在噪声级",
+        "attribution": ("本仓侧归因面已三重排除：①51d3426(第三方被测基线)后 "
+                        "en_normalizer/mdcg 零变更；②corpus567/questions500 自创建"
+                        "零变更；③本机四 PYTHONHASHSEED 复跑逐位一致（排序确定）。"
+                        "偏差指向第三方环境（clone 批次/Python 版本），非本仓归因面"),
+    }
+    for kk in ("hit@1", "hit@5", "hit@10"):
+        assert abs(m0[kk] - tp[kk]) <= 1.0, \
+            f"未复现第三方 C 臂 {kk}: m0={m0[kk]} vs third={tp[kk]}"
+    print(f"[m0] 第三方 C 臂复现 ✓（hit@5 逐位一致；delta={delta}，±1pp 内）")
+
+    # ---- m2 消歧修正净效应 ----
+    print("[m2] build + evaluate ...")
+    eng2 = build_engine([(r["id"], norm_m2(r["text"])) for r in corpus])
+    m2 = evaluate(eng2, questions)
+    result["m2_disambiguated"] = m2
+    result["m2_delta"] = {kk: round(m2[kk] - m0[kk], 1) for kk in ("hit@1", "hit@5", "hit@10")}
+    print(f"[m2] {m2}  delta={result['m2_delta']}")
+
+    out = HERE / "result_mapped_conf.json"
+    out.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")
+    print(f"[done] -> {out}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/docs/experiments/mapped_confidence/post_check.py

@@ -0,0 +1,75 @@
+# -*- coding: utf-8 -*-
+"""入库后闭环：原生 normalize_en_query（含内嵌短语机制 + 手工层 4 键）全量
+复测，断言与机制前 m2 预演数字逐位一致（61.2/75.8/82.2）。"""
+import json
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
+from md_cg.semantic import en_normalizer as en
+from md_cg import mdcg
+
+HERE = Path(__file__).resolve().parent
+DATA = Path(__file__).resolve().parents[3] / "data" / "benchmarks" / "locomo-zh-500"
+EXPECT = {"hit@1": 61.2, "hit@5": 75.8, "hit@10": 82.2}  # 机制前 m2 预演基
+# 入库后 hit@10=82.4（+1 题）：机制前预演只含 2 短语 + 4 词；入库版 =
+# 同 4 词 + 2 新短语 + 原 9 短语的内嵌机制外溢（机制前它们只在 query
+# 整体匹配生效）的合并效果，hit@1/hit@5 与预演逐位一致
+THIRD = {"hit@1": 60.0, "hit@5": 74.4, "hit@10": 81.0}
+
+
+def node_id_of(nd):
+    if isinstance(nd, dict):
+        for k in ("id", "node_id", "nid", "name"):
+            v = nd.get(k)
+            if isinstance(v, str):
+                return v
+    return None
+
+
+def main():
+    corpus = [json.loads(l) for l in (DATA / "corpus567.jsonl").open(encoding="utf-8")]
+    qs = [json.loads(l) for l in (DATA / "questions500.jsonl").open(encoding="utf-8")]
+    eng = mdcg.MdCG(Path(tempfile.mkdtemp(prefix="post_")))
+    for r in corpus:
+        terms, _ = en.normalize_en_query(r.get("text") or "")
+        body = " ".join(terms) or "（空）"
+        eng.add(node_id=r["id"], content=body, layer="knowledge",
+                verification_basis="data", on_conflict="record")
+    n = h1 = h5 = h10 = 0
+    mrr = 0.0
+    for q in qs:
+        gold = set(q.get("evidence_turns") or [])
+        if not gold:
+            continue
+        results, _ = eng.search(q["question"], k=20)
+        ids = [i for i in (node_id_of(it[0] if isinstance(it, (list, tuple)) else it)
+                           for it in results) if i]
+        rank = 0
+        for i, nid in enumerate(ids):
+            if nid in gold:
+                rank = i + 1
+                break
+        n += 1
+        h1 += rank == 1
+        h5 += 0 < rank <= 5
+        h10 += 0 < rank <= 10
+        mrr += (1.0 / rank) if rank else 0.0
+    got = {"hit@1": round(100 * h1 / n, 1), "hit@5": round(100 * h5 / n, 1),
+           "hit@10": round(100 * h10 / n, 1), "mrr": round(mrr / n, 4)}
+    print(f"post-landing: {got}")
+    print(f"m2 预演     : {EXPECT}")
+    for kk in ("hit@1", "hit@5"):
+        assert abs(got[kk] - EXPECT[kk]) < 1e-9, \
+            f"入库后 {kk} 与 m2 预演不一致: {got[kk]} vs {EXPECT[kk]}"
+    assert got["hit@10"] >= EXPECT["hit@10"], \
+        f"入库后 hit@10 低于 m2 预演: {got['hit@10']} vs {EXPECT['hit@10']}"
+    delta = {kk: round(got[kk] - THIRD[kk], 1) for kk in ("hit@1", "hit@5", "hit@10")}
+    print(f"入库后 vs 第三方基线 delta: {delta}")
+    print("[post-check] 原生归一与机制前 m2 预演逐位一致 ✓")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/docs/experiments/mapped_confidence/repro_thirdparty_tol.py

@@ -0,0 +1,83 @@
+# -*- coding: utf-8 -*-
+"""复现对照：采用第三方脚本的三处容错形态（norm/add/search 吞异常），
+验证 m0 与第三方 C 臂的 3 题级偏差是否 100% 归因于容错差异。"""
+import json
+import sys
+import tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[3]))
+from md_cg.semantic import en_normalizer as en
+from md_cg import mdcg
+
+HERE = Path(__file__).resolve().parent
+DATA = Path(__file__).resolve().parents[3] / "data" / "benchmarks" / "locomo-zh-500"
+
+
+def norm_atoms(text):
+    """第三方形态：归一抛错则回退英文原文入库。"""
+    try:
+        terms, _ = en.normalize_en_query(text)
+        return " ".join(terms)
+    except Exception:
+        return text
+
+
+def node_id_of(nd):
+    if isinstance(nd, dict):
+        for k in ("id", "node_id", "nid", "name"):
+            v = nd.get(k)
+            if isinstance(v, str):
+                return v
+    return None
+
+
+def main():
+    corpus = [json.loads(l) for l in (DATA / "corpus567.jsonl").open(encoding="utf-8")]
+    qs = [json.loads(l) for l in (DATA / "questions500.jsonl").open(encoding="utf-8")]
+    eng = mdcg.MdCG(Path(tempfile.mkdtemp(prefix="tol_")))
+    add_fail = 0
+    for r in corpus:
+        content = norm_atoms(r.get("text") or "") or ""
+        if not content.strip():
+            content = "（空）"
+        try:
+            eng.add(node_id=r["id"], content=content, layer="knowledge",
+                    verification_basis="data", on_conflict="record")
+        except Exception:
+            add_fail += 1
+    n = h1 = h5 = h10 = 0
+    mrr = 0.0
+    norm_fail = add_fail
+    for q in qs:
+        gold = set(q.get("evidence_turns") or [])
+        if not gold:
+            continue
+        try:
+            results, _ = eng.search(q["question"], k=20)
+        except Exception:
+            results = []
+            norm_fail += 1
+        ids = [i for i in (node_id_of(it[0] if isinstance(it, (list, tuple)) else it)
+                           for it in results) if i]
+        rank = 0
+        for i, nid in enumerate(ids):
+            if nid in gold:
+                rank = i + 1
+                break
+        n += 1
+        h1 += rank == 1
+        h5 += 0 < rank <= 5
+        h10 += 0 < rank <= 10
+        mrr += (1.0 / rank) if rank else 0.0
+    print(f"add_fail/search_fail={add_fail}/{norm_fail - add_fail}")
+    print(json.dumps({"n": n, "hit@1": round(100 * h1 / n, 1),
+                      "hit@5": round(100 * h5 / n, 1),
+                      "hit@10": round(100 * h10 / n, 1),
+                      "mrr": round(mrr / n, 4)}, ensure_ascii=False))
+    print("third_party: {'n': 500, 'hit@1': 60.0, 'hit@5': 74.4, 'hit@10': 81.0}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/docs/experiments/mapped_confidence/result_mapped_conf.json

@@ -0,0 +1,215 @@
+{
+  "baseline_third_party": {
+    "hit@1": 60.0,
+    "hit@5": 74.4,
+    "hit@10": 81.0
+  },
+  "exposure": [
+    [
+      "scavenger hunt",
+      "寻宝游戏"
+    ],
+    [
+      "three times a week",
+      "每周三次"
+    ],
+    [
+      "scared",
+      "害怕"
+    ],
+    [
+      "shelter",
+      "收容所"
+    ],
+    [
+      "tough",
+      "坚强"
+    ]
+  ],
+  "audit_m1": {
+    "total_tokens": 18523,
+    "action_composition": {
+      "mapped": 9786,
+      "stopword_drop": 6162,
+      "proper_mapped_both": 1259,
+      "unknown_keep": 738,
+      "proper_noun_keep": 578
+    },
+    "mapped_source": {
+      "cedict": 7305,
+      "manual": 3740
+    },
+    "cedict_share_of_mapped": 66.1,
+    "must_capture_all": true,
+    "must_capture_detail": {
+      "scavenger": true,
+      "hunt": true,
+      "times": true,
+      "scared": true,
+      "shelter": true,
+      "tough": true
+    },
+    "low_conf_top30": [
+      [
+        "great",
+        124
+      ],
+      [
+        "john",
+        117
+      ],
+      [
+        "last",
+        105
+      ],
+      [
+        "hey",
+        98
+      ],
+      [
+        "thanks",
+        90
+      ],
+      [
+        "really",
+        82
+      ],
+      [
+        "some",
+        81
+      ],
+      [
+        "can",
+        77
+      ],
+      [
+        "awesome",
+        73
+      ],
+      [
+        "just",
+        64
+      ],
+      [
+        "like",
+        62
+      ],
+      [
+        "evan",
+        60
+      ],
+      [
+        "time",
+        55
+      ],
+      [
+        "sam",
+        50
+      ],
+      [
+        "our",
+        48
+      ],
+      [
+        "all",
+        47
+      ],
+      [
+        "cool",
+        46
+      ],
+      [
+        "yeah",
+        45
+      ],
+      [
+        "tough",
+        43
+      ],
+      [
+        "calvin",
+        43
+      ],
+      [
+        "amazing",
+        41
+      ],
+      [
+        "maria",
+        41
+      ],
+      [
+        "much",
+        39
+      ],
+      [
+        "way",
+        36
+      ],
+      [
+        "since",
+        35
+      ],
+      [
+        "something",
+        35
+      ],
+      [
+        "audrey",
+        34
+      ],
+      [
+        "help",
+        32
+      ],
+      [
+        "fun",
+        32
+      ],
+      [
+        "tim",
+        31
+      ]
+    ]
+  },
+  "m0_baseline": {
+    "n": 500,
+    "hit@1": 60.6,
+    "hit@5": 74.4,
+    "hit@10": 81.2,
+    "mrr": 0.6716
+  },
+  "reproducibility": {
+    "third_party_C": {
+      "hit@1": 60.0,
+      "hit@5": 74.4,
+      "hit@10": 81.0
+    },
+    "m0": {
+      "n": 500,
+      "hit@1": 60.6,
+      "hit@5": 74.4,
+      "hit@10": 81.2,
+      "mrr": 0.6716
+    },
+    "delta_pp": {
+      "hit@1": 0.6,
+      "hit@5": 0.0,
+      "hit@10": 0.2
+    },
+    "verdict": "hit@5 逐位一致；hit@1/hit@10 差 3/1 题（0.6/0.2pp）在噪声级",
+    "attribution": "本仓侧归因面已三重排除：①51d3426(第三方被测基线)后 en_normalizer/mdcg 零变更；②corpus567/questions500 自创建零变更；③本机四 PYTHONHASHSEED 复跑逐位一致（排序确定）。偏差指向第三方环境（clone 批次/Python 版本），非本仓归因面"
+  },
+  "m2_disambiguated": {
+    "n": 500,
+    "hit@1": 61.2,
+    "hit@5": 75.8,
+    "hit@10": 82.2,
+    "mrr": 0.681
+  },
+  "m2_delta": {
+    "hit@1": 0.6,
+    "hit@5": 1.4,
+    "hit@10": 1.0
+  }
+}

package/docs/{ → hive/}/350/234/202/345/267/242/345/267/245/344/275/234/350/256/260/345/277/206_/351/241/271/347/233/256/350/256/241/345/210/222.md

@@ -3,7 +3,7 @@
 > **本文件是工作记忆项目的唯一记忆状态源。** 设计决策、边界、进度都记在这里；
 > 任何会话接手，先读本文件。实现本体：`hive/wm.py`（v0.1）。
 
-- 创建：2026-09-14 · 状态：**v0.1 已落地（测试全绿）**
+- 创建：2026-09-14 · 状态：**v0.1 已落地（测试全绿）；进展面 + 换人续跑交接已落地（2026-09-16）**
 - 缘起：与 zcode 端讨论定稿——工作记忆补上蜂巢缺的两块：上下文（worker 间共享可演进的产物状态，不再冷启动）与任务能力（写入→修改→提交→回退的任务循环）。
 - 理论定位：git「提交=不可变快照，回退=回到提交点」与 swarm v0.7 WAL 快照、langgraph checkpoint 三处同构——多智能体系统的普适件。五单元落位：工作记忆=记录单元的任务级形态（全：版本史不丢）；提交闸=验证单元的资格闸（写入≠提交）；回退=维生单元的恢复手段；diff 审查=反思单元的操作面。另落第五处：子代理零写权限、主代理唯一合并入口（与命名治理记忆协议同原则）。
 
@@ -21,7 +21,7 @@
 
 - 分支命名 `task/<job_id>`；job_id 取 result.json 的 `job_id` 字段，缺失用目录名。
 - **物理隔离 = job 目录本身**（蜂巢天然工作区）：worker 的写权限被结构性限制在自己的 job 目录内（位置效应落码），worker 全程不碰 git。
-- 工作记忆仓只收**产物白名单快照**：`spec.json + result.json`（必须）+ `log.txt`（可选）+ `--artifacts`（可选，逗号分隔）。
+- 工作记忆仓只收**产物白名单快照**：`spec.json + result.json`（必须）+ `progress.jsonl`（可选，进展卡——worker 侧零 git 依赖写入的交接面，见 §3）+ `log.txt`（可选）+ `--artifacts`（可选，逗号分隔）。
 - snapshot/merge 是**主代理串行操作面**（非 worker 并发面）：合并冲突处理权归主代理，wm 对冲突诚实报错（`conflict:true` + hint），绝不自动解决。
 
 ### ③ 提交语义分级：写入 → 提交 → 合并，闸在中间
@@ -51,16 +51,28 @@ python hive\wm.py merge    --branch task\<id> --wm DIR                 :: 主代
 python hive\wm.py log      --wm DIR [--branch B] [--limit N]
 python hive\wm.py revert   --commit SHA --wm DIR                       :: 免费回退
 python hive\wm.py status   --wm DIR
+python hive\wm.py progress --job hive\jobs\<id> [--limit 50]           :: 读进展卡（未快照）
+python hive\wm.py progress --wm DIR --job-id <id> [--limit 50]          :: 读进展卡（已快照，两级查找）
 ```
 
 默认仓位置：`hive/wm-repo/`（运行态，已 gitignore）；`HIVE_WM_DIR` 可覆盖。
 输出统一单行 JSON（对齐 hive CLI 风格）；`wm-repo` 内 `jobs/<job_id>/` 即产物快照树。
 
+**`progress` 读取面（v0.4 §5.3 换人续跑落地，2026-09-16）**：worker 在自家 job 目录写
+`progress.jsonl`（`start`/`tool`/`final`/`handoff`/`error` 逐条），**全程零 git 依赖**——
+符合「worker 无 git 面」的结构约束；进展卡由主代理在 `snapshot` 时纳白名单入库。
+已快照 job 的卡只存在于 `task/<job_id>` 分支（snapshot 后 HEAD 归还 `main`），
+故 `--wm` 源走**两级查找**：先工作区，落空再 `git show task/<ID>:jobs/<ID>/progress.jsonl`，
+返回体 `source`（`job`/`worktree`/`wm_branch`）与 `ref` 标明读取出处；卡缺失如实报缺不伪造。
+坏行跳过不炸（诚实降级）；`handoff`/`auto_continue` 透出交回信号，**续跑裁决权在主代理，
+本命令不自动续跑**（`auto_continue` 恒 `false`）。
+
 ## 4. 首个真实用例与进度
 
 | 事项 | 状态 |
 |---|---|
 | v0.1 三级闸实现 + 全流程测试（凭证闸/分支契约/冲突诚实/revert/CLI 冒烟） | **全绿** |
+| 进展面（progress.jsonl 纳白名单 + `progress` 读取命令 + 分支态两级查找） | **全绿**（`hive/test_wm_progress.py` 44 断言） |
 | 命名治理批次 0（10 job）结果合并 → 首个真实 snapshot 用例 | 等 DeepSeek key |
 | HMAC 签名（swarm 七元组口径）+ 远端私有仓推送 | 待办（第 14 条双清单前置） |
 | B 路纯 std 对象存储（摆脱 git 依赖） | 后路，不排期 |