task-ledger 1.3.1 → 1.3.3

package/README.md

@@ -31,7 +31,7 @@
 直接跑：
 
 ```bash
-python3 <SKILL.md 所在目录>/scripts/progress.py <子命令> --repo <当前工作区>
+python3 <SKILL.md 所在目录>/scripts/progress.py <子命令> --repo <工作区根>
 ```
 
 子命令：`new` `claim` `set` `log` `close` `list` `history` `show` `tags` `validate`。命令参考（参数 / 一句话 / 举例）、任务生命周期、纪律（数据完整性 / 人类授权 / 故障处置）全在 `SKILL.md`；参数细节看 `<子命令> --help`（不要凭记忆编）。

package/SKILL.md

@@ -131,10 +131,10 @@ allowed-tools: Read,Edit,Bash,Grep
 ## 怎么调用
 
 ```bash
-python3 <本 SKILL.md 所在目录>/scripts/progress.py <子命令> --repo <当前工作区>
+python3 <本 SKILL.md 所在目录>/scripts/progress.py <子命令> --repo <工作区根>
 ```
 
-- 定位项目：`--repo <目录>` 给了就用；不给就从当前目录逐级向上找第一个含 `ledger/` 的目录。
+- 定位项目：`--repo <工作区根>`（**直接含有 `ledger/` 的那个目录**）给了就校验后用；不给就从当前目录逐级向上找。`ledger/` 本身、以及它下面的任何子目录都不是根，指过去会被直接拒绝（判据只看位置，不看目录里有哪些文件 —— 项目根自带 `pool.json`、`history/`、`worklog/` 都不影响）。
 - `--no-sync`（放在子命令**前**）：用户明确要求「先别同步」时才用；之后自己 `git add ledger && commit && push`。
 - `--json` 只对只读命令（`list` / `show` / `history` / `validate`）有意义；写命令不接收 `--json`，传了是用法错。`--json` 里的时间字段是 UTC，人话输出是本地时间。
 - 命令回执只用来确认生效；任务状态以 `show` / `list` 为准。
@@ -193,7 +193,7 @@ python3 <本 SKILL.md 所在目录>/scripts/progress.py <子命令> --repo <当
 
 ### 人类授权（跑之前问不问）
 
