task-ledger 1.2.9 → 1.3.1

package/scripts/ledgerkit/actions/query_history.py

@@ -0,0 +1,173 @@
+"""只读：查已结案（按结案时间过滤，倒序取最近）。不写任何字节、不依赖格式升级。
+
+时间区间一律落在**结案时间** `finished` 上 —— 历史文件本来就按结案月归档
+（`history/<结案年月>.md`），按创建时间过滤会漏掉「上月建、本月结」的记录。
+"""
+
+from __future__ import annotations
+
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+from ..core import history_md
+from ..core.identity import Identity, normalize
+from ..core.paths import HISTORY_DIR, LEGACY_HISTORY_REL, month_of, to_repo_rel
+from ..core.time import now, time_key
+from ..errors import Fail
+from ..store.history_store import HistoryStore
+from .query import COUNT_CAP, HistoryQuery
+from .result import HistoryResult, rel
+
+#: 一次最多读多少个历史文件（按月分文件；不区分连续 / 分散，只数总数）。
+MAX_HISTORY_FILES = 13
+#: 没给任何时间参数时，默认只看最近几个自然月。
+DEFAULT_HISTORY_MONTHS = 3
+
+
+def _recent_month_keys(count: int) -> list[str]:
+    """最近 count 个自然月的月份键（含当月），按当前 UTC 推，从新到旧。"""
+    stamp = now()
+    year, month = int(stamp[0:4]), int(stamp[5:7])
+    keys: list[str] = []
+    for _ in range(max(count, 0)):
+        keys.append(f"{year:04d}{month:02d}")
+        month -= 1
+        if month == 0:
+            year, month = year - 1, 12
+    return keys
+
+
+def _shift_month(ym: str, delta: int) -> str:
+    """`YYYYMM` 偏移 delta 个月；越过年份边界自动进位 / 借位。"""
+    idx = int(ym[0:4]) * 12 + (int(ym[4:6]) - 1) + delta
+    return f"{idx // 12:04d}{idx % 12 + 1:02d}"
+
+
+def _month_keys_between(lo_ym: str, hi_ym: str) -> list[str]:
+    """`[lo_ym, hi_ym]` 闭区间内的月份键（升序）；两端给反了也能兜住。"""
+    if lo_ym > hi_ym:
+        lo_ym, hi_ym = hi_ym, lo_ym
+    keys: list[str] = []
+    cur = lo_ym
+    while cur <= hi_ym:
+        keys.append(cur)
+        cur = _shift_month(cur, 1)
+    return keys
+
+
+def _month_end(ym: str) -> str:
+    """`YYYYMM` 所在月的最后一秒（`YYYY-MM-DD HH:MM:SS`），用于把老平铺文件也框进区间。"""
+    year, month = int(ym[0:4]), int(ym[4:6])
+    nxt = datetime(year + (1 if month == 12 else 0), (month % 12) + 1, 1)
+    return (nxt - timedelta(seconds=1)).strftime("%Y-%m-%d %H:%M:%S")
+
+
+def _target_month_keys(q: HistoryQuery) -> list[str]:
+    """由时间参数算出「要读的月份键」；超过上限直接 Fail（不碰磁盘）。
+
+    - 无任何时间参数 ⇒ 最近 `DEFAULT_HISTORY_MONTHS` 个自然月；
+    - `--months N` ⇒ 最近 N 个自然月（与 `--since/--until` 互斥）；
+    - `--since/--until` ⇒ 结案月区间（只给一端时，另一端按默认口径补齐）。
+    """
+    if q.months is not None and (q.since or q.until):
+        raise Fail("--months 与 --since/--until 不能同时用（时间口径二选一）。")
+    if q.months is not None:
+        if q.months < 1:
+            raise Fail("--months 至少为 1。")
+        keys = _recent_month_keys(q.months)
+    elif q.since or q.until:
+        if q.since:
+            lo = month_of(q.since)
+        elif q.until:
+            # 只给 --until：往前补到默认窗口（与「默认近 3 月」一致）
+            lo = _shift_month(month_of(q.until), -(DEFAULT_HISTORY_MONTHS - 1))
+        else:  # pragma: no cover - 上面已保证至少给了一个
+            raise Fail("--since/--until 至少要给一个。")
+        hi = month_of(q.until) if q.until else month_of(now())
+        if not lo or not hi:
+            raise Fail("--since/--until 时间格式不对，算不出月份。")
+        keys = _month_keys_between(lo, hi)
+    else:
+        keys = _recent_month_keys(DEFAULT_HISTORY_MONTHS)
+    # 上限卡的是「要读的文件总数」，不是月跨度：按月分文件，一个键一个文件；
+    # 连不连续、将来把多段时间拼在一起也都只数总数。
+    files = sorted(set(keys))
+    if len(files) > MAX_HISTORY_FILES:
+        raise Fail(
+            f"历史查询一次最多读 {MAX_HISTORY_FILES} 个历史文件（按月分文件，不区分连续/分散），"
+            f"本次要读 {len(files)} 个 ⇒ 缩小 --since/--until 或 --months。"
+        )
+    return files
+
+
+def _candidate_paths(repo: Path, keys: list[str]) -> list[Path]:
+    """按月键【直接拼】`history/<年月>.md`（不扫磁盘）；存量平铺文件按固定路径顺带一看。"""
+    paths = [repo / to_repo_rel(HISTORY_DIR / f"{ym}.md") for ym in keys]
+    paths.append(repo / to_repo_rel(LEGACY_HISTORY_REL))
+    return paths
+
+
+def query_history(repo: Path, me: Identity, q: HistoryQuery) -> HistoryResult:
+    """`--owner` / `--mine` 一律**精确相等**（不做前缀 / 子串）；`--since` / `--until` 比 `finished`（结案时间）。"""
+    keys = _target_month_keys(q)
+    store = HistoryStore(repo)
+    records: list[dict[str, Any]] = []
+    warnings: list[str] = []
+    for path in _candidate_paths(repo, keys):
+        if not path.is_file():
+            continue  # 该月无记录 / 老平铺文件不存在 ⇒ 跳过，不报错
+        rows, warns = history_md.parse_history(store.read(path))
+        warnings.extend(f"{rel(repo, path)}：{w}" for w in warns)
+        for row in rows:
+            row = dict(row)
+            row["src"] = rel(repo, path)
+            row["created"] = time_key(row.get("created") or "") or row.get("created")
+            row["finished"] = time_key(row.get("finished") or "") or row.get("finished")
+            records.append(row)
+
+    if q.mine:
+        wanted = {k for k in (me.email, *me.aliases) if k}
+        wanted = {normalize(k) for k in wanted}
+        records = [r for r in records if normalize(r.get("owner") or "") in wanted]
+    elif q.owner:
+        key = normalize(q.owner)
+        records = [r for r in records if normalize(r.get("owner") or "") == key]
+    if q.category:
+        records = [r for r in records if (r.get("category") or "") == q.category]
+    if q.tag:
+        records = [r for r in records if q.tag in (r.get("tags") or ())]
+
+    # 有效结案区间：显式 --since/--until 优先（精确到秒），缺的一端用月份窗口补，
+    # 这样老平铺文件里的行也会被同一条规则框住，不会在月份查询里「漏网」。
+    lo_key, hi_key = min(keys), max(keys)
+    eff_since = q.since or f"{lo_key[0:4]}-{lo_key[4:6]}-01 00:00:00"
+    eff_until = q.until or _month_end(hi_key)
+    records = [r for r in records if (r.get("finished") or "") >= eff_since]
+    records = [r for r in records if (r.get("finished") or "") <= eff_until]
+
+    records.sort(key=lambda r: str(r.get("finished") or ""), reverse=True)
+    capped = False
+    if q.count_only and len(records) > COUNT_CAP:
+        capped = True
+        records = records[:COUNT_CAP]
+    elif q.limit:
+        records = records[: int(q.limit)]
+
+    filters = {
+        "owner": q.owner,
+        "mine": q.mine,
+        "category": q.category,
+        "tag": q.tag,
+        "since": q.since,
+        "until": q.until,
+        "limit": q.limit,
+        "months": q.months,
+    }
+    return HistoryResult(
+        count=len(records),
+        filters=filters,
+        records=tuple(records),
+        warnings=tuple(warnings),
+        capped=capped,
+    )

