misterdev 0.2.0__py3-none-any.whl

misterdev/core/reporting/report.py

@@ -0,0 +1,377 @@
+"""Build report generation, ported from /build Phase 6.
+
+Produces a structured markdown report summarizing the build session.
+"""
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Optional
+
+from misterdev.core.planning.assessment import (
+    HealthCheck,
+    ProjectAssessment,
+)
+from misterdev.core.models import Task
+from misterdev.core.context.scratchpad import Scratchpad
+from misterdev.core.modes import BuildMode
+from misterdev.core.verification.validator import ValidationResult
+from misterdev.logging_setup import setup_logger
+
+logger = setup_logger(__name__)
+
+
+def _failure_reason(task: Task) -> str:
+    """A concise, table-safe reason a task failed, from its last execution result.
+
+    Surfaces WHY a task failed (gate error, acceptance, low certainty, …) in the
+    report instead of forcing a dig through logs. Falls back to the status when no
+    result detail is available.
+    """
+    history = getattr(task, "execution_history", None) or []
+    detail = ""
+    if history:
+        last = history[-1]
+        detail = (
+            getattr(last, "logs", "") or getattr(last, "message", "") or ""
+        ).strip()
+    if not detail:
+        return getattr(task, "status", "failed") or "failed"
+    # First non-empty line, flattened and escaped for a markdown table cell.
+    line = next((ln.strip() for ln in detail.splitlines() if ln.strip()), detail)
+    line = line.replace("|", "\\|")
+    return line[:120] + ("…" if len(line) > 120 else "")
+
+
+class BuildReport:
+    def __init__(
+        self,
+        mode: BuildMode,
+        project_name: str,
+        assessment: ProjectAssessment,
+        start_time: datetime,
+    ):
+        self.mode = mode
+        self.project_name = project_name
+        self.assessment = assessment
+        self.start_time = start_time
+        self.end_time: Optional[datetime] = None
+        self.completed_tasks: list[Task] = []
+        self.failed_tasks: list[Task] = []
+        self.deferred_tasks: list[Task] = []
+        self.key_decisions: list[str] = []
+        self.scratchpad: Optional[Scratchpad] = None
+        self.health_before: Optional[HealthCheck] = None
+        self.health_after: Optional[HealthCheck] = None
+        self.validation: Optional[ValidationResult] = None
+        self.validation_passed: Optional[bool] = None
+        self.llm_calls: int = 0
+        self.llm_tokens: int = 0
+        # Split so a run's token profile is legible: input (prompt/context) vs
+        # output (completion). A large input:output ratio means the run is
+        # context-bound — the lever is narrower context / prompt caching, not
+        # shorter outputs.
+        self.llm_prompt_tokens: int = 0
+        self.llm_completion_tokens: int = 0
+        self.llm_cost: float = 0.0
+        self.llm_cache_read_tokens: int = 0
+        self.cost_by_task: dict = {}
+        # Best-effort subsystems that threw during the run (e.g. AB-MCTS,
+        # probes). Surfaced in the report so a silently-dead subsystem is
+        # visible to the morning reader, not just buried in a log.
+        self.degraded_subsystems: list[str] = []
+        # Unmet-goal gaps from the optional goal-completion check (advisory: the
+        # gates can be green while the goal is not fully met). Empty unless the
+        # check ran and returned a GAP verdict.
+        self.goal_gaps: list[str] = []
+
+    def finalize(self, end_time: Optional[datetime] = None):
+        self.end_time = end_time or datetime.now(timezone.utc)
+
+    def to_dict(self) -> dict:
+        """Structured representation for programmatic access / history."""
+        return {
+            "mode": self.mode.value,
+            "project": self.project_name,
+            "start_time": self.start_time.isoformat(),
+            "end_time": self.end_time.isoformat() if self.end_time else None,
+            "completed": [t.id for t in self.completed_tasks],
+            "failed": [t.id for t in self.failed_tasks],
+            "deferred": [t.id for t in self.deferred_tasks],
+            "validation_passed": self.validation_passed,
+            "llm_calls": self.llm_calls,
+            "llm_tokens": self.llm_tokens,
+            "llm_prompt_tokens": self.llm_prompt_tokens,
+            "llm_completion_tokens": self.llm_completion_tokens,
+            "llm_cache_read_tokens": self.llm_cache_read_tokens,
+            "llm_cost": self.llm_cost,
+            "degraded_subsystems": list(self.degraded_subsystems),
+            "goal_gaps": list(self.goal_gaps),
+        }
+
+    def save(self, project_path: Path) -> Optional[Path]:
+        """Persist the report (markdown + JSON) under .orchestrator/reports.
+
+        Failure to write a report must never abort a build, so write errors are
+        logged and swallowed rather than propagated.
+        """
+        try:
+            reports_dir = Path(project_path) / ".orchestrator" / "reports"
+            reports_dir.mkdir(parents=True, exist_ok=True)
+            stamp = (self.end_time or self.start_time).strftime("%Y%m%d_%H%M%S")
+            md_path = reports_dir / f"report_{stamp}.md"
+            md_path.write_text(self.to_markdown(), encoding="utf-8")
+            (reports_dir / f"report_{stamp}.json").write_text(
+                json.dumps(self.to_dict(), indent=2), encoding="utf-8"
+            )
+            logger.info(f"Report saved to {md_path}")
+            return md_path
+        except OSError as e:
+            logger.error(f"Failed to save build report: {e}")
+            return None
+
+    def _verdict_block(self) -> list[str]:
+        """Top-line go/no-go verdict plus an evidence block, derived purely
+        from existing report fields (no LLM calls, no I/O)."""
+        n_completed = len(self.completed_tasks)
+        n_failed = len(self.failed_tasks)
+        n_deferred = len(self.deferred_tasks)
+        nothing_done = (n_completed + n_failed + n_deferred) == 0
+
+        if self.validation_passed is False or (
+            nothing_done and self.validation_passed is not True
+        ):
+            verdict = "FAILED"
+            reason = "build/test gate is red or nothing meaningful completed."
+        elif self.validation_passed and n_failed == 0:
+            verdict = "SHIP"
+            reason = "validation passed and no tasks failed."
+        else:
+            verdict = "NEEDS REVIEW"
+            reason = "build largely succeeded but has open issues; see below."
+
+        lines = [f"## Verdict: {verdict}", f"_{reason}_\n", "### Evidence"]
+        lines.append(
+            f"- Tasks: {n_completed} completed, {n_failed} failed, {n_deferred} deferred"
+        )
+        if self.validation:
+            lines.append(f"- Validation: {self.validation.summary()}")
+        elif self.validation_passed is not None:
+            lines.append(
+                f"- Validation: {'passed' if self.validation_passed else 'failed'}"
+            )
+        if self.health_before or self.health_after:
+            hb = self.health_before or HealthCheck()
+            ha = self.health_after or HealthCheck()
+            lines.append(
+                f"- Health: builds {'YES' if hb.builds else 'NO'} -> "
+                f"{'YES' if ha.builds else 'NO'}, "
+                f"tests {hb.test_failures} fail -> {ha.test_failures} fail, "
+                f"lint {hb.lint_warnings} -> {ha.lint_warnings} warnings"
+            )
+        if self.validation and self.validation.diff_stats:
+            lines.append(f"- Diff: {self.validation.diff_stats}")
+        if self.llm_calls > 0:
+            lines.append(
+                f"- LLM: {self.llm_calls} calls, {self.llm_tokens:,} tokens, "
+                f"${self.llm_cost:.4f}"
+            )
+
+        blocking = list(self.failed_tasks)
+        issues = list(self.validation.issues) if self.validation else []
+        if blocking or issues:
+            lines.append("\n**Blocking items:**")
+            for t in blocking:
+                lines.append(f"- Failed task {t.id}: {t.title or t.description[:60]}")
+            for issue in issues:
+                lines.append(f"- {issue}")
+        if self.degraded_subsystems:
+            names = ", ".join(d.split(":")[0] for d in self.degraded_subsystems)
+            lines.append(f"\n**Degraded subsystems** (ran WITHOUT: {names}):")
+            for d in self.degraded_subsystems:
+                lines.append(f"- {d}")
+        if self.goal_gaps:
+            lines.append(
+                "\n**Goal gaps** (advisory: gates passed but the goal may not be "
+                "fully met):"
+            )
+            for gap in self.goal_gaps:
+                lines.append(f"- {gap}")
+        lines.append("")
+        return lines
+
+    def to_markdown(self) -> str:
+        self.end_time = self.end_time or datetime.now(timezone.utc)
+        duration = (self.end_time - self.start_time).total_seconds()
+        duration_min = duration / 60
+
+        s = self.assessment.structure
+        langs = ", ".join(s.languages) if s.languages else "unknown"
+
+        lines = [
+            "## Build Report\n",
+            f"**Mode**: {self.mode.value} | **Duration**: ~{duration_min:.1f} minutes",
+            f"**Project**: {self.project_name} | **Type**: {s.project_type} | **Languages**: {langs}\n",
+        ]
+
+        # Go/no-go verdict: someone returning to an unattended run must see
+        # "can I ship this?" up front, derived purely from existing fields,
+        # before scanning the task tables below.
+        lines.extend(self._verdict_block())
+
+        # Validation banner: a failed quality gate must be visible at the top,
+        # not buried while the report otherwise reads as a success.
+        if self.validation_passed is not None:
+            if self.validation_passed:
+                lines.append("**Validation: PASSED**\n")
+            else:
+                lines.append(
+                    "**Validation: FAILED** - quality gate did not pass; see issues below."
+                )
+                if self.validation and self.validation.issues:
+                    for issue in self.validation.issues:
+                        lines.append(f"- {issue}")
+                lines.append("")
+
+        # Health Before -> After
+        if self.health_before or self.health_after:
+            lines.append("### Health Before -> After")
+            lines.append("| Check | Before | After |")
+            lines.append("|-------|--------|-------|")
+            hb = self.health_before or HealthCheck()
+            ha = self.health_after or HealthCheck()
+            lines.append(
+                f"| Builds | {'YES' if hb.builds else 'NO'} | {'YES' if ha.builds else 'NO'} |"
+            )
+            lines.append(
+                f"| Tests | {hb.test_count - hb.test_failures} pass, {hb.test_failures} fail | "
+                f"{ha.test_count - ha.test_failures} pass, {ha.test_failures} fail |"
+            )
+            lines.append(
+                f"| Lint | {hb.lint_warnings} warnings | {ha.lint_warnings} warnings |"
+            )
+            lines.append("")
+
+        # Technical Debt & Risk
+        lines.append("### Technical Debt & Risk")
+        lines.append(f"**Debt Score**: {self.assessment.tech_debt.score}/100")
+        lines.append(f"**Risk Level**: {self.assessment.risk.level.upper()}")
+        if self.assessment.risk.factors:
+            lines.append("\n**Risk Factors:**")
+            for factor in self.assessment.risk.factors:
+                lines.append(f"- {factor}")
+        lines.append("")
+
+        # Task summary
+        lines.append("### Tasks")
+        lines.append("| Status | Count |")
+        lines.append("|--------|-------|")
+        lines.append(f"| Completed | {len(self.completed_tasks)} |")
+        lines.append(f"| Failed | {len(self.failed_tasks)} |")
+        lines.append(f"| Deferred | {len(self.deferred_tasks)} |")
+        lines.append("")
+
+        # Completed tasks
+        if self.completed_tasks:
+            lines.append("### Completed Tasks")
+            lines.append("| # | ID | Title |")
+            lines.append("|---|------|-------|")
+            for i, t in enumerate(self.completed_tasks, 1):
+                lines.append(f"| {i} | {t.id} | {t.title or t.description[:60]} |")
+            lines.append("")
+
+        # Failed tasks
+        if self.failed_tasks:
+            lines.append("### Failed Tasks")
+            lines.append("| ID | Title | Reason |")
+            lines.append("|------|-------|--------|")
+            for t in self.failed_tasks:
+                lines.append(
+                    f"| {t.id} | {t.title or t.description[:50]} | "
+                    f"{_failure_reason(t)} |"
+                )
+            lines.append("")
+
+        # Deferred tasks
+        if self.deferred_tasks:
+            lines.append("### Deferred Tasks")
+            lines.append("| ID | Title |")
+            lines.append("|------|-------|")
+            for t in self.deferred_tasks:
+                lines.append(f"| {t.id} | {t.title or t.description[:60]} |")
+            lines.append("")
+
+        # Key decisions
+        if self.key_decisions:
+            lines.append("### Key Decisions")
+            for d in self.key_decisions:
+                lines.append(f"- {d}")
+            lines.append("")
+
+        # Scratchpad discoveries
+        if self.scratchpad and len(self.scratchpad) > 0:
+            lines.append("### Scratchpad Discoveries")
+            for entry in self.scratchpad.entries:
+                lines.append(f"- [{entry.category}] {entry.discovery}")
+            lines.append("")
+
+        # Validation
+        if self.validation:
+            lines.append("### Validation")
+            lines.append(f"- {self.validation.summary()}")
+            if self.validation.diff_stats:
+                lines.append(f"\n```\n{self.validation.diff_stats}\n```")
+            lines.append("")
+
+        # LLM usage
+        if self.llm_calls > 0:
+            lines.append("### LLM Usage")
+            lines.append(
+                f"- {self.llm_calls} calls, {self.llm_tokens:,} tokens, "
+                f"${self.llm_cost:.4f} estimated cost"
+            )
+            if self.llm_prompt_tokens or self.llm_completion_tokens:
+                lines.append(
+                    f"- Tokens: {self.llm_prompt_tokens:,} input (context) / "
+                    f"{self.llm_completion_tokens:,} output"
+                )
+            if self.llm_cache_read_tokens > 0 and self.llm_tokens > 0:
+                rate = 100.0 * self.llm_cache_read_tokens / self.llm_tokens
+                lines.append(
+                    f"- Cache: {self.llm_cache_read_tokens:,} tokens read from cache ({rate:.0f}% of total)"
+                )
+            # Actionable token-efficiency signal: a run whose input dwarfs its
+            # output is context-bound — the lever is narrower context / more
+            # prompt-cache reuse, not shorter completions.
+            if self.llm_completion_tokens > 0:
+                ratio = self.llm_prompt_tokens / self.llm_completion_tokens
+                if ratio >= 8:
+                    lines.append(
+                        f"- Token profile: context-bound ({ratio:.0f}:1 input:output). "
+                        "Consider enabling prompt caching and narrowing context."
+                    )
+            if self.cost_by_task:
+                top = sorted(
+                    self.cost_by_task.items(), key=lambda kv: kv[1], reverse=True
+                )[:5]
+                lines.append("- Most expensive tasks:")
+                for tid, cost in top:
+                    lines.append(f"  - {tid}: ${cost:.4f}")
+            lines.append("")
+
+        # Summary line
+        total = (
+            len(self.completed_tasks)
+            + len(self.failed_tasks)
+            + len(self.deferred_tasks)
+        )
+        validation_note = ""
+        if self.validation_passed is False:
+            validation_note = " VALIDATION FAILED."
+        lines.append("---")
+        lines.append(
+            f"*{len(self.completed_tasks)}/{total} tasks completed.{validation_note} "
+            f"Duration: {duration_min:.1f}m.*"
+        )
+
+        return "\n".join(lines)

