@furongjun1999/dsh-memory 0.4.7 → 0.4.8

package/md_cg/mreview/rules/duplication.json

@@ -0,0 +1,21 @@
+{
+  "spec_version": 1,
+  "domain": "duplication",
+  "rules": [
+    {
+      "id": "R-DUP-HASH-GROUP",
+      "title": "包内内容指纹重复",
+      "severity": "HIGH",
+      "matcher": {},
+      "mechanical": [{"check": "dup_hash_group", "issue_kind": "dup_content"}],
+      "llm": [
+        {
+          "check": "merge_or_keep",
+          "question": "同指纹成员是否应合并为一个节点（保留最新、其余合并计数）？给出可合并子集与理由；若属刻意的多副本（不同 session/分支）则说明保留理由。",
+          "expect": "可合并子集 或 保留理由"
+        }
+      ],
+      "remedy": "合并（merge；受保护节点须剔除）"
+    }
+  ]
+}

package/md_cg/mreview/rules/field_coverage.json

@@ -0,0 +1,54 @@
+{
+  "spec_version": 1,
+  "domain": "field_coverage",
+  "rules": [
+    {
+      "id": "R-ROLE-MISSING",
+      "title": "knowledge 节点缺 role 归属",
+      "severity": "WARN",
+      "matcher": {"layer": ["knowledge"]},
+      "mechanical": [{"check": "field_absent", "field": "role", "issue_kind": "missing_field"}],
+      "llm": [
+        {
+          "check": "role_inferable",
+          "question": "该节点能否从 writer/tags/正文确定 role（user/agent/tool/system/command 等）？能则给出 role 值，不能则 UNKNOWN。只输出 role 判定，不改写正文。",
+          "expect": "role 取值 或 UNKNOWN"
+        }
+      ],
+      "remedy": "按 writer/tags 回填 role（backfill，M4 由 designer 终裁）"
+    },
+    {
+      "id": "R-EVIDENCE-ZERO",
+      "title": "knowledge 节点无验证证据计数",
+      "severity": "WARN",
+      "matcher": {"layer": ["knowledge"]},
+      "mechanical": [{"check": "evidence_zero", "issue_kind": "missing_field"}],
+      "llm": [
+        {
+          "check": "evidence_sufficient",
+          "question": "verification_basis 与正文四要素是否已自足（不依赖 evidence_count 也能复核）？给出 SUFFICIENT 或 NEEDS_EVIDENCE 与理由。",
+          "expect": "SUFFICIENT 或 NEEDS_EVIDENCE"
+        }
+      ],
+      "remedy": "回填 evidence_count 或降权（backfill / demote）"
+    },
+    {
+      "id": "R-BASIS-MISSING",
+      "title": "节点缺验证基底（无法判定验证档）",
+      "severity": "WARN",
+      "matcher": {},
+      "mechanical": [{"check": "field_absent", "field": "verification_basis", "issue_kind": "missing_field"}],
+      "llm": [],
+      "remedy": "补 verification_basis（backfill；逃逸口 other 供『分析过但无法归类』）"
+    },
+    {
+      "id": "R-BASIS-RATIO-PACKAGE",
+      "title": "包内基底覆盖率过低（包级对照片段）",
+      "severity": "INFO",
+      "matcher": {},
+      "mechanical": [{"check": "field_ratio_below", "field": "verification_basis", "ratio": 0.9}],
+      "llm": [],
+      "remedy": "整包回填（backfill，需人工裁决）"
+    }
+  ]
+}

package/md_cg/mreview/rules/source_license.json

@@ -0,0 +1,21 @@
+{
+  "spec_version": 1,
+  "domain": "source_license",
+  "rules": [
+    {
+      "id": "R-BASIS-LICENSE",
+      "title": "赛道与验证基底不相容（来源执照）",
+      "severity": "HIGH",
+      "matcher": {},
+      "mechanical": [{"check": "basis_licensed", "issue_kind": "weak_source"}],
+      "llm": [
+        {
+          "check": "basis_replace",
+          "question": "该节点基底与赛道不相容：应替换为相容基底、降级还是移层？给出裁决与理由（允许基底见 evidence 字段）。",
+          "expect": "替换基底 或 降权 或 移层"
+        }
+      ],
+      "remedy": "替换基底 / 降权 / 移层（backfill / demote / move_layer）"
+    }
+  ]
+}

