task-harbor 0.7.0__py3-none-any.whl

opus_manager/preflight.py

@@ -0,0 +1,92 @@
+"""Deterministic environment recipes and baseline evidence in disposable worktrees."""
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import uuid
+import hashlib
+from pathlib import Path
+
+from .gitops import detached_worktree_add, worktree_remove, changed_paths, git
+from .verification import run_checks
+
+
+def verification_mutations(cfg, cwd: Path) -> list[str]:
+    tracked = set(filter(None, git(cwd, "ls-files", "-z").stdout.split("\0")))
+    return [p for p in changed_paths(cwd) if p in tracked or p not in cfg.verification_artifacts]
+
+
+def collect_artifacts(cfg, cwd: Path, destination: Path) -> list[dict]:
+    """Retain explicit check outputs; never follow links outside the worktree."""
+    records = []
+    for name in cfg.verification_artifacts:
+        source = cwd / name
+        record = {"source": name}
+        if not source.resolve().is_relative_to(cwd.resolve()) or source.is_symlink():
+            record["status"] = "rejected_path"
+        elif not source.is_file():
+            record["status"] = "missing"
+        elif source.stat().st_size > 20 * 1024 * 1024:
+            record["status"] = "too_large"
+        else:
+            data = source.read_bytes()
+            digest = hashlib.sha256(data).hexdigest()
+            destination.mkdir(parents=True, exist_ok=True)
+            target = destination / (digest + source.suffix)
+            target.write_bytes(data)
+            record.update(status="retained", path=str(target.resolve()), sha256=digest, bytes=len(data))
+        records.append(record)
+    return records
+
+
+def suggestions(repo: Path) -> list[str]:
+    found = []
+    package = repo / "package.json"
+    if package.exists():
+        scripts = json.loads(package.read_text(encoding="utf-8")).get("scripts", {})
+        for name in ("test", "lint", "build"):
+            if name in scripts:
+                found.append(f"npm run {name}")
+    if (repo / "pytest.ini").exists() or ((repo / "pyproject.toml").exists() and (repo / "tests").is_dir()):
+        found.append("python -m pytest")
+    if (repo / "Cargo.toml").exists():
+        found.append("cargo test")
+    if (repo / "go.mod").exists():
+        found.append("go test ./...")
+    return found
+
+
+def execute_checks(cfg, cwd: Path, env=None) -> dict:
+    missing = [f"executable:{name}" for name in cfg.required_executables if not shutil.which(name)]
+    missing += [f"environment:{name}" for name in cfg.required_env if not (env or os.environ).get(name)]
+    setup = []
+    checks = []
+    if not missing:
+        setup = run_checks(cfg.setup_commands, cwd, timeout=cfg.verification_timeout_seconds,
+                           limit=cfg.evidence_max_chars, env=env)
+        if all(c["exit_code"] == 0 and not c["timed_out"] for c in setup):
+            checks = run_checks(cfg.verification_commands, cwd, timeout=cfg.verification_timeout_seconds,
+                                limit=cfg.evidence_max_chars, env=env)
+    # Explicit artifact paths may be newly generated, never edits to tracked files.
+    mutation = verification_mutations(cfg, cwd)
+    status = "PASS"
+    if missing or any(c["exit_code"] or c["timed_out"] for c in setup) or mutation:
+        status = "ENVIRONMENT_BLOCKED"
+    elif any(c["exit_code"] or c["timed_out"] for c in checks):
+        status = "FAIL"
+    elif not checks:
+        status = "UNVERIFIED"
+    return {"status": status, "missing": missing, "setup": setup, "checks": checks,
+            "mutated_paths": mutation, "commands": list(cfg.verification_commands)}
+
+
+def baseline(repo: Path, cfg, commit: str, env=None) -> dict:
+    path = repo.parent / f".{repo.name}-harbor-preflight-{uuid.uuid4().hex}"
+    detached_worktree_add(repo, path, commit)
+    try:
+        result = execute_checks(cfg, path, env)
+        result.update(commit=commit, suggestions=suggestions(path))
+        return result
+    finally:
+        worktree_remove(repo, path, force=True)

opus_manager/prompts.py

