@blxzer/pactile 0.5.0

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

@@ -0,0 +1,241 @@
+#!/usr/bin/env python3
+"""
+Task JSONL context management.
+
+Provides:
+    cmd_add_context   - Add entry to JSONL context file
+    cmd_validate      - Validate JSONL context files
+    cmd_list_context  - List JSONL context entries
+
+Note:
+    ``cmd_init_context`` was removed in v0.5.0-beta.12. JSONL context files
+    are now seeded at ``task.py create`` time with a self-describing
+    ``_example`` line; the AI agent curates real entries during planning when
+    the task needs sub-agent/spec context. See ``.pactile/workflow.md`` for the
+    current planning artifact contract.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+
+from .log import Colors, colored
+from .paths import get_repo_root
+from .task_utils import resolve_task_dir
+from .injection_budget import (
+    JSONL_MAX_ENTRIES,
+    JSONL_MAX_TOTAL_CHARS,
+    measure_jsonl_manifest,
+)
+
+
+# =============================================================================
+# Command: add-context
+# =============================================================================
+
+def cmd_add_context(args: argparse.Namespace) -> int:
+    """Add entry to JSONL context file."""
+    repo_root = get_repo_root()
+    target_dir = resolve_task_dir(args.dir, repo_root)
+
+    jsonl_name = args.file
+    path = args.path
+    reason = args.reason or "Added manually"
+
+    if not target_dir.is_dir():
+        print(colored(f"Error: Directory not found: {target_dir}", Colors.RED))
+        return 1
+
+    # Support shorthand
+    if not jsonl_name.endswith(".jsonl"):
+        jsonl_name = f"{jsonl_name}.jsonl"
+
+    jsonl_file = target_dir / jsonl_name
+    full_path = repo_root / path
+
+    entry_type = "file"
+    if full_path.is_dir():
+        entry_type = "directory"
+        if not path.endswith("/"):
+            path = f"{path}/"
+    elif not full_path.is_file():
+        print(colored(f"Error: Path not found: {path}", Colors.RED))
+        return 1
+
+    # Check if already exists
+    if jsonl_file.is_file():
+        content = jsonl_file.read_text(encoding="utf-8")
+        if f'"{path}"' in content:
+            print(colored(f"Warning: Entry already exists for {path}", Colors.YELLOW))
+            return 0
+
+    # Add entry
+    entry: dict
+    if entry_type == "directory":
+        entry = {"file": path, "type": "directory", "reason": reason}
+    else:
+        entry = {"file": path, "reason": reason}
+
+    with jsonl_file.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(entry, ensure_ascii=False) + "\n")
+
+    print(colored(f"Added {entry_type}: {path}", Colors.GREEN))
+    return 0
+
+
+# =============================================================================
+# Command: validate
+# =============================================================================
+
+def cmd_validate(args: argparse.Namespace) -> int:
+    """Validate JSONL context files."""
+    repo_root = get_repo_root()
+    target_dir = resolve_task_dir(args.dir, repo_root)
+
+    if not target_dir.is_dir():
+        print(colored("Error: task directory required", Colors.RED))
+        return 1
+
+    print(colored("=== Validating Context Files ===", Colors.BLUE))
+    print(f"Target dir: {target_dir}")
+    print()
+
+    total_errors = 0
+    for jsonl_name in ["implement.jsonl", "check.jsonl"]:
+        jsonl_file = target_dir / jsonl_name
+        errors = _validate_jsonl(jsonl_file, repo_root)
+        total_errors += errors
+
+    print()
+    if total_errors == 0:
+        print(colored("✓ All validations passed", Colors.GREEN))
+        return 0
+    else:
+        print(colored(f"✗ Validation failed ({total_errors} errors)", Colors.RED))
+        return 1
+
+
+def _validate_jsonl(jsonl_file: Path, repo_root: Path) -> int:
+    """Validate a single JSONL file.
+
+    Seed rows (no ``file`` field — typically ``{"_example": "..."}``) are
+    skipped silently; they are self-describing comments, not real entries.
+    """
+    file_name = jsonl_file.name
+    errors = 0
+
+    if not jsonl_file.is_file():
+        print(f"  {colored(f'{file_name}: not found (skipped)', Colors.YELLOW)}")
+        return 0
+
+    line_num = 0
+    real_entries = 0
+    for line in jsonl_file.read_text(encoding="utf-8").splitlines():
+        line_num += 1
+        if not line.strip():
+            continue
+
+        try:
+            data = json.loads(line)
+        except json.JSONDecodeError:
+            print(f"  {colored(f'{file_name}:{line_num}: Invalid JSON', Colors.RED)}")
+            errors += 1
+            continue
+
+        file_path = data.get("file")
+        entry_type = data.get("type", "file")
+
+        if not file_path:
+            # Seed / comment row — skip silently
+            continue
+
+        real_entries += 1
+        full_path = repo_root / file_path
+        if entry_type == "directory":
+            if not full_path.is_dir():
+                print(f"  {colored(f'{file_name}:{line_num}: Directory not found: {file_path}', Colors.RED)}")
+                errors += 1
+        else:
+            if not full_path.is_file():
+                print(f"  {colored(f'{file_name}:{line_num}: File not found: {file_path}', Colors.RED)}")
+                errors += 1
+
+    if errors == 0:
+        print(f"  {colored(f'{file_name}: ✓ ({real_entries} entries)', Colors.GREEN)}")
+        budget = measure_jsonl_manifest(repo_root, jsonl_file.parent, file_name)
+        if real_entries > JSONL_MAX_ENTRIES:
+            print(
+                f"  {colored(f'{file_name}: budget WARN — {real_entries} entries (max {JSONL_MAX_ENTRIES})', Colors.YELLOW)}"
+            )
+        if budget.expanded_chars > JSONL_MAX_TOTAL_CHARS:
+            print(
+                f"  {colored(f'{file_name}: budget WARN — expanded {budget.expanded_chars} chars (max {JSONL_MAX_TOTAL_CHARS})', Colors.YELLOW)}"
+            )
+        elif budget.skipped:
+            print(
+                f"  {colored(f'{file_name}: budget WARN — {len(budget.skipped)} entries would be skipped at dispatch', Colors.YELLOW)}"
+            )
+    else:
+        print(f"  {colored(f'{file_name}: ✗ ({errors} errors)', Colors.RED)}")
+
+    return errors
+
+
+# =============================================================================
+# Command: list-context
+# =============================================================================
+
+def cmd_list_context(args: argparse.Namespace) -> int:
+    """List JSONL context entries."""
+    repo_root = get_repo_root()
+    target_dir = resolve_task_dir(args.dir, repo_root)
+
+    if not target_dir.is_dir():
+        print(colored("Error: task directory required", Colors.RED))
+        return 1
+
+    print(colored("=== Context Files ===", Colors.BLUE))
+    print()
+
+    for jsonl_name in ["implement.jsonl", "check.jsonl"]:
+        jsonl_file = target_dir / jsonl_name
+        if not jsonl_file.is_file():
+            continue
+
+        print(colored(f"[{jsonl_name}]", Colors.CYAN))
+
+        count = 0
+        seed_only = True
+        for line in jsonl_file.read_text(encoding="utf-8").splitlines():
+            if not line.strip():
+                continue
+
+            try:
+                data = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+
+            file_path = data.get("file")
+            if not file_path:
+                # Seed / comment row — don't count as a real entry
+                continue
+            seed_only = False
+
+            count += 1
+            entry_type = data.get("type", "file")
+            reason = data.get("reason", "-")
+
+            if entry_type == "directory":
+                print(f"  {colored(f'{count}.', Colors.GREEN)} [DIR] {file_path}")
+            else:
+                print(f"  {colored(f'{count}.', Colors.GREEN)} {file_path}")
+            print(f"     {colored('→', Colors.YELLOW)} {reason}")
+
+        if seed_only:
+            print(f"  {colored('(no curated entries yet — only seed row)', Colors.YELLOW)}")
+
+        print()
+
+    return 0

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

@@ -0,0 +1,286 @@
+#!/usr/bin/env python3
+"""Task dashboard rendering for framework entry routing."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .active_task import resolve_selected_task
+from .paths import DIR_TASKS, DIR_WORKFLOW, get_developer, get_repo_root, get_tasks_dir
+from .task_dependencies import dashboard_deps_line
+from .task_gates import verify_evidence_status
+from .task_map import get_child_state
+from .tasks import (
+    children_progress,
+    format_child_task_display,
+    iter_active_tasks,
+    load_parent_child_integration_states,
+)
+
+
+_KERNEL_PHASE_ORDER = (
+    "open",
+    "define",
+    "approve",
+    "execute",
+    "verify",
+    "integrate",
+    "close",
+)
+
+_KERNEL_PHASE_HUMAN = {
+    "open": "Open",
+    "define": "Define",
+    "approve": "Approve",
+    "execute": "Execute",
+    "verify": "Verify",
+    "integrate": "Integrate",
+    "close": "Close",
+}
+
+_STATUS_TO_KERNEL_PHASE = {
+    "planning": "define",
+    "in_progress": "execute",
+    "review": "verify",
+    "completed": "close",
+    "done": "close",
+}
+
+_PHASE_DEFAULT_CONDITION = {
+    "open": "ready",
+    "define": "ready",
+    "approve": "waiting",
+    "execute": "active",
+    "verify": "waiting",
+    "integrate": "waiting",
+    "close": "ready",
+}
+
+_VALID_CONDITIONS = frozenset({"ready", "active", "waiting", "blocked"})
+_VALID_OUTCOMES = frozenset({"completed", "cancelled", "failed"})
+
+
+def _task_path(dir_name: str) -> str:
+    return f"{DIR_WORKFLOW}/{DIR_TASKS}/{dir_name}"
+
+
+def format_verify_summary(task_dir: Path, task_data: dict) -> str:
+    """Return a compact verify evidence label for dashboard task lines."""
+    verify_path = task_dir / "verify.md"
+    if not verify_path.is_file():
+        return "[verify: missing]"
+    status = verify_evidence_status(task_dir, task_data)
+    if all(status.values()):
+        return "[verify: ok]"
+    if any(status.values()):
+        return "[verify: partial]"
+    return "[verify: missing]"
+
+
+def project_kernel_surface(task_dir: Path, task_data: dict | None = None) -> dict:
+    """Read-only Kernel projection: phase, condition, outcome, human title.
+
+    Prefers `kernel.json` when present. Does not mutate `task.json.status`.
+    Integrate is a visible slot only when topology is parent-child or the
+    task is already in that phase.
+    """
+    data = task_data if isinstance(task_data, dict) else {}
+    kernel = _load_kernel_json(task_dir)
+    phase: str | None = None
+    condition: str | None = None
+    outcome = None
+    if isinstance(kernel, dict):
+        raw_phase = kernel.get("phase")
+        if raw_phase in _KERNEL_PHASE_HUMAN:
+            phase = raw_phase
+            condition = kernel.get("condition")
+            outcome = kernel.get("outcome")
+    status = data.get("status") if isinstance(data.get("status"), str) else ""
+    if phase is None:
+        phase = _STATUS_TO_KERNEL_PHASE.get(status, "open")
+        condition = _PHASE_DEFAULT_CONDITION.get(phase, "ready")
+        outcome = "completed" if phase == "close" else None
+    if condition not in _VALID_CONDITIONS:
+        condition = _PHASE_DEFAULT_CONDITION.get(phase, "ready")
+    if outcome not in _VALID_OUTCOMES and outcome is not None:
+        outcome = None
+    topology_kind = _topology_kind(data, kernel)
+    return {
+        "phase": phase,
+        "condition": condition,
+        "outcome": outcome,
+        "status": status,
+        "humanPhase": _KERNEL_PHASE_HUMAN[phase],
+        "showIntegrate": phase == "integrate" or topology_kind == "parent-child",
+    }
+
+
+def _load_kernel_json(task_dir: Path) -> dict | None:
+    path = task_dir / "kernel.json"
+    if not path.is_file():
+        return None
+    try:
+        parsed = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+def _topology_kind(task_data: dict, kernel: dict | None) -> str | None:
+    topo = task_data.get("topology")
+    if isinstance(topo, dict) and isinstance(topo.get("kind"), str):
+        return topo["kind"]
+    if not isinstance(kernel, dict):
+        return None
+    projection = kernel.get("projection")
+    extras = projection.get("extras") if isinstance(projection, dict) else None
+    extra_topo = extras.get("topology") if isinstance(extras, dict) else None
+    if isinstance(extra_topo, dict) and isinstance(extra_topo.get("kind"), str):
+        return extra_topo["kind"]
+    return None
+
+
+def _selected_line(
+    repo_root: Path,
+    platform_input: dict | None = None,
+    platform: str | None = None,
+) -> str:
+    selected = resolve_selected_task(repo_root, platform_input, platform)
+    if selected.task_path:
+        suffix = f" ({selected.source})" if selected.source else ""
+        return f"Selected task: {selected.task_path}{suffix}"
+    return (
+        "Selected task: none "
+        "(no session pointer — use task.py select <task> or task.py list)"
+    )
+
+
+def render_task_dashboard(
+    repo_root: Path | None = None,
+    platform_input: dict | None = None,
+    platform: str | None = None,
+) -> str:
+    """Render a compact, non-mutating Task Dashboard."""
+    if repo_root is None:
+        repo_root = get_repo_root()
+
+    tasks_dir = get_tasks_dir(repo_root)
+    developer = get_developer(repo_root)
+    all_tasks = {task.dir_name: task for task in iter_active_tasks(tasks_dir)}
+    all_statuses = {name: task.status for name, task in all_tasks.items()}
+    surfaces = {
+        name: project_kernel_surface(task.directory, task.raw or {})
+        for name, task in all_tasks.items()
+    }
+    selected = resolve_selected_task(repo_root, platform_input, platform)
+
+    lines: list[str] = [
+        "Task Dashboard",
+        "Pactile framework: active",
+        _selected_line(repo_root, platform_input, platform),
+        "",
+    ]
+
+    if not all_tasks:
+        lines.append("Tasks: none")
+    else:
+        printed: set[str] = set()
+        show_integrate = any(item["showIntegrate"] for item in surfaces.values())
+        phase_order = (
+            _KERNEL_PHASE_ORDER
+            if show_integrate
+            else tuple(phase for phase in _KERNEL_PHASE_ORDER if phase != "integrate")
+        )
+        for phase in phase_order:
+            names = [
+                name
+                for name, task in sorted(all_tasks.items())
+                if surfaces[name]["phase"] == phase and not task.parent
+            ]
+            if not names:
+                continue
+            lines.append(f"{_KERNEL_PHASE_HUMAN[phase]}:")
+            for name in names:
+                _append_task(
+                    lines, name, all_tasks, all_statuses, printed, surfaces
+                )
+            lines.append("")
+
+        other_names = [
+            name
+            for name, task in sorted(all_tasks.items())
+            if name not in printed and not task.parent
+        ]
+        if other_names:
+            lines.append("Other:")
+            for name in other_names:
+                _append_task(
+                    lines, name, all_tasks, all_statuses, printed, surfaces
+                )
+            lines.append("")
+
+    lines.append("Suggested actions:")
+    lines.append("  - Select a task: python ./.pactile/scripts/task.py select <task>")
+    lines.append("  - Create a task: python ./.pactile/scripts/task.py create \"<title>\" --slug <slug>")
+    lines.append("  - Inspect raw list: python ./.pactile/scripts/task.py list")
+    if not selected.task_path:
+        lines.append(
+            "  - No selected task: Intake — direct answer, clarify, pool intent, or Open Proposal"
+        )
+    if developer:
+        lines.append(f"Developer: {developer}")
+
+    return "\n".join(line.rstrip() for line in lines).rstrip()
+
+
+def _append_task(
+    lines: list[str],
+    name: str,
+    all_tasks: dict,
+    all_statuses: dict[str, str],
+    printed: set[str],
+    surfaces: dict[str, dict],
+    indent: int = 0,
+    parent_dir: Path | None = None,
+) -> None:
+    task = all_tasks[name]
+    printed.add(name)
+    integration_states = None
+    if task.children:
+        integration_states = load_parent_child_integration_states(
+            task.directory, task.children
+        )
+    progress = children_progress(
+        task.children, all_statuses, integration_states
+    )
+    integration_state = None
+    if parent_dir is not None:
+        integration_state = get_child_state(parent_dir, name)
+    human_phase = surfaces.get(name, {}).get("humanPhase") or "Open"
+    status_display = format_child_task_display(human_phase, integration_state)
+    assignee = task.assignee or "-"
+    verify_summary = format_verify_summary(task.directory, task.raw or {})
+    prefix = "  " * indent + "  - "
+    lines.append(
+        f"{prefix}{_task_path(name)} ({status_display}){progress} [{assignee}] {verify_summary}"
+    )
+    deps_line = dashboard_deps_line(
+        task.directory,
+        task.raw or {},
+        parent_dir=parent_dir,
+    )
+    if deps_line:
+        lines.append(f"{prefix}{deps_line}")
+    for child_name in task.children:
+        if child_name in all_tasks:
+            _append_task(
+                lines,
+                child_name,
+                all_tasks,
+                all_statuses,
+                printed,
+                surfaces,
+                indent + 1,
+                parent_dir=task.directory,
+            )