package/md_cg/mreview/rules/template_flow.json

@@ -0,0 +1,21 @@
+{
+  "spec_version": 1,
+  "domain": "template_flow",
+  "rules": [
+    {
+      "id": "R-TEMPLATE-FLOW",
+      "title": "同模板流水（去数字骨架相同）",
+      "severity": "INFO",
+      "matcher": {},
+      "mechanical": [{"check": "template_flow_digits_only", "issue_kind": "template_flow"}],
+      "llm": [
+        {
+          "check": "batch_summary_candidate",
+          "question": "这些同模板条目是否应合并为一个『批次汇总』节点（保留可追溯信息与关键差异）？给出结论与理由。",
+          "expect": "MERGE_TO_SUMMARY 或 KEEP_AS_IS"
+        }
+      ],
+      "remedy": "合并为批次汇总节点（merge，样本一次裁决整组）"
+    }
+  ]
+}

package/md_cg/mreview/ruleset.py

@@ -0,0 +1,238 @@
+# -*- coding: utf-8 -*-
+"""记忆评审流水线 · 级 3：D3 规则装配（确定性，零写入）。
+
+真源：docs/记忆评审系统_立项设计与施工交接_20260915.md §3 第 3 级 + §5 D3。
+
+**规则全落数据文件**（`rules/*.json`）——新增/调整规则**零代码改动**（Ghidra G2 吸收件：
+把「规则」与「引擎」解耦，规则库可增删而引擎冻结）。引擎只提供**机械检查器注册表**：
+
+==================== ==========================================================
+检查器                语义（确定性、纯输入、可复算）
+==================== ==========================================================
+field_absent          条目字段为空 → 逐条 issue
+evidence_zero         evidence_count==0 → 逐条 issue
+field_ratio_below     包级字段覆盖率低于阈值 → 一条包级 issue
+dup_hash_group        包内同 content_hash → 除首条外逐条 issue
+template_flow_digits_only  包内正文骨架相同（只换数字）→ 除首条外逐条 issue
+basis_licensed        来源执照——赛道与验证基底不相容（复用 crosscheck 判据）
+==================== ==========================================================
+
+机械检查在蜂巢 job **之前**本地跑完：LLM 只看机械无法裁决的语义问题（token 经济 + 可复算）。
+规则 matcher 语义：`layer` / `tags_any` 表示「包内存在该类条目」→ 规则入包，
+检查执行时按同一条件**过滤到该类条目**（绝不跨层套用）。
+"""
+from __future__ import annotations
+
+import collections
+import json
+import os
+
+from .. import crosscheck as CC
+from .. import writelimit as WL
+
+RULES_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), "rules")
+SEVERITIES = ("INFO", "WARN", "HIGH")
+_BLANK = (None, "", "None", "[]", "{}")
+
+
+def _blank(v) -> bool:
+    if isinstance(v, (list, tuple, dict)):
+        return not v
+    return v is None or str(v).strip() in ("", "None")
+
+
+def _as_int(v) -> int:
+    try:
+        return int(v)
+    except (TypeError, ValueError):
+        return 0
+
+
+def _issue(entry, rule, kind, field, evidence, severity=None) -> dict:
+    return {"ref": entry.get("ref"), "node_id": entry.get("node_id"),
+            "field": field, "issue_kind": kind, "evidence": evidence,
+            "rule_id": rule["id"], "severity": severity or rule.get("severity") or "WARN"}
+
+
+# ---------------------------- 机械检查器注册表 ----------------------------
+
+def _chk_field_absent(entries, spec, rule):
+    field = spec.get("field")
+    return [_issue(e, rule, spec.get("issue_kind") or "missing_field", field,
+                   "字段 %s 为空" % field) for e in entries if _blank(e.get(field))]
+
+
+def _chk_evidence_zero(entries, spec, rule):
+    return [_issue(e, rule, spec.get("issue_kind") or "missing_field", "evidence_count",
+                   "evidence_count=0（无验证证据计数）")
+            for e in entries if _as_int(e.get("evidence_count")) == 0]
+
+
+def _chk_field_ratio_below(entries, spec, rule):
+    field, thr = spec.get("field"), float(spec.get("ratio", 1.0))
+    ratio = sum(1 for e in entries if not _blank(e.get(field))) / max(len(entries), 1)
+    if ratio >= thr:
+        return []
+    return [{"ref": None, "node_id": None, "field": field, "issue_kind": "package_ratio",
+             "evidence": "包内 %s 覆盖率 %.3f < %.3f（%d 条）" % (field, ratio, thr, len(entries)),
+             "rule_id": rule["id"], "severity": rule.get("severity") or "INFO"}]
+
+
+def _chk_dup_hash_group(entries, spec, rule):
+    seen, out = {}, []
+    for e in entries:
+        h = str(e.get("content_hash") or "")
+        if _blank(h) or h == "None":
+            continue
+        if h in seen:
+            out.append(_issue(e, rule, "dup_content", "content_hash",
+                              "同包内与 %s 同指纹 %s" % (seen[h], h)))
+        else:
+            seen[h] = e.get("ref")
+    return out
+
+
+def _chk_template_flow(entries, spec, rule):
+    seen, out = {}, []
+    for e in entries:
+        sk = WL._skeleton(e.get("excerpt") or "")
+        if not sk or len(sk) < WL.MIN_SKELETON:
+            continue
+        if sk in seen:
+            out.append(_issue(e, rule, "template_flow", "content",
+                              "同模板流水（去数字骨架与 %s 相同）：%s" % (seen[sk], sk[:40])))
+        else:
+            seen[sk] = e.get("ref")
+    return out
+
+
+def _chk_basis_licensed(entries, spec, rule):
+    out = []
+    for e in entries:
+        basis = e.get("verification_basis")
+        if _blank(basis):
+            continue
+        fm = {"layer": e.get("layer"), "tags": e.get("tags") or []}
+        track = CC.classify_track(fm, e.get("excerpt") or "")
+        if not CC.basis_licensed(track, basis):
+            out.append(_issue(e, rule, "weak_source", "verification_basis",
+                              "赛道 %s（政策 %s）不允许基底 %s；允许 %s"
+                              % (track, CC.source_policy(track), basis,
+                                 "/".join(CC.allowed_basis(track)))))
+    return out
+
+
+MECH_CHECKS = {
+    "field_absent": _chk_field_absent,
+    "evidence_zero": _chk_evidence_zero,
+    "field_ratio_below": _chk_field_ratio_below,
+    "dup_hash_group": _chk_dup_hash_group,
+    "template_flow_digits_only": _chk_template_flow,
+    "basis_licensed": _chk_basis_licensed,
+}
+
+
+# ---------------------------- 规则库加载 ----------------------------
+
+def load_rules(rules_dir=None) -> dict:
+    """读 `rules/*.json`。格式非法/字段缺失/id 重复 → 抛 ValueError（不静默降级）。"""
+    d = rules_dir or RULES_DIR
+    files = sorted(f for f in os.listdir(d) if f.endswith(".json")) if os.path.isdir(d) else []
+    rules, ids = [], {}
+    for fn in files:
+        with open(os.path.join(d, fn), encoding="utf-8") as f:
+            doc = json.load(f)
+        for r in doc.get("rules") or []:
+            miss = [k for k in ("id", "matcher", "severity") if k not in r]
+            if miss:
+                raise ValueError("规则库 %s：规则缺字段 %s（%s）" % (fn, miss, r.get("id")))
+            if r["severity"] not in SEVERITIES:
+                raise ValueError("规则库 %s：severity=%s 非法（%s）" % (fn, r["severity"], r["id"]))
+            if r["id"] in ids:
+                raise ValueError("规则 id 重复：%s（%s / %s）" % (r["id"], ids[r["id"]], fn))
+            ids[r["id"]] = fn
+            for spec in list(r.get("mechanical") or []):
+                if spec.get("check") not in MECH_CHECKS:
+                    raise ValueError("规则库 %s：未知机械检查 %s（%s）"
+                                     % (fn, spec.get("check"), r["id"]))
+            rules.append(r)
+    return {"rules_dir": d, "files": files, "rules": rules, "count": len(rules)}
+
+
+def _match(rule, ctx) -> tuple:
+    """matcher 语义：包内**存在**该类条目即入包（执行时按同条件过滤）。"""
+    m = rule.get("matcher") or {}
+    if m.get("layer") and not (ctx["layers"] & set(m["layer"])):
+        return False, "包内无 %s 层条目" % "/".join(m["layer"])
+    if m.get("tags_any") and not (ctx["tag_prefixes"] & set(m["tags_any"])):
+        return False, "包内无 %s 标签" % "/".join(m["tags_any"])
+    return True, "matcher 命中"
+
+
+def _scope(entries, rule) -> list:
+    m = rule.get("matcher") or {}
+    if m.get("layer"):
+        want = set(m["layer"])
+        return [e for e in entries if str(e.get("layer")) in want]
+    return list(entries)
+
+
+def _as_rules(rules, rules_dir=None) -> list:
+    """规则入参防呆：None→读规则库；{"rules":[...]}→取内层；列表→原样。
+
+    仿 cg/stg「op 必填」防呆：传错形态时给出明确入口，而非静默 AttributeError。
+    """
+    if rules is None:
+        return load_rules(rules_dir)["rules"]
+    if isinstance(rules, dict):
+        if "rules" not in rules:
+            raise ValueError("规则入参 dict 缺少 rules 键（应为规则列表或 load_rules 结果）")
+        return list(rules.get("rules") or [])
+    return list(rules)
+
+
+def assemble(pkg: dict, *, rules=None, rules_dir=None) -> dict:
+    """单个待评包 → 规则集 + 机械检查结果 + 待 LLM 检查清单。"""
+    rl = _as_rules(rules, rules_dir)
+    entries = pkg.get("entries") or []
+    ctx = {"layers": {str(e.get("layer") or "") for e in entries},
+           "tag_prefixes": {str(t).split(":", 1)[0] for e in entries
+                            for t in (e.get("tags") or [])}}
+    matched, mech, llm = [], [], []
+    for rule in rl:
+        ok, why = _match(rule, ctx)
+        if not ok:
+            continue
+        scoped = _scope(entries, rule)
+        matched.append({"id": rule["id"], "title": rule.get("title"),
+                        "severity": rule.get("severity"), "why": why,
+                        "scope": len(scoped), "remedy": rule.get("remedy")})
+        for spec in rule.get("mechanical") or []:
+            mech += MECH_CHECKS[spec["check"]](scoped, spec, rule)
+        for spec in rule.get("llm") or []:
+            llm.append({"rule_id": rule["id"], "check": spec.get("check"),
+                        "question": spec.get("question"),
+                        "expect": spec.get("expect"),
+                        "scope_refs": [e.get("ref") for e in scoped][:200]})
+    cnt = collections.Counter(i["issue_kind"] for i in mech)
+    return {"bundle_id": pkg.get("bundle_id"), "group_kind": pkg.get("group_kind"),
+            "group_key": pkg.get("group_key"), "size": len(entries),
+            "matched": matched, "mechanical": mech, "llm": llm,
+            "mechanical_by_kind": dict(cnt),
+            "mechanical_flagged": len({i.get("ref") for i in mech if i.get("ref")})}
+
+
+def assemble_all(result: dict, *, rules=None, rules_dir=None) -> dict:
+    """全部包装配 + 汇总（包级统计供 M2 spec 与 M4 量化复跑）。"""
+    rl = _as_rules(rules, rules_dir)
+    out = [assemble(p, rules=rl) for p in result.get("bundles") or []]
+    kinds = collections.Counter()
+    for a in out:
+        kinds.update(a["mechanical_by_kind"])
+    return {"packages": out, "stats": {
+        "bundles": len(out),
+        "mechanical_total": sum(len(a["mechanical"]) for a in out),
+        "mechanical_by_kind": dict(kinds),
+        "llm_checks": sum(len(a["llm"]) for a in out),
+        "rules": [r["id"] for r in rl]},
+        "bundles_input": result.get("stats")}