@@ -0,0 +1,259 @@
+from __future__ import annotations
+
+import json
+
+from .models import BacklogTask
+
+
+def task_context(t: BacklogTask) -> str:
+    return json.dumps({
+        "id": t.task_id,
+        "title": t.title,
+        "priority": t.priority.value,
+        "dependencies": t.dependencies,
+        "acceptance_criteria": t.acceptance_criteria,
+        "acceptance_ids": {f"AC-{i+1}": text for i, text in enumerate(t.acceptance_criteria)},
+        "next_action": t.next_action,
+        "task_agreement": t.metadata.get("contract", {}),
+    }, indent=2)
+
+
+def select_work(candidates: list[BacklogTask], slots: int, completed: list[str]) -> str:
+    items = [json.loads(task_context(t)) for t in candidates]
+    return f"""You are the IT Manager for this repository. Choose up to {slots} tasks to send to independent planners now.
+
+The harness has already enforced hard dependency completion and planner capacity. Use engineering judgment among the eligible tasks. The default priority order is blocker > critical bug > high-risk/high-dependency > core functionality > lower-risk > polish, but you may account for sequencing, risk reduction, and useful parallelism. Do not solve or plan the tasks here.
+
+Completed task IDs: {json.dumps(completed)}
+Eligible candidates:
+{json.dumps(items, indent=2)}
+
+Return ONLY JSON:
+{{"task_ids":["TASK-ID", ...], "reason":"short scheduling rationale"}}
+Do not select a task that is not in the candidate list. Do not exceed {slots} tasks.
+"""
+
+
+def planner(t: BacklogTask, repo_snapshot: str) -> str:
+    return f"""You are the planner for one software task. Produce the strongest implementation plan you can after inspecting the repository. You are not the implementer: do not edit files.
+
+Task:
+{task_context(t)}
+
+Repository snapshot:
+{repo_snapshot}
+
+Use your own engineering judgment. Investigate enough of the codebase to resolve material uncertainty, identify dependencies and likely integration points, and make the plan executable without turning it into brittle line-by-line instructions. Call out assumptions, risks, validation, and any reason the task should not proceed yet. The plan should preserve implementation freedom where multiple approaches are reasonable.
+
+Return a Markdown plan suitable for plans/{t.task_id}.md. End with a concise "Acceptance mapping" section that connects the task's acceptance criteria to verification evidence.
+"""
+
+
+def plan_review(t: BacklogTask, plan: str, repo_snapshot: str) -> str:
+    return f"""You are the IT Manager reviewing a planner's work. Independently assess whether the plan is accurate, sufficiently grounded in the current repository, aligned with the task, and safe to hand to an implementer. Do not approve just because a plan is detailed. Do not rewrite the plan unless rework is needed.
+
+Task:
+{task_context(t)}
+
+Repository snapshot:
+{repo_snapshot}
+
+Proposed plan:
+---
+{plan}
+---
+
+If a material user decision is missing, return verdict NEEDS_CLARIFICATION and questions as a list of concise strings. Do not invent the answers.
+
+Return ONLY JSON:
+{{"verdict":"APPROVED"|"REWORK"|"NEEDS_CLARIFICATION", "feedback":"concise, actionable review feedback", "material_risks":["..."]}}
+Use REWORK only for material gaps, incorrect assumptions, missing dependency/acceptance coverage, or a plan likely to cause bad implementation. Preserve implementer discretion on non-material design choices.
+"""
+
+
+def plan_rework(t: BacklogTask, previous_plan: str, feedback: str) -> str:
+    return f"""You are the same planning role revising a plan after manager review. Re-inspect the repository where useful and correct the material issues. Keep sound parts; do not mechanically obey feedback that conflicts with repository evidence.
+
+Task:
+{task_context(t)}
+
+Previous plan:
+---
+{previous_plan}
+---
+
+Manager feedback:
+{feedback}
+
+Return only the revised Markdown plan. Preserve implementation freedom where the evidence does not force a single approach.
+"""
+
+
+def implement(t: BacklogTask, plan: str) -> str:
+    return f"""You are the implementer for this task. Work directly in the current isolated Git worktree and implement the approved plan to production quality.
+
+Task:
+{task_context(t)}
+
+Approved plan:
+---
+{plan}
+---
+
+Use your engineering judgment. The plan is a validated guide, not a prohibition on necessary repo-grounded adjustments. If you discover a material contradiction, prefer the repository and acceptance criteria and explain it in your final response.
+
+Requirements enforced by the harness:
+- Do not edit BACKLOG.md or .manager/.
+- Do not push, create PRs, publish packages, deploy, or alter remote repositories/services.
+- Do not commit; the harness creates local checkpoint commits.
+- Run appropriate focused validation while implementing when practical.
+
+Finish with a concise implementation summary, tests/validation run, and any remaining uncertainty.
+"""
+
+
+def same_implementer_fix(t: BacklogTask, qa_evidence: str, attempt: int) -> str:
+    return f"""QA did not verify your implementation. This is repair attempt {attempt}. You retain your implementation context.
+
+Task:
+{task_context(t)}
+
+Independent QA evidence:
+---
+{qa_evidence}
+---
+
+Diagnose the evidence against the actual repository and fix the underlying issue. Do not merely patch toward the wording of QA if the evidence points elsewhere. Re-run relevant validation. Do not edit BACKLOG.md/.manager, push, create PRs, publish, deploy, or commit.
+
+Finish with what changed and what you validated.
+"""
+
+
+def qa(t: BacklogTask, plan: str, verification_commands: list[str]) -> str:
+    commands = json.dumps(verification_commands)
+    return f"""You are an independent QA agent. You did not implement this task and do not inherit the implementer's reasoning. Inspect the current disposable verification worktree and determine whether the delivered code satisfies the approved plan and acceptance criteria.
+
+Task:
+{task_context(t)}
+
+Approved plan:
+---
+{plan}
+---
+
+Configured verification commands (run when applicable; add focused checks when engineering judgment requires it):
+{commands}
+
+You may inspect files and run commands. Do not edit source code, fix the implementation, push, publish, deploy, or create PRs. Distinguish an actual implementation failure from inability to verify due to environment/tooling.
+
+Return ONLY JSON:
+{{
+  "verdict":"PASS"|"FAIL"|"UNVERIFIED",
+  "summary":"short conclusion",
+  "acceptance": [{{"criterion_id":"AC-1", "criterion":"...", "status":"PASS"|"FAIL"|"UNVERIFIED", "evidence":"specific evidence"}}],
+  "commands_run":[{{"command":"...", "result":"..."}}],
+  "failures":["concrete reproducible failure evidence"],
+  "risks":["remaining risk if any"]
+}}
+PASS only when every acceptance ID appears exactly once with specific evidence.
+"""
+
+
+def classify_escalation(t: BacklogTask, qa_evidence: str) -> str:
+    return f"""You are the IT Manager handling a third QA failure. The prior implementer context is considered potentially poisoned. Choose the evidence-gathering role for a clean restart; do not propose the implementation solution.
+
+Task:
+{task_context(t)}
+
+Concrete QA evidence:
+---
+{qa_evidence}
+---
+
+Choose INVESTIGATOR when a localized question/reproduction can settle the failure. Choose AUDITOR when the failure depends on a general claim over a broader population/configuration/data surface and needs systematic coverage. Use your judgment rather than keyword rules.
+
+Return ONLY JSON:
+{{"role":"INVESTIGATOR"|"AUDITOR", "question":"neutral evidence question the diagnostic agent should answer", "reason":"short rationale"}}
+"""
+
+
+def diagnose(t: BacklogTask, role: str, question: str, qa_evidence: str) -> str:
+    return f"""You are an independent {role.lower()} brought in after repeated implementation failures. Your job is evidence gathering, not implementation. Inspect the current repository state and answer the diagnostic question neutrally.
+
+Task:
+{task_context(t)}
+
+Diagnostic question:
+{question}
+
+Observed QA evidence:
+---
+{qa_evidence}
+---
+
+Do not edit code and do not prescribe a full solution. Establish facts, reproductions, scope, and uncertainty that a fresh implementer needs to avoid repeating known mistakes.
+
+Return ONLY JSON:
+{{"findings":["concrete evidence"], "scope":"what is and is not established", "neutral_failure_note":"short neutral description of where the prior attempt appears to fail", "uncertainties":["..."]}}
+"""
+
+
+def fresh_implementer(t: BacklogTask, restart_packet: str) -> str:
+    return f"""You are a fresh implementer taking over after a previous implementation repeatedly failed QA. You have deliberately NOT been given the previous implementer's conversation or solution strategy.
+
+Clean restart packet:
+---
+{restart_packet}
+---
+
+Independently diagnose and implement the best solution in this isolated worktree. Treat prior details only as evidence, not instructions. Preserve freedom to choose a different implementation strategy.
+
+Do not edit BACKLOG.md/.manager, push, create PRs, publish, deploy, or commit. Finish with a concise summary and validation performed.
+"""
+
+
+def code_review(batch_task_ids: list[str], base_commit: str, diff_stat: str) -> str:
+    return f"""You are an independent senior code reviewer. Review the cumulative code delivered since the last code-review checkpoint. Focus on blockers, correctness bugs, security/reliability problems, regressions, and critical maintainability issues. Avoid blocking on style or subjective polish.
+
+Tasks in/around this review batch: {json.dumps(batch_task_ids)}
+Review base commit: {base_commit}
+Current diff summary:
+{diff_stat}
+
+Inspect the repository and diff directly. Do not edit code.
+
+Return ONLY JSON:
+{{
+  "verdict":"PASS"|"CHANGES_REQUIRED",
+  "findings":[{{"severity":"BLOCKER"|"BUG"|"CRITICAL"|"NON_BLOCKING", "title":"...", "evidence":"file/behavior-specific evidence", "affected_task_ids":["TASK-ID"]}}],
+  "summary":"concise review conclusion"
+}}
+CHANGES_REQUIRED only when at least one finding is BLOCKER, BUG, or CRITICAL.
+"""
+
+
+def review_fix(review_json: str) -> str:
+    return f"""You are an implementer assigned to resolve critical findings from an independent cumulative code review on the integration branch. Work in the isolated review-fix worktree.
+
+Review findings:
+---
+{review_json}
+---
+
+Use engineering judgment to fix the root causes without broad unrelated refactors. Do not edit BACKLOG.md/.manager, push, create PRs, publish, deploy, or commit. Run relevant validation and summarize the changes.
+"""
+
+
+def review_qa(review_json: str, verification_commands: list[str]) -> str:
+    return f"""You are independent QA verifying fixes for cumulative code-review findings.
+
+Original code review:
+---
+{review_json}
+---
+
+Configured verification commands: {json.dumps(verification_commands)}
+
+Inspect and test the disposable worktree. Do not edit source code. Return ONLY JSON:
+{{"verdict":"PASS"|"FAIL"|"UNVERIFIED", "summary":"...", "failures":["concrete evidence"], "commands_run":[{{"command":"...", "result":"..."}}]}}
+"""