misterdev/core/reporting/report_view.py

@@ -0,0 +1,151 @@
+"""Aggregated, read-only view over a project's ``.orchestrator/`` artifacts.
+
+The orchestrator writes three streams under ``.orchestrator/``: an append-only
+audit trail (``audit.jsonl``), the persistent model-performance ledger
+(``model_stats.json``), and per-build reports (``reports/report_*.json``). Each
+is observability that, until now, had no consolidated reader. This module
+summarizes all three into plain dicts so a ``report`` command (or any caller) can
+show what happened, what each model actually cost, and how the last build went —
+without re-running anything. Pure and defensive: a missing or malformed file
+yields an empty/None summary, never an error.
+"""
+
+import json
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+_ARTIFACT_DIR = ".orchestrator"
+
+
+def _read_jsonl(path: Path) -> List[Dict[str, Any]]:
+    """Read a JSONL file into a list of objects, skipping unreadable lines."""
+    events: List[Dict[str, Any]] = []
+    try:
+        with open(path, encoding="utf-8") as fh:
+            for line in fh:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    obj = json.loads(line)
+                except ValueError:
+                    continue
+                if isinstance(obj, dict):
+                    events.append(obj)
+    except OSError:
+        return []
+    return events
+
+
+def summarize_audit(audit_path: Path) -> Dict[str, Any]:
+    """Aggregate the audit trail: event counts, command pass/fail, edits, gates.
+
+    Returns zeros/empties when the file is absent or empty, so the caller can
+    render a consistent shape regardless.
+    """
+    events = _read_jsonl(Path(audit_path))
+    by_type: Dict[str, int] = {}
+    cmd_ok = cmd_failed = 0
+    edits: Dict[str, int] = {}
+    gov_escalated = gov_blocked = 0
+    for e in events:
+        etype = str(e.get("type", "?"))
+        by_type[etype] = by_type.get(etype, 0) + 1
+        if etype == "command":
+            if e.get("ok"):
+                cmd_ok += 1
+            else:
+                cmd_failed += 1
+        elif etype == "edit":
+            path = str(e.get("path", "?"))
+            edits[path] = edits.get(path, 0) + 1
+        elif etype == "gate":
+            if e.get("escalated"):
+                gov_escalated += 1
+            if e.get("allowed") is False:
+                gov_blocked += 1
+    return {
+        "total_events": len(events),
+        "by_type": by_type,
+        "commands": {"ok": cmd_ok, "failed": cmd_failed},
+        "edits": {"total": sum(edits.values()), "by_file": edits},
+        "governance": {"escalated": gov_escalated, "blocked": gov_blocked},
+    }
+
+
+def summarize_models(ledger_path: Path) -> List[Dict[str, Any]]:
+    """Per-model performance from the ledger, aggregated across category/complexity.
+
+    Surfaces the data that drives selection — attempts, gate-pass rate, first-try
+    rate, and mean cost of a success — so a previously-invisible model choice
+    becomes legible. Sorted by attempts (most-exercised first). Empty when the
+    ledger is absent.
+    """
+    path = Path(ledger_path)
+    if not path.exists():
+        return []
+    from misterdev.core.economics.model_ledger import ModelLedger
+
+    ledger = ModelLedger(path)
+    agg: Dict[str, Dict[str, float]] = {}
+    for s in ledger.all_stats():
+        a = agg.setdefault(
+            s.model,
+            {
+                "attempts": 0.0,
+                "successes": 0.0,
+                "first_try_attempts": 0.0,
+                "first_try_successes": 0.0,
+                "total_cost": 0.0,
+            },
+        )
+        a["attempts"] += s.attempts
+        a["successes"] += s.successes
+        a["first_try_attempts"] += s.first_try_attempts
+        a["first_try_successes"] += s.first_try_successes
+        a["total_cost"] += s.total_cost
+    rows: List[Dict[str, Any]] = []
+    for model, a in agg.items():
+        att = a["attempts"]
+        fta = a["first_try_attempts"]
+        succ = a["successes"]
+        rows.append(
+            {
+                "model": model,
+                "attempts": round(att, 1),
+                "success_rate": (succ / att) if att else 0.0,
+                "first_try_rate": (a["first_try_successes"] / fta) if fta else 0.0,
+                "avg_cost": (a["total_cost"] / succ) if succ else 0.0,
+            }
+        )
+    rows.sort(key=lambda r: r["attempts"], reverse=True)
+    return rows
+
+
+def latest_report(reports_dir: Path) -> Optional[Dict[str, Any]]:
+    """The most recent saved build report (JSON), or None.
+
+    Report filenames are timestamp-stamped (``report_YYYYMMDD_HHMMSS.json``), so
+    a lexical sort is chronological and the last entry is the newest.
+    """
+    d = Path(reports_dir)
+    if not d.is_dir():
+        return None
+    candidates = sorted(d.glob("report_*.json"))
+    if not candidates:
+        return None
+    try:
+        obj = json.loads(candidates[-1].read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+    return obj if isinstance(obj, dict) else None
+
+
+def collect(project_path: Path) -> Dict[str, Any]:
+    """Collect the audit, model, and latest-report summaries for a project."""
+    root = Path(project_path) / _ARTIFACT_DIR
+    return {
+        "audit": summarize_audit(root / "audit.jsonl"),
+        "models": summarize_models(root / "model_stats.json"),
+        "latest_report": latest_report(root / "reports"),
+    }

misterdev/core/task.py

@@ -0,0 +1,163 @@
+import frontmatter
+from pathlib import Path
+from typing import List, Dict, Any, Optional
+
+from misterdev.config import get_setting
+from misterdev.core.models import Task
+from misterdev.logging_setup import setup_logger
+
+logger = setup_logger(__name__)
+
+
+class TaskManager:
+    """Manages discovery, loading, and updating of tasks for a project."""
+
+    def __init__(self, project: Any):
+        self.project = project
+        self.devplan_dir = self.project.config.get("devplan_dir", "devplan")
+        self.tasks: Dict[str, Task] = {}
+
+    def discover_tasks(self) -> List[Task]:
+        """Scans the devplan directory for markdown files with front-matter."""
+        devplan_path = self.project.path / self.devplan_dir
+        if not devplan_path.exists():
+            logger.warning(f"Devplan directory {devplan_path} does not exist.")
+            return []
+
+        self.tasks.clear()
+        discovered_tasks = []
+        for file_path in sorted(devplan_path.rglob("*.md")):
+            try:
+                task = self._load_task_from_file(file_path)
+                if task:
+                    self.tasks[task.id] = task
+                    discovered_tasks.append(task)
+            except Exception as e:
+                logger.error(f"Error loading task from {file_path}: {e}")
+
+        self._resolve_dependency_ids()
+        if get_setting(self.project.config, "orchestrator", "auto_detect_dependencies"):
+            self._detect_file_overlaps()
+        logger.info(f"Discovered {len(discovered_tasks)} tasks.")
+        return discovered_tasks
+
+    def _detect_file_overlaps(self):
+        """Add implicit dependencies when tasks touch the same file.
+
+        Two independent tasks that modify (or create-then-modify) the same file
+        would conflict if run in the same wave. Chaining them by ID keeps the
+        edits serialized in a deterministic order.
+        """
+        file_to_tasks: Dict[str, List[str]] = {}
+        for task in sorted(self.tasks.values(), key=lambda t: t.id):
+            for f in list(task.files_to_modify) + list(task.files_to_create):
+                file_to_tasks.setdefault(f, []).append(task.id)
+
+        added = 0
+        for file_path, task_ids in file_to_tasks.items():
+            if len(task_ids) < 2:
+                continue
+            for i in range(1, len(task_ids)):
+                later = self.tasks[task_ids[i]]
+                earlier_id = task_ids[i - 1]
+                if earlier_id != later.id and earlier_id not in later.dependencies:
+                    later.dependencies.append(earlier_id)
+                    added += 1
+                    logger.info(
+                        f"Implicit dependency: {later.id} depends on {earlier_id} "
+                        f"(both touch {file_path})"
+                    )
+        if added:
+            logger.info(f"Detected {added} implicit dependencies from file overlaps")
+
+    def _resolve_dependency_ids(self):
+        """Resolve short dependency IDs (e.g., '001') to full task IDs (e.g., '001-posting-shard')."""
+        all_ids = set(self.tasks.keys())
+        for task in self.tasks.values():
+            resolved = []
+            for dep in task.dependencies:
+                # YAML may parse a numeric id (e.g. `depends_on: [999]`) as int;
+                # coerce so prefix matching and comparisons don't crash.
+                dep = str(dep)
+                if dep in all_ids:
+                    resolved.append(dep)
+                else:
+                    # Try prefix match: "001" matches "001-posting-shard"
+                    matches = [
+                        tid
+                        for tid in all_ids
+                        if tid.startswith(dep + "-") or tid == dep
+                    ]
+                    if len(matches) == 1:
+                        resolved.append(matches[0])
+                    elif len(matches) > 1:
+                        logger.warning(
+                            f"Ambiguous dependency '{dep}' in {task.id}: matches {matches}"
+                        )
+                        resolved.append(matches[0])
+                    else:
+                        logger.warning(f"Unresolved dependency '{dep}' in {task.id}")
+                        resolved.append(dep)
+            task.dependencies = resolved
+
+    def _load_task_from_file(self, file_path: Path) -> Optional[Task]:
+        with open(file_path, "r", encoding="utf-8") as f:
+            post = frontmatter.load(f)
+
+        if not post.metadata or "status" not in post.metadata:
+            return None
+
+        task_id = file_path.stem
+
+        meta = post.metadata
+        depends_on = meta.get("depends_on", [])
+        if not isinstance(depends_on, list):
+            depends_on = [depends_on]
+        # YAML may parse a numeric id (e.g. `depends_on: [999]`) as int; coerce
+        # so the typed Task model accepts it instead of dropping the whole task.
+        depends_on = [str(d) for d in depends_on]
+
+        return Task(
+            id=task_id,
+            description=post.content,
+            type="markdown_planner",
+            status=meta.get("status", "pending"),
+            source_ref=str(file_path),
+            project_ref=str(self.project.path),
+            processor_data=meta,
+            dependencies=depends_on,
+            files_to_modify=meta.get("files_to_modify", []),
+            files_to_create=meta.get("files_to_create", []),
+            context_files=meta.get("context_files", []),
+            category=meta.get("category", "feature"),
+            complexity=meta.get("complexity", "medium"),
+            title=meta.get("title", task_id),
+        )
+
+    def get_pending_tasks(self) -> List[Task]:
+        return [t for t in self.tasks.values() if t.status == "pending"]
+
+    def update_task_status(self, task_id: str, new_status: str):
+        if task_id not in self.tasks:
+            logger.warning(
+                f"Task {task_id} not in task registry, status update skipped."
+            )
+            return
+
+        task = self.tasks[task_id]
+        task.status = new_status
+
+        # Persist back to the markdown file. Decomposed tasks (from build())
+        # have no backing file, so persistence is expected to be skipped.
+        if task.source_ref:
+            try:
+                with open(task.source_ref, "r", encoding="utf-8") as f:
+                    post = frontmatter.load(f)
+
+                post.metadata["status"] = new_status
+
+                with open(task.source_ref, "w", encoding="utf-8") as f:
+                    f.write(frontmatter.dumps(post))
+                logger.info(f"Updated task {task_id} status to {new_status}")
+            except Exception as e:
+                logger.error(f"Failed to persist task status for {task_id}: {e}")