task-ledger 1.2.2 → 1.2.4

package/README.md

@@ -118,7 +118,9 @@
 - 临时文件名唯一（`mkstemp`），写完 `fsync` 再 `os.replace`，无论成败都清理临时文件
 - key 按字母序落盘，减少两人同时新增时的文本冲突
 - 冲突时**报错要求重跑**，不静默覆盖
-- 脚本里**没有任何** `git pull` / `rebase` / `commit` —— 冲突不要靠拉取去"解决"
+- 写入成功后脚本会**自动同步**：把本次改动的台账文件 `git add <精确文件>` + `commit`（消息 `ledger(<命令>): <提交者>`）；当前分支有上游跟踪分支时再 `push`。全程确定性脚本，不依赖大模型
+- 无 git 仓库 / 无上游跟踪 / 被 `.gitignore` 排除 / 无实际变更 都会静默跳过；`--no-sync` 或环境变量 `TASK_LEDGER_NO_SYNC=1` 可关闭
+- 冲突**仍不靠 `git pull` / `rebase` 解决**：并发靠指纹复查 + 原子写防覆盖，冲突时**报错要求重跑**，不静默合并
 
 ### 结案是原子操作
 
@@ -192,7 +194,8 @@ stateDiagram-v2
     note right of doing
         set --owner 交接：owner 换成别人
         （只有当前 owner 能执行）
