task-ledger 1.2.9 → 1.3.1

package/scripts/ledgerkit/core/history_md.py

@@ -0,0 +1,350 @@
+"""历史表格的文本操作：拼行、解析、旧列数升级。
+
+**自己不开文件**：升级要回链 worklog 读头部，那件事由调用方传 `read_worklog`
+回调进来（`str -> str | None`），core 只做文本换算。
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Iterable
+from pathlib import Path
+from typing import Any
+
+from .paths import to_history_rel
+from .time import TIME_RE, time_key
+
+HISTORY_TITLE = "# 进度历史（已结案）"
+HISTORY_HEADER = "| 结案时间 | 创建时间 | 工作包 | 分类 | 标签 | owner | creator | 完成了什么 | 过程文档 |"
+HISTORY_SEP = "|---|---|---|---|---|---|---|---|---|"
+
+# 最旧格式把 owner 缝在工作包末尾：最右一个「空格 + @」之后整段是 owner。
+OLD_OWNER_RE = re.compile(r"^(?P<title>.*\S)\s+@(?P<owner>\S.*)$")
+_LINK_RE = re.compile(r"\[[^\]]*\]\(([^)]*)\)")
+_TAG_SPLIT_RE = re.compile(r"[,，、]")
+
+Row = dict[str, Any]  # 一条历史行：见 parse_history 的返回
+
+
+def esc_cell(text: str) -> str:
+    """表格单元格：折叠空白并转义竖线，避免把历史表格写坏。"""
+    return " ".join((text or "").split()).replace("|", "\\|")
+
+
+def owner_cell(owner: str | None) -> str:
+    """owner 列的展示值：人名前加 @（`@` 只是展示约定，匹配一律用裸标识）。"""
+    return f"@{owner}" if owner else ""
+
+
+def creator_cell(creator: str | None) -> str:
+    """creator 列展示值（与 owner_cell 同一 `@` 约定）。"""
+    return f"@{creator}" if creator else ""
+
+
+def split_row(line: str) -> list[str]:
+    """按 `|` 切表格行：转义竖线 `\\|` 不当分隔符，切完反转义、去首尾空单元。"""
+    cells = re.split(r"(?<!\\)\|", line.strip())
+    if cells and cells[0] == "":
+        cells = cells[1:]
+    if cells and cells[-1] == "":
+        cells = cells[:-1]
+    return [c.strip().replace("\\|", "|") for c in cells]
+
+
+def is_sep_row(cells: list[str]) -> bool:
+    return bool(cells) and all(re.fullmatch(r":?-+:?", c) for c in cells)
+
+
+def _looks_like_header(cells: list[str]) -> bool:
+    # 按内容判、不按位置判：无表头的老文件首行就是数据，按位置判会把第一条记录当表头删掉。
+    return bool(cells) and cells[0] in ("时间", "结案时间")
+
+
+def history_line(
+    finished: str,
+    created: str | None,
+    title: str,
+    owner: str | None,
+    summary: str,
+    worklog: str | None,
+    category: str | None = None,
+    tags: Iterable[str] | None = None,
+    creator: str | None = None,
+) -> str:
+    """九列的一行。`worklog` 收**相对 `ledger/`** 的路径，这里负责换成相对 `history/` 的链接。
+
+    owner / creator 传**裸标识**（`@` 由 owner_cell / creator_cell 加），外面别先加。
+    """
+    log_rel = to_history_rel(worklog) if worklog else ""
+    tag_cell = esc_cell("、".join(tags) if tags else "")
+    link = f"[{log_rel}]({log_rel})" if log_rel else ""
+    return (
+        f"| {finished} | {created or ''} | {esc_cell(title)} "
+        f"| {esc_cell(category or '')} | {tag_cell} "
+        f"| {esc_cell(owner_cell(owner))} | {esc_cell(creator_cell(creator))} "
+        f"| {esc_cell(summary)} | {link} |\n"
+    )
+
+
+def history_line_for_cols(
+    cols: int,
+    finished: str,
+    created: str | None,
+    title: str,
+    owner: str | None,
+    summary: str,
+    worklog: str | None,
+    category: str | None = None,
+    tags: Iterable[str] | None = None,
+    creator: str | None = None,
+) -> str:
+    """「历史层有无法解析的行、不敢整体升级」时按现有列数追加一行，避免列错位。
+
+    GFM 按首行列数渲染，列数写错会被静默丢弃 / 错位。少列的文件硬塞 9 列会把整行挤歪。
+    """
+    log_rel = to_history_rel(worklog) if worklog else ""
+    link = f"[{log_rel}]({log_rel})" if log_rel else ""
+    if cols <= 4:
+        who = f" @{owner}" if owner else ""
+        return (
+            f"| {finished} | {esc_cell(title + who)} | {esc_cell(summary)} | {link} |\n"
+        )
+    if cols == 5:
+        return (
+            f"| {finished} | {esc_cell(title)} | {esc_cell(owner_cell(owner))} "
+            f"| {esc_cell(summary)} | {link} |\n"
+        )
+    if cols == 6:
+        return (
+            f"| {finished} | {created or ''} | {esc_cell(title)} "
+            f"| {esc_cell(owner_cell(owner))} | {esc_cell(summary)} | {link} |\n"
+        )
+    return history_line(
+        finished, created, title, owner, summary, worklog, category, tags, creator
+    )
+
+
+def history_cols(text: str) -> int:
+    """现有历史表格数据行的列数（取众数、平局取较大）；无数据行时按 6。"""
+    counts: dict[int, int] = {}
+    for raw in text.splitlines():
+        if not raw.strip().startswith("|"):
+            continue
+        cells = split_row(raw)
+        if not cells or is_sep_row(cells) or _looks_like_header(cells):
+            continue
+        if len(cells) >= 4:
+            counts[len(cells)] = counts.get(len(cells), 0) + 1
+    if not counts:
+        return 6
+    return max(counts, key=lambda k: (counts[k], k))
+
+
+def parse_history(text: str) -> tuple[list[Row], list[str]]:
+    """解析历史表 → (records, warnings)。**逐行按自己的列数判别**，表头只用来跳过。
+
+    兼容 9 / 8 / 6 / 5（两种）/ 4 列；坏行（列数不在列、时间列不合法）跳过并警告，不中断。
+    返回的键：finished / created / title / category / tags / owner / creator / summary /
+    worklog / fmt / line。owner 与 creator 一律**剥掉 `@`**（匹配用裸标识）。
+    """
+    records: list[Row] = []
+    warnings: list[str] = []
+    for lineno, raw in enumerate(text.splitlines(), 1):
+        if not raw.strip().startswith("|"):
+            continue
+        cells = split_row(raw)
+        if not cells or is_sep_row(cells) or _looks_like_header(cells):
+            continue
+        created = ""
+        category: str | None = None
+        tags: list[str] = []
+        creator: str | None = None
+        if len(cells) == 9:
+            (
+                finished,
+                created,
+                title,
+                category,
+                tag_cell,
+                owner,
+                creator,
+                summary,
+                doc,
+            ) = cells
+            fmt = "v9"
+            category = category.strip() or None
+            tags = [t.strip() for t in _TAG_SPLIT_RE.split(tag_cell) if t.strip()]
+            creator = creator.strip().removeprefix("@") or None
+        elif len(cells) == 8:
+            finished, created, title, category, tag_cell, owner, summary, doc = cells
+            fmt = "v8"
+            category = category.strip() or None
+            tags = [t.strip() for t in _TAG_SPLIT_RE.split(tag_cell) if t.strip()]
+        elif len(cells) == 6:
+            finished, created, title, owner, summary, doc = cells
+            fmt = "v6"
+        elif len(cells) == 5 and TIME_RE.fullmatch(cells[1]):
+            # 旧 ledger 格式（结案 / 创建 / 工作包 / 摘要 / 文档）：行内自带创建时间。
+            finished, created, title, summary, doc = cells
+            owner = ""
+            fmt = "v5ledger"
+        elif len(cells) == 5:
+            finished, title, owner, summary, doc = cells
+            fmt = "v5"
+        elif len(cells) == 4:
+            finished, title, summary, doc = cells
+            m = OLD_OWNER_RE.match(title)
+            owner = m.group("owner") if m else ""
+            if m:
+                title = m.group("title")
+            fmt = "v4"
+        else:
+            warnings.append(f"第 {lineno} 行列数不是 4 / 5 / 6 / 8 / 9，已跳过")
+            continue
+        if not TIME_RE.fullmatch(finished):
+            warnings.append(f"第 {lineno} 行时间列 {finished!r} 不合法，已跳过")
+            continue
+        m = _LINK_RE.fullmatch(doc.strip())
+        log = m.group(1) if m else doc.strip()
+        records.append(
+            {
+                "finished": finished,
+                "created": time_key(created) if created else None,
+                "title": title,
+                "category": category,
+                "tags": tuple(tags),
+                "owner": (owner or "").strip().removeprefix("@") or None,
+                "creator": creator,
+                "summary": summary,
+                "worklog": log or None,
+                "fmt": fmt,
+                "line": lineno,
+            }
+        )
+    return records, warnings
+
+
+def _drop_trailing_blank(out: list[str]) -> None:
+    """去掉已在结果里的尾部空行（丢弃重复表头时用）：中间的空行会把 GFM 表格截断。"""
+    while out and not out[-1].strip():
+        out.pop()
+
+
+def upgrade_history(
+    text: str,
+    *,
+    read_worklog: Callable[[str], dict[str, Any] | None],
+    fallback_created: str,
+) -> tuple[str, int] | None:
+    """旧格式（4 / 5 / 6 / 8 列）→ v9。**全部数据行可解析才返回 (新文本, 转换行数)**，否则 None。
+
+    `None` 的语义是「不敢动」：调用方必须退回 `history_line_for_cols` 按原列数追加并明示，
+    绝不半升级、绝不猜。分类 / 标签 / creator / 缺的创建时间都靠 `read_worklog` 回链补，
+    读不到就留空（创建时间除外：留空会让排序失效，所以退化到 `fallback_created`）。
+
+    `read_worklog` 的契约：`(log_name: str) -> dict | None` —— 收**文件名**（历史末列的
+    basename，不是路径），返回 `{"created", "creator", "category", "tags"}`。core 只消费
+    返回值，自己不开文件。
+    """
+    out: list[str] = []
+    converted = 0
+    seen_header = False
+    seen_sep = False
+    for raw in text.splitlines():
+        if not raw.strip().startswith("|"):
+            out.append(raw)
+            continue
+        cells = split_row(raw)
+        if not cells:
+            out.append(raw)
+            continue
+        if is_sep_row(cells):
+            if seen_sep:
+                _drop_trailing_blank(out)
+                continue
+            seen_sep = True
+            out.append(HISTORY_SEP)
+            continue
+        if _looks_like_header(cells):
+            if seen_header:
+                _drop_trailing_blank(out)
+                continue
+            seen_header = True
+            out.append(HISTORY_HEADER)
+            continue
+        if len(cells) == 9:
+            if time_key(cells[0]) is None:
+                return None
+            out.append("| " + " | ".join(cells) + " |")
+            continue
+        explicit_created: str | None = None
+        creator: str | None = None
+        if len(cells) == 8:
+            finished, created, title, category, tag_cell, owner, summary, doc = cells
+            if time_key(finished) is None:
+                return None
+            created_key = time_key(created.strip())
+            tags = [t.strip() for t in _TAG_SPLIT_RE.split(tag_cell) if t.strip()]
+            creator = (_meta_of(doc, read_worklog) or {}).get("creator")
+            out.append(
+                f"| {finished} | {created_key or ''} | {esc_cell(title)} "
+                f"| {esc_cell(category.strip())} "
+                f"| {esc_cell('、'.join(tags) if tags else '')} "
+                f"| {esc_cell(owner_cell(owner.lstrip('@')))} "
+                f"| {esc_cell(creator_cell(creator))} "
+                f"| {esc_cell(summary)} | {doc} |"
+            )
+            converted += 1
+            continue
+        if len(cells) == 6:
+            finished, created, title, owner, summary, doc = cells
+            owner = owner.lstrip("@")
+            explicit_created = time_key(created.strip())
+        elif len(cells) == 5 and TIME_RE.fullmatch(cells[1]):
+            finished, created_cell, title, summary, doc = cells
+            owner = ""
+            explicit_created = time_key(created_cell.strip())
+        elif len(cells) == 5:
+            finished, title, owner, summary, doc = cells
+            owner = owner.lstrip("@")
+        elif len(cells) == 4:
+            finished, title, summary, doc = cells
+            m = OLD_OWNER_RE.match(title)
+            owner = m.group("owner") if m else ""
+            if m:
+                title = m.group("title")
+        else:
+            return None
+        finished_key = time_key(finished)
+        if finished_key is None:
+            return None
+        meta = _meta_of(doc, read_worklog)
+        created = explicit_created or (meta or {}).get("created") or fallback_created
+        category = (meta or {}).get("category")
+        tags = tuple((meta or {}).get("tags") or ())
+        creator = (meta or {}).get("creator")
+        out.append(
+            f"| {finished_key} | {created} | {esc_cell(title)} "
+            f"| {esc_cell(category or '')} "
+            f"| {esc_cell('、'.join(tags) if tags else '')} "
+            f"| {esc_cell(owner_cell(owner))} "
+            f"| {esc_cell(creator_cell(creator))} "
+            f"| {esc_cell(summary)} | {doc} |"
+        )
+        converted += 1
+    return "\n".join(out) + "\n", converted
+
+
+def _link_target(cell: str) -> str:
+    m = _LINK_RE.fullmatch((cell or "").strip())
+    return (m.group(1) if m else (cell or "")).strip()
+
+
+def _meta_of(
+    doc: str, read_worklog: Callable[[str], dict[str, Any] | None]
+) -> dict[str, Any] | None:
+    """顺着历史行的文档链接取回 worklog 头部四样（`read_worklog` 收文件名）。"""
+    target = _link_target(doc)
+    if not target:
+        return None
+    return read_worklog(Path(target).name)

package/scripts/ledgerkit/core/identity.py

@@ -0,0 +1,43 @@
+"""身份这个值对象：归一化与比较规则。**只做字符串换算，不读 git**（读 git 归 env.py）。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+
+
+@dataclass(frozen=True)
+class Identity:
+    """一个人的身份。`email` 是分区键（归一化后的裸标识），`name` 只用于显示。"""
+
+    email: str
+    name: str = ""
+    aliases: tuple[str, ...] = ()
+
+    def label(self) -> str:
+        """显示名：没名字就用邮箱。"""
+        return self.name or self.email
+
+
+def normalize(who: str) -> str:
+    """归一化：去首尾空白 + 转小写。全仓只此一处。"""
+    return (who or "").strip().lower()
+
+
+def keys(identity: Identity) -> tuple[str, ...]:
+    """这个身份的全部可比标识：自己 + aliases（去重、保持顺序）。"""
+    out: list[str] = []
+    for value in (identity.email, *identity.aliases):
+        key = normalize(value)
+        if key and key not in out:
+            out.append(key)
+    return tuple(out)
+
+
+def is_me(identity: Identity, who: str | None) -> bool:
+    """`who`（可能是邮箱、名字或别名）是不是这个人。"""
+    return normalize(who or "") in keys(identity)
+
+
+def with_aliases(identity: Identity, aliases: tuple[str, ...]) -> Identity:
+    """换一个带 aliases 的同身份对象（索引里读到别名后由外壳装配）。"""
+    return replace(identity, aliases=tuple(aliases))