package/md_cg/nodefile.py

@@ -37,6 +37,7 @@ CCG 要素的语义对应（白箱第 1 篇第 17 章）：
 拿 `observation_position` 单槽加前缀冒充，等于把坐标的一维当成整条生效条件。
 故 CCG_REQUIRED == CCG_MARKS：6 行缺一不可，缺则补写、或按 q-3 判 BLINDSPOT。
 """
+import hashlib
 import json
 import time
 
@@ -48,6 +49,27 @@ CCG_MARKS = ("功能名", "生效条件", "子功能", "执行", "验证方式",
 # 见 `condition_space_text`）——生效条件必须由 condition_space 四槽合成显式声明，
 # 不存在「常用条件默认省略」的合法情形。缺它即缺证据：补写，或判 BLINDSPOT。
 CCG_REQUIRED = CCG_MARKS
+
+# ---- 裁定 B（使用者 2026-09-16）：六要素的契约角色（术语真源） -----------------
+# 六要素不是注释/描述，而是**接口契约**——每行在契约里有一个确定角色：
+#     功能名 = 签名 signature（可执行入口符号）
+#     生效条件 = 前置条件 precondition（由 condition_space 四槽合成，唯一入口）
+#     子功能 = 依赖 dependency
+#     执行 = 调用 invocation
+#     验证方式 = 后置条件 postcondition + test
+#     不适用条件 = 拒绝域 rejection_domain
+# 「生效条件」的契约角色正是 **precondition**——这与其「不可隐含、必须四槽合成」
+# 的既有硬约束同源：缺前置条件的接口无法判定可否调用，故缺参即编译错误。
+# 本常量是术语的**唯一真源**；其余模块（如 ccgc.CONTRACT_ROLES）一律引用本处，
+# 禁止各自再定义一份，防「术语双写法」漂移。
+CCG_CONTRACT_ROLES = {
+    "功能名":     "签名 signature（可执行入口符号）",
+    "生效条件":   "前置条件 precondition",
+    "子功能":     "依赖 dependency",
+    "执行":       "调用 invocation",
+    "验证方式":   "后置条件 postcondition + test",
+    "不适用条件": "拒绝域 rejection_domain",
+}
 # 外部验证基底的可取值（frontmatter.verification_basis）
 #
 # 分两档（口径：文科宽松、理科严格）：
@@ -64,6 +86,22 @@ REPRODUCIBLE_BASIS = ("compiler", "test", "measurement", "formal_proof", "data")
 CONSISTENCY_BASIS = ("textbook", "public_kb")
 
 
+def content_hash(content: str) -> str:
+    """节点正文的**内容指纹**（sha256 前 12 位）——全仓唯一实现。
+
+    两处共用且必须逐位一致，否则对账/变更探测会永远"匹配成功"而失去意义
+    （与 `codeindex.region_hash` 同一纪律：两侧各写一份哈希算法，漂移就悄悄失效）：
+      ① 索引快照 `_index.json` 的 `content_hash`（变更探测）；
+      ② 写入两段式（`twophase`）的 intent 载荷指纹——崩溃后靠它回答
+         「那笔写入到底落盘了没有」。
+
+    口径：只哈希**正文**，不含 frontmatter——frontmatter 会被写路径正常改写
+    （importance / protected / 生命周期状态 / 时间戳），把它算进去则「内容没变、
+    元数据变了」也会判成不匹配，对账会大面积误报 interrupted。
+    """
+    return hashlib.sha256((content or "").encode("utf-8")).hexdigest()[:12]
+
+
 def dumps(frontmatter: dict, content: str) -> str:
     lines = [_DELIM]
     for k in sorted(frontmatter):

package/md_cg/predict.py

@@ -428,10 +428,18 @@ def predictability(blindspot):
 def anchor_from_description(cg, description):
     """盲区描述 → 锚点节点（检索器打分，与 AEIS 的 LIKE→坐标回退同构）。
 
