eduevidence 6.2.0 → 6.3.0

package/schemas/v2/intake.schema.json

@@ -0,0 +1,191 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://eduevidence.dev/schemas/v2/intake.schema.json",
+  "title": "Intake",
+  "description": "One-shot two-round user intake for a run: research question, execution enhancements, depth, optional enhancement mappings, Frame boundary hints, and wrap-up confirmation. User answers only mode and questions; the agent infers the rest. Non-question preferences live in ~/.eduevidence/prefs.json (see definitions.Prefs) and never record the research question. All five report themes stay rendered; default_main_theme only selects which one to open.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "research_question",
+    "enhancements",
+    "depth",
+    "summary_confirmed"
+  ],
+  "properties": {
+    "schema_version": { "type": "integer", "minimum": 1 },
+    "research_question": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Canonical research question collected in round 1. Stored on the run, never in prefs."
+    },
+    "enhancements": {
+      "type": "array",
+      "description": "Execution enhancements selected in round 1. Use [\"none\"] when the user enables nothing.",
+      "items": {
+        "type": "string",
+        "enum": ["agent_mcp", "jev", "semdecide", "none"]
+      },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "depth": {
+      "type": "string",
+      "enum": ["S", "M", "L"],
+      "description": "Resolved complexity depth after auto rules (S quick check / M standard / L deep)."
+    },
+    "depth_choice": {
+      "type": "string",
+      "enum": ["S", "M", "L", "auto"],
+      "description": "What the user picked in round 1. auto means the agent applies the depth guideline."
+    },
+    "depth_rationale": {
+      "type": "string",
+      "description": "Why depth resolved to S/M/L (auto guideline or explicit choice)."
+    },
+    "mcp": {
+      "type": ["object", "null"],
+      "description": "Round-2 Agent MCP block. Present only when agent_mcp is selected.",
+      "additionalProperties": false,
+      "properties": {
+        "authorized": { "type": "boolean" },
+        "role_mapping": {
+          "type": "object",
+          "description": "role -> {cli, model} authorization table confirmed by the user.",
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": ["cli", "model"],
+            "properties": {
+              "cli": { "type": "string", "minLength": 1 },
+              "model": { "type": "string", "minLength": 1 }
+            }
+          }
+        },
+        "note": { "type": "string" }
+      }
+    },
+    "jev": {
+      "type": ["object", "null"],
+      "description": "Round-2 Jev block. Present only when jev is selected.",
+      "additionalProperties": false,
+      "properties": {
+        "tool_subset": {
+          "type": "array",
+          "items": { "type": "string", "minLength": 1 },
+          "uniqueItems": true
+        },
+        "note": { "type": "string" }
+      }
+    },
+    "semdecide": {
+      "type": ["object", "null"],
+      "description": "Round-2 SemDecide block. Present only when semdecide is selected.",
+      "additionalProperties": false,
+      "properties": {
+        "purpose": { "type": "string", "minLength": 1 },
+        "note": { "type": "string" }
+      }
+    },
+    "frame_hints": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Background deep-dive boundary hints (population / intervention / comparison / primary_outcome / context). Inferred values are proposals only; unknown fields stay absent (never fabricated).",
+      "properties": {
+        "population": { "type": "string" },
+        "intervention": { "type": "string" },
+        "comparison": { "type": "string" },
+        "primary_outcome": { "type": "string" },
+        "context": { "type": "string" },
+        "domain": { "type": "string" },
+        "confirmed": { "type": "boolean" }
+      }
+    },
+    "summary_confirmed": {
+      "type": "boolean",
+      "description": "Wrap-up summary accepted once; the run then continues unattended."
+    },
+    "open_browser": {
+      "type": "boolean",
+      "description": "Whether to open the main report in a browser when the run finishes."
+    },
+    "default_main_theme": {
+      "type": "string",
+      "enum": ["claude", "academic", "datalab", "datalab-dark", "presentation"],
+      "description": "Which of the five baked themes to open as the main report. All five remain rendered."
+    },
+    "interactive": { "type": "boolean" },
+    "prefs_path": {
+      "type": "string",
+      "description": "Absolute path of the prefs file written for this intake (never contains the research question)."
+    },
+    "source": {
+      "type": "string",
+      "enum": ["interactive", "silent", "yes_flag", "prefs"]
+    }
+  },
+  "definitions": {
+    "Prefs": {
+      "title": "Prefs",
+      "description": "Durable non-question preferences at ~/.eduevidence/prefs.json. Never store a research question here.",
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "schema_version": { "type": "integer", "minimum": 1 },
+        "enhancement": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["agent_mcp", "jev", "semdecide", "none"]
+          },
+          "uniqueItems": true
+        },
+        "mcp": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "role_mapping": {
+              "type": "object",
+              "additionalProperties": {
+                "type": "object",
+                "additionalProperties": false,
+                "required": ["cli", "model"],
+                "properties": {
+                  "cli": { "type": "string", "minLength": 1 },
+                  "model": { "type": "string", "minLength": 1 }
+                }
+              }
+            }
+          }
+        },
+        "jev": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "tool_subset": {
+              "type": "array",
+              "items": { "type": "string", "minLength": 1 },
+              "uniqueItems": true
+            }
+          }
+        },
+        "semdecide": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "purpose": { "type": "string" }
+          }
+        },
+        "depth_preference": {
+          "type": "string",
+          "enum": ["S", "M", "L", "auto"]
+        },
+        "open_browser": { "type": "boolean" },
+        "default_main_theme": {
+          "type": "string",
+          "enum": ["claude", "academic", "datalab", "datalab-dark", "presentation"]
+        }
+      }
+    }
+  }
+}

