task-ledger 1.3.2 → 1.3.4

package/README.md

@@ -31,10 +31,10 @@
 直接跑：
 
 ```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`（不要凭记忆编）。
+子命令：`new` `claim` `set` `log` `close` `list` `history` `show` `validate`。命令参考（参数 / 一句话 / 举例）、任务生命周期、纪律（数据完整性 / 人类授权 / 故障处置）全在 `SKILL.md`；参数细节看 `<子命令> --help`（不要凭记忆编）。
 
 ## 深入参考（references/，按需读）
 

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: task-ledger
 description: 本地任务台账，跨会话记录在办任务的归属、进度与起止。当用户要登记一件新的事（新建任务 / 建个坑 / 这活我领了）、记录已有任务的进展（接着做 / 记一条进展 / 这轮先记下）、查看任务状态或历史（现在该做什么 / 这活谁在做 / 上周做过什么）、给任务结案或退回（做完了 / 验收通过 / 不做了 / 退回待认领）、整理标签或检查台账一致性时加载；只是改代码、讨论方案时不要用。
-version: 1.3.0
+version: 1.3.4
 allowed-tools: Read,Edit,Bash,Grep
 ---
 
@@ -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` 为准。
@@ -145,7 +145,7 @@ python3 <本 SKILL.md 所在目录>/scripts/progress.py <子命令> --repo <当
 
 1. **建（只建，不认领）—— 默认**：「新建一个任务」「新建个任务，我们来干 X」「新建个任务，我需要处理 Y」→ `new --title "…"`。落公共池、待认领。
 2. **建并认领 —— 仅限明确说法**：用户明确说「新建一个任务**并开始做 / 并执行**」这类带着「现在就开始」的话 → `new --title "…" --self`。直接归自己名下、「进行中」。**除这种明确说法，其他一律按第 1 条只建** —— 别替用户决定他要开始做；拿不定，问一句。
-3. **找已有的**：用户说「我们来做 X」→ 先 `list --mine` 找自己名下的，在做的直接接着做；没有 → `list --pool` 里找，找到先问用户：「X 还没认领，认领它吗？」→ 用户点头再 `claim`；哪儿都没有 → 按第 1/2 条的判定规则建。
+3. **找已有的**：用户说「我们来做 X」→ 先 `list --mine` 找自己名下的，在做的直接接着做；没有 → `list --pool` 里找，找到先问用户：「X 还没认领，认领它吗？」→ 用户点头再 `claim`；哪儿都没有 → **不擅自建**：问「要为 X 建个任务吗？」，同意才按第 1/2 条建，不同意就只干活、不登记。
 4. **认领**：`claim --id <任务号>` —— 认到自己名下，状态即「进行中」。
 5. **推进**：改 worklog 前五节 → 按「过程文档」节的收工三步记 `log`。卡住也 `log`（写清卡在哪，状态不动）；「先放一放」同理 —— 是暂停，不是释放。
 6. **交付待验收**：任务留「进行中」，「待办」写「待用户验收」，「下一步」写清验收看什么；照收工三步记一条 `log --note "已交付待验收：…"`。
@@ -193,11 +193,11 @@ python3 <本 SKILL.md 所在目录>/scripts/progress.py <子命令> --repo <当
 
 ### 人类授权（跑之前问不问）
 
-项目没有 `ledger/` ⇒ 先问「要不要建个台账记这活？」，不许自建。用户同意 ⇒ 直接跑第一条写命令，且**必须带 `--repo <项目根>`**：不带时脚本只从当前目录逐级往上找第一个含 `ledger/` 的目录，一个都没有就退 1 报「找不到台账」，绝不就地建；台账由这条写命令顺带建出来，没有 `init` 命令。之后可以不带 `--repo`，但查找是**逐级往上**的 —— 在本项目的子目录里跑可能命中上层项目的台账，拿不准就一直带 `--repo <项目根>`。
+项目没有 `ledger/` ⇒ 先问「要不要建个台账记这活？」，不许自建。用户同意 ⇒ 直接跑第一条写命令，且**必须带 `--repo <工作区根>`**（根是直接含有 `ledger/` 的那个目录，`ledger/` 本身不是根、指到它会被拒绝）：不带时脚本只从当前目录逐级往上找第一个含 `ledger/` 的目录，一个都没有就退 1 报「找不到台账」，绝不就地建；台账由这条写命令顺带建出来，没有 `init` 命令。之后可以不带 `--repo`，但查找是**逐级往上**的 —— 在本项目的子目录里跑可能命中上层项目的台账，拿不准就一直带 `--repo <工作区根>`。
 
 | 命令 | 档位 | 要求 |
 |---|---|---|
-| `new` / `claim` / `set` | 动手类 | 执行前把完整参数复述给用户并取得确认 |
+| `new` / `claim` / `set` | 动手类 | 执行前复述完整参数并取得确认；**`new` 仅当用户原话点名要建且标题可直取原话时免复述**，标题需另拟或拿不准仍复述一次（`claim`/`set` 一律复述） |
 | `log` | 免确认 | 本任务的推进 / 卡点 / 交付记录直接跑，跑完一句话交代「已记执行记录：…」；要替用户下结论，先问（任务不在自己名下会直接被拒） |
 | `close` | 独立授权 | 仅认明确说「结束掉 / close 掉」（完整判定见生命周期第 8 条）；说得含糊必须反问「是要结束这个任务吗？」；**agent 自判「干完了」不算** |
 | `list` / `show` / `history` / `validate` | 只读 | 直接跑 |

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "task-ledger",
-	"version": "1.3.2",
+	"version": "1.3.4",
 	"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/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

@@ -10,6 +10,7 @@ from pathlib import Path
 
 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
@@ -17,7 +18,10 @@ from ..store.task_store import TaskStore
 
 def bootstrap(repo: Path, me: Identity) -> Identity:
     """写序：`owners/` 目录 → 池 → 索引（登记自己）→ 我的分片。已登记 ⇒ 零写。"""
-    ensure_dir(repo / to_repo_rel(LEDGER_DIR))
+    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)

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/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/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)