package/scripts/ledgerkit/actions/registry.py

@@ -0,0 +1,82 @@
+"""动作名册：命令写法 → `ActionSpec`。只有 `shell/cli.py` 与 `shell/runner.py` 会 import 它。
+
+**渲染函数只存名字**，不 import `shell/render.py` —— 否则 actions → shell 的依赖就反了；
+由 runner 用 `getattr(render, spec.render)` 取到函数。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+
+from ..errors import Fail
+from . import (
+    bootstrap,
+    claim,
+    close_task,
+    list_tasks,
+    log_progress,
+    new_task,
+    query_history,
+    set_task,
+    show_task,
+    validate,
+)
+
+
+@dataclass(frozen=True)
+class ActionSpec:
+    func: Callable  # (repo, me, **params) -> Result | 视图对象
+    render: str  # 渲染函数**名**；runner 用 getattr 取
+    readonly: bool = False
+    lock_action: str = ""  # 交给 lock_scope 的动作名；默认同命令名
+    params: tuple[str, ...] = field(default=())  # 从参数里挑哪些键传给 func
+
+
+ACTIONS: dict[str, ActionSpec] = {
+    "new": ActionSpec(
+        new_task.new_task,
+        "result",
+        params=("title", "tid", "created", "category", "tags", "mine"),
+    ),
+    "claim": ActionSpec(claim.claim, "result", params=("tid",)),
+    "set": ActionSpec(
+        set_task.set_task,
+        "result",
+        params=("tid", "owner"),
+        lock_action="set",
+    ),
+    "log": ActionSpec(log_progress.log_progress, "result", params=("tid", "note")),
+    "close": ActionSpec(
+        close_task.close_task,
+        "result",
+        params=("tid", "summary", "finished", "category", "tags"),
+    ),
+    "list": ActionSpec(
+        list_tasks.list_tasks, "list_view", readonly=True, params=("q",)
+    ),
+    "show": ActionSpec(
+        show_task.show_task, "show_view", readonly=True, params=("tid",)
+    ),
+    "history": ActionSpec(
+        query_history.query_history, "history_view", readonly=True, params=("q",)
+    ),
+    "validate": ActionSpec(
+        validate.validate, "validate_view", readonly=True, params=("deep",)
+    ),
+}
+
+READONLY = tuple(name for name, spec in ACTIONS.items() if spec.readonly)
+
+
+def spec_of(command: str) -> ActionSpec:
+    """按命令写法取名册项；不在名册里就是用法错（业务错，退 1 人话）。"""
+    spec = ACTIONS.get(command)
+    if spec is None:
+        raise Fail(f"未知命令：{command}")
+    return spec
+
+
+def bootstrap_func():
+    """自举不是名册里的命令（runner 单独调），这里只给它的入口，避免 shell 直接 import 动作。"""
+    return bootstrap.bootstrap

package/scripts/ledgerkit/actions/release.py

@@ -0,0 +1,51 @@
+"""释放：写回公共池，再删我分片那行，再记一笔。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..core.identity import Identity
+from ..core.paths import POOL_REL, shard_rel
+from ..core.time import now
+from ..core.worklog_md import exec_line
+from ..errors import Fail
+from ..store.task_store import TaskStore
+from ..store.worklog_store import WorklogStore
+from .result import Result, rel
+
+
+def release(repo: Path, me: Identity, tid: str) -> Result:
+    """写序：写回池（已有同号就不覆盖）→ 删我分片那行 → 过程文档记一笔。"""
+    pool = TaskStore(repo, POOL_REL)
+    mine = TaskStore(repo, shard_rel(me.email), identity=me)
+    task = mine.get(tid)  # 锁内重读
+    if task is None:
+        if pool.get(tid) is not None:
+            return Result(
+                already_done=True,
+                where=rel(repo, pool.path),
+                notices=(f"任务 {tid} 已经在公共池里，无需重复释放。",),
+            )
+        raise Fail(f"任务 {tid} 不在我的分片里，也没在公共池里。")
+
+    back = dict(task)
+    back["owner"] = None
+    back["status"] = "open"
+    back["updated"] = now()
+    if pool.get(tid) is None:
+        pool.put(tid, back)
+    mine.drop(tid)
+
+    logs = WorklogStore(repo)
+    path = logs.find(tid, back.get("worklog"))
+    note = None
+    if path is None:
+        note = f"任务 {tid} 已退回公共池，但过程文档没找到，跳过执行记录。"
+    else:
+        logs.append_exec(path, exec_line(now(), me.email, "release", "释放回公共池"))
+    return Result(
+        changed=("owner", "status", "updated"),
+        where=rel(repo, pool.path),
+        message=f"释放 {tid}：{back.get('title') or ''}".strip(),
+        notices=(note,) if note else (),
+    )