-    只取**首个可用候选**：按标签/层过滤掉推断脚手架（`gap_hint`/`scene`）与
-    负记忆（`unresolved`/`rejected`），其余按检索名次顺延。过滤理由见上方常量注释。
-    候选全被过滤时返回 None（等价「无锚点」），由调用方按 no_anchor 处理，
-    而不是硬凑一个不可起推的节点。
+    择锚规则：候选池内**可起推者优先**——出边非空是路线生成的必要条件，无出边的
+    节点只能靠语义回退硬凑路线，起点语义即失真。**全部不可起推时才降级**为首个合格
+    候选（诚实降级：宁可标注锚点弱，不假装有锚）。
+    动机（实测）：同分并列时检索序不可依赖——「正题节点」与其「同名+近义描述」变体
+    词法分可完全相同（各自都为 1.0），纯按检索名次取首位会漂到无出边的近义变体上。
+
+    过滤与择锚分两关：先按标签/层过滤掉推断脚手架（`gap_hint`/`scene`）与负记忆
+    （`unresolved`/`rejected`），再在剩余候选里按**可起推资格**择优——出边非空者
+    立即采纳，无出边者记为降级候选继续后看，全池无可起推者才降级取首个合格候选。
+    候选全被过滤时返回 None（等价「无锚点」），由调用方按 no_anchor 处理。
+    邻接表不可用（chain 取表异常）时退回「取首个合格候选」——辅助判据故障不应
+    让整条预测链失效（兜底优先于择优）。
     """
     q = str(description or "").strip()
     if not q:
@@ -440,6 +448,12 @@ def anchor_from_description(cg, description):
         results, _meta = cg.search(q, k=ANCHOR_FETCH_K, record=False, judge=False)
     except Exception:
         return None
+    try:
+        from . import chain
+        out_edges = chain.adjacency(cg)
+    except Exception:
+        out_edges = None
+    fallback = None
     for item in results:
         nd = item[0] if isinstance(item, (tuple, list)) else item
         if not isinstance(nd, dict):
@@ -459,8 +473,12 @@ def anchor_from_description(cg, description):
         # 兜底：fs 派生的 id 可能是相对路径（如 unresolved/bs_x.md），归一为裸节点名
         if "/" in str(nid) and str(nid).endswith(".md"):
             nid = os.path.basename(str(nid))[:-3]
-        return nid
-    return None
+        # 可起推资格：出边非空是路线生成的必要条件；不可起推者只作降级候选。
+        if out_edges is None or out_edges.get(nid):
+            return nid
+        if fallback is None:
+            fallback = nid
+    return fallback
 
 
 # ---------------------------------------------------------------- 路线生成

package/md_cg/protect.py

@@ -3,14 +3,14 @@
 
 理论出处（全部来自本仓已有文档，非外部发明）：
 
-  · `docs/灵枢_自我层定义.md:6`
+  · `docs/mdcg/灵枢_自我层定义.md:6`
       SELF 层 = 身份 + 价值观 + 图接口，**不可遗忘**、跨会话自动加载。
       任何实例都能改写自我层 = 自我认知可被任意覆写，与「自我」定义冲突。
-  · `docs/认知图_MD目录方案_v0.1.md:53`
+  · `docs/mdcg/认知图_MD目录方案_v0.1.md:53`
       `anchor/  # 锚点层（不可遗忘，保护）`
-  · `docs/认知图_MD目录方案_v0.1.md:412-416`
+  · `docs/mdcg/认知图_MD目录方案_v0.1.md:412-416`
       「importance 提升（保护：不可遗忘记入 anchor/ 且**受保护标记**）」
-  · `docs/tool_table_v0.3.0.md:15`
+  · `docs/mdcg/tool_table_v0.3.0.md:15`
       「importance_hint 可显式提示重要性（**≥0.7 触发不可遗忘保护**）」
 
 三层保护（任一命中即受保护）：

package/md_cg/refindex.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 """md_cg · 统一 ref 协议 + 索引水位（增量）+ 漂移/悬空巡检
 