package/scripts/build_evidence_library.py

@@ -17,9 +17,15 @@ schemas/v4/evidence-library.schema.json using the repo's zero-dependency
 validator (scripts/validate_schema.py).
 
 Direction semantics (adoption-relevant, conservative):
-  support    -> evidence favors adopting the intervention  (=> pilot)
-  contradict -> evidence opposes adopting the intervention (=> reject)
+  support    -> evidence favors adopting the intervention
+                (offline screening cap => pilot; never adopt)
+  contradict -> evidence opposes adopting the intervention
+                (oppose-only => reject; mixed with support is an unresolved
+                conflict and must fall to INSUFFICIENT_EVIDENCE via
+                engine.decision_policy.decision_outcome)
   neutral    -> inconclusive
+The library never emits adopt: full ADOPT is decided only by
+engine.decision_policy.decision_outcome (High + support + direct primary).
 For gold units the coarse rule is: if a question's expected decision range is
 purely reject-oriented ("reject" present and "pilot" absent), its
 key_claims/key_supporting_sources are harmful evidence => contradict, and its
@@ -266,10 +272,14 @@ def build(generated_at: str | None = None) -> tuple[dict[str, Any], int]:
             "key_claims/key_supporting_sources/known_contradictions/correct_outcome_types）"
             "+ 3 个示例工作流 evidence.jsonl（ai-coding-assistant / ai-tutor / ai-writing-assistant）"
             "抽取生成；按 (source_id, outcome_token, claim_text) 去重合并。"
-            "direction 语义为采纳方向：support=支持采纳（初步裁决=>pilot），"
-            "contradict=反对采纳（=>reject），neutral=中性；金标准条目按 expected_decision_range "
+            "direction 语义为采纳方向：support=支持采纳（离线初筛上限 => pilot，永不输出 adopt），"
+            "contradict=反对采纳（oppose-only 时 => reject；与 support 并存属未决冲突，应交 "
+            "engine.decision_policy.decision_outcome 判为 INSUFFICIENT_EVIDENCE），neutral=中性；"
+            "金标准条目按 expected_decision_range "
             "粗粒度映射方向（纯 reject 问题反向映射），conflict 与混合方向问题的单条断言方向可能不精确。"
-            "仅用于离线初步裁决（preliminary，保守），从不直接给出 adopt。"
+            "仅用于离线初步裁决（preliminary，保守），从不直接给出 adopt；"
+            "完整 ADOPT 只能由 engine.decision_policy.decision_outcome 给出"
+            "（High + support + 主要结果 directness 2）。"
         ),
     }
     _validate(library)

package/scripts/dashboard_server.py

@@ -524,7 +524,8 @@ class StudioHandler(http.server.SimpleHTTPRequestHandler):
         self._send_report_bytes(html_path.read_bytes())
 
 