package/scripts/ledgerkit/actions/result.py

@@ -0,0 +1,88 @@
+"""动作的返回值长什么样。字段名是**公开契约**，插件看板直接读，外壳不许重新算。
+
+写动作返回 `Result`，只读动作返回各自的视图对象（不再套一层统一的壳）。
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+def rel(repo: Path, path: Path) -> str:
+    """绝对路径 → 相对 repo 的字符串（输出给人 / 给界面的一律这个基准）。"""
+    try:
+        return str(Path(path).resolve().relative_to(Path(repo).resolve()))
+    except ValueError:
+        return str(path)
+
+
+@dataclass(frozen=True)
+class WorklogView:
+    """「这条任务的过程文档要怎么显示」。"""
+
+    path: str | None = None  # 相对 repo
+    text: str | None = None  # 全文；读不到时为 None
+    error: str | None = None  # 读不到的原因（缺失 / 读不了），给人看
+
+
+@dataclass(frozen=True)
+class Result:
+    """写动作的返回。"""
+
+    changed: tuple[str, ...] = ()  # 改了哪些**字段名**（不是文件名、不是任务号）
+    where: str | None = None  # 主要落在哪个文件（**相对 repo**）
+    already_done: bool = False  # 重跑发现已经做过 ⇒ 退出码仍是 0
+    message: str | None = None  # git 提交说明；None ⇒ 外壳用默认模板
+    worklog: WorklogView | None = None
+    payload: dict[str, Any] = field(default_factory=dict)
+    notices: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class TaskRow:
+    """人话表格的一行（9 字段投影）。`--json` 吐的是 `rows`（原样任务对象），不是它。"""
+
+    tid: str
+    title: str
+    status: str
+    owner: str | None = None  # 显示名
+    created: str | None = None
+    started: str | None = None
+    category: str | None = None
+    tags: tuple[str, ...] = ()
+    where: str | None = None  # 所在文件（相对 repo）
+
+
+@dataclass(frozen=True)
+class ListResult:
+    rows: dict[str, dict[str, Any]] = field(default_factory=dict)  # tid → 原样任务对象
+    table: tuple[TaskRow, ...] = ()
+    notices: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class ShowResult:
+    task: dict[str, Any] = field(default_factory=dict)
+    worklog: WorklogView | None = None
+    others: tuple[str, ...] = ()  # 同一个任务号还出现在哪些文件里
+    notices: tuple[str, ...] = ()
+
+
+@dataclass(frozen=True)
+class HistoryResult:
+    count: int = 0
+    filters: dict[str, Any] = field(default_factory=dict)  # 回显生效的筛选
+    records: tuple[dict[str, Any], ...] = ()
+    warnings: tuple[str, ...] = ()
+    capped: bool = False
+
+
+@dataclass(frozen=True)
+class ValidationReport:
+    problems: tuple[str, ...] = ()  # 只有它影响退出码
+    notices: tuple[str, ...] = ()  # 只提示，不改退出码
+    checked_files: int = 0
+    total_tasks: int = 0
+    deep: bool = False  # 本次是深度检查（--deep）还是默认浅度

package/scripts/ledgerkit/actions/set_task.py

@@ -0,0 +1,43 @@
+"""改归属的入口：只看 `--owner`，决定走哪个动作，**自己不加锁、不改任何文件**。
+
+它是全树唯一的跨动作引用点（import `release` / `handoff` / `claim`）。
+
+任务状态只随命令语义变（认领 → 进行中、释放 → 待认领、结案 → 历史），
+**没有单独的「改状态」入口**：`--status` 于 2026-10-23 删除 —— 全仓没有任何
+产品调用方（看板只有 claim / release / close 三个写路由），且它能制造
+「归我名下、状态却还是待认领」的坏状态（看板上显示成没人认领）。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..core.identity import Identity, is_me
+from ..core.paths import shard_rel
+from ..errors import Fail
+from ..store.task_store import TaskStore
+from . import claim as claim_mod
+from . import handoff as handoff_mod
+from . import release as release_mod
+from .result import Result, rel
+
+
+def set_task(repo: Path, me: Identity, tid: str, *, owner: str | None) -> Result:
+    """路由：空串 = 释放；别人 = 交接；自己 = 已认领则空转、没认领先认领。"""
+    if owner is None:
+        raise Fail(
+            "set 必须带 --owner：空串 = 释放回公共池；对方身份 = 交接（预留通道，agent 不用）。"
+        )
+    target = owner.strip()
+    if not target:
+        return release_mod.release(repo, me, tid)
+    if not is_me(me, target):
+        return handoff_mod.handoff(repo, me, tid, to=target)
+    mine = TaskStore(repo, shard_rel(me.email), identity=me)
+    if mine.get(tid) is not None:
+        return Result(
+            already_done=True,
+            where=rel(repo, mine.path),
+            notices=(f"任务 {tid} 已经在你名下，无需操作。",),
+        )
+    return claim_mod.claim(repo, me, tid)

