@hupan56/wlkj 3.0.0 → 3.1.3

package/templates/qoder/scripts/{task → domain/task}/task_relations.py

@@ -1,424 +1,425 @@
-#!/usr/bin/env python3
-# -*- coding: utf-8 -*-
-"""task_relations.py - task 关系/排期层 (v3.0 f6 从 task.py 拆出)"""
-# v3.0 路径自举
-import os as _o, sys as _s, argparse
-from pathlib import Path
-from datetime import datetime
-_cp = _o.path.join(_o.path.dirname(_o.path.dirname(_o.path.abspath(__file__))), 'common')
-if _cp not in _s.path: _s.path.insert(0, _cp)
-from bootstrap import setup; setup()
-
-import os, sys, json, shutil
-from datetime import datetime
-from pathlib import Path
-from common.paths import (
-    DIR_TASKS, DIR_ARCHIVE, FILE_TASK_JSON,
-    get_repo_root, get_developer, get_tasks_dir,
-)
-from common.active_task import (
-    clear_active_task, resolve_active_task, resolve_context_key, set_active_task,
-)
-from common.task_utils import (
-    resolve_task_dir, run_task_hooks, load_task_json, write_task_json,
-    modify_task_json, assert_can_modify_task,
-)
-from common.atomicio import atomic_write_json, safe_read_json, atomic_write_text
-
-
-def cmd_add_subtask(args: argparse.Namespace) -> int:
-    """添加子任务关联。"""
-    repo_root = get_repo_root()
-    parent_dir = resolve_task_dir(args.parent, repo_root)
-    child_dir = resolve_task_dir(args.child, repo_root)
-
-    if not parent_dir.is_dir():
-        print(f"Error: Parent task not found: {args.parent}", file=sys.stderr)
-        return 1
-    if not child_dir.is_dir():
-        print(f"Error: Child task not found: {args.child}", file=sys.stderr)
-        return 1
-
-    # 零信任 ACL: 只有 parent 的 creator/assignee/admin 能加子任务
-    try:
-        assert_can_modify_task(parent_dir, "add-subtask", repo_root)
-    except PermissionError as e:
-        print(str(e), file=sys.stderr)
-        return 4
-
-    parent_data = load_task_json(parent_dir)
-    child_data = load_task_json(child_dir)
-
-    if not parent_data or not child_data:
-        print("Error: Missing task.json", file=sys.stderr)
-        return 1
-
-    child_name = child_dir.name
-    children = parent_data.get("children", [])
-    if child_name not in children:
-        children.append(child_name)
-        parent_data["children"] = children
-        parent_data["updated_at"] = datetime.now().isoformat()
-        write_task_json(parent_dir, parent_data)
-
-    # 子任务记录父任务
-    child_data["parent"] = parent_dir.name
-    child_data["updated_at"] = datetime.now().isoformat()
-    write_task_json(child_dir, child_data)
-
-    print(f"Subtask added: {parent_dir.name} -> {child_dir.name}")
-    return 0
-
-
-def cmd_remove_subtask(args: argparse.Namespace) -> int:
-    """移除子任务关联。"""
-    repo_root = get_repo_root()
-    parent_dir = resolve_task_dir(args.parent, repo_root)
-    child_dir = resolve_task_dir(args.child, repo_root)
-
-    # 零信任 ACL
-    if parent_dir.is_dir():
-        try:
-            assert_can_modify_task(parent_dir, "remove-subtask", repo_root)
-        except PermissionError as e:
-            print(str(e), file=sys.stderr)
-            return 4
-
-    parent_data = load_task_json(parent_dir)
-    child_data = load_task_json(child_dir)
-
-    if parent_data:
-        children = parent_data.get("children", [])
-        if child_dir.name in children:
-            children.remove(child_dir.name)
-            parent_data["children"] = children
-            parent_data["updated_at"] = datetime.now().isoformat()
-            write_task_json(parent_dir, parent_data)
-
-    if child_data:
-        child_data["parent"] = None
-        child_data["updated_at"] = datetime.now().isoformat()
-        write_task_json(child_dir, child_data)
-
-    print(f"Subtask removed: {parent_dir.name} -x- {child_dir.name}")
-    return 0
-
-
-# =============================================================================
-# 工具函数
-# =============================================================================
-
-def _generate_slug(title: str) -> str:
-    """从标题生成 URL-safe slug。"""
-    # 简单处理: 小写, 空格转连字符, 只保留字母数字和连字符
-    slug = title.lower().strip()
-    slug = "".join(c if c.isalnum() or c in " -_" else "" for c in slug)
-    slug = slug.replace(" ", "-").replace("_", "-")
-    slug = "-".join(part for part in slug.split("-") if part)
-    return slug[:50] if slug else "untitled"
-
-
-# =============================================================================
-# 命令: set-due / block / unblock / gantt (B2 能力增强)
-# =============================================================================
-
-def cmd_set_due(args: argparse.Namespace) -> int:
-    """设置任务截止日期。用法: task.py set-due <task> <YYYY-MM-DD>"""
-    repo_root = get_repo_root()
-    full_path = resolve_task_dir(args.task, repo_root)
-    if not full_path.is_dir():
-        print(f"Error: Task not found: {args.task}", file=sys.stderr)
-        return 1
-    # ACL
-    try:
-        assert_can_modify_task(full_path, "set-due", repo_root)
-    except PermissionError as e:
-        print(str(e), file=sys.stderr)
-        return 4
-    def _set_due_mutator(data):
-        data["due_date"] = args.due_date
-        data["updated_at"] = datetime.now().isoformat()
-    if not modify_task_json(full_path, _set_due_mutator):
-        print("Error: Missing task.json", file=sys.stderr)
-        return 1
-    print(f"Set due_date: {args.due_date} ({full_path.name})")
-    return 0
-
-
-def cmd_reassign(args: argparse.Namespace) -> int:
-    """改派任务负责人。用法: task.py reassign <task> <new_assignee>
-
-    场景: PM 建任务后改派给开发(多角色协作必需)。
-    ACL: 只有 creator/admin 能改派(防恶意抢占/甩锅)。
-    保留改派历史(assignee_history), 便于追溯。
-    """
-    repo_root = get_repo_root()
-    full_path = resolve_task_dir(args.task, repo_root)
-    if not full_path.is_dir():
-        print(f"Error: Task not found: {args.task}", file=sys.stderr)
-        return 1
-    # ACL: 只有 creator/admin 能改派 (assignee 自己不能转手甩锅)
-    try:
-        assert_can_modify_task(full_path, "reassign", repo_root)
-    except PermissionError as e:
-        print(str(e), file=sys.stderr)
-        return 4
-
-    new_assignee = (args.new_assignee or "").strip()
-    if not new_assignee:
-        print("Error: new_assignee 不能为空", file=sys.stderr)
-        return 1
-
-    changed = {"from": None, "to": new_assignee}
-
-    def _reassign_mutator(data):
-        old = data.get("assignee")
-        changed["from"] = old
-        data["assignee"] = new_assignee
-        data["updated_at"] = datetime.now().isoformat()
-        # 记录改派历史 (追溯用)
-        hist = data.get("assignee_history") or []
-        hist.append({
-            "from": old,
-            "to": new_assignee,
-            "by": get_developer(repo_root),
-            "at": datetime.now().isoformat(),
-        })
-        data["assignee_history"] = hist
-
-    if not modify_task_json(full_path, _reassign_mutator):
-        print("Error: Missing task.json", file=sys.stderr)
-        return 1
-
-    if changed["from"] == new_assignee:
-        print(f"Note: assignee 已是 {new_assignee}, 无变化 ({full_path.name})")
-    else:
-        print(f"Reassigned: {changed['from']} -> {new_assignee} ({full_path.name})")
-        print(f"  改派人: {get_developer(repo_root)} (已记录到 assignee_history)")
-    return 0
-
-
-def cmd_block(args: argparse.Namespace) -> int:
-    """标记任务被另一任务阻塞。自动维护反向 blocks 关系。
-    用法: task.py block <task> <blocked-by-task>
-    语义: <task> 被 <blocked-by-task> 阻塞 (要等它完成)。
-    """
-    repo_root = get_repo_root()
-    task_dir = resolve_task_dir(args.task, repo_root)
-    blocker_dir = resolve_task_dir(args.blocker, repo_root)
-    if not task_dir.is_dir():
-        print(f"Error: Task not found: {args.task}", file=sys.stderr)
-        return 1
-    if not blocker_dir.is_dir():
-        print(f"Error: Blocker task not found: {args.blocker}", file=sys.stderr)
-        return 1
-    # ACL: 只有 task 的 owner 能加依赖
-    try:
-        assert_can_modify_task(task_dir, "block", repo_root)
-    except PermissionError as e:
-        print(str(e), file=sys.stderr)
-        return 4
-
-    # 检测循环依赖
-    if _would_create_cycle(task_dir.name, blocker_dir.name, repo_root):
-        print(f"Error: 循环依赖检测到 ({blocker_dir.name} 已直接/间接依赖 {task_dir.name})",
-              file=sys.stderr)
-        return 1
-
-    # 检查是否已存在依赖关系 (先读, 幂等)
-    task_data = load_task_json(task_dir)
-    if not task_data:
-        print("Error: Missing task.json", file=sys.stderr)
-        return 1
-    if blocker_dir.name in (task_data.get("blocked_by") or []):
-        print(f"Already blocked by {blocker_dir.name}")
-        return 0
-
-    # 锁内更新 task.blocked_by
-    def _block_mutator(data):
-        blocked_by = data.get("blocked_by") or []
-        if blocker_dir.name not in blocked_by:
-            blocked_by.append(blocker_dir.name)
-            data["blocked_by"] = blocked_by
-            data["updated_at"] = datetime.now().isoformat()
-    modify_task_json(task_dir, _block_mutator)
-
-    # 锁内反向更新 blocker.blocks
-    def _block_reverse_mutator(data):
-        blocks = data.get("blocks") or []
-        if task_dir.name not in blocks:
-            blocks.append(task_dir.name)
-            data["blocks"] = blocks
-            data["updated_at"] = datetime.now().isoformat()
-    modify_task_json(blocker_dir, _block_reverse_mutator)
-
-    print(f"{task_dir.name} now blocked by {blocker_dir.name}")
-    return 0
-
-
-def cmd_unblock(args: argparse.Namespace) -> int:
-    """移除阻塞关系。用法: task.py unblock <task> <blocked-by-task>"""
-    repo_root = get_repo_root()
-    task_dir = resolve_task_dir(args.task, repo_root)
-    blocker_dir = resolve_task_dir(args.blocker, repo_root)
-    if task_dir.is_dir():
-        try:
-            assert_can_modify_task(task_dir, "unblock", repo_root)
-        except PermissionError as e:
-            print(str(e), file=sys.stderr)
-            return 4
-
-    removed = False
-    # 锁内从 task.blocked_by 删
-    if task_dir.is_dir():
-        def _unblock_mutator(data):
-            nonlocal removed
-            if blocker_dir.name in (data.get("blocked_by") or []):
-                data["blocked_by"] = [x for x in (data.get("blocked_by") or []) if x != blocker_dir.name]
-                data["updated_at"] = datetime.now().isoformat()
-                removed = True
-        modify_task_json(task_dir, _unblock_mutator)
-
-    # 锁内从 blocker.blocks 删
-    if blocker_dir.is_dir():
-        def _unblock_reverse_mutator(data):
-            nonlocal removed
-            if task_dir.name in (data.get("blocks") or []):
-                data["blocks"] = [x for x in (data.get("blocks") or []) if x != task_dir.name]
-                data["updated_at"] = datetime.now().isoformat()
-                removed = True
-        modify_task_json(blocker_dir, _unblock_reverse_mutator)
-
-    if removed:
-        print(f"Removed block: {task_dir.name} no longer blocked by {blocker_dir.name}")
-    else:
-        print(f"No such block relationship found")
-    return 0
-
-
-def _would_create_cycle(task_name: str, blocker_name: str, repo_root) -> bool:
-    """检测添加 task←blocker 后是否会形成循环依赖。
-    即: blocker 是否(直接/间接)已经依赖 task?
-    """
-    if task_name == blocker_name:
-        return True
-    # BFS: 从 blocker 出发, 沿 blocked_by 走, 看能否回到 task
-    visited = set()
-    queue = [blocker_name]
-    tasks_dir = get_tasks_dir(repo_root)
-    while queue:
-        current = queue.pop(0)
-        if current in visited:
-            continue
-        visited.add(current)
-        if current == task_name:
-            return True
-        cur_dir = tasks_dir / current
-        data = load_task_json(cur_dir) if cur_dir.is_dir() else None
-        if data:
-            for dep in (data.get("blocked_by") or []):
-                if dep not in visited:
-                    queue.append(dep)
-    return False
-
-
-def _is_task_ready(task_data: dict) -> bool:
-    """任务是否"可立即开始": 未完成 且 无未完成的 blocked_by。"""
-    if task_data.get("status") == "completed":
-        return False
-    blocked_by = task_data.get("blocked_by") or []
-    # blocked_by 为空 = 可开始 (这里简化: 不深入查依赖是否完成, 由调用方保证)
-    return len(blocked_by) == 0
-
-
-def cmd_gantt(args: argparse.Namespace) -> int:
-    """渲染 markdown 甘特图 (按 start_date/due_date 排期)。
-    用法: task.py gantt [--weeks 4]
-    """
-    repo_root = get_repo_root()
-    tasks_dir = get_tasks_dir(repo_root)
-    if not tasks_dir.is_dir():
-        print("No tasks directory")
-        return 0
-
-    from datetime import date, timedelta
-    today = date.today()
-    weeks = args.weeks if hasattr(args, "weeks") else 4
-    end = today + timedelta(weeks=weeks)
-
-    # 收集有日期的任务
-    items = []
-    for d in sorted(tasks_dir.iterdir()):
-        if not d.is_dir():
-            continue
-        data = load_task_json(d)
-        if not data:
-            continue
-        due = data.get("due_date")
-        start = data.get("start_date")
-        if not due and not start:
-            continue
-        items.append({
-            "name": d.name,
-            "title": data.get("title", d.name),
-            "start": start,
-            "due": due,
-            "status": data.get("status", "?"),
-            "assignee": data.get("assignee", "?"),
-        })
-
-    if not items:
-        print("No tasks with dates. 用 'task.py set-due <task> <YYYY-MM-DD>' 添加截止日期。")
-        return 0
-
-    # 按开始/截止日期排序
-    items.sort(key=lambda x: (x.get("start") or x.get("due") or "9999"))
-
-    print(f"# 任务排期 ({today} ~ {end})\n")
-    print("| 任务 | 负责人 | 开始 | 截止 | 状态 |")
-    print("|------|--------|------|------|------|")
-    for it in items:
-        start = it.get("start") or "-"
-        due = it.get("due") or "-"
-        # 标记逾期
-        if it.get("due") and it["status"] != "completed":
-            try:
-                due_date = date.fromisoformat(it["due"])
-                if due_date < today:
-                    due = f"⚠️ {due} (逾期)"
-            except ValueError:
-                pass
-        print(f"| {it['name']} | {it['assignee']} | {start} | {due} | {it['status']} |")
-
-    # 简单时间轴 (ASCII)
-    print(f"\n## 时间轴 ({weeks} 周)\n")
-    print("```")
-    for it in items:
-        start_s = it.get("start") or it.get("due")
-        if not start_s:
-            continue
-        try:
-            start_d = date.fromisoformat(start_s) if it.get("start") else today
-        except ValueError:
-            start_d = today
-        due_s = it.get("due")
-        try:
-            due_d = date.fromisoformat(due_s) if due_s else start_d + timedelta(days=7)
-        except ValueError:
-            due_d = start_d + timedelta(days=7)
-        # 计算相对今天的偏移
-        start_off = max(0, (start_d - today).days)
-        due_off = min(weeks * 7, (due_d - today).days)
-        if due_off < 0:
-            bar = "[逾期]" + "=" * 5
-        else:
-            bar = " " * (start_off // 2) + "[" + "=" * max(1, (due_off - start_off) // 2) + "]"
-        print(f"{it['name'][:20]:20} {bar}")
-    print("```")
-    return 0
-
-
-# =============================================================================
-# Main
-# =============================================================================
-
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+"""task_relations.py - task 关系/排期层 (v3.0 f6 从 task.py 拆出)"""
+# v3.0 路径自举
+import os as _o, sys as _s, argparse
+from pathlib import Path
+from datetime import datetime
+_cp = _o.path.join(_o.path.dirname(_o.path.dirname(_o.path.abspath(__file__))), 'foundation')
+if _cp not in _s.path: _s.path.insert(0, _cp)
+from bootstrap import setup; setup()
+from foundation.core.paths import get_repo_root
+
+import os, sys, json, shutil
+from datetime import datetime
+from pathlib import Path
+from foundation.core.paths import (
+    DIR_TASKS, DIR_ARCHIVE, FILE_TASK_JSON,
+    get_repo_root, get_developer, get_tasks_dir,
+)
+from foundation.integrations.active_task import (
+    clear_active_task, resolve_active_task, resolve_context_key, set_active_task,
+)
+from foundation.data.task_utils import (
+    resolve_task_dir, run_task_hooks, load_task_json, write_task_json,
+    modify_task_json, assert_can_modify_task,
+)
+from foundation.io.atomicio import atomic_write_json, safe_read_json, atomic_write_text
+
+
+def cmd_add_subtask(args: argparse.Namespace) -> int:
+    """添加子任务关联。"""
+    repo_root = get_repo_root()
+    parent_dir = resolve_task_dir(args.parent, repo_root)
+    child_dir = resolve_task_dir(args.child, repo_root)
+
+    if not parent_dir.is_dir():
+        print(f"Error: Parent task not found: {args.parent}", file=sys.stderr)
+        return 1
+    if not child_dir.is_dir():
+        print(f"Error: Child task not found: {args.child}", file=sys.stderr)
+        return 1
+
+    # 零信任 ACL: 只有 parent 的 creator/assignee/admin 能加子任务
+    try:
+        assert_can_modify_task(parent_dir, "add-subtask", repo_root)
+    except PermissionError as e:
+        print(str(e), file=sys.stderr)
+        return 4
+
+    parent_data = load_task_json(parent_dir)
+    child_data = load_task_json(child_dir)
+
+    if not parent_data or not child_data:
+        print("Error: Missing task.json", file=sys.stderr)
+        return 1
+
+    child_name = child_dir.name
+    children = parent_data.get("children", [])
+    if child_name not in children:
+        children.append(child_name)
+        parent_data["children"] = children
+        parent_data["updated_at"] = datetime.now().isoformat()
+        write_task_json(parent_dir, parent_data)
+
+    # 子任务记录父任务
+    child_data["parent"] = parent_dir.name
+    child_data["updated_at"] = datetime.now().isoformat()
+    write_task_json(child_dir, child_data)
+
+    print(f"Subtask added: {parent_dir.name} -> {child_dir.name}")
+    return 0
+
+
+def cmd_remove_subtask(args: argparse.Namespace) -> int:
+    """移除子任务关联。"""
+    repo_root = get_repo_root()
+    parent_dir = resolve_task_dir(args.parent, repo_root)
+    child_dir = resolve_task_dir(args.child, repo_root)
+
+    # 零信任 ACL
+    if parent_dir.is_dir():
+        try:
+            assert_can_modify_task(parent_dir, "remove-subtask", repo_root)
+        except PermissionError as e:
+            print(str(e), file=sys.stderr)
+            return 4
+
+    parent_data = load_task_json(parent_dir)
+    child_data = load_task_json(child_dir)
+
+    if parent_data:
+        children = parent_data.get("children", [])
+        if child_dir.name in children:
+            children.remove(child_dir.name)
+            parent_data["children"] = children
+            parent_data["updated_at"] = datetime.now().isoformat()
+            write_task_json(parent_dir, parent_data)
+
+    if child_data:
+        child_data["parent"] = None
+        child_data["updated_at"] = datetime.now().isoformat()
+        write_task_json(child_dir, child_data)
+
+    print(f"Subtask removed: {parent_dir.name} -x- {child_dir.name}")
+    return 0
+
+
+# =============================================================================
+# 工具函数
+# =============================================================================
+
+def _generate_slug(title: str) -> str:
+    """从标题生成 URL-safe slug。"""
+    # 简单处理: 小写, 空格转连字符, 只保留字母数字和连字符
+    slug = title.lower().strip()
+    slug = "".join(c if c.isalnum() or c in " -_" else "" for c in slug)
+    slug = slug.replace(" ", "-").replace("_", "-")
+    slug = "-".join(part for part in slug.split("-") if part)
+    return slug[:50] if slug else "untitled"
+
+
+# =============================================================================
+# 命令: set-due / block / unblock / gantt (B2 能力增强)
+# =============================================================================
+
+def cmd_set_due(args: argparse.Namespace) -> int:
+    """设置任务截止日期。用法: task.py set-due <task> <YYYY-MM-DD>"""
+    repo_root = get_repo_root()
+    full_path = resolve_task_dir(args.task, repo_root)
+    if not full_path.is_dir():
+        print(f"Error: Task not found: {args.task}", file=sys.stderr)
+        return 1
+    # ACL
+    try:
+        assert_can_modify_task(full_path, "set-due", repo_root)
+    except PermissionError as e:
+        print(str(e), file=sys.stderr)
+        return 4
+    def _set_due_mutator(data):
+        data["due_date"] = args.due_date
+        data["updated_at"] = datetime.now().isoformat()
+    if not modify_task_json(full_path, _set_due_mutator):
+        print("Error: Missing task.json", file=sys.stderr)
+        return 1
+    print(f"Set due_date: {args.due_date} ({full_path.name})")
+    return 0
+
+
+def cmd_reassign(args: argparse.Namespace) -> int:
+    """改派任务负责人。用法: task.py reassign <task> <new_assignee>
+
+    场景: PM 建任务后改派给开发(多角色协作必需)。
+    ACL: 只有 creator/admin 能改派(防恶意抢占/甩锅)。
+    保留改派历史(assignee_history), 便于追溯。
+    """
+    repo_root = get_repo_root()
+    full_path = resolve_task_dir(args.task, repo_root)
+    if not full_path.is_dir():
+        print(f"Error: Task not found: {args.task}", file=sys.stderr)
+        return 1
+    # ACL: 只有 creator/admin 能改派 (assignee 自己不能转手甩锅)
+    try:
+        assert_can_modify_task(full_path, "reassign", repo_root)
+    except PermissionError as e:
+        print(str(e), file=sys.stderr)
+        return 4
+
+    new_assignee = (args.new_assignee or "").strip()
+    if not new_assignee:
+        print("Error: new_assignee 不能为空", file=sys.stderr)
+        return 1
+
+    changed = {"from": None, "to": new_assignee}
+
+    def _reassign_mutator(data):
+        old = data.get("assignee")
+        changed["from"] = old
+        data["assignee"] = new_assignee
+        data["updated_at"] = datetime.now().isoformat()
+        # 记录改派历史 (追溯用)
+        hist = data.get("assignee_history") or []
+        hist.append({
+            "from": old,
+            "to": new_assignee,
+            "by": get_developer(repo_root),
+            "at": datetime.now().isoformat(),
+        })
+        data["assignee_history"] = hist
+
+    if not modify_task_json(full_path, _reassign_mutator):
+        print("Error: Missing task.json", file=sys.stderr)
+        return 1
+
+    if changed["from"] == new_assignee:
+        print(f"Note: assignee 已是 {new_assignee}, 无变化 ({full_path.name})")
+    else:
+        print(f"Reassigned: {changed['from']} -> {new_assignee} ({full_path.name})")
+        print(f"  改派人: {get_developer(repo_root)} (已记录到 assignee_history)")
+    return 0
+
+
+def cmd_block(args: argparse.Namespace) -> int:
+    """标记任务被另一任务阻塞。自动维护反向 blocks 关系。
+    用法: task.py block <task> <blocked-by-task>
+    语义: <task> 被 <blocked-by-task> 阻塞 (要等它完成)。
+    """
+    repo_root = get_repo_root()
+    task_dir = resolve_task_dir(args.task, repo_root)
+    blocker_dir = resolve_task_dir(args.blocker, repo_root)
+    if not task_dir.is_dir():
+        print(f"Error: Task not found: {args.task}", file=sys.stderr)
+        return 1
+    if not blocker_dir.is_dir():
+        print(f"Error: Blocker task not found: {args.blocker}", file=sys.stderr)
+        return 1
+    # ACL: 只有 task 的 owner 能加依赖
+    try:
+        assert_can_modify_task(task_dir, "block", repo_root)
+    except PermissionError as e:
+        print(str(e), file=sys.stderr)
+        return 4
+
+    # 检测循环依赖
+    if _would_create_cycle(task_dir.name, blocker_dir.name, repo_root):
+        print(f"Error: 循环依赖检测到 ({blocker_dir.name} 已直接/间接依赖 {task_dir.name})",
+              file=sys.stderr)
+        return 1
+
+    # 检查是否已存在依赖关系 (先读, 幂等)
+    task_data = load_task_json(task_dir)
+    if not task_data:
+        print("Error: Missing task.json", file=sys.stderr)
+        return 1
+    if blocker_dir.name in (task_data.get("blocked_by") or []):
+        print(f"Already blocked by {blocker_dir.name}")
+        return 0
+
+    # 锁内更新 task.blocked_by
+    def _block_mutator(data):
+        blocked_by = data.get("blocked_by") or []
+        if blocker_dir.name not in blocked_by:
+            blocked_by.append(blocker_dir.name)
+            data["blocked_by"] = blocked_by
+            data["updated_at"] = datetime.now().isoformat()
+    modify_task_json(task_dir, _block_mutator)
+
+    # 锁内反向更新 blocker.blocks
+    def _block_reverse_mutator(data):
+        blocks = data.get("blocks") or []
+        if task_dir.name not in blocks:
+            blocks.append(task_dir.name)
+            data["blocks"] = blocks
+            data["updated_at"] = datetime.now().isoformat()
+    modify_task_json(blocker_dir, _block_reverse_mutator)
+
+    print(f"{task_dir.name} now blocked by {blocker_dir.name}")
+    return 0
+
+
+def cmd_unblock(args: argparse.Namespace) -> int:
+    """移除阻塞关系。用法: task.py unblock <task> <blocked-by-task>"""
+    repo_root = get_repo_root()
+    task_dir = resolve_task_dir(args.task, repo_root)
+    blocker_dir = resolve_task_dir(args.blocker, repo_root)
+    if task_dir.is_dir():
+        try:
+            assert_can_modify_task(task_dir, "unblock", repo_root)
+        except PermissionError as e:
+            print(str(e), file=sys.stderr)
+            return 4
+
+    removed = False
+    # 锁内从 task.blocked_by 删
+    if task_dir.is_dir():
+        def _unblock_mutator(data):
+            nonlocal removed
+            if blocker_dir.name in (data.get("blocked_by") or []):
+                data["blocked_by"] = [x for x in (data.get("blocked_by") or []) if x != blocker_dir.name]
+                data["updated_at"] = datetime.now().isoformat()
+                removed = True
+        modify_task_json(task_dir, _unblock_mutator)
+
+    # 锁内从 blocker.blocks 删
+    if blocker_dir.is_dir():
+        def _unblock_reverse_mutator(data):
+            nonlocal removed
+            if task_dir.name in (data.get("blocks") or []):
+                data["blocks"] = [x for x in (data.get("blocks") or []) if x != task_dir.name]
+                data["updated_at"] = datetime.now().isoformat()
+                removed = True
+        modify_task_json(blocker_dir, _unblock_reverse_mutator)
+
+    if removed:
+        print(f"Removed block: {task_dir.name} no longer blocked by {blocker_dir.name}")
+    else:
+        print(f"No such block relationship found")
+    return 0
+
+
+def _would_create_cycle(task_name: str, blocker_name: str, repo_root) -> bool:
+    """检测添加 task←blocker 后是否会形成循环依赖。
+    即: blocker 是否(直接/间接)已经依赖 task?
+    """
+    if task_name == blocker_name:
+        return True
+    # BFS: 从 blocker 出发, 沿 blocked_by 走, 看能否回到 task
+    visited = set()
+    queue = [blocker_name]
+    tasks_dir = get_tasks_dir(repo_root)
+    while queue:
+        current = queue.pop(0)
+        if current in visited:
+            continue
+        visited.add(current)
+        if current == task_name:
+            return True
+        cur_dir = tasks_dir / current
+        data = load_task_json(cur_dir) if cur_dir.is_dir() else None
+        if data:
+            for dep in (data.get("blocked_by") or []):
+                if dep not in visited:
+                    queue.append(dep)
+    return False
+
+
+def _is_task_ready(task_data: dict) -> bool:
+    """任务是否"可立即开始": 未完成 且 无未完成的 blocked_by。"""
+    if task_data.get("status") == "completed":
+        return False
+    blocked_by = task_data.get("blocked_by") or []
+    # blocked_by 为空 = 可开始 (这里简化: 不深入查依赖是否完成, 由调用方保证)
+    return len(blocked_by) == 0
+
+
+def cmd_gantt(args: argparse.Namespace) -> int:
+    """渲染 markdown 甘特图 (按 start_date/due_date 排期)。
+    用法: task.py gantt [--weeks 4]
+    """
+    repo_root = get_repo_root()
+    tasks_dir = get_tasks_dir(repo_root)
+    if not tasks_dir.is_dir():
+        print("No tasks directory")
+        return 0
+
+    from datetime import date, timedelta
+    today = date.today()
+    weeks = args.weeks if hasattr(args, "weeks") else 4
+    end = today + timedelta(weeks=weeks)
+
+    # 收集有日期的任务
+    items = []
+    for d in sorted(tasks_dir.iterdir()):
+        if not d.is_dir():
+            continue
+        data = load_task_json(d)
+        if not data:
+            continue
+        due = data.get("due_date")
+        start = data.get("start_date")
+        if not due and not start:
+            continue
+        items.append({
+            "name": d.name,
+            "title": data.get("title", d.name),
+            "start": start,
+            "due": due,
+            "status": data.get("status", "?"),
+            "assignee": data.get("assignee", "?"),
+        })
+
+    if not items:
+        print("No tasks with dates. 用 'task.py set-due <task> <YYYY-MM-DD>' 添加截止日期。")
+        return 0
+
+    # 按开始/截止日期排序
+    items.sort(key=lambda x: (x.get("start") or x.get("due") or "9999"))
+
+    print(f"# 任务排期 ({today} ~ {end})\n")
+    print("| 任务 | 负责人 | 开始 | 截止 | 状态 |")
+    print("|------|--------|------|------|------|")
+    for it in items:
+        start = it.get("start") or "-"
+        due = it.get("due") or "-"
+        # 标记逾期
+        if it.get("due") and it["status"] != "completed":
+            try:
+                due_date = date.fromisoformat(it["due"])
+                if due_date < today:
+                    due = f"⚠️ {due} (逾期)"
+            except ValueError:
+                pass
+        print(f"| {it['name']} | {it['assignee']} | {start} | {due} | {it['status']} |")
+
+    # 简单时间轴 (ASCII)
+    print(f"\n## 时间轴 ({weeks} 周)\n")
+    print("```")
+    for it in items:
+        start_s = it.get("start") or it.get("due")
+        if not start_s:
+            continue
+        try:
+            start_d = date.fromisoformat(start_s) if it.get("start") else today
+        except ValueError:
+            start_d = today
+        due_s = it.get("due")
+        try:
+            due_d = date.fromisoformat(due_s) if due_s else start_d + timedelta(days=7)
+        except ValueError:
+            due_d = start_d + timedelta(days=7)
+        # 计算相对今天的偏移
+        start_off = max(0, (start_d - today).days)
+        due_off = min(weeks * 7, (due_d - today).days)
+        if due_off < 0:
+            bar = "[逾期]" + "=" * 5
+        else:
+            bar = " " * (start_off // 2) + "[" + "=" * max(1, (due_off - start_off) // 2) + "]"
+        print(f"{it['name'][:20]:20} {bar}")
+    print("```")
+    return 0
+
+
+# =============================================================================
+# Main
+# =============================================================================
+