package/scripts/ledgerkit/core/ids.py

@@ -0,0 +1,58 @@
+"""任务号：生成、形态校验。只做字符串换算。"""
+
+from __future__ import annotations
+
+import re
+import secrets
+from collections.abc import Mapping
+
+from ..errors import Fail
+from .time import now
+
+ID_RE = re.compile(r"[a-z0-9\u4e00-\u9fff][a-z0-9\u4e00-\u9fff-]*\Z")
+
+
+def slugify(title: str) -> str:
+    """任务号用：保留 ASCII 字母数字与汉字，其余转连字符，截到 40 字。"""
+    s = re.sub(r"[^a-z0-9\u4e00-\u9fff]+", "-", title.strip().lower())
+    return s.strip("-")[:40].strip("-")
+
+
+def id_stamp(created: str) -> str:
+    """`created`（YYYY-MM-DD HH:MM:SS）→ 任务号前缀 `YYYYMMDD-HHMM`（任务号只到分）。"""
+    return (
+        f"{created[0:4]}{created[5:7]}{created[8:10]}-{created[11:13]}{created[14:16]}"
+    )
+
+
+def make_id(title: str, tasks: Mapping[str, object], created: str | None = None) -> str:
+    """按标题生成一个不撞号的任务号。
+
+    随机码不能省：`make_id` 只在**在办**任务里去重，而结案的过程文档长期留在磁盘上，
+    去掉随机码会让新任务撞上已结案文档的名字。
+    """
+    slug = slugify(title)
+    if not slug:
+        raise Fail(
+            "标题里没有可用字符（字母、数字或汉字），无法自动生成任务号。"
+            f'用 --id 指定一个，例如 --id "task-{secrets.token_hex(2)}"。'
+        )
+    stamp = id_stamp(created or now())
+    for _ in range(20):
+        tid = f"{stamp}-{slug}-{secrets.token_hex(2)}"
+        if tid not in tasks:
+            return tid
+    raise Fail("任务号连续冲突 20 次，请检查台账是否异常。")
+
+
+def require_task_id(tid: str) -> str:
+    """任务号形态校验（全仓唯一入口）。不合法直接抛 Fail。"""
+    value = (tid or "").strip()
+    if not value:
+        raise Fail("任务号不能为空。")
+    if not ID_RE.fullmatch(value.lower()):
+        raise Fail(
+            f"任务号 {tid!r} 不合法：只能用小写字母、数字、汉字和连字符，"
+            "且不能以连字符开头或结尾。"
+        )
+    return value