-def run_dashboard_server(host: str = "127.0.0.1", port: int = 8765) -> None:
+def run_dashboard_server(host: str = "127.0.0.1", port: int = 8765,
+                         open_browser: bool = False) -> None:
     server = None
     actual_port = port
     for offset in range(10):
@@ -541,12 +542,20 @@ def run_dashboard_server(host: str = "127.0.0.1", port: int = 8765) -> None:
     if server is None:
         print(f"❌ 端口 {port}-{port + 9} 均被占用。")
         return
+    studio_url = f"http://{host}:{actual_port}/studio/"
     print("============================================================")
     print(f"🚀 EduEvidence Web Studio running at http://{host}:{actual_port}/")
     print("   Research Studio  /studio/  (read-only)")
     print("   Projects, evidence, revisions and five-theme reports")
     print("   Projection API   /api/studio/catalog")
     print("============================================================")
+    if open_browser:
+        try:
+            import webbrowser
+            webbrowser.open(studio_url)
+            print(f"🌐 opened {studio_url}")
+        except Exception as exc:  # pragma: no cover - browser may be absent
+            print(f"⚠️  failed to open browser: {exc}")
     try:
         server.serve_forever()
     except KeyboardInterrupt:
@@ -557,8 +566,10 @@ def main() -> None:
     parser = argparse.ArgumentParser()
     parser.add_argument("--host", default="127.0.0.1")
     parser.add_argument("--port", type=int, default=8765)
+    parser.add_argument("--open", action="store_true",
+                        help="open the Studio URL in the system browser once the server is up")
     args = parser.parse_args()
-    run_dashboard_server(args.host, args.port)
+    run_dashboard_server(args.host, args.port, open_browser=args.open)
 
 
 if __name__ == "__main__":

package/scripts/intake/__init__.py

@@ -0,0 +1,31 @@
+"""intake — one-shot two-round user intake + durable prefs + report open."""
+from __future__ import annotations
+
+from .browser import (
+    maybe_open_after_run,
+    open_report,
+    open_url,
+    resolve_main_report,
+)
+from .constants import (
+    DEPTH_CHOICES,
+    ENHANCEMENTS,
+    ENHANCEMENT_BLURBS,
+    DEPTH_BLURBS,
+    FRAME_SLOTS,
+    THEME_NAMES,
+)
+from .depth import auto_resolve_depth, resolve_depth
+from .background import infer_frame_hints
+from .prefs import default_prefs, load_prefs, prefs_path, save_prefs
+from .prompts import PROMPT_SCRIPT
+from .session import run_intake
+
+__all__ = [
+    "DEPTH_BLURBS", "DEPTH_CHOICES", "ENHANCEMENTS", "ENHANCEMENT_BLURBS",
+    "FRAME_SLOTS", "PROMPT_SCRIPT", "THEME_NAMES",
+    "auto_resolve_depth", "default_prefs", "infer_frame_hints",
+    "load_prefs", "maybe_open_after_run", "open_report", "open_url",
+    "prefs_path", "resolve_depth", "resolve_main_report", "run_intake",
+    "save_prefs",
+]

package/scripts/intake/__main__.py

