@blxzer/pactile 0.5.0

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

@@ -0,0 +1,592 @@
+#!/usr/bin/env python3
+"""
+Subagent dispatch prompt builder — single source for hook + CLI Layer 2.
+
+Agent-facing only; not documented in user README.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+from typing import Literal
+
+from .injection_budget import (
+    JSONL_MAX_ENTRIES,
+    JSONL_MAX_FILE_CHARS,
+    JSONL_MAX_TOTAL_CHARS,
+)
+from .io import read_json
+from .paths import FILE_TASK_JSON
+
+DIR_WORKFLOW = ".pactile"
+DIR_SPEC = "spec"
+
+AGENT_IMPLEMENT = "pactile-implement"
+AGENT_CHECK = "pactile-check"
+AGENT_RESEARCH = "pactile-research"
+
+AGENTS_ALL = (AGENT_IMPLEMENT, AGENT_CHECK, AGENT_RESEARCH)
+AGENTS_REQUIRE_TASK = (AGENT_IMPLEMENT, AGENT_CHECK)
+
+INJECTION_MARKER = "<!-- pactile-hook-injected -->"
+
+DispatchRole = Literal["implement", "check", "research"]
+
+DEFAULT_SCOPES: dict[str, str] = {
+    "implement": (
+        "Implement per prd.md and implement.md; run project lint/typecheck/tests."
+    ),
+    "check": (
+        "Review against prd/spec; fix in-contract defects; record evidence in verify.md."
+    ),
+    "research": "Research and persist to {TASK}/research/.",
+}
+
+
+def prompt_has_injection_marker(text: str) -> bool:
+    return INJECTION_MARKER in text
+
+
+def read_file_content(base_path: str, file_path: str) -> str | None:
+    full_path = os.path.join(base_path, file_path)
+    if os.path.exists(full_path) and os.path.isfile(full_path):
+        try:
+            with open(full_path, "r", encoding="utf-8") as f:
+                return f.read()
+        except OSError:
+            return None
+    return None
+
+
+def read_directory_contents(
+    base_path: str, dir_path: str, max_files: int = 20
+) -> list[tuple[str, str]]:
+    full_path = os.path.join(base_path, dir_path)
+    if not os.path.exists(full_path) or not os.path.isdir(full_path):
+        return []
+
+    results: list[tuple[str, str]] = []
+    try:
+        md_files = sorted(
+            f
+            for f in os.listdir(full_path)
+            if f.endswith(".md") and os.path.isfile(os.path.join(full_path, f))
+        )
+        for filename in md_files[:max_files]:
+            file_full_path = os.path.join(full_path, filename)
+            relative_path = os.path.join(dir_path, filename)
+            try:
+                with open(file_full_path, "r", encoding="utf-8") as f:
+                    results.append((relative_path, f.read()))
+            except OSError:
+                continue
+    except OSError:
+        pass
+    return results
+
+
+def read_jsonl_entries(
+    base_path: str,
+    jsonl_path: str,
+    *,
+    warn_prefix: str = "subagent-dispatch",
+    apply_budget: bool = True,
+) -> tuple[list[tuple[str, str]], list[str]]:
+    full_path = os.path.join(base_path, jsonl_path)
+    if not os.path.exists(full_path):
+        print(
+            f"[{warn_prefix}] WARN: {jsonl_path} not found — "
+            "sub-agent will receive only task artifacts",
+            file=sys.stderr,
+        )
+        return [], []
+
+    results: list[tuple[str, str]] = []
+    skipped: list[str] = []
+    saw_real_entry = False
+    loaded_entries = 0
+    total_chars = 0
+    try:
+        with open(full_path, "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    item = json.loads(line)
+                    file_path = item.get("file") or item.get("path")
+                    entry_type = item.get("type", "file")
+                    if not file_path:
+                        continue
+                    saw_real_entry = True
+                    if apply_budget and loaded_entries >= JSONL_MAX_ENTRIES:
+                        skipped.append(f"{file_path}: entry cap ({JSONL_MAX_ENTRIES})")
+                        continue
+
+                    expanded: list[tuple[str, str]] = []
+                    if entry_type == "directory":
+                        expanded = read_directory_contents(base_path, file_path)
+                    else:
+                        content = read_file_content(base_path, file_path)
+                        if content:
+                            expanded = [(file_path, content)]
+
+                    if not expanded:
+                        skipped.append(f"{file_path}: missing or empty")
+                        continue
+
+                    block_chars = sum(len(content) for _, content in expanded)
+                    if apply_budget and block_chars > JSONL_MAX_FILE_CHARS:
+                        skipped.append(
+                            f"{file_path}: file cap ({block_chars}>{JSONL_MAX_FILE_CHARS} chars)"
+                        )
+                        continue
+                    if apply_budget and total_chars + block_chars > JSONL_MAX_TOTAL_CHARS:
+                        skipped.append(
+                            f"{file_path}: total cap "
+                            f"({total_chars + block_chars}>{JSONL_MAX_TOTAL_CHARS})"
+                        )
+                        continue
+
+                    results.extend(expanded)
+                    total_chars += block_chars
+                    loaded_entries += 1
+                except json.JSONDecodeError:
+                    continue
+    except OSError:
+        pass
+
+    if not saw_real_entry:
+        print(
+            f"[{warn_prefix}] WARN: {jsonl_path} has no curated entries "
+            "(only seed / empty) — sub-agent will receive only task artifacts.",
+            file=sys.stderr,
+        )
+    elif apply_budget and (results or skipped):
+        loaded_paths = ", ".join(path for path, _ in results) or "(none)"
+        print(
+            f"[{warn_prefix}] injection-budget: {jsonl_path} "
+            f"loaded {loaded_entries} entries ({total_chars} chars): {loaded_paths}",
+            file=sys.stderr,
+        )
+        for reason in skipped:
+            print(f"[{warn_prefix}] injection-budget: skipped {reason}", file=sys.stderr)
+    return results, skipped
+
+
+def get_agent_context(repo_root: str, task_dir: str, agent_type: str) -> str:
+    context_parts: list[str] = []
+    agent_jsonl = f"{task_dir}/{agent_type}.jsonl"
+    entries, _ = read_jsonl_entries(repo_root, agent_jsonl)
+    for file_path, content in entries:
+        context_parts.append(f"=== {file_path} ===\n{content}")
+    return "\n\n".join(context_parts)
+
+
+def get_implement_context(repo_root: str, task_dir: str) -> str:
+    context_parts: list[str] = []
+    base_context = get_agent_context(repo_root, task_dir, "implement")
+    if base_context:
+        context_parts.append(base_context)
+
+    prd_content = read_file_content(repo_root, f"{task_dir}/prd.md")
+    if prd_content:
+        context_parts.append(f"=== {task_dir}/prd.md (Requirements) ===\n{prd_content}")
+
+    design_content = read_file_content(repo_root, f"{task_dir}/design.md")
+    if design_content:
+        context_parts.append(
+            f"=== {task_dir}/design.md (Technical Design) ===\n{design_content}"
+        )
+
+    implement_plan_content = read_file_content(repo_root, f"{task_dir}/implement.md")
+    if implement_plan_content:
+        context_parts.append(
+            f"=== {task_dir}/implement.md (Execution Plan) ===\n{implement_plan_content}"
+        )
+    return "\n\n".join(context_parts)
+
+
+def get_check_context(repo_root: str, task_dir: str) -> str:
+    context_parts: list[str] = []
+    entries, _ = read_jsonl_entries(repo_root, f"{task_dir}/check.jsonl")
+    for file_path, content in entries:
+        context_parts.append(f"=== {file_path} ===\n{content}")
+
+    prd_content = read_file_content(repo_root, f"{task_dir}/prd.md")
+    if prd_content:
+        context_parts.append(f"=== {task_dir}/prd.md (Requirements) ===\n{prd_content}")
+
+    design_content = read_file_content(repo_root, f"{task_dir}/design.md")
+    if design_content:
+        context_parts.append(
+            f"=== {task_dir}/design.md (Technical Design) ===\n{design_content}"
+        )
+
+    implement_plan_content = read_file_content(repo_root, f"{task_dir}/implement.md")
+    if implement_plan_content:
+        context_parts.append(
+            f"=== {task_dir}/implement.md (Execution Plan) ===\n{implement_plan_content}"
+        )
+    return "\n\n".join(context_parts)
+
+
+def get_finish_context(repo_root: str, task_dir: str) -> str:
+    return get_check_context(repo_root, task_dir)
+
+
+def get_research_context(repo_root: str, task_dir: str | None) -> str:
+    context_parts: list[str] = []
+
+    if task_dir:
+        entries, _ = read_jsonl_entries(repo_root, f"{task_dir}/research.jsonl")
+        for file_path, content in entries:
+            context_parts.append(f"=== {file_path} ===\n{content}")
+
+        prd_content = read_file_content(repo_root, f"{task_dir}/prd.md")
+        if prd_content:
+            context_parts.append(
+                f"=== {task_dir}/prd.md (Requirements) ===\n{prd_content}"
+            )
+
+        design_content = read_file_content(repo_root, f"{task_dir}/design.md")
+        if design_content:
+            context_parts.append(
+                f"=== {task_dir}/design.md (Technical Design) ===\n{design_content}"
+            )
+
+    spec_path = f"{DIR_WORKFLOW}/{DIR_SPEC}"
+    spec_root = Path(repo_root) / DIR_WORKFLOW / DIR_SPEC
+
+    tree_lines = [f"{spec_path}/"]
+    if spec_root.is_dir():
+        pkg_dirs = sorted(d for d in spec_root.iterdir() if d.is_dir())
+        for i, pkg_dir in enumerate(pkg_dirs):
+            is_last = i == len(pkg_dirs) - 1
+            prefix = "└── " if is_last else "├── "
+            layers = sorted(d.name for d in pkg_dir.iterdir() if d.is_dir())
+            layer_info = f" ({', '.join(layers)})" if layers else ""
+            tree_lines.append(f"{prefix}{pkg_dir.name}/{layer_info}")
+
+    project_structure = f"""## Project Spec Directory Structure
+
+```
+{chr(10).join(tree_lines)}
+```
+
+To get structured package info, run: `python ./{DIR_WORKFLOW}/scripts/get_context.py --mode packages`
+
+## Search Tips
+
+- Spec files: `{spec_path}/**/*.md`
+- Code search: Use Glob and Grep tools
+- External facts / docs: load `smart-search-cli` skill and use Bash (`smart-search` CLI), not Cursor WebSearch/WebFetch by default"""
+    context_parts.append(project_structure)
+    return "\n\n".join(context_parts)
+
+
+def build_implement_prompt(original_prompt: str, context: str) -> str:
+    return f"""{INJECTION_MARKER}
+# Implement Agent Task
+
+You are the Implement Agent in the Multi-Agent Pipeline.
+
+## Your Context
+
+All the information you need has been prepared for you:
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Understand specs** - All dev specs are injected above, understand them
+2. **Understand task artifacts** - Read requirements, technical design if present, and execution plan if present
+3. **Implement feature** - Implement following specs and task artifacts
+4. **Self-check** - Ensure code quality against check specs
+
+## Important Constraints
+
+- Do NOT execute git commit, only code modifications
+- Follow all dev specs injected above
+- Report list of modified/created files when done"""
+
+
+def build_check_prompt(original_prompt: str, context: str) -> str:
+    return f"""{INJECTION_MARKER}
+# Check Agent Task
+
+You are the Check Agent in the Multi-Agent Pipeline (code and cross-layer checker).
+
+## Your Context
+
+All check specs and dev specs you need:
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Get changes** - Run `git diff --name-only` and `git diff` to get code changes
+2. **Check against specs** - Check item by item against specs above
+3. **Self-fix** - Fix issues directly, don't just report
+4. **Run verification** - Run project's lint and typecheck commands
+
+## Important Constraints
+
+- Fix issues yourself, don't just report
+- Must execute complete checklist in check specs
+- Pay special attention to impact radius analysis (L1-L5)"""
+
+
+def build_finish_prompt(original_prompt: str, context: str) -> str:
+    return f"""{INJECTION_MARKER}
+# Finish Agent Task
+
+You are performing the final check before creating a PR.
+
+## Your Context
+
+Finish checklist and requirements:
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Review changes** - Run `git diff --name-only` to see all changed files
+2. **Verify task artifacts** - Check requirements in prd.md and, when present, design.md / implement.md
+3. **Spec sync** - Analyze whether changes introduce new patterns, contracts, or conventions
+4. **Run final checks** - Execute lint and typecheck
+5. **Confirm ready** - Ensure code is ready for PR
+
+## Important Constraints
+
+- You MAY update spec files when gaps are detected (use update-spec.md as guide)
+- MUST read the target spec file BEFORE editing (avoid duplicating existing content)
+- Do NOT update specs for trivial changes (typos, formatting, obvious fixes)
+- Verify all acceptance criteria in prd.md are met"""
+
+
+def build_research_prompt(original_prompt: str, context: str) -> str:
+    return f"""{INJECTION_MARKER}
+# Research Agent Task
+
+You are the Pactile Research Agent.
+
+## Core Principle
+
+**You do one thing: find, explain, and PERSIST information.**
+
+Conversations get compacted; files do not. Every research topic MUST be written under `{{TASK_DIR}}/research/`. Chat-only findings are a failure.
+
+## Dispatch contract
+
+- External facts: load `smart-search-cli` skill + Bash — default **not** Cursor `WebSearch`/`WebFetch`.
+- Do NOT spawn nested `pactile-implement` / `pactile-check` / `pactile-research` sub-agents.
+
+## Project Info
+
+{context}
+
+---
+
+## Your Task
+
+{original_prompt}
+
+---
+
+## Workflow
+
+1. **Resolve task** — ensure `{{TASK_DIR}}/research/` exists
+2. **Classify** — internal / external / mixed
+3. **Search** — Glob/Grep/Read for repo; `smart-search-cli` + CLI for external
+4. **Persist** — Write each topic to `{{TASK_DIR}}/research/<topic-slug>.md`
+5. **Report** — Reply with file paths + one-line summaries only
+
+## Write ALLOWED
+
+- `{{TASK_DIR}}/research/*.md` only
+
+## Write FORBIDDEN
+
+- Code, `.pactile/spec/`, platform config, git operations"""
+
+
+def _repo_relative(task_dir: Path, repo_root: Path) -> str:
+    try:
+        return task_dir.relative_to(repo_root).as_posix()
+    except ValueError:
+        return task_dir.as_posix()
+
+
+def _truncate_context(context: str, max_chars: int | None, warnings: list[str]) -> str:
+    if max_chars is None or len(context) <= max_chars:
+        return context
+    warnings.append(f"context truncated at {max_chars} chars")
+    return context[:max_chars] + "\n...[truncated]..."
+
+
+def _resolve_scope(role: DispatchRole, scope: str | None, task_rel: str) -> str:
+    if scope and scope.strip():
+        return scope.strip()
+    default = DEFAULT_SCOPES[role]
+    if role == "research":
+        return default.replace("{TASK}", task_rel)
+    return default
+
+
+def _compose_task_prompt(task_rel: str, scope: str) -> str:
+    return f"Selected task: {task_rel}\n\n{scope}"
+
+
+def build_dispatch_prompt(
+    repo_root: Path,
+    task_dir: Path,
+    role: str,
+    *,
+    scope: str | None = None,
+    finish: bool = False,
+    max_chars: int | None = None,
+    original_prompt: str | None = None,
+    require_in_progress: bool = True,
+) -> tuple[str | None, list[str], list[str]]:
+    """
+    Build a full subagent dispatch prompt.
+
+    Returns (prompt, warnings, errors). prompt is None on hard failure.
+    When original_prompt is set (hook path), it is used as the task section as-is.
+    """
+    warnings: list[str] = []
+    errors: list[str] = []
+
+    if role not in ("implement", "check", "research"):
+        errors.append(f"invalid role: {role!r}")
+        return None, warnings, errors
+
+    repo_root_str = str(repo_root)
+    if not task_dir.is_dir():
+        errors.append(f"task directory not found: {task_dir}")
+        return None, warnings, errors
+
+    task_rel = _repo_relative(task_dir, repo_root)
+    prd_path = task_dir / "prd.md"
+    if role in ("implement", "check"):
+        if not prd_path.is_file():
+            errors.append(f"prd.md missing under {task_rel}")
+            return None, warnings, errors
+    elif not prd_path.is_file():
+        warnings.append(f"prd.md missing under {task_rel}")
+
+    if role in ("implement", "check") and require_in_progress:
+        task_json_path = task_dir / FILE_TASK_JSON
+        task_data = read_json(task_json_path) if task_json_path.is_file() else None
+        status = (task_data or {}).get("status")
+        if status != "in_progress":
+            errors.append(f"task status must be in_progress, got {status!r}")
+
+    if original_prompt is not None:
+        task_prompt = original_prompt
+    else:
+        resolved_scope = _resolve_scope(role, scope, task_rel)  # type: ignore[arg-type]
+        task_prompt = _compose_task_prompt(task_rel, resolved_scope)
+
+    if role == "implement":
+        context = get_implement_context(repo_root_str, task_rel)
+        context = _truncate_context(context, max_chars, warnings)
+        if not context:
+            errors.append("no implement context available")
+            return None, warnings, errors
+        prompt = build_implement_prompt(task_prompt, context)
+    elif role == "check":
+        context = get_finish_context(repo_root_str, task_rel) if finish else get_check_context(
+            repo_root_str, task_rel
+        )
+        context = _truncate_context(context, max_chars, warnings)
+        if not context:
+            errors.append("no check context available")
+            return None, warnings, errors
+        prompt = (
+            build_finish_prompt(task_prompt, context)
+            if finish
+            else build_check_prompt(task_prompt, context)
+        )
+    else:
+        context = get_research_context(repo_root_str, task_rel)
+        context = _truncate_context(context, max_chars, warnings)
+        if not context:
+            errors.append("no research context available")
+            return None, warnings, errors
+        prompt = build_research_prompt(task_prompt, context)
+
+    return prompt, warnings, errors
+
+
+def build_dispatch_prompt_for_agent(
+    repo_root: str,
+    task_dir: str,
+    subagent_type: str,
+    original_prompt: str,
+    *,
+    finish: bool = False,
+    max_chars: int | None = None,
+) -> str | None:
+    """Hook helper: map subagent type to role and build prompt."""
+    if subagent_type == AGENT_RESEARCH and not task_dir:
+        context = get_research_context(repo_root, None)
+        if max_chars is not None and len(context) > max_chars:
+            context = context[:max_chars] + "\n...[truncated]..."
+        if not context:
+            return None
+        return build_research_prompt(original_prompt, context)
+
+    role_map = {
+        AGENT_IMPLEMENT: "implement",
+        AGENT_CHECK: "check",
+        AGENT_RESEARCH: "research",
+    }
+    role = role_map.get(subagent_type)
+    if not role:
+        return None
+
+    repo_path = Path(repo_root)
+    task_path = repo_path / task_dir.replace("\\", "/")
+    is_finish = finish or "[finish]" in original_prompt.lower()
+    prompt, _, errors = build_dispatch_prompt(
+        repo_path,
+        task_path,
+        role,
+        finish=is_finish if role == "check" else False,
+        max_chars=max_chars,
+        original_prompt=original_prompt,
+        require_in_progress=False,
+    )
+    if errors:
+        for item in errors:
+            print(f"[inject-subagent-context] {item}", file=sys.stderr)
+        return None
+    return prompt