-        阻塞 = 接任务满 7 天；停滞 = 最后更新满 3 天
+        超期 = 接任务满 14 天；停滞 = 最后更新满 3 天
+        积压 = 待认领满 30 天
         （都由看板按时间算，不是状态）
     end note
 ```

package/SKILL.md

@@ -34,7 +34,7 @@ allowed-tools: Read,Write,Bash,Grep
 | 「谁在做 X」「有哪些在办」 | `list`；在等认领的加 `--status open` |
 | 「这个任务到哪一步了」「这轮做了什么」 | `show --id`（任务 JSON + worklog 全文） |
 | 「某件老活什么时候做的」「谁做过哪些活」 | `history`（可按 `--owner` / `--since` 筛） |
-| 「哪些任务停太久」 | `list --json`：`updated` 满 3 天＝停滞、`started` 满 7 天＝阻塞（看板算，别改状态） |
+| 「哪些任务停太久」 | `list --json`：`updated` 满 3 天＝停滞、`started` 满 14 天＝超期、`created` 满 30 天仍 `open`＝积压（看板算，别改状态） |
 | 「新建一个任务」 | `new`（`--self` = 建完即认领） |
 | 「这活我领了」 | `claim`（只对 `open` 有效） |
 | 「开始做 / 接着做 X」 | 还是 `open` 就先 `claim`；已是 `doing` 就直接改正文 + `log` |
@@ -61,7 +61,7 @@ python3 <本 SKILL.md 所在目录>/scripts/progress.py <子命令> --repo <当
 
 ## 铁律
 
-- **状态只有 `open` / `doing`**；`done` 只能由 `close` 产生。**没有 `blocked` 状态**：阻塞 = `started` 满 7 天、停滞 = `updated` 满 3 天，都由看板按时间算，`progress.json` 里不存、不手改；卡在哪写进正文。
+- **状态只有 `open` / `doing`**；`done` 只能由 `close` 产生。**没有 `blocked` 状态**：超期 = `started` 满 14 天、停滞 = `updated` 满 3 天、积压 = `created` 满 30 天且仍 `open`，都由看板按时间算，`progress.json` 里不存、不手改；卡在哪写进正文。
 - **`log` 就是刷新 `updated` 的动作**：该记不记，任务会被看板标成停滞。
 - **owner = 当前 `git config user.name`**，不能由外部传入；读不到就报错（先让用户配 git）。**只能动自己名下**的任务（`open` 的先 `claim`），不是你的直接拒绝 —— 不要绕过脚本改 JSON。
 - **换人只能「释放 → 认领」**：skill 不提供交接，随便写的名字都是假的。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-ledger",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "Task-ledger skill for coding agents: per-workspace progress tracking (ledger/progress.json, 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

@@ -1,6 +1,6 @@
 # 状态与时间模型
 
-> TL;DR：状态只有 `open` / `doing`；`done` 由 `close` 产生。阻塞 = `started` 满 7 天、停滞 = `updated` 满 3 天，看板算、不存字段。`updated` 由 `new/claim/set/log` 刷新。owner 只取当前 git 身份。
+> TL;DR：状态只有 `open` / `doing`；`done` 由 `close` 产生。超期 = `started` 满 14 天、停滞 = `updated` 满 3 天、积压 = `created` 满 30 天仍 `open`，看板算、不存字段。`updated` 由 `new/claim/set/log` 刷新。owner 只取当前 git 身份。
 
 ## 状态机
 
@@ -12,15 +12,16 @@ doing ──set --status open──> open          # 释放认领，执行记录
 - `open`：已建、等认领。`doing`：已认领、在做。`done` 只由 `close` 产生。
 - **没有 `blocked` 状态**（2026-10-19 取消）。旧数据里残留的 `blocked` 读侧当进行中：`list --status blocked` 可捞出，用 `set --status doing` 归位；新写入一律拒绝。
 
-## 两个标记（看板计算，不是状态）
+## 三个标记（看板计算，不是状态）
 
 | 标记 | 依据 | 阈值 |
 |---|---|---|
-| 阻塞 | `started`（接任务）至今，中途更新不影响 | 满 7 天 |
+| 积压 | `created`（建了）至今仍 `open`（没人认领） | 满 30 天 |
+| 超期 | `started`（接任务）至今，中途更新不影响 | 满 14 天 |
 | 停滞 | `updated`（最后推进）至今 | 满 3 天 |
 
-- 真源：`packages/plugin/src/host/services/home.service.ts` 的 `OVERDUE_DAYS = 7` / `STALE_DAYS = 3`；看板随响应下发 `staleDays`，界面文案不硬编码。
-- 脚本不算这两个值，`progress.json` 里也不存；agent 要回答「哪些停太久」时用 `list --json` 的 `updated` / `started` 与当前时间比。
+- 真源：`packages/plugin/src/host/services/home.service.ts` 的 `BACKLOG_DAYS = 30` / `OVERDUE_DAYS = 14` / `STALE_DAYS = 3`；看板随响应下发三个天数，界面文案不硬编码。
+- 脚本不算这三个值，`progress.json` 里也不存；agent 要回答「哪些停太久」时用 `list --json` 的 `created` / `updated` / `started` 与当前时间比。
 - 老数据没有 `updated` 时，读侧回退到 `started`，再到 `created`。
 
 ## 时间

package/scripts/progress.py

@@ -38,7 +38,7 @@ except ImportError:
     msvcrt = None
 
 STATUSES = ("open", "doing")
-# 旧数据只读兼容：早期版本有 blocked 状态（手动标「卡住」）。现在阻塞按时间判定
+# 旧数据只读兼容：早期版本有 blocked 状态（手动标「卡住」）。现在超期按时间判定
 # （接任务满 7 天），不再允许新写入；list / validate / 看板仍能吃老文件。
 LEGACY_STATUSES = ("blocked",)
 PROGRESS_REL = Path("ledger/progress.json")
@@ -245,6 +245,10 @@ def read_json(path: Path) -> dict[str, Any]:
     return data
 
 
+# 本次进程内被台账写入的真实文件路径，供写成功后一次性自动同步（git commit/push）。
+CHANGED_FILES: list[Path] = []
+
+
 def write_text_atomic(path: Path, text: str) -> None:
     """原子写文本：同目录唯一临时名 + fsync + os.replace，写完清理临时文件。
 
@@ -265,6 +269,7 @@ def write_text_atomic(path: Path, text: str) -> None:
             fh.flush()
             os.fsync(fh.fileno())
         os.replace(tmp, path)
+        CHANGED_FILES.append(path)  # 记下本次改动，供写后自动同步
         tmp = None
     except OSError as exc:
         raise Fail(f"写 {path} 失败：{exc}")
@@ -349,6 +354,68 @@ def commit_guarded(
     write_json(path, data)
 
 
+def _git(*args: str, timeout: int | None = None) -> subprocess.CompletedProcess:
+    """跑一条 git 命令，吞掉输出（同步用，不污染 stdout）。"""
+    return subprocess.run(list(args), capture_output=True, text=True, timeout=timeout)
+
+
+def _git_actor(repo_root: str) -> str:
+    """提交者：复用 git 身份；取不到用占位，不阻断提交。"""
+    out = _git("git", "-C", repo_root, "config", "user.name")
+    return out.stdout.strip() or "ledger-script"
+
+
+def git_sync(action: str) -> None:
+    """写成功后调用一次：把本次改动的台账文件提交；有上游跟踪分支则推送。
+
+    纯脚本、确定性，不依赖大模型。无 git / 无上游 / 全被 ignore / 无实际变更 都静默跳过。
+    同步是尽力而为：任何异常都不影响已完成的台账写入（只打印提示）。
+    """
+    if os.environ.get("TASK_LEDGER_NO_SYNC"):
+        return
+    try:
+        files = [p for p in CHANGED_FILES if p.exists()]
+        if not files:
+            return
+        # 从任一文件反查仓库根，不依赖调用方透传 --repo
+        top = _git("git", "-C", str(files[0].parent), "rev-parse", "--show-toplevel")
+        if top.returncode != 0:
+            return  # 不是 git 项目 → 跳过（规则1：有才提交）
+        root = top.stdout.strip()
+        # 只 add 本次真实改动、且未被 ignore 的文件
+        to_add = [
+            str(f)
+            for f in files
+            if _git("git", "-C", root, "check-ignore", "-q", str(f)).returncode != 0
+        ]
+        if not to_add:
+            return  # 全被 ignore → 尊重用户选择，不强行提交
+        _git("git", "-C", root, "add", *to_add)
+        if _git("git", "-C", root, "diff", "--cached", "--quiet").returncode == 0:
+            return  # 无实际变更
+        actor = _git_actor(root)
+        _git("git", "-C", root, "commit", "-m", f"ledger({action}): {actor}")
+        # 规则2：有上游跟踪分支才推
+        if _git("git", "-C", root, "rev-parse", "--abbrev-ref", "@{upstream}").returncode != 0:
+            return
+        try:
+            _git("git", "-C", root, "push", timeout=30)
+        except (subprocess.CalledProcessError, subprocess.TimeoutExpired):
+            # 非快进：自动 rebase 一次再推；冲突 / 超时则放弃，绝不 --force
+            try:
+                _git("git", "-C", root, "pull", "--rebase", "--autostash", timeout=30)
+                _git("git", "-C", root, "push", timeout=30)
+            except (subprocess.CalledProcessError, subprocess.TimeoutExpired):
+                print(
+                    "提示：本地已提交，但推送被拒（他人已推 / 需认证 / 超时）。"
+                    "请手动 `git pull --rebase` 解决后重试；本次改动已安全留在本地。",
+                    file=sys.stderr,
+                )
+    except Exception as exc:  # noqa: BLE001 —— 同步失败不应污染台账主流程
+        print(f"提示：写后自动同步未执行（{type(exc).__name__}: {exc}）。数据已写入本地。",
+              file=sys.stderr)
+
+
 def require_task_id(tid: str) -> str:
     """任务号会参与拼路径，任何命令拿到它都要先验一遍。"""
     if not ID_RE.fullmatch(tid):
@@ -1364,7 +1431,7 @@ def cmd_set(args: argparse.Namespace) -> None:
         )
     if status == "blocked":
         raise Fail(
-            "没有 blocked 状态：阻塞由时间自动判定（接任务满 7 天仍未结案），"
+            "没有 blocked 状态：超期由时间自动判定（接任务满 14 天仍未结案），"
             "状态只有 open / doing；卡在哪里请写进 worklog。"
         )
     if status == "done":
@@ -2070,6 +2137,11 @@ def build_parser() -> argparse.ArgumentParser:
         prog="progress.py",
         description="管理项目任务进度（ledger/progress.json + worklog + 历史）",
     )
+    parser.add_argument(
+        "--no-sync",
+        action="store_true",
+        help="跳过写后自动 git 提交 / 推送（等价于 TASK_LEDGER_NO_SYNC=1）",
+    )
     sub = parser.add_subparsers(dest="command", required=True)
 
     def add_repo(p: argparse.ArgumentParser) -> None:
@@ -2202,6 +2274,8 @@ def build_parser() -> argparse.ArgumentParser:
 
 def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
+    if getattr(args, "no_sync", False):
+        os.environ["TASK_LEDGER_NO_SYNC"] = "1"
     try:
         args.func(args)
     except Fail as exc:
@@ -2221,6 +2295,7 @@ def main(argv: list[str] | None = None) -> int:
     except Exception as exc:  # noqa: BLE001 —— 兜底：未预期的失败用独立退出码，与业务错误区分
         print(f"错误：未预期的失败 {type(exc).__name__}: {exc}", file=sys.stderr)
         return 3
+    git_sync(args.command)  # 写成功后一次性自动同步（commit / push）
     return 0