opus_manager/providers.py

@@ -0,0 +1,11 @@
+from pathlib import Path
+
+from .claude import ClaudeClient
+from .codex import CodexClient
+from .config import Config
+
+
+def create_client(config: Config, hooks_dir: Path) -> ClaudeClient | CodexClient:
+    if config.provider == "codex":
+        return CodexClient(config, hooks_dir)
+    return ClaudeClient(config, hooks_dir)

opus_manager/reporting.py

@@ -0,0 +1,82 @@
+"""Offline run reports: no server, external assets, or model calls."""
+from __future__ import annotations
+
+import html
+import json
+from pathlib import Path
+
+from .state import load_state
+from .usage import summarize
+
+
+def task_evidence(run_dir: Path, task) -> dict:
+    if not task.last_qa_path:
+        return {"verification_level": "not_verified"}
+    path = Path(task.last_qa_path).resolve()
+    if not path.is_relative_to(run_dir.resolve()) or not path.exists():
+        return {"verification_level": "evidence_unavailable"}
+    return json.loads(path.read_text(encoding="utf-8"))
+
+
+def review_text(report: dict, task_id: str | None = None) -> str:
+    lines = [f'Task Harbor review: {report["run_id"]}', f'Branch: {report["integration_branch"]}']
+    selected = [t for t in report["tasks"] if task_id is None or t["id"] == task_id]
+    if not selected:
+        raise ValueError(f"Task not found: {task_id}")
+    for task in selected:
+        evidence = task["evidence"]
+        lines += ["", f'{task["id"]}: {task["title"]}', f'Status: {task["status"]}',
+                  f'Checkpoint: {evidence.get("checkpoint_commit", "not recorded")}',
+                  f'Verification: {evidence.get("verification_level", "legacy/unknown")}',
+                  "Task agreement: " + json.dumps(task["contract"], indent=2),
+                  "Acceptance: " + json.dumps(evidence.get("acceptance", []), indent=2),
+                  "Executed checks: " + json.dumps(evidence.get("harness_checks", []), indent=2),
+                  "Before/after reproduction: " + json.dumps(evidence.get("reproduction", {}), indent=2),
+                  "Artifacts: " + json.dumps(evidence.get("artifacts", []), indent=2),
+                  "Failure classification: " + json.dumps(evidence.get("failure_classification", []), indent=2),
+                  "Human feedback: " + json.dumps([f for f in report.get("feedback", []) if f.get("task") == task["id"]], indent=2),
+                  "Unverified / risks: " + json.dumps(evidence.get("risks", []))]
+        for file in evidence.get("changes", {}).get("files", []):
+            lines += [f'\nFILE: {file["path"]}', "Review flags: " + ", ".join(file["warnings"]), file["diff"]]
+    return "\n".join(lines)
+
+
+def run_report(run_dir: Path) -> dict:
+    state = load_state(run_dir / "state.json")
+    usage_file = run_dir / "usage.json"
+    usage = json.loads(usage_file.read_text(encoding="utf-8")) if usage_file.exists() else {"calls": []}
+    feedback_path = run_dir / "feedback.json"
+    feedback = json.loads(feedback_path.read_text(encoding="utf-8")) if feedback_path.exists() else []
+    completed = sum(t.status.value == "COMPLETE" for t in state.tasks.values())
+    totals = summarize(usage)
+    return {"run_id": state.run_id, "provider": state.provider, "integration_branch": state.integration_branch,
+            "feedback": feedback, "active_review_minutes": sum(f["active_review_minutes"] for f in feedback),
+            "paused": state.paused, "stop_reason": state.stop_reason,
+            "completed": completed, "total": len(state.tasks), "usage": totals,
+            "reported_cost_per_completed_task": totals["reported_cost_usd"] / completed if completed else None,
+            "tasks": [{"id": t.task_id, "title": t.title, "status": t.status.value,
+                       "dependencies": t.dependencies, "blocked_reason": t.blocked_reason,
+                       "next_action": t.next_action, "generation": t.generation,
+                       "checkpoint": t.checkpoint_commit,
+                       "contract": t.metadata.get("contract", {}),
+                       "evidence": task_evidence(run_dir, t),
+                       "usage": summarize({"calls": [c for c in usage["calls"] if c.get("task") == t.task_id]})}
+                      for t in state.tasks.values()]}
+
+
+def write_html(report: dict, output: Path) -> None:
+    esc = lambda value: html.escape(str(value if value is not None else "—"))
+    rows = "".join("<tr>" + "".join(f"<td>{esc(t[k])}</td>" for k in
+                   ("id", "title", "status", "blocked_reason", "next_action")) + "</tr>" for t in report["tasks"])
+    details = "".join(f'<details><summary>{esc(t["id"])}: {esc(t["title"])}</summary><pre>{esc(review_text(report, t["id"]))}</pre></details>' for t in report["tasks"])
+    output.write_text(f'''<!doctype html><html lang="en"><meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1"><title>Task Harbor · Run report</title>
+<style>body{{font:16px system-ui;margin:3rem;background:#101923;color:#e2eaf2}}h1{{color:#68debf}}
+table{{border-collapse:collapse;width:100%}}td,th{{padding:1rem;text-align:left;border-bottom:1px solid #35414d}}
+pre{{white-space:pre-wrap}}.scroll{{overflow:auto}}p{{line-height:1.7}}</style>
+<h1>Task Harbor</h1><p>Run {esc(report["run_id"])} · {report["completed"]}/{report["total"]} complete</p>
+<p>{esc(report["integration_branch"])}<br>{esc(report["stop_reason"])}</p>
+<h2>Usage</h2><pre>{esc(json.dumps(report["usage"], indent=2))}</pre>
+<p>Costs are CLI estimates. Calls without reported cost are unknown, not free. Snapshot; regenerate to refresh.</p>
+<div class="scroll"><table><thead><tr><th>Task</th><th>Title</th><th>Status</th><th>Blocked</th><th>Next action</th></tr></thead>
+<tbody>{rows}</tbody></table></div><h2>Evidence and diffs</h2>{details}</html>''', encoding="utf-8")

opus_manager/state.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+
+from .models import ManagerState
+
+
+def atomic_write_json(path: Path, payload: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(prefix=path.name, suffix=".tmp", dir=path.parent)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            json.dump(payload, f, indent=2)
+            f.write("\n")
+            f.flush()
+            os.fsync(f.fileno())
+        os.replace(tmp, path)
+    finally:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+
+
+def save_state(path: Path, state: ManagerState) -> None:
+    atomic_write_json(path, state.to_dict())
+
+
+def load_state(path: Path) -> ManagerState:
+    return ManagerState.from_dict(json.loads(path.read_text(encoding="utf-8")))
+
+
+def append_event(path: Path, event: dict) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("a", encoding="utf-8") as f:
+        f.write(json.dumps(event, sort_keys=True) + "\n")