@@ -0,0 +1,18 @@
+"""python -m intake — CLI entry."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+# Allow `python scripts/intake/__main__.py` without installing the package.
+if __package__ in (None, ""):
+    sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from intake.cli import main  # noqa: E402
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except ValueError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        raise SystemExit(2) from exc

package/scripts/intake/background.py

@@ -0,0 +1,78 @@
+"""Frame skeleton inference + 3–6 boundary questions (never fabricate)."""
+from __future__ import annotations
+
+import re
+from typing import Any, Callable
+
+from .constants import (
+    CONTEXT_CUES,
+    FRAME_SLOTS,
+    OUTCOME_CUES,
+    POP_CUES,
+    SLOT_LABELS,
+)
+from .prompts import ask, ask_yes
+
+
+def infer_frame_hints(question: str, domain: str = "education") -> dict[str, Any]:
+    """Propose Frame boundary hints from the question text only.
+
+    Anything not stated in the question stays absent. Never fabricate.
+    """
+    hints: dict[str, Any] = {"domain": domain, "confirmed": False}
+    text = question or ""
+    low = text.lower()
+    for cue in POP_CUES:
+        if cue.lower() in low:
+            hints["population"] = cue
+            break
+    for cue in OUTCOME_CUES:
+        if cue.lower() in low:
+            hints["primary_outcome"] = cue
+            break
+    for cue in CONTEXT_CUES:
+        if cue in text or cue.lower() in low:
+            hints["context"] = cue
+            break
+    m = re.search(r"(AI[\w\s一-鿿]{0,20}(?:工具|助手|tutor|copilot|编程)|"
+                  r"(?:翻转|项目式|同伴)教学|AI\s*编程助手)", text, re.I)
+    if m:
+        hints["intervention"] = m.group(0).strip()
+    if re.search(r"是否|影响|对比|比较|vs|与.*比|是否允许|该不该", text):
+        hints["comparison"] = "business as usual / 未使用该干预的常规做法"
+    return hints
+
+
+def boundary_questions(inferred: dict[str, Any]) -> list[tuple[str, str, str | None]]:
+    """3–6 boundary questions: (slot, prompt, default)."""
+    questions: list[tuple[str, str, str | None]] = []
+    for slot in FRAME_SLOTS:
+        questions.append((slot, f"  · {SLOT_LABELS[slot]}", inferred.get(slot)))
+    return questions[:6]
+
+
+def collect_frame_hints(question: str, *, domain: str = "education",
+                        interactive: bool,
+                        printer: Callable[[str], None] = print) -> dict[str, Any]:
+    """Infer skeleton; when interactive, ask 3–6 boundary Qs + one confirm."""
+    inferred = infer_frame_hints(question, domain=domain)
+    frame_hints = dict(inferred)
+    if not interactive:
+        frame_hints["confirmed"] = False
+        return frame_hints
+
+    printer("—— 背景智能深挖（Frame 边界，智能默认 + 一次确认；缺失不编造）——")
+    printer(f"  领域骨架：{domain}")
+    for slot, prompt, default in boundary_questions(inferred):
+        label = default if default is not None else "（未从题目推出，留空）"
+        raw = ask(prompt, label if default is not None else "")
+        if raw and not raw.startswith("（"):
+            frame_hints[slot] = raw
+        elif default is not None:
+            frame_hints[slot] = default
+        # else: leave absent — never fabricate
+    printer("  Frame 边界摘要：")
+    for slot in FRAME_SLOTS:
+        printer(f"    {slot}: {frame_hints.get(slot) or '—'}")
+    frame_hints["confirmed"] = ask_yes("  确认以上边界？(Y/n)", True)
+    return frame_hints

package/scripts/intake/browser.py

@@ -0,0 +1,79 @@
+"""Main-report resolution and optional system-browser open."""
+from __future__ import annotations
+
+import webbrowser
+from pathlib import Path
+
+from .constants import THEME_NAMES
+from .prefs import load_prefs
+from .prompts import is_interactive
+
+
+def resolve_main_report(directory: Path | str, theme: str | None = None) -> Path | None:
+    """Pick the main report file. All five themes stay on disk.
+
+    Preference order:
+      reports-5themes/EduEvidence_Report_<theme>.html
+      reports-5themes/EduEvidence_Report_claude.html
+      report.html
+      EduEvidence_Report.html
+    """
+    root = Path(directory)
+    if not root.is_dir():
+        return None
+    theme = theme if theme in THEME_NAMES else "claude"
+    variants = root / "reports-5themes"
+    candidates = [
+        variants / f"EduEvidence_Report_{theme}.html",
+        variants / "EduEvidence_Report_claude.html",
+        root / "report.html",
+        root / "EduEvidence_Report.html",
+    ]
+    for path in candidates:
+        if path.is_file() and path.stat().st_size > 2:
+            return path
+    return None
+
+
+def open_report(directory: Path | str, theme: str | None = None,
+                *, force: bool = False) -> bool:
+    """Open the preferred main report in the system browser.
+
+    Only opens when `force` or prefs.open_browser is set. The caller should
+    also suppress this on non-TTY if silent behaviour is required.
+    """
+    prefs = load_prefs()
+    if not force and not prefs.get("open_browser", True):
+        return False
+    path = resolve_main_report(directory, theme or prefs.get("default_main_theme"))
+    if path is None:
+        return False
+    try:
+        webbrowser.open(path.resolve().as_uri())
+    except Exception:
+        return False
+    return True
+
+
+def open_url(url: str, *, force: bool = False) -> bool:
+    prefs = load_prefs()
+    if not force and not prefs.get("open_browser", True):
+        return False
+    try:
+        webbrowser.open(url)
+    except Exception:
+        return False
+    return True
+
+
+def maybe_open_after_run(run_dir: Path | str, *, theme: str | None = None,
+                         interactive: bool | None = None) -> bool:
+    """End-of-run auto-open. Silent on non-TTY so tests stay quiet."""
+    if interactive is None:
+        interactive = is_interactive()
+    if not interactive:
+        return False
+    prefs = load_prefs()
+    if not prefs.get("open_browser", True):
+        return False
+    return open_report(run_dir, theme or prefs.get("default_main_theme"), force=True)

package/scripts/intake/cli.py

@@ -0,0 +1,57 @@
+"""CLI for the one-shot two-round intake."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .constants import DEPTH_CHOICES, ENHANCEMENTS
+from .prefs import load_prefs
+from .prompts import PROMPT_SCRIPT
+from .session import run_intake
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="EduEvidence two-round intake")
+    parser.add_argument("--question", default=None, help="research question")
+    parser.add_argument("--depth", default=None,
+                        choices=list(DEPTH_CHOICES) + ["quick", "standard", "deep"],
+                        help="S/M/L/auto (or legacy quick/standard/deep)")
+    parser.add_argument("--enhancement", action="append", default=None,
+                        choices=list(ENHANCEMENTS),
+                        help="execution enhancement (repeatable)")
+    parser.add_argument("--domain", default="education")
+    parser.add_argument("--yes", action="store_true",
+                        help="skip prompts; use prefs + explicit flags (unattended)")
+    parser.add_argument("--print-prompts", action="store_true",
+                        help="print the fixed two-round prompt script and exit")
+    parser.add_argument("--show-prefs", action="store_true",
+                        help="print current prefs.json and exit")
+    args = parser.parse_args(argv)
+
+    if args.print_prompts:
+        sys.stdout.write(PROMPT_SCRIPT)
+        return 0
+    if args.show_prefs:
+        print(json.dumps(load_prefs(), ensure_ascii=False, indent=2))
+        return 0
+
+    record = run_intake(
+        question=args.question,
+        depth=args.depth,
+        enhancements=args.enhancement,
+        domain=args.domain,
+        assume_yes=args.yes,
+    )
+    print(json.dumps(record, ensure_ascii=False, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    # Documented entry: `python3 -m intake.cli --print-prompts` from scripts/.
+    # Same failure contract as scripts/intake/__main__.py.
+    try:
+        raise SystemExit(main())
+    except ValueError as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        raise SystemExit(2) from exc

package/scripts/intake/constants.py

@@ -0,0 +1,57 @@
+"""Shared constants for the one-shot two-round intake."""
+from __future__ import annotations
+
+SCHEMA_VERSION = 1
+PREFS_NAME = "prefs.json"
+THEME_NAMES = ("claude", "academic", "datalab", "datalab-dark", "presentation")
+ENHANCEMENTS = ("agent_mcp", "jev", "semdecide", "none")
+DEPTH_CHOICES = ("S", "M", "L", "auto")
+DEPTH_ALIASES = {"quick": "S", "standard": "M", "deep": "L"}
+
+# Fixed round-1 labels (mirrored verbatim in skill/workflows/intake.md).
+ENHANCEMENT_BLURBS: dict[str, str] = {
+    "agent_mcp": "Agent MCP — 多 CLI/多模型分工、独立子上下文、超时恢复（可选执行增强）",
+    "jev": "Jev — 轻量工具子集派发，适合把确定性小步交给受限工具面",
+    "semdecide": "SemDecide — 语义决策辅助，只结构化上游意图，不改下游确定性路由",
+    "none": "均不启用 — 平台原生模式，零外部执行增强",
+}
+DEPTH_BLURBS: dict[str, str] = {
+    "S": "S 快检 — 单点问题，最小检索面，直接给边界结论",
+    "M": "M 标准 — 常规采用/比较问题，标准证据到决策流程",
+    "L": "L 深研 — 高影响、有争议或要试点，完整深研与决策扩展",
+    "auto": "自动 — 不选则按指南判定：单点→S，常规采用→M，高影响/争议/要试点→L，不确定取 M",
+}
+
+# Auto-depth guideline keywords (deterministic aid; the agent's judgment wins).
+L_AUTO_SIGNALS = (
+    "试点", "pilot", "高影响", "争议", "全校", "全面部署", "政策",
+    "rollout", "high-stakes", "high stakes",
+)
+S_AUTO_SIGNALS = (
+    "单点", "一句话", "快速", "简要", "是不是", "对不对", "解释一下",
+    "定义", "公式", "quick", "trivial",
+)
+M_AUTO_SIGNALS = (
+    "是否", "有效", "影响", "比较", "对比", "采用", "adopt", "vs",
+    "效果", "evidence", "review",
+)
+
+# Frame boundary slots and light inference cues (never invent; only extract).
+FRAME_SLOTS = ("population", "intervention", "comparison", "primary_outcome", "context")
+POP_CUES = (
+    "大一", "大二", "大三", "大四", "本科", "研究生", "高中", "初中", "小学",
+    "成人", "职业", "CS1", "大学生", "中学生", "小学生", "undergraduate", "K-12",
+)
+OUTCOME_CUES = (
+    "独立编程", "学习效果", "学习保持", "迁移", "学业成绩", "保持", "retention",
+    "transfer", "learning", "成绩", "能力", "依赖", "诚信",
+)
+CONTEXT_CUES = ("线上", "线下", "混合", "小班", "大班", "MOOC", "翻转", "课堂", "实验室")
+
+SLOT_LABELS = {
+    "population": "人群（目标学习者/决策对象）",
+    "intervention": "干预（具体方法/工具及用法）",
+    "comparison": "对照（与什么比较；可用 BAU）",
+    "primary_outcome": "主结果（一个主要结果指标）",
+    "context": "情境（学制/班型/线上线下/支持条件）",
+}

package/scripts/intake/depth.py

@@ -0,0 +1,53 @@
+"""Depth auto guideline: 单点→S，常规采用→M，高影响/争议/要试点→L，不确定取 M."""
+from __future__ import annotations
+
+from typing import Any
+
+from .constants import (
+    DEPTH_ALIASES,
+    DEPTH_CHOICES,
+    L_AUTO_SIGNALS,
+    M_AUTO_SIGNALS,
+    S_AUTO_SIGNALS,
+)
+
+
+def auto_resolve_depth(question: str, hints: dict[str, Any] | None = None) -> tuple[str, str]:
+    text = (question or "").lower()
+    hints = hints or {}
+    blob = " ".join(str(v) for v in hints.values() if isinstance(v, str)).lower()
+    hay = f"{text} {blob}"
+    strong_l = any(k.lower() in hay for k in L_AUTO_SIGNALS)
+    if any(k.lower() in hay for k in S_AUTO_SIGNALS) and not strong_l:
+        return "S", "auto: single-point lookup signal → S"
+    if strong_l:
+        return "L", "auto: high-impact / contested / pilot-or-policy signal → L"
+    if any(k.lower() in hay for k in M_AUTO_SIGNALS):
+        return "M", "auto: routine adoption / comparison signal → M"
+    return "M", "auto: uncertain → M (guideline default)"
+
+
+def resolve_depth(choice: str | None, question: str,
+                  hints: dict[str, Any] | None = None,
+                  prefs: dict[str, Any] | None = None) -> tuple[str, str, str]:
+    """Return (depth_choice, resolved_depth, rationale)."""
+    prefs = prefs or {}
+    if choice is not None:
+        choice = DEPTH_ALIASES.get(str(choice), str(choice))
+    if choice in ("S", "M", "L"):
+        return choice, choice, f"explicit choice {choice}"
+    if choice == "auto":
+        depth, why = auto_resolve_depth(question, hints)
+        return "auto", depth, why
+    pref = prefs.get("depth_preference") or "auto"
+    if pref in ("S", "M", "L"):
+        return pref, pref, f"prefs.depth_preference={pref}"
+    depth, why = auto_resolve_depth(question, hints)
+    return "auto", depth, why
+
+
+def normalize_depth_choice(raw: str | None) -> str | None:
+    if raw is None:
+        return None
+    mapped = DEPTH_ALIASES.get(str(raw), str(raw))
+    return mapped if mapped in DEPTH_CHOICES else raw