eduevidence 6.2.0 → 6.3.0

package/scripts/intake/enhancements.py

@@ -0,0 +1,106 @@
+"""Round-2 enhancement blocks: Agent MCP / Jev / SemDecide."""
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .constants import ENHANCEMENTS
+from .prompts import ask, ask_multi, ask_yes, split_csv
+
+
+def normalize_enhancements(enhancements: list[str] | None) -> list[str]:
+    if not enhancements:
+        return ["none"]
+    alias = {"mcp": "agent_mcp", "agent-mcp": "agent_mcp",
+             "无": "none", "不启用": "none"}
+    out: list[str] = []
+    for e in enhancements:
+        key = alias.get(str(e).strip().lower(), str(e).strip().lower())
+        if key in ENHANCEMENTS and key not in out:
+            out.append(key)
+    if not out:
+        return ["none"]
+    if "none" in out and len(out) > 1:
+        return ["none"]
+    return out
+
+
+def collect_round1_enhancements(*, prefs: dict[str, Any],
+                                enhancements: list[str] | None,
+                                interactive: bool,
+                                printer: Callable[[str], None] = print) -> list[str]:
+    from .constants import ENHANCEMENT_BLURBS
+
+    if interactive and enhancements is None:
+        printer("—— 第一轮 ——")
+        printer("2) 执行增强（可多选）：")
+        for key, blurb in ENHANCEMENT_BLURBS.items():
+            printer(f"    [{key}] {blurb}")
+        default_enh = [e for e in (prefs.get("enhancement") or ["none"])
+                       if e in ENHANCEMENTS] or ["none"]
+        enhancements = ask_multi("请选择增强", ENHANCEMENTS, default_enh)
+    elif enhancements is None:
+        enhancements = list(prefs.get("enhancement") or ["none"])
+    return normalize_enhancements(enhancements)
+
+
+def _collect_mcp(prefs: dict[str, Any], *, interactive: bool,
+                 mcp_table: list[dict[str, str]] | None,
+                 printer: Callable[[str], None]) -> dict[str, Any]:
+    role_mapping: dict[str, Any] = {}
+    if mcp_table:
+        printer("  MCP 角色 → CLI / 模型 授权表：")
+        for row in mcp_table:
+            printer(f"    {row.get('role', '?')} → {row.get('cli', '?')} / {row.get('model', '?')}")
+            if row.get("role") and row.get("cli") and row.get("model"):
+                role_mapping[str(row["role"])] = {
+                    "cli": str(row["cli"]), "model": str(row["model"])}
+    elif (prefs.get("mcp") or {}).get("role_mapping"):
+        role_mapping = dict((prefs.get("mcp") or {}).get("role_mapping") or {})
+        printer("  复用 prefs 中的 MCP 角色映射（可在批准文件中复核）。")
+    authorized = True
+    if interactive and mcp_table:
+        authorized = ask_yes("  采用上述角色→CLI/模型表并授权？(Y/n)", True)
+    elif interactive:
+        authorized = ask_yes("  启用 Agent MCP 增强（角色表将由批准流程生成）？(Y/n)", True)
+    return {"authorized": authorized, "role_mapping": role_mapping,
+            "note": "role table persisted via agent_mcp approval when authorized"}
+
+
+def _collect_jev(prefs: dict[str, Any], *, interactive: bool,
+                 printer: Callable[[str], None]) -> dict[str, Any]:
+    default_tools = list((prefs.get("jev") or {}).get("tool_subset") or
+                         ["search", "fetch", "validate"])
+    tools = default_tools
+    if interactive:
+        printer("  Jev 工具子集（只派发确定性小步；缺省 search/fetch/validate）")
+        tools = split_csv(ask("  工具子集（逗号分隔）", ",".join(default_tools)))
+    return {"tool_subset": tools or default_tools,
+            "note": "Jev dispatch stays limited to this tool subset"}
+
+
+def _collect_sem(interactive: bool, printer: Callable[[str], None]) -> dict[str, Any]:
+    default_purpose = "结构化上游 ResearchIntent / Frame，供 recommend_mode 使用"
+    purpose = default_purpose
+    if interactive:
+        printer("  SemDecide 用途（只结构化上游意图，不改下游确定性路由）")
+        purpose = ask("  用途说明", default_purpose) or default_purpose
+    return {"purpose": purpose,
+            "note": "SemDecide feeds intent only; mode_router stays deterministic"}
+
+
+def collect_round2_enhancements(
+    enhancements: list[str], *, prefs: dict[str, Any], interactive: bool,
+    mcp_table: list[dict[str, str]] | None = None,
+    printer: Callable[[str], None] = print,
+) -> tuple[dict[str, Any] | None, dict[str, Any] | None, dict[str, Any] | None]:
+    """Return (mcp_block, jev_block, sem_block); None when that enhancement is off."""
+    wants_mcp = "agent_mcp" in enhancements
+    wants_jev = "jev" in enhancements
+    wants_sem = "semdecide" in enhancements
+    if interactive and (wants_mcp or wants_jev or wants_sem):
+        printer("—— 第二轮（仅增强相关）——")
+    mcp = _collect_mcp(prefs, interactive=interactive, mcp_table=mcp_table,
+                       printer=printer) if wants_mcp else None
+    jev = _collect_jev(prefs, interactive=interactive, printer=printer) if wants_jev else None
+    sem = _collect_sem(interactive, printer) if wants_sem else None
+    return mcp, jev, sem

