@blxzer/pactile 0.5.0

package/dist/templates/pactile/scripts/common/test_task_dependencies.py

@@ -0,0 +1,329 @@
+#!/usr/bin/env python3
+"""Tests for Plan A task-level depends_on resolution (declare + soft checks)."""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from common.task_dependencies import (
+    KIND_CHILD,
+    KIND_MISSING,
+    KIND_POOL,
+    KIND_TASK,
+    NOT_SATISFIED,
+    SATISFIED,
+    UNRESOLVED,
+    dashboard_deps_line,
+    describe_dependencies,
+    find_dependency_cycles,
+    normalize_dep_list,
+    resolve_dep_ref,
+    satisfaction_status,
+)
+
+
+def _write_task(tasks_dir: Path, dir_name: str, status: str, depends_on=None) -> Path:
+    task_dir = tasks_dir / dir_name
+    task_dir.mkdir(parents=True, exist_ok=True)
+    data = {
+        "id": dir_name,
+        "name": dir_name,
+        "title": dir_name,
+        "description": "",
+        "status": status,
+    }
+    if depends_on is not None:
+        data["depends_on"] = depends_on
+    (task_dir / "task.json").write_text(json.dumps(data), encoding="utf-8")
+    return task_dir
+
+
+def _tasks_fixture(tmp_path: Path) -> Path:
+    tasks_dir = tmp_path / "repo" / ".pactile" / "tasks"
+    tasks_dir.mkdir(parents=True)
+    return tasks_dir
+
+
+def test_completed_task_is_satisfied(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    _write_task(tasks_dir, "dep-a", "completed")
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["dep-a"])
+
+    report = describe_dependencies(task_dir, {"depends_on": ["dep-a"]}, tasks_dir=tasks_dir)
+    dep = report.deps[0]
+    assert dep.kind == KIND_TASK
+    assert satisfaction_status(dep)[0] == SATISFIED
+    assert report.warnings() == []
+
+
+def test_archived_task_counts_as_completed(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    archive_dir = tasks_dir / "archive" / "2026-08"
+    archive_dir.mkdir(parents=True)
+    # Anomaly: archived task.json still says planning — location is the rule.
+    _write_task(archive_dir, "dep-archived", "planning")
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["dep-archived"])
+
+    dep = resolve_dep_ref("dep-archived", tasks_dir=tasks_dir)
+    assert dep.kind == KIND_TASK
+    assert dep.is_archived
+    status, note = satisfaction_status(dep)
+    assert status == SATISFIED
+    assert note == "archived task counts as completed"
+
+
+def test_cancelled_task_satisfied_with_cancelled_warning(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    _write_task(tasks_dir, "dep-c", "cancelled")
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["dep-c"])
+
+    report = describe_dependencies(task_dir, {"depends_on": ["dep-c"]}, tasks_dir=tasks_dir)
+    dep = report.deps[0]
+    assert dep.is_cancelled
+    assert satisfaction_status(dep)[0] == SATISFIED
+    assert any("cancelled" in w for w in report.warnings())
+
+
+def test_in_progress_dependency_is_not_satisfied(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    _write_task(tasks_dir, "dep-b", "in_progress")
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["dep-b"])
+
+    report = describe_dependencies(task_dir, {"depends_on": ["dep-b"]}, tasks_dir=tasks_dir)
+    dep = report.deps[0]
+    assert satisfaction_status(dep)[0] == NOT_SATISFIED
+    assert any("not satisfied" in w for w in report.warnings())
+
+
+def test_dangling_reference_is_unresolved_warning(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["ghost-task"])
+
+    dep = resolve_dep_ref("ghost-task", tasks_dir=tasks_dir)
+    assert dep.kind == KIND_MISSING
+    assert satisfaction_status(dep)[0] == UNRESOLVED
+    report = describe_dependencies(task_dir, {"depends_on": ["ghost-task"]}, tasks_dir=tasks_dir)
+    assert any("dangling" in w for w in report.warnings())
+
+
+def test_pool_prefix_without_pool_dir_is_ignored(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["pool:P09"])
+
+    dep = resolve_dep_ref("pool:P09", tasks_dir=tasks_dir)
+    assert dep.kind == KIND_POOL
+    status, note = satisfaction_status(dep)
+    assert status == SATISFIED
+    assert "not materialized" in (note or "")
+    report = describe_dependencies(task_dir, {"depends_on": ["pool:P09"]}, tasks_dir=tasks_dir)
+    assert report.warnings() == []
+
+
+def test_cycle_detected_across_tasks(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    task_a = _write_task(tasks_dir, "task-a", "planning", ["task-b"])
+    _write_task(tasks_dir, "task-b", "planning", ["task-a"])
+
+    report = describe_dependencies(task_a, {"depends_on": ["task-b"]}, tasks_dir=tasks_dir)
+    assert len(report.cycles) == 1
+    assert report.cycles[0][0] == report.cycles[0][-1]
+    assert any("cycle" in w for w in report.warnings())
+
+
+def test_self_reference_cycle_detected(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["task-x"])
+
+    report = describe_dependencies(task_dir, {"depends_on": ["task-x"]}, tasks_dir=tasks_dir)
+    assert report.cycles == [["task-x", "task-x"]]
+
+
+def test_find_dependency_cycles_pure(tmp_path: Path) -> None:
+    graph = {"a": ["b"], "b": ["c"], "c": ["a"], "d": []}
+    cycles = find_dependency_cycles(graph)
+    assert len(cycles) == 1
+    cycle = cycles[0]
+    assert cycle[0] == cycle[-1]
+    assert set(cycle) == {"a", "b", "c"}
+
+
+def test_scope_child_wins_over_global_task_with_same_name(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    # Global task named "shared" that IS completed — would be satisfied globally.
+    _write_task(tasks_dir, "shared", "completed")
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["shared"])
+    scope = {"shared": "open"}
+
+    dep = resolve_dep_ref("shared", tasks_dir=tasks_dir, scope_children=scope)
+    assert dep.kind == KIND_CHILD
+    assert dep.source == "task-map"
+    assert satisfaction_status(dep)[0] == NOT_SATISFIED
+
+    report = describe_dependencies(
+        task_dir, {"depends_on": ["shared"]}, tasks_dir=tasks_dir, scope_children=scope
+    )
+    assert report.deps[0].kind == KIND_CHILD
+    assert any("not satisfied" in w for w in report.warnings())
+
+
+def test_child_integrated_is_satisfied_via_scope(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["child-a"])
+    scope = {"child-a": "integrated", "child-b": "cancelled"}
+
+    dep = resolve_dep_ref("child-a", tasks_dir=tasks_dir, scope_children=scope)
+    assert dep.kind == KIND_CHILD
+    assert satisfaction_status(dep)[0] == SATISFIED
+
+    report = describe_dependencies(
+        task_dir, {"depends_on": ["child-a", "child-b"]}, tasks_dir=tasks_dir, scope_children=scope
+    )
+    assert satisfaction_status(report.deps[0])[0] == SATISFIED
+    assert report.deps[1].is_cancelled
+    assert any("cancelled" in w for w in report.warnings())
+
+
+def test_empty_depends_on_has_no_warnings_or_dashboard_line(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    task_dir = _write_task(tasks_dir, "task-x", "planning")
+    data = {"id": "task-x", "status": "planning"}
+
+    report = describe_dependencies(task_dir, data, tasks_dir=tasks_dir)
+    assert not report.has_deps()
+    assert report.warnings() == []
+    assert dashboard_deps_line(task_dir, data, tasks_dir=tasks_dir) is None
+
+
+def test_dashboard_deps_line_renders_badges(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    _write_task(tasks_dir, "dep-done", "completed")
+    _write_task(tasks_dir, "dep-wait", "in_progress")
+    _write_task(tasks_dir, "dep-gone", "cancelled")
+    task_dir = _write_task(
+        tasks_dir, "task-x", "planning", ["dep-done", "dep-wait", "dep-gone", "pool:P09"]
+    )
+    data = {
+        "id": "task-x",
+        "status": "planning",
+        "depends_on": ["dep-done", "dep-wait", "dep-gone", "pool:P09"],
+    }
+
+    line = dashboard_deps_line(task_dir, data, tasks_dir=tasks_dir)
+    assert line is not None
+    assert "dep-done ✅" in line
+    assert "dep-wait ⏳" in line
+    assert "dep-gone ✅已取消" in line
+    assert "pool:P09 ✅" in line
+
+
+def test_normalize_dep_list_dedupes_and_strips(tmp_path: Path) -> None:
+    assert normalize_dep_list(None) == []
+    assert normalize_dep_list(["a", " a ", "b", "a", "", 5]) == ["a", "b"]
+    assert normalize_dep_list("not-a-list") == []
+
+
+# =============================================================================
+# pool: delivery-based status (not linked-task Close)
+# =============================================================================
+
+def _pool_repo(
+    tmp_path: Path,
+    *,
+    delivery: str | None = "standing",
+    status: str = "accepted",
+) -> Path:
+    repo = tmp_path / "repo"
+    items_dir = repo / ".pactile" / "pool" / "items"
+    items_dir.mkdir(parents=True)
+    lines = ["id: P09", "title: t", f"status: {status}", "type: mechanism"]
+    if delivery is not None:
+        lines.append(f"delivery: {delivery}")
+    (items_dir / "P09.md").write_text(
+        "---\n" + "\n".join(lines) + "\n---\n\n## 意图\nx\n",
+        encoding="utf-8",
+    )
+    (repo / ".pactile" / "tasks").mkdir(parents=True, exist_ok=True)
+    return repo
+
+
+def test_pool_missing_item_is_unresolved(tmp_path: Path) -> None:
+    tasks_dir = _tasks_fixture(tmp_path)
+    (tmp_path / "repo" / ".pactile" / "pool" / "items").mkdir(parents=True)
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["pool:P09"])
+
+    dep = resolve_dep_ref("pool:P09", tasks_dir=tasks_dir)
+    assert dep.kind == KIND_POOL
+    status, note = satisfaction_status(dep)
+    assert status == UNRESOLVED
+    assert "not found" in (note or "")
+    report = describe_dependencies(task_dir, {"depends_on": ["pool:P09"]}, tasks_dir=tasks_dir)
+    assert any("unresolved" in w for w in report.warnings())
+
+
+def test_pool_standing_is_satisfied_without_links(tmp_path: Path) -> None:
+    repo = _pool_repo(tmp_path, delivery="standing")
+    tasks_dir = repo / ".pactile" / "tasks"
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["pool:P09"])
+
+    dep = resolve_dep_ref("pool:P09", tasks_dir=tasks_dir)
+    assert satisfaction_status(dep)[0] == SATISFIED
+    report = describe_dependencies(task_dir, {"depends_on": ["pool:P09"]}, tasks_dir=tasks_dir)
+    assert report.warnings() == []
+
+
+def test_pool_open_is_not_satisfied(tmp_path: Path) -> None:
+    repo = _pool_repo(tmp_path, delivery="open")
+    tasks_dir = repo / ".pactile" / "tasks"
+    task_dir = _write_task(tasks_dir, "task-x", "planning", ["pool:P09"])
+
+    dep = resolve_dep_ref("pool:P09", tasks_dir=tasks_dir)
+    status, note = satisfaction_status(dep)
+    assert status == NOT_SATISFIED
+    assert "remaining obligation" in (note or "")
+    report = describe_dependencies(task_dir, {"depends_on": ["pool:P09"]}, tasks_dir=tasks_dir)
+    assert any("not satisfied" in w for w in report.warnings())
+
+
+def test_pool_in_slice_is_not_satisfied(tmp_path: Path) -> None:
+    repo = _pool_repo(tmp_path, delivery="in-slice")
+    tasks_dir = repo / ".pactile" / "tasks"
+    dep = resolve_dep_ref("pool:P09", tasks_dir=tasks_dir)
+    assert satisfaction_status(dep)[0] == NOT_SATISFIED
+
+
+def test_pool_landed_is_satisfied(tmp_path: Path) -> None:
+    repo = _pool_repo(tmp_path, delivery="landed")
+    tasks_dir = repo / ".pactile" / "tasks"
+    dep = resolve_dep_ref("pool:P09", tasks_dir=tasks_dir)
+    assert satisfaction_status(dep)[0] == SATISFIED
+
+
+def test_pool_deferred_is_satisfied(tmp_path: Path) -> None:
+    repo = _pool_repo(tmp_path, delivery="deferred")
+    tasks_dir = repo / ".pactile" / "tasks"
+    dep = resolve_dep_ref("pool:P09", tasks_dir=tasks_dir)
+    assert satisfaction_status(dep)[0] == SATISFIED
+
+
+def test_pool_accepted_missing_delivery_is_not_satisfied(tmp_path: Path) -> None:
+    repo = _pool_repo(tmp_path, delivery=None)
+    tasks_dir = repo / ".pactile" / "tasks"
+    dep = resolve_dep_ref("pool:P09", tasks_dir=tasks_dir)
+    status, note = satisfaction_status(dep)
+    assert status == NOT_SATISFIED
+    assert "missing delivery" in (note or "")
+
+
+def test_pool_inbox_is_unresolved(tmp_path: Path) -> None:
+    repo = _pool_repo(tmp_path, delivery=None, status="inbox")
+    tasks_dir = repo / ".pactile" / "tasks"
+    dep = resolve_dep_ref("pool:P09", tasks_dir=tasks_dir)
+    status, note = satisfaction_status(dep)
+    assert status == UNRESOLVED
+    assert "not accepted" in (note or "")

package/dist/templates/pactile/scripts/common/test_task_store_kernel_patch.py

@@ -0,0 +1,163 @@
+#!/usr/bin/env python3
+"""Parent-Child / VCS task.json writers go through Kernel patch."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from common import kernel_command as kernel_command_mod
+from common.kernel_command import KernelCliNotFound
+from common.task_store import (
+    cmd_add_subtask,
+    cmd_remove_subtask,
+    cmd_set_base_branch,
+    cmd_set_branch,
+    cmd_set_depends_mode,
+    cmd_set_deps,
+    cmd_set_scope,
+)
+from common.test_kernel_command import FAKE_KERNEL
+
+
+def _write_task(tasks_dir: Path, dir_name: str, **fields) -> Path:
+    task_dir = tasks_dir / dir_name
+    task_dir.mkdir(parents=True, exist_ok=True)
+    data = {
+        "id": dir_name,
+        "name": dir_name,
+        "title": dir_name,
+        "status": "planning",
+        "children": [],
+        "parent": None,
+        "meta": {},
+    }
+    data.update(fields)
+    (task_dir / "task.json").write_text(
+        json.dumps(data, indent=2, ensure_ascii=False),
+        encoding="utf-8",
+    )
+    return task_dir
+
+
+def _read(task_dir: Path) -> dict:
+    return json.loads((task_dir / "task.json").read_text(encoding="utf-8"))
+
+
+@pytest.fixture
+def sandbox(tmp_path, monkeypatch):
+    repo = tmp_path / "repo"
+    tasks_dir = repo / ".pactile" / "tasks"
+    tasks_dir.mkdir(parents=True)
+    monkeypatch.setattr("common.task_store.get_repo_root", lambda: repo)
+    monkeypatch.setattr("common.task_dependencies.get_repo_root", lambda: repo)
+    script = tmp_path / "fake_kernel.py"
+    script.write_text(FAKE_KERNEL, encoding="utf-8")
+    monkeypatch.setattr(
+        kernel_command_mod,
+        "kernel_cli_argv",
+        lambda: [sys.executable, str(script)],
+    )
+    return repo, tasks_dir
+
+
+def test_add_and_remove_subtask_go_through_kernel(sandbox) -> None:
+    _repo, tasks_dir = sandbox
+    parent_dir = _write_task(tasks_dir, "parent-x")
+    child_dir = _write_task(tasks_dir, "child-a")
+
+    rc = cmd_add_subtask(
+        argparse.Namespace(parent_dir="parent-x", child_dir="child-a")
+    )
+    assert rc == 0
+
+    parent = _read(parent_dir)
+    child = _read(child_dir)
+    assert parent["children"] == ["child-a"]
+    assert child["parent"] == "parent-x"
+    assert parent["status"] == "planning"
+    assert child["status"] == "planning"
+    assert (parent_dir / "kernel.json").is_file()
+    assert (child_dir / "kernel.json").is_file()
+    parent_kernel = json.loads((parent_dir / "kernel.json").read_text(encoding="utf-8"))
+    child_kernel = json.loads((child_dir / "kernel.json").read_text(encoding="utf-8"))
+    assert parent_kernel["revision"] >= 1
+    assert child_kernel["revision"] >= 1
+    assert (parent_dir / "task-map.md").is_file()
+
+    rc = cmd_remove_subtask(
+        argparse.Namespace(parent_dir="parent-x", child_dir="child-a")
+    )
+    assert rc == 0
+    parent = _read(parent_dir)
+    child = _read(child_dir)
+    assert parent["children"] == []
+    assert child["parent"] is None
+    assert parent["status"] == "planning"
+
+
+def test_set_branch_base_and_scope_go_through_kernel(sandbox) -> None:
+    _repo, tasks_dir = sandbox
+    task_dir = _write_task(tasks_dir, "task-x")
+
+    assert cmd_set_branch(argparse.Namespace(dir="task-x", branch="feat/demo")) == 0
+    data = _read(task_dir)
+    assert data["branch"] == "feat/demo"
+    assert data["status"] == "planning"
+    kernel = json.loads((task_dir / "kernel.json").read_text(encoding="utf-8"))
+    assert kernel["revision"] >= 1
+    first_revision = kernel["revision"]
+
+    assert cmd_set_base_branch(
+        argparse.Namespace(dir="task-x", base_branch="feat/stage0-clean-baseline")
+    ) == 0
+    data = _read(task_dir)
+    assert data["base_branch"] == "feat/stage0-clean-baseline"
+    assert data["branch"] == "feat/demo"
+    kernel = json.loads((task_dir / "kernel.json").read_text(encoding="utf-8"))
+    assert kernel["revision"] > first_revision
+
+    assert cmd_set_scope(argparse.Namespace(dir="task-x", scope="cli")) == 0
+    data = _read(task_dir)
+    assert data["scope"] == "cli"
+    assert data["status"] == "planning"
+
+
+def test_set_deps_and_depends_mode_go_through_kernel(sandbox) -> None:
+    _repo, tasks_dir = sandbox
+    task_dir = _write_task(tasks_dir, "task-x")
+
+    assert cmd_set_deps(argparse.Namespace(dir="task-x", dep=["dep-a", "pool:P28"])) == 0
+    data = _read(task_dir)
+    assert data["depends_on"] == ["dep-a", "pool:P28"]
+    assert data["status"] == "planning"
+    kernel = json.loads((task_dir / "kernel.json").read_text(encoding="utf-8"))
+    assert kernel["revision"] >= 1
+    assert kernel["audit"][-1]["idempotencyKey"].startswith("patch:set-deps:")
+
+    assert cmd_set_depends_mode(argparse.Namespace(dir="task-x", mode="block")) == 0
+    data = _read(task_dir)
+    assert data["meta"]["depends_mode"] == "block"
+    assert data["depends_on"] == ["dep-a", "pool:P28"]
+    assert data["status"] == "planning"
+
+
+def test_set_branch_does_not_fallback_when_kernel_cli_missing(sandbox, monkeypatch) -> None:
+    _repo, tasks_dir = sandbox
+    task_dir = _write_task(tasks_dir, "task-x")
+
+    def _missing():
+        raise KernelCliNotFound("Kernel CLI not found")
+
+    monkeypatch.setattr(kernel_command_mod, "kernel_cli_argv", _missing)
+    rc = cmd_set_branch(argparse.Namespace(dir="task-x", branch="feat/demo"))
+    assert rc == 1
+    data = _read(task_dir)
+    assert "branch" not in data or data.get("branch") in (None, "")
+    assert not (task_dir / "kernel.json").is_file()

package/dist/templates/pactile/scripts/common/types.py

@@ -0,0 +1,110 @@
+"""
+Core type definitions for Pactile task data.
+
+Provides:
+    TaskData     — TypedDict for task.json shape (read-path type hints only)
+    TaskInfo     — Frozen dataclass for loaded task (the public API type)
+    AgentRecord  — TypedDict for registry.json agent entries
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TypedDict
+
+
+# =============================================================================
+# task.json shape (TypedDict — used only for read-path type hints)
+# =============================================================================
+
+class TaskData(TypedDict, total=False):
+    """Shape of task.json on disk.
+
+    Used only for type annotations when reading task.json.
+    Writes must use the original dict to avoid losing unknown fields.
+    """
+
+    id: str
+    name: str
+    title: str
+    description: str
+    status: str
+    dev_type: str
+    scope: str | None
+    package: str | None
+    priority: str
+    creator: str
+    assignee: str
+    createdAt: str
+    completedAt: str | None
+    branch: str | None
+    base_branch: str | None
+    worktree_path: str | None
+    commit: str | None
+    pr_url: str | None
+    subtasks: list[str]
+    children: list[str]
+    parent: str | None
+    relatedFiles: list[str]
+    notes: str
+    meta: dict
+
+
+# =============================================================================
+# Loaded task object (frozen dataclass — the public API type)
+# =============================================================================
+
+@dataclass(frozen=True)
+class TaskInfo:
+    """Immutable view of a loaded task.
+
+    Created by load_task() / iter_active_tasks().
+    Contains the commonly accessed fields; the original dict
+    is preserved in `raw` for write-back and uncommon field access.
+    """
+
+    dir_name: str
+    directory: Path
+    title: str
+    status: str
+    assignee: str
+    priority: str
+    children: tuple[str, ...]
+    parent: str | None
+    package: str | None
+    raw: dict  # original dict — use for writes and uncommon fields
+
+    @property
+    def name(self) -> str:
+        """Task name (id or name field)."""
+        return self.raw.get("name") or self.raw.get("id") or self.dir_name
+
+    @property
+    def description(self) -> str:
+        return self.raw.get("description", "")
+
+    @property
+    def branch(self) -> str | None:
+        return self.raw.get("branch")
+
+    @property
+    def meta(self) -> dict:
+        return self.raw.get("meta", {})
+
+
+# =============================================================================
+# registry.json agent entry
+# =============================================================================
+
+class AgentRecord(TypedDict, total=False):
+    """Shape of an agent entry in registry.json."""
+
+    id: str
+    pid: int
+    task_dir: str
+    worktree_path: str
+    branch: str
+    platform: str
+    started_at: str
+    status: str