package/scripts/ledgerkit/core/labels.py

@@ -0,0 +1,79 @@
+"""分类与标签：校验、拼行、拆行。只做文本换算。"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+from ..errors import Fail
+
+STATUSES = ("open", "doing")
+LEGACY_STATUSES = ("blocked",)  # 旧数据：读侧当进行中，不写回
+FORMAT_VERSION = "20261022000000"
+
+LABEL_MAX_CHARS = 4  # 含 CJK 时按「字」算
+LABEL_MAX_WORDS_EN = 3  # 纯 ASCII 时按「词」算
+TAGS_MAX_COUNT = 5
+
+CJK_RE = re.compile(r"[\u4e00-\u9fff]")
+LABEL_CAT_RE = re.compile(r"分类\*\*\s*[：:]\s*([^｜|]+)")
+LABEL_TAG_RE = re.compile(r"标签\*\*\s*[：:]\s*(.+)$")
+_SPLIT_RE = re.compile(r"[,，、]")
+
+
+def normalize_label(value: str, *, field: str) -> str:
+    """分类 / 单个标签的校验：去空白、限长。空串直接 Fail（给了就要有意义）。"""
+    text = (value or "").strip()
+    if not text:
+        raise Fail(f"{field} 不能为空。")
+    if CJK_RE.search(text):
+        if len(text) > LABEL_MAX_CHARS:
+            raise Fail(f"{field} {text!r} 太长：含中文时最多 {LABEL_MAX_CHARS} 个字。")
+    elif len(text.split()) > LABEL_MAX_WORDS_EN:
+        raise Fail(f"{field} {text!r} 太长：英文最多 {LABEL_MAX_WORDS_EN} 个词。")
+    return text
+
+
+def parse_tags(raw: str | Iterable[str] | None) -> tuple[str, ...]:
+    """标签串（「、」「,」「，」分隔）→ 去重保序的元组；超上限报错。"""
+    if raw is None:
+        return ()
+    items = list(raw) if not isinstance(raw, str) else _SPLIT_RE.split(raw)
+    out: list[str] = []
+    for item in items:
+        text = normalize_label(str(item).strip(), field="标签")
+        if text not in out:
+            out.append(text)
+    if len(out) > TAGS_MAX_COUNT:
+        raise Fail(f"标签最多 {TAGS_MAX_COUNT} 个，收到 {len(out)} 个。")
+    return tuple(out)
+
+
+def label_line(category: str | None, tags: Iterable[str] | None) -> str:
+    """过程文档头部的「分类/标签」行；两者皆空返回空串（此行不写）。"""
+    segs: list[str] = []
+    if category:
+        segs.append(f"**分类**：{category}")
+    tag_list = [t for t in (tags or ()) if t]
+    if tag_list:
+        segs.append(f"**标签**：{'、'.join(tag_list)}")
+    return "> " + " ｜ ".join(segs) if segs else ""
+
+
+def parse_label_line(text: str) -> tuple[str | None, tuple[str, ...]]:
+    """从过程文档头部（第一个 `## ` 小节之前）解析分类与标签。"""
+    for line in text.splitlines():
+        if line.startswith("## "):
+            break
+        mc = LABEL_CAT_RE.search(line)
+        mt = LABEL_TAG_RE.search(line)
+        if not (mc or mt):
+            continue
+        category = mc.group(1).strip() if mc else None
+        tags = (
+            tuple(t.strip() for t in _SPLIT_RE.split(mt.group(1).strip()) if t.strip())
+            if mt
+            else ()
+        )
+        return (category or None, tags)
+    return (None, ())

package/scripts/ledgerkit/core/paths.py

@@ -0,0 +1,93 @@
+"""路径与文件名怎么拼：只做换算，一个文件都不碰。
+
+**基准只有两个**：
+- 磁盘与 JSON 里存的（`task["worklog"]` 等）一律**相对 `ledger/`**；
+- 输出给人或给界面的（`Result.where`、`payload` 里的 `*_path`）一律**相对 repo**。
+
+换算只在这两个函数里做，任何层都不许自己拼 `..`。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+
+LEDGER_DIR = Path("ledger")
+
+POOL_REL = Path("pool.json")
+OWNERS_REL = Path("owners.json")
+OWNERS_DIR = Path("owners")
+HISTORY_DIR = Path("history")
+WORKLOG_DIR = Path("worklog")
+LEGACY_HISTORY_REL = Path("PROGRESS-HISTORY.md")  # 存量平铺文件：只读不写
+
+SHA_LEN = 12
+
+# 模板与资产的唯一定位基准：按自身位置算绝对路径，不依赖调用方 cwd。
+# ledgerkit/core/paths.py → parents: [core, ledgerkit, scripts, skill]
+SKILL_DIR = Path(__file__).resolve().parents[3]
+WORKLOG_TEMPLATE = SKILL_DIR / "assets" / "worklog.md"
+
+
+def to_repo_rel(ledger_rel: str | Path) -> Path:
+    """相对 `ledger/` 的路径 → 相对 repo 的路径。"""
+    return LEDGER_DIR / Path(ledger_rel)
+
+
+def to_ledger_rel(repo_rel: str | Path) -> str:
+    """相对 repo 的路径 → 相对 `ledger/` 的路径（已经是 `ledger/` 内的原样返回）。"""
+    p = Path(repo_rel)
+    if p.parts and p.parts[0] == LEDGER_DIR.name:
+        return Path(*p.parts[1:]).as_posix()
+    return p.as_posix()
+
+
+def to_history_rel(ledger_rel: str | Path) -> str:
+    """`ledger/` 内的路径 → 从 `ledger/history/<ym>.md` 出发的链接串。
+
+    深度固定（`history/` 与 `worklog/` 都在 `ledger/` 下），拼 `..` 只许在这一处。
+    """
+    return ("../" / Path(ledger_rel)).as_posix()
+
+
+def shard_rel(identity: str) -> Path:
+    """某人分片相对 `ledger/` 的路径：sha256(归一化身份)[:12] + .json。"""
+    digest = hashlib.sha256(identity.strip().lower().encode("utf-8")).hexdigest()
+    return OWNERS_DIR / f"{digest[:SHA_LEN]}.json"
+
+
+def month_of(stamp: str, *, fallback_now: str | None = None) -> str:
+    """存盘时间 → `YYYYMM`；取不到时用 `fallback_now`，再没有就抛错由调用方定夺。"""
+    month = re.sub(r"[^0-9]", "", (stamp or "")[:7])[:6]
+    if len(month) == 6:
+        return month
+    if fallback_now:
+        return re.sub(r"[^0-9]", "", fallback_now[:7])[:6]
+    return ""
+
+
+def worklog_dir_for(created: str) -> Path:
+    """过程文档的按月目录（相对 `ledger/`）：`worklog/<YYYYMM>/`。"""
+    return WORKLOG_DIR / month_of(created)
+
+
+def worklog_name(tid: str) -> str:
+    """过程文档的文件名：任务号剥掉前缀年月日，随机码保留。
+
+    父目录 `worklog/<YYYYMM>/` 已带年月，文件名里再写一遍是冗余；
+    自定义 `--id` 不以「8 位数字-」开头时，文件名就是任务号本身。
+    """
+    if len(tid) > 9 and tid[:8].isdigit() and tid[8] == "-":
+        return f"{tid[6:]}.md"
+    return f"{tid}.md"
+
+
+def worklog_rel(tid: str, created: str) -> str:
+    """过程文档相对 `ledger/` 的路径：任务对象与历史末列共用同一口径。"""
+    return (worklog_dir_for(created) / worklog_name(tid)).as_posix()
+
+
+def history_path_for(finished: str) -> Path:
+    """结案时间 → 历史文件相对 `ledger/` 的路径：`history/<YYYYMM>.md`。"""
+    return HISTORY_DIR / f"{month_of(finished)}.md"