-对照 `docs/认知图_索引与工程规范化_计划_v0.1.md` 的 R3（修 D + 修 F）：
+对照 `docs/mdcg/认知图_索引与工程规范化_计划_v0.1.md` 的 R3（修 D + 修 F）：
 
 **D 漂移 / 悬空检测（本模块 `check_refs`）**
   扫描带 `code_ref` / `doc_ref` 的节点，回两类问题：
@@ -598,6 +598,25 @@ def _forget_many(cg, plan, why: str) -> tuple:
     return done, blocked
 
 
+def _drop_ghosts(cg, ghosts) -> list:
+    """摘除幽灵条目的索引记录（节点文件已不存在，没有可软删的实体）。
+
+    走 `MdCG._unstage`：它顺带落删除记录，保证幽灵不会再次从分片日志里复活。
+    基础层没有该能力时如实返回空列表（不假装成功）。
+    """
+    drop = getattr(cg, "_unstage", None)
+    if not callable(drop):
+        return []
+    out = []
+    for nid in ghosts:
+        try:
+            drop(nid)
+            out.append(nid)
+        except Exception:                 # 单条失败不拖垮整批
+            continue
+    return out
+
+
 def prune_orphans(cg, *, kind: str, root: str, items, dry_run: bool = False,
                   reason: str = "") -> dict:
     """清退「同 root + 同 path，但已不在本次产出里」的**过期代**节点。
@@ -663,8 +682,23 @@ def prune_dangling(cg, *, only_roots=None, dry_run: bool = False,
     `check_refs` 只报告不处置（其原话是「悬空需人工处置」），本函数就是那个
     出口——已删脚本、被搬走的文档留下的残留节点一次清掉，而不是逐条手工
     `forget`。判定与巡检共用 `probe_ref` 的唯一实现，口径不会打架。
+
+    另清**幽灵条目**（ghosts）：索引有条目、节点文件却不存在。它们是历史
+    「删除只摘内存索引、不落盘」的遗留——`cg.get` 取不回 → 悬空清退够不着它，
+    而 `check_refs` 走 ledger 会一直报 → dangling 永不归零。判据只用唯一真源
+    （节点 .md 不存在即脏索引），与「索引是派生物」的宣言一致；`only_roots`
+    非空时跳过（幽灵条目无 ref，无法归因到某个源大域）。
     """
     nodes = (getattr(cg, "index", {}) or {}).get("nodes") or {}