package/scripts/ledgerkit/actions/show_task.py

@@ -0,0 +1,27 @@
+"""只读：看一条任务（池 + 索引登记的全部分片都扫，别人的也要能看）。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..core.identity import Identity
+from ..store.worklog_store import WorklogStore
+from .guard import load_task
+from .result import ShowResult, WorklogView, rel
+
+
+def show_task(repo: Path, me: Identity, tid: str) -> ShowResult:
+    task, where = load_task(repo, tid)
+    logs = WorklogStore(repo)
+    path = logs.find(tid, task.get("worklog"))
+    if path is None:
+        view = WorklogView(
+            path=None, text=None, error="这条任务没有过程文档（或文档已不在原处）。"
+        )
+    else:
+        view = WorklogView(path=rel(repo, path), text=logs.read(path), error=None)
+    return ShowResult(
+        task=task,
+        worklog=view,
+        others=tuple(rel(repo, p) for p in where),
+    )

package/scripts/ledgerkit/actions/validate.py

@@ -0,0 +1,224 @@
+"""只读：台账体检。两档：默认浅度只查格式，`--deep` 才读全部历史与过程文档正文。
+
+浅度（默认）：池 + 各分片的字段格式、索引与文件对不对得上、**当月**历史、每篇过程文档的模板格式。
+深度（`--deep`）：历史不止当月（全部月份），过程文档再判骨架（正文填了没）。
+
+只查格式，不查业务（该谁结案、逾期与否都不管）；也不查「同一任务号落在多个文件」——
+读侧只显示一次（`show` 会点名）、写侧已有防护，撞上了不关体检的事（2026-10-24 用户拍板）。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..core import history_md
+from ..core.identity import Identity
+from ..core.labels import STATUSES
+from ..core.paths import LEGACY_HISTORY_REL, OWNERS_REL, POOL_REL, to_repo_rel
+from ..core.time import now
+from ..core.worklog_md import (
+    duplicated_sections,
+    format_problems,
+    is_skeleton,
+    lacks_exec_section,
+)
+from ..store.history_store import HistoryStore
+from ..store.owners_index import OwnersIndex
+from ..store.task_store import TaskStore
+from ..store.worklog_store import WorklogStore
+from .guard import owner_of, status_of
+from .result import ValidationReport, rel
+
+
+def _read_tasks(repo: Path, store: TaskStore, problems: list[str]) -> dict:
+    """读一个任务文件；撞上**程序自留**的冲突标记 ⇒ 记一条 problem 继续。
+
+    推送被拒后 rebase 给 JSON 留的 `<<<<<<<` 是程序自己产的坏数据，validate
+    要能指出来（退 1 给清单），而不是整条命令退 3（2026-10-24 修）。
+    其余读错误（用户手改坏）不在此列，照旧抛出。
+    """
+    try:
+        return store.all()
+    except ValueError:
+        text = store.path.read_text(encoding="utf-8", errors="replace")
+        if "<<<<<<<" in text:
+            problems.append(
+                f"{rel(repo, store.path)} 带着冲突标记"
+                "（推送被拒后 rebase 没解完）：先解决冲突，再跑 validate。"
+            )
+            return {}
+        raise
+
+
+def _check_task_files(
+    repo: Path, index: OwnersIndex, problems: list[str]
+) -> tuple[int, int]:
+    """池 + 各分片的字段格式（owner / status / 分片归属）；返回 (查了几个文件, 几条任务)。"""
+    checked = 0
+    total = 0
+
+    pool = TaskStore(repo, POOL_REL)
+    if pool.path.exists():
+        checked += 1
+        for tid, task in _read_tasks(repo, pool, problems).items():
+            total += 1
+            if owner_of(task):
+                problems.append(
+                    f"公共池里的 {tid} 带着 owner（池里的行必须无人认领）。"
+                )
+            if task.get("status") not in STATUSES:
+                problems.append(f"公共池里的 {tid} 状态 {task.get('status')!r} 非法。")
+
+    for key, path in index.shards().items():
+        if not path.exists():
+            problems.append(f"索引登记了 {key}，但分片文件 {path.name} 不存在。")
+            continue
+        checked += 1
+        store = TaskStore(repo, Path(path).relative_to(repo / "ledger"))
+        for tid, task in _read_tasks(repo, store, problems).items():
+            total += 1
+            owner = owner_of(task)
+            if not owner:
+                problems.append(f"分片 {key} 里的 {tid} 没有 owner。")
+            elif owner != key:
+                problems.append(
+                    f"分片 {key} 里的 {tid} 的 owner 是 {owner}（分片主人与分区键不一致）。"
+                )
+            status = status_of(task)
+            if status not in STATUSES:
+                problems.append(f"分片 {key} 里的 {tid} 状态 {status!r} 非法。")
+
+    return checked, total
+
+
+def _check_orphan_shards(index: OwnersIndex, problems: list[str]) -> None:
+    """目录里有、索引没登记的分片（全仓唯一扫目录的地方）。"""
+    registered = {p.name for p in index.shards().values()}
+    for path in index.disk_shards():
+        if path.name not in registered:
+            problems.append(
+                f"owners/ 里的 {path.name} 没有在索引里登记（对它人等于不存在）。"
+            )
+
+
+def _history_paths(store: HistoryStore, *, deep: bool) -> list[Path]:
+    """要读的历史文件：浅度只读当月那个月文件（存量平铺文件不读），深度读全部。"""
+    sources = store.sources()
+    if deep:
+        return sources
+    month = now()[0:4] + now()[5:7]
+    return [p for p in sources if store.month_key(p) == month]
+
+
+def _check_history(
+    repo: Path,
+    paths: list[Path],
+    open_docs: set[str],
+    store: HistoryStore,
+    notices: list[str],
+) -> int:
+    """历史文件的格式与对账：解析警告、行尾文档链接对得上在办任务没。"""
+    checked = 0
+    for path in paths:
+        checked += 1
+        rows, warns = history_md.parse_history(store.read(path))
+        notices.extend(f"{rel(repo, path)}：{w}" for w in warns)
+        for row in rows:
+            name = Path(row.get("worklog") or "").name
+            if name and name in open_docs:
+                notices.append(
+                    f"历史里有「{row.get('title') or name}」的结案行，"
+                    "但它还挂在在办台账里。"
+                )
+    return checked
+
+
+def _check_worklog(
+    repo: Path,
+    logs: WorklogStore,
+    problems: list[str],
+    notices: list[str],
+    *,
+    deep: bool,
+) -> int:
+    """每篇过程文档：模板格式（浅度就查）+ 空骨架判定（只有 `--deep` 才判）。
+
+    一趟读完两件事都做 —— 格式要看全文找节标题，骨架吃同一份文本，别为此读第二遍。
+    """
+    checked = 0
+    for path in logs.all():
+        checked += 1
+        try:
+            text = logs.read(path)
+        except ValueError:
+            continue
+        if not text:
+            continue
+        where = rel(repo, path)
+        problems.extend(f"{where} 格式：{line}" for line in format_problems(text))
+        if lacks_exec_section(text):
+            notices.append(
+                f"{where} 没有「执行记录」节（老文档；写一条记录会自动补上）。"
+            )
+        dup = duplicated_sections(text)
+        if dup:
+            notices.append(
+                f"{where} 有重复的节：{'、'.join(f'`## {s}`' for s in dup)}。"
+            )
+        if deep and is_skeleton(text):
+            notices.append(f"{where} 还是骨架（正文没填）。")
+    return checked
+
+
+def validate(repo: Path, me: Identity, deep: bool = False) -> ValidationReport:
+    problems: list[str] = []
+    notices: list[str] = []
+    checked = 0
+    total = 0
+
+    index = OwnersIndex(repo)
+    history = HistoryStore(repo)
+    logs = WorklogStore(repo)
+
+    files, tasks = _check_task_files(repo, index, problems)
+    checked += files
+    total += tasks
+    _check_orphan_shards(index, problems)
+
+    checked += _check_history(
+        repo,
+        _history_paths(history, deep=deep),
+        _open_worklog_names(repo, index),
+        history,
+        notices,
+    )
+    checked += _check_worklog(repo, logs, problems, notices, deep=deep)
+
+    legacy = repo / to_repo_rel(LEGACY_HISTORY_REL)
+    if legacy.exists():
+        notices.append(f"存量平铺文件 {rel(repo, legacy)} 只读兼容，不会重写。")
+    if not (repo / to_repo_rel(OWNERS_REL)).exists():
+        notices.append("还没有 owners.json（索引）：跑一条写命令会自动建。")
+
+    return ValidationReport(
+        problems=tuple(problems),
+        notices=tuple(notices),
+        checked_files=checked,
+        total_tasks=total,
+        deep=deep,
+    )
+
+
+def _open_worklog_names(repo: Path, index: OwnersIndex) -> set[str]:
+    """在办任务的过程文档**文件名**集合（池 + 全部分片）：历史行按它对账。"""
+    stores = [TaskStore(repo, POOL_REL)]
+    for path in index.shards().values():
+        if path.exists():
+            stores.append(TaskStore(repo, Path(path).relative_to(repo / "ledger")))
+    out: set[str] = set()
+    for store in stores:
+        for task in store.all().values():
+            name = Path((task.get("worklog") or "").strip()).name
+            if name:
+                out.add(name)
+    return out