-项目没有 `ledger/` ⇒ 先问「要不要建个台账记这活？」，不许自建。用户同意 ⇒ 直接跑第一条写命令，且**必须带 `--repo <项目根>`**：不带时脚本只从当前目录逐级往上找第一个含 `ledger/` 的目录，一个都没有就退 1 报「找不到台账」，绝不就地建；台账由这条写命令顺带建出来，没有 `init` 命令。之后可以不带 `--repo`，但查找是**逐级往上**的 —— 在本项目的子目录里跑可能命中上层项目的台账，拿不准就一直带 `--repo <项目根>`。
+项目没有 `ledger/` ⇒ 先问「要不要建个台账记这活？」，不许自建。用户同意 ⇒ 直接跑第一条写命令，且**必须带 `--repo <工作区根>`**（根是直接含有 `ledger/` 的那个目录，`ledger/` 本身不是根、指到它会被拒绝）：不带时脚本只从当前目录逐级往上找第一个含 `ledger/` 的目录，一个都没有就退 1 报「找不到台账」，绝不就地建；台账由这条写命令顺带建出来，没有 `init` 命令。之后可以不带 `--repo`，但查找是**逐级往上**的 —— 在本项目的子目录里跑可能命中上层项目的台账，拿不准就一直带 `--repo <工作区根>`。
 
 | 命令 | 档位 | 要求 |
 |---|---|---|

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "task-ledger",
-	"version": "1.3.1",
+	"version": "1.3.3",
 	"description": "Task-ledger skill for coding agents: per-workspace progress tracking (ledger/pool.json + owners/<hash>.json shards + owners.json index, history, worklog) driven by a CLI script. Standalone install for CodeBuddy and other agents; also bundled inside the dsh-task-ledger DSH plugin.",
 	"keywords": [
 		"skill",

package/references/state-model.md

@@ -35,7 +35,7 @@ close             → 历史层 + 封卷 + 移出自己名下
 
 - 主键 = **git 邮箱**（`git var GIT_COMMITTER_IDENT` 里的 email，退回 `git config user.email`），归一化（去空白 + 小写）后比对。
 - 读不到邮箱**不报错**：走兜底链（`USER`/`LOGNAME` → `getpass` → 主机名 → 字面 `default`）并出一条提示，命令照常跑完。看到提示要告诉用户配好 git，否则任务记到兜底身份名下。
-- `owners.json` 里的 `aliases` 会并进身份比对；`list --owner` / `history --owner` 是归一化后的**精确匹配**，没有 `me` 缩写，「自己」用 `--mine`。
+- 全站只认 git 邮箱这一个身份键；`list --owner` / `history --owner` 是归一化后的**精确匹配**，没有 `me` 缩写，「自己」用 `--mine`。
 - `close` / `log` 只对自己名下的任务生效，不在名下直接拒绝；`set --owner ""` 对已在公共池里的任务是幂等空转（退 0）；`set --owner <自己>` 会把公共池里的任务认领到自己名下。
 
 ## 历史层

package/references/troubleshooting.md

@@ -54,7 +54,10 @@
 - **「本地有未推送的台账提交：… 处理：先 git push；或者加 --no-sync 只写本地（之后要记得推）」**：没有「自动补推再写」这一步，就是让你先推。
 - **「有还没入库的同名台账文件（提交会被它们挡住）」**：同名文件还没 `git add`，先入库。
 - **「仓库处于中间态（rebase-merge / rebase-apply / MERGE_HEAD）：先跑 git status 看提示，完成或中止它（git rebase --abort / git merge --abort）再跑本命令」**：上次 rebase / merge 没收尾。
-- **「找不到台账：从当前目录往上都没有 ledger/ 目录」**：`--repo` 指对项目根；第一条写命令会自动把 `ledger/` 建出来，不用先初始化。
+- **「找不到台账：从当前目录往上都没有 ledger/ 目录」**：`--repo` 指对**工作区根**（直接含有 `ledger/` 的那个目录）；第一条写命令会自动把 `ledger/` 建出来，不用先初始化。
+- **「--repo 指到了台账目录本身」**：你把 `ledger/` 当成了根；它的上一级才是工作区根，按报错里给的路径改。
+- **「--repo 指到了台账目录里面」**：你指到了 `ledger/` 下面的某个子目录（如 `ledger/worklog`）；工作区根是那个 `ledger/` 的上一级，按报错里给的路径改。
+- **「--repo 指向的不是一个目录」**：路径写错或不存在，要指到工作区根。
 
 ### 并发 / 锁（退 1 或提示）
 

package/scripts/ledgerkit/actions/bootstrap.py

@@ -1,27 +1,30 @@
 """开工前的自举：台账文件不存在就建，没登记过就把自己登记进去、建自己的分片。
 
 这三份由**外壳**单独一个 `atom` 包住，它自己不开事务、不拿锁。
-返回 `Identity`（把索引里的 `aliases` 并进来），不参与「提交说明 / where / 打印」。
+不参与「提交说明 / where / 打印」。
 """
 
 from __future__ import annotations
 
 from pathlib import Path
 
-from ..core.identity import Identity, with_aliases
+from ..core.identity import Identity
 from ..core.paths import LEDGER_DIR, OWNERS_DIR, POOL_REL, shard_rel, to_repo_rel
+from ..core.roots import as_root
 from ..store.atomic import ensure_dir
 from ..store.owners_index import OwnersIndex
 from ..store.task_store import TaskStore
 
 
 def bootstrap(repo: Path, me: Identity) -> Identity:
-    """写序：`owners/` 目录 → 池 → 索引（登记自己）→ 我的分片。已登记且没变 ⇒ 零写。"""
-    ensure_dir(repo / to_repo_rel(LEDGER_DIR))
+    """写序：`owners/` 目录 → 池 → 索引（登记自己）→ 我的分片。已登记 ⇒ 零写。"""
+    repo = as_root(
+        repo, source="工作区根"
+    )  # 门 3：写前最后确认，绝不在 ledger/ 里再套一层
+    ensure_dir(repo / LEDGER_DIR)  # 曾是 to_repo_rel(LEDGER_DIR) ⇒ 会拼出 ledger/ledger
     ensure_dir(repo / to_repo_rel(OWNERS_DIR))
     TaskStore(repo, POOL_REL).ensure_file()
     index = OwnersIndex(repo)
-    _, record = index.ensure(me)
+    _, _ = index.ensure(me)  # 登记自己（已登记则零写）
     TaskStore(repo, shard_rel(me.email), identity=me).ensure_file()
-    aliases = tuple(record.get("aliases") or ())
-    return with_aliases(me, aliases) if aliases else me
+    return me

package/scripts/ledgerkit/actions/guard.py

@@ -20,14 +20,10 @@ from .query import ListQuery
 
 
 def current_identity(repo: Path) -> Identity:
-    """env 的本机身份 + `owners.json` 里这个身份的 `aliases`（不写盘、不登记）。"""
+    """env 的本机身份（不写盘、不登记）。全站只认邮箱这一个身份键。"""
     from .. import env
-    from ..core.identity import with_aliases
 
-    me = env.current(repo)
-    record = OwnersIndex(repo).get(me.email) or {}
-    aliases = tuple(record.get("aliases") or ())
-    return with_aliases(me, aliases) if aliases else me
+    return env.current(repo)
 
 
 def require_task(tasks: Mapping[str, Any], tid: str, *, where: Path) -> dict[str, Any]:
@@ -72,7 +68,7 @@ def status_of(task: Mapping[str, Any]) -> str:
 
 
 def is_mine(task: Mapping[str, Any], me: Identity) -> bool:
-    """这条任务是不是我的（含 aliases）。"""
+    """这条任务是不是我的（按邮箱判定）。"""
     return is_me(me, owner_of(task) or "")
 
 

package/scripts/ledgerkit/actions/query_history.py

@@ -127,8 +127,7 @@ def query_history(repo: Path, me: Identity, q: HistoryQuery) -> HistoryResult:
             records.append(row)
 
     if q.mine:
-        wanted = {k for k in (me.email, *me.aliases) if k}
-        wanted = {normalize(k) for k in wanted}
+        wanted = {normalize(me.email)}
         records = [r for r in records if normalize(r.get("owner") or "") in wanted]
     elif q.owner:
         key = normalize(q.owner)

package/scripts/ledgerkit/actions/validate.py

@@ -14,7 +14,13 @@ 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.paths import (
+    LEDGER_DIR,
+    LEGACY_HISTORY_REL,
+    OWNERS_REL,
+    POOL_REL,
+    to_repo_rel,
+)
 from ..core.time import now
 from ..core.worklog_md import (
     duplicated_sections,
@@ -199,6 +205,12 @@ def validate(repo: Path, me: Identity, deep: bool = False) -> ValidationReport:
         notices.append(f"存量平铺文件 {rel(repo, legacy)} 只读兼容，不会重写。")
     if not (repo / to_repo_rel(OWNERS_REL)).exists():
         notices.append("还没有 owners.json（索引）：跑一条写命令会自动建。")
+    stray = repo / LEDGER_DIR / LEDGER_DIR
+    if stray.is_dir():
+        problems.append(
+            f"{rel(repo, stray)} 是错位的台账目录（根被当成 ledger/ 时写出来的幻影）；"
+            "确认哪份是真台账后删掉多余的，命令一律带 --repo <工作区根>。"
+        )
 
     return ValidationReport(
         problems=tuple(problems),

package/scripts/ledgerkit/core/identity.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass, replace
+from dataclasses import dataclass
 
 
 @dataclass(frozen=True)
@@ -11,7 +11,6 @@ class Identity:
 
     email: str
     name: str = ""
-    aliases: tuple[str, ...] = ()
 
     def label(self) -> str:
         """显示名：没名字就用邮箱。"""
@@ -23,21 +22,6 @@ 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))
+    """`who`（邮箱）是不是这个人。全站只认邮箱这一个身份键。"""
+    return normalize(who or "") == normalize(identity.email)

package/scripts/ledgerkit/core/roots.py

@@ -0,0 +1,74 @@
+"""工作区根的判定：哪个目录才是「直接含有 `ledger/` 的那个根」。
+
+全仓唯一实现 —— `shell/` 与 `actions/` 都调这里，不各写一份（否则口径会漂）。
+判据是**结构**（含不含 `ledger/`、自己在不在 `ledger/` 里），不看目录里有哪些文件：
+项目根自带 `pool.json`、`history/` + `worklog/`、`owners.json` + `owners/` 这类同名文件
+或目录都很常见，按「里面有什么」判会把正常项目根误当成台账目录（2026-10-25 改）。
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from ..errors import Fail
+from .paths import LEDGER_DIR
+
+
+def _under_ledger(p: Path) -> bool:
+    """`p` 自己叫 `ledger`，或它落在某个 `ledger/` 目录里面。"""
+    if p.name == LEDGER_DIR.name:
+        return True
+    return any(anc.name == LEDGER_DIR.name for anc in p.parents)
+
+
+def as_root(repo: str | Path, *, source: str = "--repo") -> Path:
+    """校验「工作区根」，只看结构：
+
+    - 直接含 `ledger/` ⇒ 就是根。哪怕项目根自己叫 `ledger`、哪怕它自己也有 `pool.json`；
+    - 不含 `ledger/`、但自己叫 `ledger` 或落在某个 `ledger/` 下 ⇒ 是台账目录 / 台账里面，拒；
+    - 其余（含全新空目录）⇒ 收，第一条写命令会在它下面建 `ledger/`。
+    """
+    p = Path(repo).expanduser()
+    if not p.is_dir():
+        raise Fail(
+            f"{source} 指向的不是一个目录：{p}\n"
+            f"  处理：指向工作区根（直接含有 ledger/ 的那个目录，不是 ledger/ 本身）。"
+        )
+    if (p / LEDGER_DIR).is_dir():
+        return p.resolve()
+    if _under_ledger(p):
+        anc = next(a for a in (p, *p.parents) if a.name == LEDGER_DIR.name)
+        root = anc.parent
+        if anc is p:
+            what = f"指到了台账目录本身：{p}"
+            why = f"它的上一级 {root} 才是工作区根 —— 在它下面跑会再建出 {p / LEDGER_DIR}。"
+        else:
+            what = f"指到了台账目录里面：{p}"
+            why = f"它已经在 {anc} 这个台账目录底下 —— 工作区根是 {anc.parent}。"
+        raise Fail(
+            f"{source} {what}\n"
+            f"  {why}\n"
+            f"  处理：把 {source} 指到 {root}\n"
+            f"      例：progress.py list --repo {root}"
+        )
+    return p.resolve()
+
+
+def root_of(start: str | Path) -> Path | None:
+    """从 `start` 往上定位工作区根；找不到返回 None。
+
+    ① 自己在台账目录里（名字叫 `ledger`、且里面没有再套一层 `ledger/`）⇒ 根是它的上一级。
+       按位置判，不看里面有什么：项目根自带 `history/` + `worklog/` 不会被误当成台账目录。
+    ② 兜底：从**自己**开始往上，取最近的、直接含 `ledger/` 的目录。`start` 必须优先于
+       祖先，否则工作区根恰好叫 `ledger` 时会被父目录抢走（2026-10-25 改）。
+    """
+    here = Path(start).resolve()
+    for anc in (here, *here.parents):
+        if anc.name == LEDGER_DIR.name and not (anc / LEDGER_DIR).is_dir():
+            root = anc.parent
+            if (root / LEDGER_DIR).is_dir():
+                return root
+    for cand in (here, *here.parents):
+        if (cand / LEDGER_DIR).is_dir():
+            return cand
+    return None

package/scripts/ledgerkit/env.py

@@ -90,4 +90,4 @@ def current(repo: Path | None = None) -> Identity:
             "配好 git config user.email 再跑，任务才会记到正确的名下。"
         )
     name = git_name(repo) or email
-    return Identity(email=normalize(email), name=name.strip(), aliases=())
+    return Identity(email=normalize(email), name=name.strip())

package/scripts/ledgerkit/shell/cli.py

@@ -12,7 +12,7 @@ import sys
 from pathlib import Path
 
 from ..actions.query import HistoryQuery, ListQuery
-from ..core.paths import LEDGER_DIR
+from ..core.roots import as_root, root_of
 from ..core.time import to_utc
 from ..errors import BUSINESS, USAGE, Fail
 from . import render, runner
@@ -27,7 +27,7 @@ def build_parser() -> argparse.ArgumentParser:
         prog="progress.py", description="任务台账（本地文件 + git 同步）"
     )
     parser.add_argument(
-        "--repo", help="台账所在仓库（默认按当前目录向上找含 ledger/ 的目录）"
+        "--repo", help="工作区根（直接含有 ledger/ 的那个目录；默认按当前目录向上找）"
     )
     parser.add_argument(
         "--no-sync", action="store_true", help="只写本地，不取最新 / 不提交 / 不推送"
@@ -169,22 +169,22 @@ def _split_tags(value: str | None) -> tuple[str, ...]:
 
 
 def resolve_repo(arg: str | None, start: Path | None = None) -> Path:
-    """`--repo` 给了就用；没给就从 `start`（默认 cwd）往上找含 `ledger/` 的目录。
+    """`--repo` 给了就校验后用；没给就从 `start`（默认 cwd）往上找。
 
     找不到 ⇒ Fail：绝不在当前目录自作主张建台账（2026-10-22 设计定稿）。
     建台账是第一条写命令的事，不需要、也没有 `init` 子命令。
     """
     if arg:
-        return Path(arg)
+        return as_root(arg, source="--repo")
     here = (start or Path.cwd()).resolve()
-    for candidate in (*here.parents, here):
-        if (candidate / LEDGER_DIR).is_dir():
-            return candidate
-    raise Fail(
-        "找不到台账：从当前目录往上都没有 ledger/ 目录。\n"
-        "  处理：回到项目根再跑；或用 --repo <项目根> 指定。\n"
-        "  第一条写命令会自动把 ledger/ 建出来，不用先初始化。"
-    )
+    root = root_of(here)
+    if root is None:
+        raise Fail(
+            "找不到台账：从当前目录往上都没有 ledger/ 目录。\n"
+            "  处理：用 --repo <工作区根> 指定（根是直接含 ledger/ 的那个目录，不是 ledger/ 本身）；\n"
+            "  或先 cd 到项目根再跑。第一条写命令会自动把 ledger/ 建出来，不用先初始化。"
+        )
+    return root
 
 
 def _repo_of(args: argparse.Namespace) -> Path:

package/scripts/ledgerkit/shell/render.py

@@ -41,6 +41,12 @@ def fail_message(exc: BaseException, *, title: str = "错误") -> None:
     _err(f"{title}：{exc}")
 
 
+def repo_banner(repo: Any, *, machine: bool) -> None:
+    """只读命令开头自报「读的是哪个台账」（输出是 JSON 时不打，否则污染机器可读结果）。"""
+    if not machine:
+        _out(f"台账：{repo}")
+
+
 def _json(data: Any) -> None:
     sys.stdout.write(json.dumps(data, ensure_ascii=False, indent=2) + "\n")
 

package/scripts/ledgerkit/shell/runner.py

@@ -91,6 +91,11 @@ def _run(command: str, args: argparse.Namespace, log: dirty.WriteLog) -> int:
     # 只读：不建 GitRepo、不进事务、不提交
     if spec.readonly:
         value = spec.func(repo, me, **params)
+        # 先自报读的是哪个台账：`--repo` 指错目录时输出会变成一片「没有任务」，不带这一行
+        # 就完全看不出读错了地方。`--count-only` 也出 JSON，同样不打（2026-10-25 改）
+        render.repo_banner(
+            repo, machine=as_json or bool(getattr(args, "count_only", False))
+        )
         _render(spec, value, args, as_json=as_json)
         if getattr(value, "problems", ()):
             return BUSINESS  # validate 有 problems ⇒ 退出码 1（§六）
@@ -219,7 +224,9 @@ def _repo_of(args: argparse.Namespace) -> Path:
     """
     repo = getattr(args, "repo", None)
     if repo:
-        return Path(repo)
+        from ..core.roots import as_root  # 门 2 兜底：绕过 cli 直调 runner 也不收错位根
+
+        return as_root(repo, source="--repo")
     from .cli import resolve_repo  # 延迟导入：cli 在模块层 import runner
 
     return resolve_repo(None)

package/scripts/ledgerkit/store/owners_index.py

@@ -1,7 +1,6 @@
 """索引 `owners.json`：谁是登记过的人、各自的分片文件是哪个、新人的登记与改名。
 
 **分片只认索引，不扫目录** —— 唯一例外是全仓仅此一处的 `disk_shards()`，它只给 `validate` 用。
-`ensure` 是 `aliases` 的唯一写入点。
 """
 
 from __future__ import annotations
@@ -32,7 +31,7 @@ class OwnersIndex:
         return self._store.all()
 
     def ensure(self, me: Identity) -> tuple[bool, dict[str, Any]]:
-        """登记 / 补 `joined` / 名字或 aliases 变了才写。返回 (这次写了没有, 记录)。"""
+        """登记 / 补 `joined`。`name` 只在首次登记时写入，之后不回写（名字是给你做对照的被动字段，不该被任何逻辑读）。返回 (这次写了没有, 记录)。"""
         key = normalize(me.email)
         with self._open() as session:
             data = session.data
@@ -43,23 +42,11 @@ class OwnersIndex:
                     "file": shard_rel(key).name,
                     "name": me.name,
                     "joined": now(),
-                    "aliases": _merge_aliases([], me.aliases),
                 }
                 workers[key] = record
                 session.mark()
                 return True, dict(record)
-            changed = False
-            if me.name and record.get("name") != me.name:
-                record["name"] = me.name
-                changed = True
-            known = list(record.get("aliases") or [])
-            aliases = _merge_aliases(known, me.aliases)  # 只增不删
-            if aliases != known:
-                record["aliases"] = aliases
-                changed = True
-            if changed:
-                session.mark()
-            return changed, dict(record)
+            return False, dict(record)
 
     def shards(self) -> dict[str, Path]:
         """身份 → 分片绝对路径（只信索引）。"""
@@ -125,11 +112,3 @@ class _IndexSession:
             self.store._flush(self.data)  # 同一个包内的受控写回口
 
 
-def _merge_aliases(known: list, extra: tuple[str, ...] | list[str]) -> list[str]:
-    """把新别名并进去，只增不删、去重保序。"""
-    out = list(known)
-    for alias in extra or ():
-        key = normalize(alias)
-        if key and key not in out:
-            out.append(key)
-    return out

package/scripts/ledgerkit/store/task_store.py

@@ -22,10 +22,7 @@ class TaskStore(JSONStore):
         self.identity = identity
 
     def _flush(self, data: dict[str, Any]) -> None:
-        """写盘时带上分片顶部的 `identity`（只改格式，不动任务内容）。"""
+        """写盘时带上分片顶部的 `identity`（只存邮箱；显示名在索引里）。"""
         if self.identity is not None:
-            data["identity"] = {
-                "email": self.identity.email,
-                "name": self.identity.name,
-            }
+            data["identity"] = {"email": self.identity.email}
         super()._flush(data)