package/scripts/intake/hooks.py

@@ -0,0 +1,90 @@
+"""Thin orchestrator hooks: prepare run context, finish with optional open."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Callable
+
+
+from .browser import maybe_open_after_run, resolve_main_report
+from .prompts import is_interactive
+from .session import run_intake
+
+
+def prepare_run(
+    *,
+    question: str,
+    depth: str | None = None,
+    enhancements: list[str] | None = None,
+    domain: str = "education",
+    assume_yes: bool = False,
+    fallback_depth: str = "M",
+) -> dict[str, Any]:
+    """Collect intake (or fall back silently). Return orchestrator inputs.
+
+    Keys: question, depth, enhancements, intake_record, wants_mcp, error.
+    """
+    interactive = (not assume_yes) and is_interactive()
+    try:
+        record = run_intake(
+            question=question,
+            depth=depth,
+            enhancements=enhancements,
+            domain=domain,
+            interactive=interactive,
+            assume_yes=assume_yes,
+        )
+    except ValueError as exc:
+        return {"error": str(exc)}
+    return {
+        "question": record["research_question"],
+        "depth": record["depth"],
+        "enhancements": list(record["enhancements"]),
+        "intake_record": record,
+        "wants_mcp": ("agent_mcp" in record["enhancements"]
+                      and "none" not in record["enhancements"]),
+        "error": None,
+    }
+
+
+def write_intake_artifact(run_dir: Path | str, intake_record: dict[str, Any] | None) -> None:
+    if not intake_record:
+        return
+    _validate_intake_record(intake_record)
+    path = Path(run_dir) / "intake.json"
+    path.write_text(json.dumps(intake_record, ensure_ascii=False, indent=2) + "\n",
+                    encoding="utf-8")
+
+
+def _validate_intake_record(record: dict[str, Any]) -> None:
+    try:
+        import jsonschema
+    except ImportError:
+        return
+    schema_path = (Path(__file__).resolve().parents[2]
+                   / "schemas" / "v2" / "intake.schema.json")
+    if not schema_path.is_file():
+        return
+    schema = json.loads(schema_path.read_text(encoding="utf-8"))
+    try:
+        jsonschema.validate(record, schema)
+    except jsonschema.ValidationError as exc:
+        raise ValueError(f"intake record failed schema validation: {exc.message}") from exc
+
+
+def after_run(
+    run_dir: Path | str,
+    *,
+    intake_record: dict[str, Any] | None,
+    summary: dict[str, Any],
+    printer: Callable[[str], None] = print,
+) -> None:
+    """Open the main report when the run completed and prefs.open_browser is set."""
+    if summary.get("failures") or not summary.get("completed_all"):
+        return
+    theme = (intake_record or {}).get("default_main_theme")
+    if not maybe_open_after_run(run_dir, theme=theme):
+        return
+    report = resolve_main_report(run_dir, theme)
+    if report is not None:
+        printer(f"opened report: {report}")

package/scripts/intake/prefs.py

@@ -0,0 +1,76 @@
+"""Durable non-question prefs at ~/.eduevidence/prefs.json."""
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any
+
+from .constants import DEPTH_CHOICES, PREFS_NAME, SCHEMA_VERSION, THEME_NAMES
+
+
+def prefs_path() -> Path:
+    """~/.eduevidence/prefs.json (EDUEVIDENCE_HOME wins)."""
+    home = Path(os.environ.get("EDUEVIDENCE_HOME", "~/.eduevidence")).expanduser()
+    return home / PREFS_NAME
+
+
+def default_prefs() -> dict[str, Any]:
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "enhancement": ["none"],
+        "mcp": {"role_mapping": {}},
+        "jev": {"tool_subset": []},
+        "semdecide": {"purpose": ""},
+        "depth_preference": "auto",
+        "open_browser": True,
+        "default_main_theme": "claude",
+    }
+
+
+def _sanitize(prefs: dict[str, Any]) -> dict[str, Any]:
+    prefs.pop("question", None)
+    prefs.pop("research_question", None)
+    if prefs.get("default_main_theme") not in THEME_NAMES:
+        prefs["default_main_theme"] = "claude"
+    if prefs.get("depth_preference") not in DEPTH_CHOICES:
+        prefs["depth_preference"] = "auto"
+    enh = prefs.get("enhancement") or ["none"]
+    if "none" in enh and len(enh) > 1:
+        enh = ["none"]
+    prefs["enhancement"] = enh or ["none"]
+    return prefs
+
+
+def load_prefs() -> dict[str, Any]:
+    """Load prefs; missing/corrupt → defaults. Never contains a question."""
+    path = prefs_path()
+    prefs = default_prefs()
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return prefs
+    if not isinstance(data, dict):
+        return prefs
+    for key in ("schema_version", "enhancement", "mcp", "jev", "semdecide",
+                "depth_preference", "open_browser", "default_main_theme"):
+        if key in data:
+            prefs[key] = data[key]
+    return _sanitize(prefs)
+
+
+def save_prefs(prefs: dict[str, Any]) -> Path:
+    """Persist non-question prefs. Refuses to write a question field.
+
+    Atomic write: temp file + os.replace so a crash cannot leave a torn prefs.json.
+    """
+    payload = {k: v for k, v in prefs.items()
+               if k not in ("question", "research_question")}
+    payload.setdefault("schema_version", SCHEMA_VERSION)
+    path = prefs_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(".json.tmp")
+    tmp.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n",
+                   encoding="utf-8")
+    os.replace(tmp, path)
+    return path

package/scripts/intake/prompts.py

@@ -0,0 +1,85 @@
+"""TTY prompt helpers and the fixed two-round prompt script."""
+from __future__ import annotations
+
+import re
+import sys
+
+
+def is_interactive() -> bool:
+    try:
+        return sys.stdin.isatty() and sys.stdout.isatty()
+    except Exception:
+        return False
+
+
+def ask(prompt: str, default: str | None = None) -> str:
+    """Single-line ask; empty input keeps default. Never invents a default."""
+    suffix = f" [{default}]" if default not in (None, "") else ""
+    try:
+        raw = input(f"{prompt}{suffix}: ").strip()
+    except EOFError:
+        return default or ""
+    return raw or (default or "")
+
+
+def ask_yes(prompt: str, default_yes: bool = True) -> bool:
+    default = "Y" if default_yes else "n"
+    ans = ask(prompt, default).lower()
+    return ans not in ("n", "no")
+
+
+def ask_multi(prompt: str, allowed: tuple[str, ...], default: list[str]) -> list[str]:
+    """Comma-separated multi-select against `allowed`."""
+    legend = "/".join(allowed)
+    raw = ask(f"{prompt}（可多选，逗号分隔，{legend}）",
+              ",".join(default) if default else None)
+    if not raw:
+        return list(default) or ["none"]
+    alias = {"mcp": "agent_mcp", "agent-mcp": "agent_mcp",
+             "否": "none", "无": "none", "不启用": "none"}
+    picked: list[str] = []
+    for token in re.split(r"[,，\s]+", raw):
+        t = token.strip().lower()
+        if not t:
+            continue
+        key = alias.get(t, t)
+        if key in allowed and key not in picked:
+            picked.append(key)
+    if not picked:
+        return list(default) or ["none"]
+    if "none" in picked and len(picked) > 1:
+        return ["none"]
+    return picked
+
+
+def split_csv(raw: str) -> list[str]:
+    return [t.strip() for t in re.split(r"[,，\s]+", raw or "") if t.strip()]
+
+
+PROMPT_SCRIPT = """\
+EduEvidence 一次性两轮引导（固定语句，用户只答模式和问题）
+
+—— 第一轮 ——
+1) 研究问题（必填）
+2) 执行增强（可多选，各附一句话简介）：
+   [agent_mcp] Agent MCP — 多 CLI/多模型分工、独立子上下文、超时恢复（可选执行增强）
+   [jev]       Jev — 轻量工具子集派发，适合把确定性小步交给受限工具面
+   [semdecide] SemDecide — 语义决策辅助，只结构化上游意图，不改下游确定性路由
+   [none]      均不启用 — 平台原生模式，零外部执行增强
+3) 深度：
+   [S]    S 快检 — 单点问题，最小检索面，直接给边界结论
+   [M]    M 标准 — 常规采用/比较问题，标准证据到决策流程
+   [L]    L 深研 — 高影响、有争议或要试点，完整深研与决策扩展
+   [auto] 自动 — 单点→S，常规采用→M，高影响/争议/要试点→L，不确定取 M
+
+—— 第二轮（仅增强开启时的增强项；背景深挖始终执行）——
+· Agent MCP 开 → 角色 → CLI / 模型 授权表（只展示已扫描到的真实 CLI/模型）
+· Jev 开 → 工具子集（search / fetch / validate / …）
+· SemDecide 开 → 用途说明（只结构化上游意图）
+· 背景智能深挖：按题目推断领域 Frame 骨架后，针对该题追问 3–6 个影响边界的问题
+  （人群 / 干预 / 对照 / 主结果 / 情境），智能默认 + 一次确认，禁止编造。
+
+—— 收尾 ——
+摘要一次确认后无人值守。prefs 只记 enhancement / mcp·jev 映射 / depth /
+open_browser / default_main_theme，不记研究问题。五主题全渲染，主报告只决定打开哪份。
+"""

package/scripts/intake/session.py

@@ -0,0 +1,152 @@
+"""One-shot two-round intake session (question → mode → confirm → unattended)."""
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from .background import collect_frame_hints
+from .constants import DEPTH_BLURBS, DEPTH_CHOICES, FRAME_SLOTS, SCHEMA_VERSION, THEME_NAMES
+from .depth import normalize_depth_choice, resolve_depth
+from .enhancements import collect_round1_enhancements, collect_round2_enhancements
+from .prefs import load_prefs, prefs_path, save_prefs
+from .prompts import ask, ask_yes, is_interactive
+
+
+def _round1_question(question: str | None, *, interactive: bool) -> str:
+    q = (question or "").strip()
+    if interactive and not q:
+        q = ask("1) 研究问题（必填）")
+    if not q:
+        raise ValueError("research question is required (round 1)")
+    return q
+
+
+def _round1_depth(depth: str | None, *, prefs: dict[str, Any],
+                  interactive: bool,
+                  printer: Callable[[str], None]) -> str | None:
+    depth_choice = normalize_depth_choice(depth)
+    if interactive and depth_choice is None:
+        printer("3) 深度：")
+        for key, blurb in DEPTH_BLURBS.items():
+            printer(f"    [{key}] {blurb}")
+        picked = ask("请选择深度 (S/M/L/auto)", prefs.get("depth_preference") or "auto")
+        depth_choice = picked if picked in DEPTH_CHOICES else "auto"
+    return depth_choice
+
+
+def _wrap_up(*, question: str, enhancements: list[str], depth_resolved: str,
+             depth_why: str, frame_hints: dict[str, Any],
+             open_browser_flag: bool, theme: str, interactive: bool,
+             printer: Callable[[str], None]) -> bool:
+    if not interactive:
+        return True
+    printer("—— 收尾摘要（一次确认后无人值守）——")
+    printer(f"  问题：{question}")
+    printer(f"  增强：{', '.join(enhancements)}")
+    printer(f"  深度：{depth_resolved}（{depth_why}）")
+    printer(f"  边界：{ {k: frame_hints.get(k) for k in FRAME_SLOTS} }")
+    printer(f"  结束后打开报告：{'是' if open_browser_flag else '否'} ｜ 主主题：{theme}")
+    confirmed = ask_yes("  确认并开始无人值守执行？(Y/n)", True)
+    if not confirmed:
+        raise ValueError("intake summary not confirmed; abort before unattended run")
+    return True
+
+
+def _persist_prefs(enhancements: list[str], mcp_block: dict[str, Any] | None,
+                   jev_block: dict[str, Any] | None, sem_block: dict[str, Any] | None,
+                   prefs: dict[str, Any], *, depth_choice: str,
+                   open_browser_flag: bool, theme: str) -> None:
+    next_prefs = {
+        "schema_version": SCHEMA_VERSION,
+        "enhancement": enhancements,
+        "mcp": {"role_mapping": (mcp_block or {}).get("role_mapping")
+                or (prefs.get("mcp") or {}).get("role_mapping") or {}},
+        "jev": {"tool_subset": (jev_block or {}).get("tool_subset")
+                or (prefs.get("jev") or {}).get("tool_subset") or []},
+        "depth_preference": depth_choice,
+        "open_browser": open_browser_flag,
+        "default_main_theme": theme,
+    }
+    if sem_block and sem_block.get("purpose"):
+        next_prefs["semdecide"] = {"purpose": sem_block["purpose"]}
+    save_prefs(next_prefs)
+
+
+def run_intake(
+    question: str | None = None,
+    *,
+    depth: str | None = None,
+    enhancements: list[str] | None = None,
+    domain: str = "education",
+    interactive: bool | None = None,
+    assume_yes: bool = False,
+    open_browser: bool | None = None,
+    default_main_theme: str | None = None,
+    mcp_table: list[dict[str, str]] | None = None,
+    persist_prefs: bool = True,
+    printer: Callable[[str], None] = print,
+) -> dict[str, Any]:
+    """Run the one-shot two-round intake and return a validated intake record.
+
+    - `assume_yes` / non-TTY → silent: prefs + explicit args only, no prompts.
+    - `interactive` forces TTY behaviour (tests can inject `printer` + stdin).
+    - User answers only mode and questions; everything else is inferred with
+      hard no-fabrication rules.
+    """
+    prefs = load_prefs()
+    if interactive is None:
+        interactive = (not assume_yes) and is_interactive()
+
+    q = _round1_question(question, interactive=interactive)
+    enhancements = collect_round1_enhancements(
+        prefs=prefs, enhancements=enhancements,
+        interactive=interactive, printer=printer)
+    depth_choice = _round1_depth(depth, prefs=prefs, interactive=interactive,
+                                 printer=printer)
+
+    mcp_block, jev_block, sem_block = collect_round2_enhancements(
+        enhancements, prefs=prefs, interactive=interactive,
+        mcp_table=mcp_table, printer=printer)
+
+    frame_hints = collect_frame_hints(q, domain=domain, interactive=interactive,
+                                      printer=printer)
+
+    depth_choice, depth_resolved, depth_why = resolve_depth(
+        depth_choice if depth_choice in DEPTH_CHOICES else (depth_choice or None),
+        q, frame_hints, prefs)
+
+    open_browser_flag = (prefs.get("open_browser", True) if open_browser is None
+                         else bool(open_browser))
+    theme = default_main_theme or prefs.get("default_main_theme") or "claude"
+    if theme not in THEME_NAMES:
+        theme = "claude"
+
+    source = "interactive" if interactive else ("yes_flag" if assume_yes else "silent")
+    summary_confirmed = _wrap_up(
+        question=q, enhancements=enhancements, depth_resolved=depth_resolved,
+        depth_why=depth_why, frame_hints=frame_hints,
+        open_browser_flag=open_browser_flag, theme=theme,
+        interactive=interactive, printer=printer)
+
+    record: dict[str, Any] = {
+        "schema_version": SCHEMA_VERSION,
+        "research_question": q,
+        "enhancements": enhancements,
+        "depth": depth_resolved,
+        "depth_choice": depth_choice if depth_choice in DEPTH_CHOICES else "auto",
+        "depth_rationale": depth_why,
+        "mcp": mcp_block,
+        "jev": jev_block,
+        "semdecide": sem_block,
+        "frame_hints": frame_hints,
+        "summary_confirmed": summary_confirmed,
+        "open_browser": open_browser_flag,
+        "default_main_theme": theme,
+        "interactive": bool(interactive),
+        "source": source,
+    }
+    if persist_prefs:
+        _persist_prefs(enhancements, mcp_block, jev_block, sem_block, prefs,
+                       depth_choice=record["depth_choice"],
+                       open_browser_flag=open_browser_flag, theme=theme)
+        record["prefs_path"] = str(prefs_path())
+    return record

package/scripts/lint_file_layers.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""scripts/lint_file_layers.py — file-layer hard gate.
+
+Scans engine/ scripts/ integrations/ skill/ visualization/eduevidence-report/scripts/
+for *.py *.js *.ts and enforces:
+
+  * single file > 300 lines → ERROR (monument / legacy → WARNING only)
+  * new / moved files must be ≤ 300 lines (not eligible for whitelists)
+  * new / moved files must be ≤ 300 lines (not eligible for the whitelist)
+
+Monument whitelist = build_report.py, orchestrator.py, agent_mcp.py,
+pre_verdict_gate.py, living.py, evidence_graph.py. Anything else over the
+budget is an ERROR unless monument/legacy WARNING. Exit 1 on any ERROR.
+
+Usage:
+    python3 scripts/lint_file_layers.py
+Exit code 1 when any ERROR.
+"""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent
+
+MAX_LINES = 300
+
+SCAN_ROOTS = (
+    "engine",
+    "scripts",
+    "integrations",
+    "skill",
+    "visualization/eduevidence-report/scripts",
+)
+
+# Historical monument whitelist — WARNING only (not ERROR).
+# ONLY these six pre-split giants are grandfathered. New or moved files
+# MUST NOT be added here — keep them ≤ MAX_LINES instead.
+MONUMENT_BASENAMES = {
+    "build_report.py",
+    "orchestrator.py",
+    "agent_mcp.py",
+    "pre_verdict_gate.py",
+    "living.py",
+    "evidence_graph.py",
+}
+
+# Pre-existing large files (before the layering gate). WARNING only.
+# New/moved files must never be added here — keep them ≤ MAX_LINES.
+LEGACY_LARGE_BASENAMES = {
+    "analysis.py", "core.py", "runner.py", "graph_store.py", "library_builtin.py",
+    "meta_analysis.py", "migration.py", "orchestration.py", "pilot.py",
+    "studio_read_model.py", "tribunal.py", "benchmark_evaluator.py",
+    "benchmark_judge.py", "benchmark_v2.py", "benchmark_v3.py",
+    "build_esl_artifacts.py", "build_evidence_library.py", "build_result.py",
+    "check_protocol_alignment.py", "dashboard_server.py",
+    "enrich_projects_human_and_lieflat.py", "generate_new_projects.py",
+    "render_report_html.py", "research_auto_cli.py", "run_workspace.py",
+    "test_adversarial_empirical.py", "build_figures.py", "charts_data.py",
+    "lieflat_engine.py", "zh_labels.py", "library.py",
+}
+
+EXTS = {".py", ".js", ".ts"}
+SKIP_DIRS = {"__pycache__", "node_modules", ".git", ".venv", "venv"}
+
+
+def _iter_sources() -> list[Path]:
+    found: list[Path] = []
+    for root_name in SCAN_ROOTS:
+        root = ROOT / root_name
+        if not root.is_dir():
+            continue
+        for path in sorted(root.rglob("*")):
+            if not path.is_file() or path.suffix not in EXTS:
+                continue
+            if any(part in SKIP_DIRS for part in path.parts):
+                continue
+            found.append(path)
+    return found
+
+
+def check_file_layers() -> tuple[list[str], list[str]]:
+    """Return (errors, warnings)."""
+    errors: list[str] = []
+    warnings: list[str] = []
+    for path in _iter_sources():
+        rel = path.relative_to(ROOT).as_posix()
+        try:
+            n = sum(1 for _ in path.open(encoding="utf-8", errors="replace"))
+        except OSError as exc:
+            errors.append(f"{rel}: unreadable ({exc})")
+            continue
+        if n <= MAX_LINES:
+            continue
+        msg = f"{rel}: {n} lines > {MAX_LINES}"
+        if path.name in MONUMENT_BASENAMES:
+            warnings.append(
+                f"{msg} (monument whitelist — WARNING only; split when touched)")
+        elif path.name in LEGACY_LARGE_BASENAMES:
+            warnings.append(
+                f"{msg} (legacy large file — WARNING only; split when touched)")
+        else:
+            errors.append(
+                f"{msg} (not on monument whitelist; new/moved must be ≤ {MAX_LINES})")
+    return errors, warnings
+
+
+def main() -> int:
+    print("[*] Running file-layer hard gate "
+          f"(max {MAX_LINES} lines; monuments+legacy WARNING only: "
+          f"{', '.join(sorted(MONUMENT_BASENAMES))})...")
+    errors, warnings = check_file_layers()
+    for w in warnings:
+        print(f"    ! {w}")
+    if errors:
+        print(f"[-] File-layer lint FAILED with {len(errors)} error(s):",
+              file=sys.stderr)
+        for e in errors:
+            print(f"    • {e}", file=sys.stderr)
+        return 1
+    print(f"[+] File-layer lint PASSED: {len(warnings)} monument warning(s), 0 error(s).")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())