+    ghosts = []
+    if not only_roots:
+        for nid, e in list(nodes.items()):
+            tags = (e or {}).get("tags") or []
+            if not any(t in ("code", "doc") for t in tags):
+                continue
+            path = (e or {}).get("path") or ""
+            if path and not os.path.exists(os.path.join(cg.root, path)):
+                ghosts.append(nid)
     # 同 prune_orphans：ref 只在节点 frontmatter 里，索引条目里没有，
     # 必须 cg.get 取回节点再 ref_of（否则恒空、静默不删）。
     todo = []
@@ -684,7 +718,7 @@ def prune_dangling(cg, *, only_roots=None, dry_run: bool = False,
         if only_roots and not any(_same_root(ref.get("root"), r) for r in only_roots):
             continue
         todo.append((nid, ref))
-    truncated = len(todo) > max_nodes
+    truncated = len(todo) > max_nodes or len(ghosts) > max_nodes
     plan = []
     for nid, ref in todo[:max_nodes]:
         try:
@@ -695,14 +729,19 @@ def prune_dangling(cg, *, only_roots=None, dry_run: bool = False,
 
     why = reason or ("源文件已删除，索引节点悬空（回读必然失败），"
                      "清退以消除永不消失的 dangling")
+    ghost_plan = sorted(ghosts)[:max_nodes]
     base = {"scanned": len(nodes), "candidates": len(plan),
+            "ghosts": len(ghost_plan),
             "dry_run": bool(dry_run), "truncated": truncated,
             "max_nodes": max_nodes}
     if dry_run:
         return {**base, "ok": True, "count": len(plan), "pruned": sorted(plan)[:50],
+                "ghost_pruned": ghost_plan[:50],
                 "skipped_protected": [], "reason": why}
     done, blocked = _forget_many(cg, plan, why)
+    dropped = _drop_ghosts(cg, ghost_plan)
     return {**base, "ok": True, "count": len(done), "pruned": done[:50],
+            "ghost_pruned": dropped[:50],
             "skipped_protected": blocked[:20], "reason": why}
 
 

package/md_cg/scrub.py

@@ -622,7 +622,11 @@ def decontaminate(cg, node_ids=None, *, kinds=None, dry_run: bool = True,
                 fm = _fm_of(cg, nid, None)
                 if str(fm.get("layer") or "") != "contextual":
                     cg._move_layer(nid, "contextual", reason=f"scrub:{kind}")
-                    done.append("demote")
+                    # 层降级 = 生命周期降级（②）：状态同批推进（负路由，失败不抛）
+                    _st = cg.set_state(nid, "demoted", reason=f"scrub:{kind}",
+                                       actor=actor or "scrub")
+                    done.append("demote" if _st.get("ok") else
+                                f"demote_state:{_st.get('error')}")
             except Exception as exc:                      # noqa: BLE001
                 done.append(f"demote_failed:{type(exc).__name__}")
         n_applied += 1

package/md_cg/self_state.py

@@ -2,7 +2,7 @@
 """md_cg · 自我状态层（SELF STATE）：薄自我 + 富索引
 
 理论约束（本仓已有文档，非外部发明）：
-  · `docs/灵枢_自我层定义.md:6`
+  · `docs/mdcg/灵枢_自我层定义.md:6`
       SELF 层 = 身份 + 价值观 + 图接口，**不可遗忘**、跨会话自动加载。
       自我层是**薄的**——它不该变成事件仓库。
   · 智能论 §十一：情绪 = 信息差二阶 d^2D/dt^2；§十：P_gap / P_trust；