diff --git a/planfile/__init__.py b/planfile/__init__.py index 56156104..feb0ec53 100644 --- a/planfile/__init__.py +++ b/planfile/__init__.py @@ -910,6 +910,48 @@ def admit_comparative_findings( dry_run=dry_run, ) + def reconcile_in_progress( + self, + *, + apply: bool = False, + sprint: str = "active", + workspace_root: str | Path | None = None, + now: datetime | None = None, + actor: str = "planfile.reconcile", + ) -> dict: + """Reconcile ``in_progress`` tickets against live leases, worktrees, and merge receipts.""" + from planfile.reconcile import reconcile_in_progress + + return reconcile_in_progress( + self, + apply=apply, + sprint=sprint, + workspace_root=workspace_root, + now=now, + actor=actor, + ) + + reconcile = reconcile_in_progress + + def executable_queue( + self, + *, + sprint: str = "active", + workspace_root: str | Path | None = None, + queue: str | None = None, + now: datetime | None = None, + ) -> dict: + """Return the canonical ``planfile.executable-queue/v1`` summary for this repository.""" + from planfile.executable_queue import executable_queue + + return executable_queue( + self, + sprint=sprint, + workspace_root=workspace_root, + queue=queue, + now=now, + ) + def quick_ticket(name: str, tool: str = "unknown", **kwargs) -> Ticket: """One-liner ticket creation for tools.""" @@ -934,6 +976,12 @@ def quick_ticket(name: str, tool: str = "unknown", **kwargs) -> Ticket: "ComparativeFindingProposal", "ExecutorOwnershipSpec", "ObsoleteTargetHeadError", "admit_comparative_findings", "compute_comparative_dedupe_key", "compute_requirement_fingerprint", + # Reconciliation & Executable Queue + "EXECUTABLE_QUEUE_SCHEMA", "RECONCILE_REPORT_SCHEMA", + "CandidateEvaluation", "evaluate_executable_candidate", + "executable_queue", "executable_skip_reason", + "fleet_executable_queue", "is_executable_candidate", + "reconcile", "reconcile_fleet_in_progress", "reconcile_in_progress", # Store & API "PlanfileStore", "Planfile", "quick_ticket", # Executors (lazy loaded) @@ -962,6 +1010,23 @@ def quick_ticket(name: str, tool: str = "unknown", **kwargs) -> Ticket: "compute_requirement_fingerprint", }) +_RECONCILE_EXPORTS = frozenset({ + "RECONCILE_REPORT_SCHEMA", + "reconcile", + "reconcile_fleet_in_progress", + "reconcile_in_progress", +}) + +_EXECUTABLE_QUEUE_EXPORTS = frozenset({ + "EXECUTABLE_QUEUE_SCHEMA", + "CandidateEvaluation", + "evaluate_executable_candidate", + "executable_queue", + "executable_skip_reason", + "fleet_executable_queue", + "is_executable_candidate", +}) + _TESTQL_EXPORTS = frozenset({ "run_testql_validation", "build_testql_tickets", @@ -984,6 +1049,24 @@ def __getattr__(name): value = getattr(comparative_findings, name) globals()[name] = value return value + if name in _RECONCILE_EXPORTS: + import importlib + + reconcile_mod = importlib.import_module("planfile.reconcile") + if name == "reconcile": + return reconcile_mod + value = getattr(reconcile_mod, name) + globals()[name] = value + return value + if name in _EXECUTABLE_QUEUE_EXPORTS: + import importlib + + executable_queue_mod = importlib.import_module("planfile.executable_queue") + if name == "executable_queue": + return executable_queue_mod + value = getattr(executable_queue_mod, name) + globals()[name] = value + return value if name in _TESTQL_EXPORTS: from planfile import testql_integration diff --git a/planfile/cli/extra_commands.py b/planfile/cli/extra_commands.py index a52d4b04..658b2b0a 100644 --- a/planfile/cli/extra_commands.py +++ b/planfile/cli/extra_commands.py @@ -5,12 +5,18 @@ Commands are organized into separate modules for better maintainability. """ +import typer + from planfile.cli.groups.examples import create_examples_app from planfile.cli.groups.health import create_health_app +from planfile.cli.groups.ticket.reconcile import ( + ticket_executable_queue, + ticket_reconcile, +) -def add_extra_commands(app): - """Add health and examples command groups to the CLI app.""" +def add_extra_commands(app: typer.Typer) -> None: + """Add health, examples, reconciliation, and executable-queue commands to the CLI app.""" # Add health commands health_app = create_health_app() app.add_typer(health_app, name="health") @@ -18,3 +24,7 @@ def add_extra_commands(app): # Add examples commands examples_app = create_examples_app() app.add_typer(examples_app, name="examples") + + # Top-level reconciliation and canonical executable queue commands + app.command("reconcile")(ticket_reconcile) + app.command("executable-queue")(ticket_executable_queue) diff --git a/planfile/cli/groups/ticket/__init__.py b/planfile/cli/groups/ticket/__init__.py index 21abf01c..e61a074b 100644 --- a/planfile/cli/groups/ticket/__init__.py +++ b/planfile/cli/groups/ticket/__init__.py @@ -35,6 +35,10 @@ ticket_validate, ticket_waves, ) +from planfile.cli.groups.ticket.reconcile import ( + ticket_executable_queue, + ticket_reconcile, +) def register_ticket_commands(app: typer.Typer) -> None: @@ -81,5 +85,7 @@ def ticket_callback(ctx: typer.Context) -> None: ticket_app.command("decompose")(ticket_decompose) ticket_app.command("coverage")(ticket_coverage) ticket_app.command("prune-deps")(ticket_prune_deps) + ticket_app.command("reconcile")(ticket_reconcile) + ticket_app.command("executable-queue")(ticket_executable_queue) app.add_typer(ticket_app, name="ticket") diff --git a/planfile/cli/groups/ticket/reconcile.py b/planfile/cli/groups/ticket/reconcile.py new file mode 100644 index 00000000..056b62c6 --- /dev/null +++ b/planfile/cli/groups/ticket/reconcile.py @@ -0,0 +1,220 @@ +"""CLI commands for ``in_progress`` reconciliation and canonical executable queue reporting.""" + +from __future__ import annotations + +import json +import sys +from typing import Any + +import typer +import yaml +from rich.table import Table + +from planfile.cli.core import console + + +def _emit_structured(payload: dict[str, Any], fmt: str) -> bool: + normalized = fmt.strip().lower() + if normalized == "json": + sys.stdout.write(json.dumps(payload, indent=2, sort_keys=False) + "\n") + return True + if normalized == "yaml": + sys.stdout.write(yaml.safe_dump(payload, sort_keys=False, allow_unicode=True)) + return True + return False + + +def _render_reconcile_table(report: dict[str, Any]) -> None: + counts = report["counts"] + mode_label = "APPLIED" if report["mode"] == "apply" else "DRY-RUN" + console.print( + f"[bold]in_progress reconciliation ({mode_label})[/bold] — " + f"scanned={counts['scanned_in_progress']} " + f"merged->done={counts['merged_to_done']} " + f"abandoned->open={counts['abandoned_to_open']} " + f"active={counts['active_retained']} " + f"unobserved={counts['unobserved_preserved']}" + ) + decisions = report.get("decisions") or [] + if not decisions: + console.print("[dim]No in_progress tickets found in scope.[/dim]") + return + + table = Table(show_header=True) + table.add_column("Ticket", style="cyan", no_wrap=True) + table.add_column("Sprint") + table.add_column("Class") + table.add_column("Transition", no_wrap=True) + table.add_column("Applied") + table.add_column("Reason / Evidence") + + for item in decisions: + evidence = str(item.get("reason") or "") + if item.get("terminalSha"): + evidence = f"{evidence} ({str(item['terminalSha'])[:12]})" + elif item.get("leaseId"): + evidence = f"{evidence}" + table.add_row( + str(item.get("id") or ""), + str(item.get("sprint") or ""), + str(item.get("classification") or ""), + f"{item.get('previous_status')} -> {item.get('proposed_status')}", + "yes" if item.get("applied") else "no", + evidence, + ) + console.print(table) + + +def _render_executable_queue_table(report: dict[str, Any]) -> None: + counts = report["counts"] + console.print( + f"[bold]Executable Pending Queue ({report['schema']})[/bold] — " + f"executable={counts['executable']} " + f"open={counts['open']} " + f"in_progress={counts['in_progress']} " + f"excluded={counts['excluded']} " + f"scanned={counts['total_scanned']}" + ) + candidates = report.get("candidates") or [] + if not candidates: + console.print("[dim]No executable candidates in scope.[/dim]") + return + + table = Table(show_header=True) + table.add_column("ID", style="cyan", no_wrap=True) + table.add_column("Priority", no_wrap=True) + table.add_column("Sprint", no_wrap=True) + table.add_column("Repository") + table.add_column("Name") + + for cand in candidates: + table.add_row( + str(cand.get("id") or ""), + str(cand.get("priority") or "normal"), + str(cand.get("sprint") or "current"), + str(cand.get("repository") or cand.get("repo_path") or ""), + str(cand.get("name") or ""), + ) + console.print(table) + + +def ticket_reconcile( + project: str = typer.Option(".", "--project", "-p", help="Project directory"), + sprint: str = typer.Option( + "active", + "--sprint", + "-s", + help="Sprint scope ('active', 'current', 'backlog', 'all', or sprint ID)", + ), + workspace_root: str | None = typer.Option( + None, + "--workspace-root", + "-w", + help="Workspace directory for resolving external target repositories", + ), + fleet: bool = typer.Option( + False, + "--fleet", + help="Reconcile all .planfile repositories discovered under workspace root", + ), + apply: bool = typer.Option( + False, + "--apply", + help="Atomically apply status transitions (default is dry-run report)", + ), + actor: str = typer.Option( + "planfile.reconcile", + "--actor", + help="Audit actor recorded when --apply mutates tickets", + ), + fmt: str = typer.Option( + "table", + "--format", + "-f", + help="Output format: table, json, or yaml", + ), +) -> None: + """Reconcile in_progress tickets with live leases, worktrees, and merge receipts.""" + if fmt.strip().lower() not in {"table", "json", "yaml"}: + console.print(f"[red]Unsupported format: {fmt} (choose table, json, or yaml)[/red]") + raise typer.Exit(2) + + from planfile.reconcile import reconcile_fleet_in_progress, reconcile_in_progress + + if fleet: + root_dir = workspace_root or project + report = reconcile_fleet_in_progress( + root_dir, + apply=apply, + sprint=sprint, + actor=actor, + ) + else: + report = reconcile_in_progress( + project, + apply=apply, + sprint=sprint, + workspace_root=workspace_root, + actor=actor, + ) + + if not _emit_structured(report, fmt): + _render_reconcile_table(report) + + +def ticket_executable_queue( + project: str = typer.Option(".", "--project", "-p", help="Project directory"), + sprint: str = typer.Option( + "active", + "--sprint", + "-s", + help="Sprint scope ('active', 'current', 'backlog', 'all', or sprint ID)", + ), + workspace_root: str | None = typer.Option( + None, + "--workspace-root", + "-w", + help="Workspace directory for resolving external target repositories", + ), + fleet: bool = typer.Option( + False, + "--fleet", + help="Aggregate canonical executable queue across all fleet repositories", + ), + queue: str | None = typer.Option( + None, + "--queue", + "-q", + help="Filter candidates by execution queue name", + ), + fmt: str = typer.Option( + "table", + "--format", + "-f", + help="Output format: table, json, or yaml", + ), +) -> None: + """Evaluate and report the canonical planfile.executable-queue/v1 pending queue.""" + if fmt.strip().lower() not in {"table", "json", "yaml"}: + console.print(f"[red]Unsupported format: {fmt} (choose table, json, or yaml)[/red]") + raise typer.Exit(2) + + from planfile.executable_queue import executable_queue, fleet_executable_queue + + if fleet: + root_dir = workspace_root or project + report = fleet_executable_queue( + root_dir, + sprint=sprint, + queue=queue, + ) + else: + report = executable_queue( + project, + sprint=sprint, + workspace_root=workspace_root, + queue=queue, + ) + + if not _emit_structured(report, fmt): + _render_executable_queue_table(report) diff --git a/planfile/contracts.py b/planfile/contracts.py index 7c660b29..4f715c4c 100644 --- a/planfile/contracts.py +++ b/planfile/contracts.py @@ -4,16 +4,19 @@ import hashlib import json -from typing import Any, Literal +from typing import Any, Final, Literal from pydantic import BaseModel, ConfigDict, Field, field_validator from planfile.core.models import TicketSource -TICKET_PROPOSAL_SCHEMA_ID = "planfile.ticket-proposal.v1" +TICKET_PROPOSAL_SCHEMA_ID: Final = "planfile.ticket-proposal.v1" +EXECUTABLE_QUEUE_SCHEMA: Final = "planfile.executable-queue/v1" +RECONCILE_REPORT_SCHEMA: Final = "planfile.in-progress-reconciliation/v1" +RECONCILE_MERGE_EVIDENCE_SCHEMA: Final = "planfile.reconcile-merge-evidence/v1" -def _canonical_json(payload: dict) -> str: +def _canonical_json(payload: dict[str, Any]) -> str: return json.dumps( payload, ensure_ascii=False, @@ -109,7 +112,7 @@ def canonical_json(self) -> str: def proposal_hash(self) -> str: return hashlib.sha256(self.canonical_json().encode("utf-8")).hexdigest() - def to_ticket_kwargs(self) -> dict: + def to_ticket_kwargs(self) -> dict[str, Any]: """Return safe Ticket constructor fields; Koru still chooses queue/sprint/executor.""" context: dict[str, Any] = { @@ -136,8 +139,84 @@ def to_ticket_kwargs(self) -> dict: } +class ExecutableCandidateV1(BaseModel): + """Canonical executable candidate entry shared by Planfile, Heyasa, and monag.""" + + model_config = ConfigDict(extra="forbid", frozen=True) + + id: str = Field(min_length=1) + name: str + priority: str = "normal" + sprint: str = "current" + queue: str = "default" + repository: str | None = None + repo_path: str + labels: list[str] = Field(default_factory=list) + files: list[str] = Field(default_factory=list) + blocked_by: list[str] = Field(default_factory=list) + created_at: str | None = None + + +class ExecutableSkippedItemV1(BaseModel): + """Ticket excluded from the executable pending queue with machine-readable reason.""" + + model_config = ConfigDict(extra="forbid", frozen=True) + + id: str = Field(min_length=1) + status: str + sprint: str = "current" + reason: str = Field(min_length=1) + category: str = Field(min_length=1) + repository: str | None = None + + +class ExecutableQueueCountsV1(BaseModel): + """Aggregate backlog status and executable queue counts.""" + + model_config = ConfigDict(extra="forbid", frozen=True) + + total_scanned: int = 0 + open: int = 0 + in_progress: int = 0 + blocked: int = 0 + done: int = 0 + canceled: int = 0 + failed: int = 0 + review: int = 0 + executable: int = 0 + excluded: int = 0 + + +class ExecutableQueueSummaryV1(BaseModel): + """Canonical ``planfile.executable-queue/v1`` summary contract.""" + + model_config = ConfigDict(extra="forbid", frozen=True, populate_by_name=True) + + schema_id: Literal["planfile.executable-queue/v1"] = Field( + default=EXECUTABLE_QUEUE_SCHEMA, + alias="schema", + ) + generated_at: str + project_dir: str + repository: str | None = None + sprint: str = "active" + queue: str | None = None + counts: ExecutableQueueCountsV1 + excluded_by_reason: dict[str, int] = Field(default_factory=dict) + candidate_ids: list[str] = Field(default_factory=list) + candidates: list[ExecutableCandidateV1] = Field(default_factory=list) + skipped: list[ExecutableSkippedItemV1] = Field(default_factory=list) + + __all__ = [ + "EXECUTABLE_QUEUE_SCHEMA", + "RECONCILE_MERGE_EVIDENCE_SCHEMA", + "RECONCILE_REPORT_SCHEMA", "TICKET_PROPOSAL_SCHEMA_ID", + "ExecutableCandidateV1", + "ExecutableQueueCountsV1", + "ExecutableQueueSummaryV1", + "ExecutableSkippedItemV1", "TicketProposalSourceV1", "TicketProposalV1", ] diff --git a/planfile/executable_queue.py b/planfile/executable_queue.py new file mode 100644 index 00000000..2caf3e79 --- /dev/null +++ b/planfile/executable_queue.py @@ -0,0 +1,588 @@ +"""Canonical executable pending queue specification shared across Planfile, Heyasa, and monag.""" + +from __future__ import annotations + +import os +import sys +import types +from collections.abc import Mapping, MutableMapping +from dataclasses import dataclass +from datetime import datetime +from pathlib import Path +from typing import TYPE_CHECKING, Any + +from planfile.contracts import ( + EXECUTABLE_QUEUE_SCHEMA, + ExecutableCandidateV1, + ExecutableQueueCountsV1, + ExecutableQueueSummaryV1, + ExecutableSkippedItemV1, +) +from planfile.core.models import Ticket +from planfile.reconcile import ( + TargetRepoObservation, + _build_slug_index, + _utc_now, + discover_planfile_repositories, + find_live_ticket_binding, + iter_sprint_tickets, + resolve_ticket_target_repo, +) + +if TYPE_CHECKING: + from planfile import Planfile + +RUNNABLE_EXECUTION_STATES: frozenset[str] = frozenset({"", "pending", "ready"}) +SATISFIED_DEPENDENCY_STATUSES: frozenset[str] = frozenset({"done", "canceled"}) +_PRIORITY_ORDER: dict[str, int] = { + "critical": 0, + "high": 1, + "normal": 2, + "medium": 2, + "low": 3, +} + + +@dataclass(frozen=True) +class CandidateEvaluation: + """Detailed evaluation outcome for one candidate ticket.""" + + executable: bool + reason: str = "" + category: str = "executable" + repo_path: str | None = None + repository: str | None = None + + def to_dict(self) -> dict[str, Any]: + return { + "executable": self.executable, + "reason": self.reason, + "category": self.category, + "repo_path": self.repo_path, + "repository": self.repository, + } + + +def _normalize_status(raw: Any) -> str: + val = raw.value if hasattr(raw, "value") else str(raw or "") + lowered = val.strip().lower() + if lowered == "cancelled": + return "canceled" + if lowered in {"completed", "closed", "resolved"}: + return "done" + return lowered + + +def _ticket_field(ticket: Ticket | Mapping[str, Any], name: str, default: Any = None) -> Any: + if isinstance(ticket, Ticket): + return getattr(ticket, name, default) + return ticket.get(name, default) + + +def _extract_exec_state_and_queue(ticket: Ticket | Mapping[str, Any]) -> tuple[str, str]: + execution = _ticket_field(ticket, "execution") + if execution is None: + return "", "default" + if isinstance(execution, Mapping): + state = str(execution.get("state") or "").strip().lower() + queue = str(execution.get("queue") or "default").strip() or "default" + return state, queue + state = str(getattr(execution, "state", "") or "").strip().lower() + queue = str(getattr(execution, "queue", "default") or "default").strip() or "default" + return state, queue + + +def _check_autonomy_and_goal(ticket: Ticket | Mapping[str, Any]) -> tuple[str, str]: + if os.environ.get("PLANFILE_NO_AUTONOMY_FILTER") != "1": + require_envelope = os.environ.get( + "PLANFILE_REQUIRE_PROCESS_ENVELOPE", "" + ).strip().lower() in {"1", "true", "yes", "on"} + if require_envelope: + inputs = _ticket_field(ticket, "inputs") + manifest = ( + inputs.get("process_manifest") + if isinstance(inputs, Mapping) + else getattr(inputs, "process_manifest", None) + ) + if ( + not isinstance(manifest, Mapping) + or manifest.get("schema") != "subactor.process-envelope.v2" + ): + return "process-envelope-required", "process_envelope" + definitions = manifest.get("definitions") + valid = ( + bool(str(manifest.get("reason") or "").strip()) + and bool(str(manifest.get("requested_by") or "").strip()) + and isinstance(definitions, Mapping) + and all( + isinstance(definitions.get(kind), list) and definitions[kind] + for kind in ("aql", "eql", "oql", "uri") + ) + ) + if not valid: + return "process-envelope-invalid", "process_envelope" + + raw_labels = _ticket_field(ticket, "labels") or [] + labels = [str(lbl).strip().lower() for lbl in raw_labels] + if "blocked" in labels: + return "label:blocked", "blocked" + if "autonomy-frontier" in labels: + return "autonomy-frontier", "autonomy_blocked" + if "actor:human" in labels: + return "actor:human", "human_owned" + for lbl in labels: + if lbl.startswith("waiting:"): + return lbl, "waiting" + if lbl.startswith("needs-human"): + return lbl, "human_owned" + + goal = (os.environ.get("CURRENT_GOAL") or "").strip() + if goal: + domain = goal.split(".")[0].lower() + raw_labels = _ticket_field(ticket, "labels") or [] + labels = [str(lbl).strip().lower() for lbl in raw_labels] + if f"goal:{goal.lower()}" not in labels and f"goal:{domain}" not in labels: + name = str(_ticket_field(ticket, "name", "") or "") + desc = str(_ticket_field(ticket, "description", "") or "") + blob = f"{name} {desc} {' '.join(labels)}".lower() + if domain not in blob: + return "goal-frozen", "goal_frozen" + + return "", "" + + +def _resolve_dependency_status( + dep_id: str, + *, + pf: Planfile | None, + ticket_by_id: Mapping[str, Ticket | Mapping[str, Any]] | None, +) -> str | None: + if ticket_by_id is not None and dep_id in ticket_by_id: + dep = ticket_by_id[dep_id] + return _normalize_status(_ticket_field(dep, "status")) + if pf is not None: + dep_ticket = pf.get_ticket(dep_id) + if dep_ticket is not None: + return _normalize_status(dep_ticket.status) + return None + + +def evaluate_executable_candidate( + ticket: Ticket | Mapping[str, Any], + *, + pf: Planfile | None = None, + ticket_by_id: Mapping[str, Ticket | Mapping[str, Any]] | None = None, + repo_path: str | Path | None = None, + workspace_root: str | Path | None = None, + queue: str | None = None, + now: datetime | None = None, + observations: MutableMapping[Path, TargetRepoObservation] | None = None, + slug_index: Mapping[str, Path] | None = None, +) -> CandidateEvaluation: + """Evaluate whether ``ticket`` belongs to the canonical executable pending queue.""" + + sprint = str(_ticket_field(ticket, "sprint", "current") or "current").strip() + if sprint.startswith(("history-", "archive-")): + return CandidateEvaluation( + executable=False, + reason="archived_sprint", + category="archived", + ) + + status = _normalize_status(_ticket_field(ticket, "status")) + if status != "open": + return CandidateEvaluation( + executable=False, + reason=f"status:{status or 'unknown'}", + category=f"status_{status or 'unknown'}", + ) + + exec_state, ticket_queue = _extract_exec_state_and_queue(ticket) + if exec_state not in RUNNABLE_EXECUTION_STATES: + return CandidateEvaluation( + executable=False, + reason=f"exec_state:{exec_state}", + category="exec_state", + ) + + if queue is not None and ticket_queue != queue: + return CandidateEvaluation( + executable=False, + reason=f"queue:{ticket_queue}", + category="queue_mismatch", + ) + + autonomy_reason, autonomy_category = _check_autonomy_and_goal(ticket) + if autonomy_reason: + return CandidateEvaluation( + executable=False, + reason=autonomy_reason, + category=autonomy_category, + ) + + blocked_by = _ticket_field(ticket, "blocked_by") or [] + for raw_dep in blocked_by: + dep_id = str(raw_dep or "").strip() + if not dep_id: + continue + dep_status = _resolve_dependency_status( + dep_id, + pf=pf, + ticket_by_id=ticket_by_id, + ) + if dep_status is None or dep_status not in SATISFIED_DEPENDENCY_STATUSES: + return CandidateEvaluation( + executable=False, + reason=f"blocked_by:{dep_id}", + category="dependency_unresolved", + ) + + current_time = _utc_now(now) + default_repo = ( + Path(repo_path) + if repo_path is not None + else (pf.store.primary_project_dir if pf is not None else None) + ) + ws_root = Path(workspace_root) if workspace_root is not None else None + obs_cache: MutableMapping[Path, TargetRepoObservation] = ( + observations if observations is not None else {} + ) + + obs, unobserved_reason = resolve_ticket_target_repo( + ticket, + default_repo_dir=default_repo, + workspace_root=ws_root, + now=current_time, + observations=obs_cache, + slug_index=slug_index, + ) + if obs is None or unobserved_reason is not None: + return CandidateEvaluation( + executable=False, + reason=unobserved_reason or "target_repository_invalid", + category="invalid_target_repository", + ) + + live_status = find_live_ticket_binding(ticket, obs, now=current_time) + if live_status.ambiguous_error is not None: + return CandidateEvaluation( + executable=False, + reason=live_status.ambiguous_error, + category="ambiguous_lease_state", + repo_path=str(obs.repo_dir), + repository=obs.repository_slug, + ) + if live_status.is_live: + return CandidateEvaluation( + executable=False, + reason=live_status.reason, + category="active_lease", + repo_path=str(obs.repo_dir), + repository=obs.repository_slug, + ) + + return CandidateEvaluation( + executable=True, + reason="", + category="executable", + repo_path=str(obs.repo_dir), + repository=obs.repository_slug, + ) + + +def is_executable_candidate( + ticket: Ticket | Mapping[str, Any], + *, + pf: Planfile | None = None, + ticket_by_id: Mapping[str, Ticket | Mapping[str, Any]] | None = None, + repo_path: str | Path | None = None, + workspace_root: str | Path | None = None, + queue: str | None = None, + now: datetime | None = None, + observations: MutableMapping[Path, TargetRepoObservation] | None = None, +) -> bool: + """Return ``True`` iff ``ticket`` satisfies the canonical executable pending queue contract.""" + + return evaluate_executable_candidate( + ticket, + pf=pf, + ticket_by_id=ticket_by_id, + repo_path=repo_path, + workspace_root=workspace_root, + queue=queue, + now=now, + observations=observations, + ).executable + + +def executable_skip_reason( + ticket: Ticket | Mapping[str, Any], + *, + pf: Planfile | None = None, + ticket_by_id: Mapping[str, Ticket | Mapping[str, Any]] | None = None, + repo_path: str | Path | None = None, + workspace_root: str | Path | None = None, + queue: str | None = None, + now: datetime | None = None, + observations: MutableMapping[Path, TargetRepoObservation] | None = None, +) -> str: + """Return ``''`` when ``ticket`` is executable, else its canonical skip reason.""" + + return evaluate_executable_candidate( + ticket, + pf=pf, + ticket_by_id=ticket_by_id, + repo_path=repo_path, + workspace_root=workspace_root, + queue=queue, + now=now, + observations=observations, + ).reason + + +def _candidate_sort_key( + item: tuple[Ticket, CandidateEvaluation], +) -> tuple[int, int, str, str]: + ticket = item[0] + labels = [str(lbl).lower() for lbl in (ticket.labels or [])] + is_bug = 0 if "bug" in labels else 1 + priority_str = str(ticket.priority or "normal").strip().lower() + created_str = ( + ticket.created_at.isoformat() + if isinstance(ticket.created_at, datetime) + else str(ticket.created_at or "") + ) + return (_PRIORITY_ORDER.get(priority_str, 99), is_bug, created_str, ticket.id) + + +def executable_queue( + pf_or_path: Planfile | str | Path = ".", + *, + sprint: str = "active", + workspace_root: str | Path | None = None, + queue: str | None = None, + now: datetime | None = None, + observations: MutableMapping[Path, TargetRepoObservation] | None = None, +) -> dict[str, Any]: + """Compute the canonical ``planfile.executable-queue/v1`` summary for one repository.""" + + from planfile import Planfile as PlanfileCls + + pf = ( + pf_or_path + if isinstance(pf_or_path, PlanfileCls) + else PlanfileCls(str(pf_or_path)) + ) + current_time = _utc_now(now) + now_iso = current_time.isoformat().replace("+00:00", "Z") + default_repo = pf.store.primary_project_dir + ws_root = Path(workspace_root) if workspace_root is not None else None + obs_cache: MutableMapping[Path, TargetRepoObservation] = ( + observations if observations is not None else {} + ) + slug_index = _build_slug_index(ws_root, obs_cache, current_time) + + tickets = iter_sprint_tickets(pf, sprint=sprint) + ticket_by_id = pf._ticket_snapshot_with_dependencies(tickets) + + status_counts: dict[str, int] = { + "open": 0, + "in_progress": 0, + "blocked": 0, + "done": 0, + "canceled": 0, + "failed": 0, + "review": 0, + } + excluded_by_reason: dict[str, int] = {} + executable_pairs: list[tuple[Ticket, CandidateEvaluation]] = [] + skipped_items: list[ExecutableSkippedItemV1] = [] + + for ticket in tickets: + norm_status = _normalize_status(ticket.status) + if norm_status in status_counts: + status_counts[norm_status] += 1 + + evaluation = evaluate_executable_candidate( + ticket, + pf=pf, + ticket_by_id=ticket_by_id, + repo_path=default_repo, + workspace_root=ws_root, + queue=queue, + now=current_time, + observations=obs_cache, + slug_index=slug_index, + ) + if evaluation.executable: + executable_pairs.append((ticket, evaluation)) + else: + excluded_by_reason[evaluation.category] = ( + excluded_by_reason.get(evaluation.category, 0) + 1 + ) + skipped_items.append( + ExecutableSkippedItemV1( + id=ticket.id, + status=norm_status or "unknown", + sprint=ticket.sprint or "current", + reason=evaluation.reason, + category=evaluation.category, + repository=evaluation.repository, + ) + ) + + executable_pairs.sort(key=_candidate_sort_key) + candidate_models: list[ExecutableCandidateV1] = [] + for ticket, evaluation in executable_pairs: + _, ticket_queue = _extract_exec_state_and_queue(ticket) + created_iso = ( + ticket.created_at.isoformat() + if isinstance(ticket.created_at, datetime) + else (str(ticket.created_at) if ticket.created_at else None) + ) + candidate_models.append( + ExecutableCandidateV1( + id=ticket.id, + name=ticket.name, + priority=str(ticket.priority or "normal"), + sprint=ticket.sprint or "current", + queue=ticket_queue, + repository=evaluation.repository, + repo_path=evaluation.repo_path or str(default_repo), + labels=list(ticket.labels or []), + files=list(ticket.files or []), + blocked_by=list(ticket.blocked_by or []), + created_at=created_iso, + ) + ) + + default_obs = obs_cache.get(default_repo.resolve()) if default_repo.exists() else None + summary = ExecutableQueueSummaryV1( + generated_at=now_iso, + project_dir=str(default_repo), + repository=default_obs.repository_slug if default_obs else None, + sprint=sprint, + queue=queue, + counts=ExecutableQueueCountsV1( + total_scanned=len(tickets), + open=status_counts["open"], + in_progress=status_counts["in_progress"], + blocked=status_counts["blocked"], + done=status_counts["done"], + canceled=status_counts["canceled"], + failed=status_counts["failed"], + review=status_counts["review"], + executable=len(candidate_models), + excluded=len(skipped_items), + ), + excluded_by_reason=dict(sorted(excluded_by_reason.items())), + candidate_ids=[cand.id for cand in candidate_models], + candidates=candidate_models, + skipped=skipped_items, + ) + return summary.model_dump(mode="json", by_alias=True) + + +def fleet_executable_queue( + workspace_root: str | Path, + *, + sprint: str = "active", + queue: str | None = None, + now: datetime | None = None, + max_depth: int = 2, +) -> dict[str, Any]: + """Compute a unified ``planfile.executable-queue/v1`` report across all fleet repositories.""" + + current_time = _utc_now(now) + now_iso = current_time.isoformat().replace("+00:00", "Z") + ws_path = Path(workspace_root) + obs_cache: dict[Path, TargetRepoObservation] = {} + repos = discover_planfile_repositories(ws_path, max_depth=max_depth) + + totals = { + "total_scanned": 0, + "open": 0, + "in_progress": 0, + "blocked": 0, + "done": 0, + "canceled": 0, + "failed": 0, + "review": 0, + "executable": 0, + "excluded": 0, + } + excluded_by_reason: dict[str, int] = {} + all_candidates: list[dict[str, Any]] = [] + all_skipped: list[dict[str, Any]] = [] + repo_summaries: list[dict[str, Any]] = [] + + for repo_dir in repos: + repo_report = executable_queue( + repo_dir, + sprint=sprint, + workspace_root=ws_path, + queue=queue, + now=current_time, + observations=obs_cache, + ) + repo_summaries.append( + { + "project_dir": repo_report["project_dir"], + "repository": repo_report["repository"], + "counts": repo_report["counts"], + "candidate_ids": repo_report["candidate_ids"], + } + ) + for key in totals: + totals[key] += int(repo_report["counts"][key]) + for reason_key, count in repo_report["excluded_by_reason"].items(): + excluded_by_reason[reason_key] = ( + excluded_by_reason.get(reason_key, 0) + int(count) + ) + all_candidates.extend(repo_report["candidates"]) + all_skipped.extend(repo_report["skipped"]) + + all_candidates.sort( + key=lambda c: ( + _PRIORITY_ORDER.get(str(c.get("priority") or "normal").lower(), 99), + 0 if "bug" in [str(x).lower() for x in (c.get("labels") or [])] else 1, + str(c.get("created_at") or ""), + str(c.get("repository") or ""), + str(c.get("id") or ""), + ) + ) + return { + "schema": EXECUTABLE_QUEUE_SCHEMA, + "generated_at": now_iso, + "workspace_root": str(ws_path), + "sprint": sprint, + "queue": queue, + "repositories_scanned": len(repos), + "counts": totals, + "excluded_by_reason": dict(sorted(excluded_by_reason.items())), + "candidate_ids": [str(c["id"]) for c in all_candidates], + "candidates": all_candidates, + "skipped": all_skipped, + "repositories": repo_summaries, + } + + +__all__ = [ + "EXECUTABLE_QUEUE_SCHEMA", + "RUNNABLE_EXECUTION_STATES", + "SATISFIED_DEPENDENCY_STATUSES", + "CandidateEvaluation", + "evaluate_executable_candidate", + "executable_queue", + "executable_skip_reason", + "fleet_executable_queue", + "is_executable_candidate", +] + + +class _CallableExecutableQueueModule(types.ModuleType): + def __call__(self, *args: Any, **kwargs: Any) -> dict[str, Any]: + return executable_queue(*args, **kwargs) + + +sys.modules[__name__].__class__ = _CallableExecutableQueueModule diff --git a/planfile/reconcile.py b/planfile/reconcile.py new file mode 100644 index 00000000..ce643eb8 --- /dev/null +++ b/planfile/reconcile.py @@ -0,0 +1,1534 @@ +"""Reconcile Planfile ``in_progress`` status with live leases, worktrees, and merge receipts.""" + +from __future__ import annotations + +import json +import os +import re +import subprocess +import sys +import types +from collections.abc import Mapping, MutableMapping +from dataclasses import dataclass, field +from datetime import datetime, timezone +from pathlib import Path +from typing import TYPE_CHECKING, Any + +from planfile.contracts import ( + RECONCILE_MERGE_EVIDENCE_SCHEMA, + RECONCILE_REPORT_SCHEMA, +) +from planfile.core.models import Ticket, TicketExecution + +if TYPE_CHECKING: + from planfile import Planfile + +TERMINAL_LEASE_PHASES: frozenset[str] = frozenset( + {"merged", "closed", "cancelled", "canceled", "expired", "released"} +) +_GIT_SHA_RE = re.compile(r"^[0-9a-fA-F]{40,64}$") +_NATIVE_TICKET_RE = re.compile(r"\bticket-(\d{3,})\b", re.IGNORECASE) +_PLANFILE_ID_RE = re.compile(r"\b([A-Z][A-Z0-9]{1,9}-\d+)\b") +_GITHUB_URL_SLUG_RE = re.compile( + r"github\.com[:/]([A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+?)(?:\.git|/|$)", + re.IGNORECASE, +) +_GITHUB_ISSUE_REF_RE = re.compile( + r"(?:issue|github|closes|fixes|refs)?[\s:#]*#(\d+)\b", + re.IGNORECASE, +) +_RECEIPT_PR_RE = re.compile( + r"(?:pr[-:]?|/pull/|:)(\d+)(?:/merged)?$", + re.IGNORECASE, +) + + +@dataclass(frozen=True) +class LiveLeaseInfo: + """Active, non-expired ``.subactor/leases/*.json`` writer lease.""" + + lease_id: str + ticket_id: str + worktree_id: str + branch_ref: str + owner_actor: str + owner_session: str + phase: str + expires_at: str + tokens: frozenset[str] = field(default_factory=frozenset) + + +@dataclass(frozen=True) +class WorktreeInfo: + """Observed linked Git worktree in a target repository.""" + + path: Path + worktree_id: str + branch: str + head_sha: str + ticket_id: str | None + dirty: bool + ahead: int + observation_failed: bool = False + tokens: frozenset[str] = field(default_factory=frozenset) + + @property + def active(self) -> bool: + return self.dirty or self.ahead > 0 + + +@dataclass(frozen=True) +class TerminalReceiptEntry: + """Raw ``merged`` entry from ``.git/new-project/terminal-receipts.json``.""" + + ticket_id: str + receipt_ref: str + terminal_sha: str + head_sha: str + target_branch: str + pull_request: int | None = None + planfile_ticket_id: str | None = None + + +@dataclass(frozen=True) +class VerifiedMergeEvidence: + """Git-ancestry-verified merge evidence for closing an ``in_progress`` ticket.""" + + terminal_receipt_ref: str + terminal_sha: str + head_sha: str | None + target_branch: str + native_ticket_id: str | None = None + + +@dataclass +class TargetRepoObservation: + """Cached local Git, lease, worktree, and receipt snapshot for one target repository.""" + + repo_dir: Path + observable: bool + error: str | None = None + primary_checkout: Path | None = None + git_common_dir: Path | None = None + repository_slug: str | None = None + target_branch: str = "main" + target_ref: str | None = None + live_leases: list[LiveLeaseInfo] = field(default_factory=list) + worktrees: list[WorktreeInfo] = field(default_factory=list) + merged_receipts: list[TerminalReceiptEntry] = field(default_factory=list) + planfile_to_native: dict[str, set[str]] = field(default_factory=dict) + issue_to_native: dict[int, set[str]] = field(default_factory=dict) + unmerged_ticket_nums: set[str] = field(default_factory=set) + corrupt_lease_files: list[str] = field(default_factory=list) + receipt_registry_corrupt: bool = False + _ancestry_cache: dict[tuple[str, str], bool] = field(default_factory=dict) + + +def _utc_now(now: datetime | None = None) -> datetime: + if now is None: + return datetime.now(timezone.utc) + if now.tzinfo is None: + return now.replace(tzinfo=timezone.utc) + return now.astimezone(timezone.utc) + + +def _parse_iso_datetime(value: Any) -> datetime | None: + if isinstance(value, datetime): + dt = value + elif isinstance(value, str) and value.strip(): + try: + dt = datetime.fromisoformat(value.strip().replace("Z", "+00:00")) + except ValueError: + return None + else: + return None + if dt.tzinfo is None: + dt = dt.replace(tzinfo=timezone.utc) + return dt.astimezone(timezone.utc) + + +def _git_env() -> dict[str, str]: + env = {k: v for k, v in os.environ.items() if not k.startswith("GIT_")} + env["GIT_TERMINAL_PROMPT"] = "0" + return env + + +def _run_git( + cwd: Path, + *args: str, + timeout: float = 5.0, +) -> tuple[int, str]: + try: + proc = subprocess.run( + ["git", "-C", str(cwd), *args], + capture_output=True, + text=True, + check=False, + env=_git_env(), + timeout=timeout, + ) + return proc.returncode, proc.stdout + except (OSError, subprocess.SubprocessError): + return 1, "" + + +def _parse_origin_slug(url: str) -> str | None: + cleaned = url.strip() + if not cleaned: + return None + match = _GITHUB_URL_SLUG_RE.search(cleaned) + if match: + return match.group(1).removesuffix(".git").lower() + parts = [p for p in cleaned.removesuffix(".git").rstrip("/").split("/") if p] + if len(parts) >= 2 and ":" in parts[-2]: + owner = parts[-2].split(":")[-1] + return f"{owner}/{parts[-1]}".lower() + if len(parts) >= 2 and all(part not in {".", ".."} for part in parts[-2:]): + return f"{parts[-2]}/{parts[-1]}".lower() + return None + + +def _normalize_native_ticket(raw: str) -> str | None: + match = _NATIVE_TICKET_RE.search(raw) + if not match: + return None + return f"ticket-{int(match.group(1)):03d}" + + +def _extract_tokens(*texts: Any) -> frozenset[str]: + markers: set[str] = set() + for item in texts: + if not isinstance(item, str) or not item: + continue + lowered = item.lower() + markers.add(lowered) + for pf_match in _PLANFILE_ID_RE.finditer(item.upper()): + markers.add(pf_match.group(1).lower()) + for native_match in _NATIVE_TICKET_RE.finditer(lowered): + markers.add(f"ticket-{int(native_match.group(1)):03d}") + return frozenset(markers) + + +def _determine_target_branch_and_ref(primary: Path) -> tuple[str, str | None]: + target_branch = "main" + manifest_path = primary / ".governance" / "manifest.json" + if manifest_path.is_file() and not manifest_path.is_symlink(): + try: + manifest = json.loads(manifest_path.read_text(encoding="utf-8")) + branches = (manifest.get("delivery") or {}).get("targetBranches") + if isinstance(branches, list) and branches and isinstance(branches[0], str): + target_branch = branches[0].strip() or "main" + except (OSError, json.JSONDecodeError): + pass + + candidates = [ + f"refs/remotes/origin/{target_branch}", + f"refs/heads/{target_branch}", + ] + if target_branch == "main": + candidates.extend(["refs/remotes/origin/master", "refs/heads/master"]) + for ref in candidates: + rc, out = _run_git(primary, "rev-parse", "--verify", f"{ref}^{{commit}}") + if rc == 0 and out.strip(): + resolved_branch = ref.rsplit("/", 1)[-1] + return resolved_branch, ref + rc, out = _run_git(primary, "rev-parse", "--verify", "HEAD^{commit}") + if rc == 0 and out.strip(): + return target_branch, out.strip() + return target_branch, None + + +def _index_native_ticket_links( + checkout_root: Path, + planfile_to_native: dict[str, set[str]], + issue_to_native: dict[int, set[str]], +) -> set[str]: + found_tokens: set[str] = set() + project_dir = checkout_root / "project" + if not project_dir.is_dir() or project_dir.is_symlink(): + return found_tokens + try: + entries = sorted(project_dir.iterdir()) + except OSError: + return found_tokens + for entry in entries: + if not entry.is_dir() or entry.is_symlink(): + continue + native_id = _normalize_native_ticket(entry.name) + if not native_id: + continue + readme = entry / "README.md" + if not readme.is_file() or readme.is_symlink(): + continue + try: + text = readme.read_text(encoding="utf-8", errors="replace") + except OSError: + continue + for pf_match in _PLANFILE_ID_RE.finditer(text): + pf_id = pf_match.group(1).upper() + planfile_to_native.setdefault(pf_id, set()).add(native_id) + found_tokens.add(pf_id.lower()) + for issue_match in _GITHUB_ISSUE_REF_RE.finditer(text): + try: + issue_num = int(issue_match.group(1)) + except ValueError: + continue + issue_to_native.setdefault(issue_num, set()).add(native_id) + return found_tokens + + +def _scan_leases(primary: Path, now: datetime, obs: TargetRepoObservation) -> None: + subactor_dir = primary / ".subactor" + leases_dir = subactor_dir / "leases" + if subactor_dir.is_symlink() or leases_dir.is_symlink(): + obs.observable = False + obs.error = "lease_directory_symlink" + return + if not leases_dir.exists(): + return + if not leases_dir.is_dir(): + obs.observable = False + obs.error = "lease_directory_invalid" + return + try: + lease_files = sorted(leases_dir.glob("*.json")) + except OSError: + obs.observable = False + obs.error = "lease_directory_unreadable" + return + + for lease_file in lease_files: + if lease_file.is_symlink(): + obs.corrupt_lease_files.append(lease_file.name) + continue + try: + payload = json.loads(lease_file.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError): + obs.corrupt_lease_files.append(lease_file.name) + continue + if not isinstance(payload, dict): + obs.corrupt_lease_files.append(lease_file.name) + continue + phase = str( + payload.get("phase") or payload.get("status") or payload.get("state") or "" + ).strip().lower() + if phase in TERMINAL_LEASE_PHASES: + continue + if payload.get("releasedAt") not in (None, ""): + continue + expires_raw = payload.get("expiresAt") + expires_dt = _parse_iso_datetime(expires_raw) + if expires_dt is None: + obs.corrupt_lease_files.append(lease_file.name) + continue + if expires_dt <= now: + continue + + raw_ticket = str(payload.get("ticketId") or payload.get("ticket") or "").strip() + norm_native = _normalize_native_ticket(raw_ticket) + ticket_id = norm_native or raw_ticket + lease_id = str(payload.get("leaseId") or lease_file.stem).strip() + worktree_id = str(payload.get("worktreeId") or lease_file.stem).strip() + branch_ref = str(payload.get("branchRef") or "").strip() + owner_actor = str(payload.get("ownerActor") or "").strip() + owner_session = str(payload.get("ownerSession") or "").strip() + tokens = _extract_tokens( + ticket_id, + raw_ticket, + lease_id, + worktree_id, + branch_ref, + owner_session, + lease_file.stem, + ) + obs.live_leases.append( + LiveLeaseInfo( + lease_id=lease_id, + ticket_id=ticket_id, + worktree_id=worktree_id, + branch_ref=branch_ref, + owner_actor=owner_actor, + owner_session=owner_session, + phase=phase or "claimed", + expires_at=str(expires_raw), + tokens=tokens, + ) + ) + + +def _parse_worktree_porcelain(raw: str) -> list[dict[str, str]]: + records: list[dict[str, str]] = [] + current: dict[str, str] = {} + for chunk in raw.split("\0"): + if not chunk: + if "worktree" in current: + records.append(current) + current = {} + continue + if " " in chunk: + key, val = chunk.split(" ", 1) + current[key] = val + else: + current[chunk] = "true" + if "worktree" in current: + records.append(current) + return records + + +def _scan_worktrees(primary: Path, obs: TargetRepoObservation) -> None: + rc, raw = _run_git(primary, "worktree", "list", "--porcelain", "-z") + if rc != 0: + obs.observable = False + obs.error = "worktree_list_failed" + return + records = _parse_worktree_porcelain(raw) + for idx, entry in enumerate(records): + wt_raw = entry.get("worktree", "") + if not wt_raw or idx == 0: + continue + wt_path = Path(wt_raw) + branch_ref = entry.get("branch", "") + branch_short = branch_ref.removeprefix("refs/heads/") + head_sha = entry.get("HEAD", "") + worktree_id = wt_path.name + native_ticket = ( + _normalize_native_ticket(worktree_id) + or _normalize_native_ticket(branch_short) + ) + readme_tokens: set[str] = set() + dirty = False + ahead = 0 + obs_failed = False + + if wt_path.is_symlink(): + obs_failed = True + elif wt_path.is_dir(): + readme_tokens = _index_native_ticket_links( + wt_path, + obs.planfile_to_native, + obs.issue_to_native, + ) + st_rc, st_out = _run_git( + wt_path, + "status", + "--porcelain=v1", + "--untracked-files=all", + ) + if st_rc != 0: + obs_failed = True + else: + dirty = bool(st_out.strip()) + if obs.target_ref and head_sha: + av_rc, av_out = _run_git( + primary, + "rev-list", + "--count", + f"{obs.target_ref}..{head_sha}", + ) + if av_rc == 0 and av_out.strip().isdigit(): + ahead = int(av_out.strip()) + elif av_rc != 0: + obs_failed = True + + base_tokens = set( + _extract_tokens(worktree_id, branch_short, native_ticket or "") + ) + base_tokens.update(readme_tokens) + obs.worktrees.append( + WorktreeInfo( + path=wt_path, + worktree_id=worktree_id, + branch=branch_short, + head_sha=head_sha, + ticket_id=native_ticket, + dirty=dirty, + ahead=ahead, + observation_failed=obs_failed, + tokens=frozenset(base_tokens), + ) + ) + + +def _scan_unmerged_ticket_branches(primary: Path, obs: TargetRepoObservation) -> None: + if not obs.target_ref: + return + rc, out = _run_git( + primary, + "for-each-ref", + "--format=%(refname:short)\t%(objectname)", + "refs/heads/ticket", + "refs/heads/ticket-*", + ) + if rc != 0: + return + for line in out.splitlines(): + if "\t" not in line: + continue + branch_name, sha = line.split("\t", 1) + native = _normalize_native_ticket(branch_name) + if not native or not sha: + continue + if not _is_git_ancestor(obs, sha.strip(), obs.target_ref): + obs.unmerged_ticket_nums.add(native) + + +def _scan_terminal_receipts(git_common_dir: Path, obs: TargetRepoObservation) -> None: + receipts_path = git_common_dir / "new-project" / "terminal-receipts.json" + if receipts_path.is_symlink(): + obs.receipt_registry_corrupt = True + return + if not receipts_path.exists(): + return + try: + payload = json.loads(receipts_path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError): + obs.receipt_registry_corrupt = True + return + if not isinstance(payload, dict): + obs.receipt_registry_corrupt = True + return + items = payload.get("receipts") + if not isinstance(items, list): + obs.receipt_registry_corrupt = True + return + for item in items: + if not isinstance(item, dict): + continue + if str(item.get("outcome") or "").strip().lower() != "merged": + continue + raw_ticket = str(item.get("ticketId") or item.get("ticket") or "").strip() + terminal_sha = str(item.get("terminalSha") or "").strip() + head_sha = str(item.get("headSha") or "").strip() + receipt_ref = str(item.get("receiptRef") or "").strip() + target_branch = str(item.get("targetBranch") or obs.target_branch).strip() + if not raw_ticket or not _GIT_SHA_RE.fullmatch(terminal_sha): + continue + norm_ticket = _normalize_native_ticket(raw_ticket) or raw_ticket + pr_num: int | None = None + if isinstance(item.get("pullRequest"), int): + pr_num = int(item["pullRequest"]) + elif receipt_ref: + pr_match = _RECEIPT_PR_RE.search(receipt_ref) + if pr_match: + pr_num = int(pr_match.group(1)) + pf_ticket = str( + item.get("planfileTicketId") or item.get("planfileTicket") or "" + ).strip() or None + obs.merged_receipts.append( + TerminalReceiptEntry( + ticket_id=norm_ticket, + receipt_ref=receipt_ref or f"receipt:terminal-sha:{terminal_sha}", + terminal_sha=terminal_sha, + head_sha=head_sha, + target_branch=target_branch, + pull_request=pr_num, + planfile_ticket_id=pf_ticket, + ) + ) + + +def _is_git_ancestor(obs: TargetRepoObservation, ancestor_sha: str, target_ref: str) -> bool: + if obs.primary_checkout is None or not _GIT_SHA_RE.fullmatch(ancestor_sha): + return False + cache_key = (ancestor_sha.lower(), target_ref) + cached = obs._ancestry_cache.get(cache_key) + if cached is not None: + return cached + rc, _ = _run_git( + obs.primary_checkout, + "merge-base", + "--is-ancestor", + ancestor_sha, + target_ref, + ) + result = rc == 0 + obs._ancestry_cache[cache_key] = result + return result + + +def observe_target_repository( + repo_dir: str | Path, + *, + now: datetime | None = None, +) -> TargetRepoObservation: + """Inspect a local Git checkout for leases, worktrees, and merge receipts.""" + + current_time = _utc_now(now) + candidate = Path(repo_dir) + if candidate.is_symlink(): + return TargetRepoObservation( + repo_dir=candidate, + observable=False, + error="target_repository_symlink", + ) + if not candidate.exists() or not candidate.is_dir(): + return TargetRepoObservation( + repo_dir=candidate, + observable=False, + error="target_repository_missing", + ) + resolved = candidate.resolve() + git_marker = resolved / ".git" + if git_marker.is_symlink() or not git_marker.exists(): + return TargetRepoObservation( + repo_dir=resolved, + observable=False, + error="target_repository_not_git", + ) + rc_common, raw_common = _run_git( + resolved, + "rev-parse", + "--path-format=absolute", + "--git-common-dir", + ) + if rc_common != 0 or not raw_common.strip(): + return TargetRepoObservation( + repo_dir=resolved, + observable=False, + error="target_repository_not_git", + ) + git_common_dir = Path(raw_common.strip()).resolve() + rc_wt, raw_wt = _run_git(resolved, "worktree", "list", "--porcelain", "-z") + if rc_wt != 0 or not raw_wt: + return TargetRepoObservation( + repo_dir=resolved, + observable=False, + error="worktree_list_failed", + ) + wt_records = _parse_worktree_porcelain(raw_wt) + if not wt_records or not wt_records[0].get("worktree"): + return TargetRepoObservation( + repo_dir=resolved, + observable=False, + error="primary_checkout_unavailable", + ) + primary = Path(wt_records[0]["worktree"]) + if primary.is_symlink() or not primary.is_dir(): + return TargetRepoObservation( + repo_dir=resolved, + observable=False, + error="primary_checkout_symlink_or_missing", + ) + primary = primary.resolve() + + rc_origin, origin_url = _run_git(primary, "config", "--get", "remote.origin.url") + repo_slug = _parse_origin_slug(origin_url) if rc_origin == 0 else None + target_branch, target_ref = _determine_target_branch_and_ref(primary) + + obs = TargetRepoObservation( + repo_dir=resolved, + observable=True, + primary_checkout=primary, + git_common_dir=git_common_dir, + repository_slug=repo_slug, + target_branch=target_branch, + target_ref=target_ref, + ) + _index_native_ticket_links(primary, obs.planfile_to_native, obs.issue_to_native) + _scan_leases(primary, current_time, obs) + if not obs.observable: + return obs + _scan_worktrees(primary, obs) + if not obs.observable: + return obs + _scan_unmerged_ticket_branches(primary, obs) + _scan_terminal_receipts(git_common_dir, obs) + return obs + + +def discover_planfile_repositories( + workspace_root: str | Path, + *, + max_depth: int = 2, +) -> list[Path]: + """Discover non-symlinked local repositories containing a ``.planfile`` directory.""" + + root = Path(workspace_root) + if root.is_symlink() or not root.is_dir(): + return [] + found: list[Path] = [] + queue: list[tuple[Path, int]] = [(root.resolve(), 0)] + while queue: + current, depth = queue.pop(0) + if depth > 0: + pf_dir = current / ".planfile" + if pf_dir.is_dir() and not pf_dir.is_symlink(): + found.append(current) + continue + if depth < max_depth: + try: + children = sorted(current.iterdir()) + except OSError: + continue + for entry in children: + if entry.name.startswith(".") or entry.is_symlink(): + continue + if entry.is_dir(): + queue.append((entry, depth + 1)) + return found + + +def _ticket_dict_view(ticket: Ticket | Mapping[str, Any]) -> dict[str, Any]: + if isinstance(ticket, Ticket): + return ticket.model_dump(mode="python", exclude_none=False) + return dict(ticket) + + +def _extract_repo_hints(data: Mapping[str, Any]) -> tuple[str | None, str | None]: + """Return ``(explicit_repo_path, explicit_repo_slug)`` declared on a ticket.""" + + path_keys = ("repo_path", "target_repo_path", "project_dir", "repository_path") + slug_keys = ("repository", "repo", "target_repository") + + containers: list[Mapping[str, Any]] = [] + source = data.get("source") + if isinstance(source, Mapping) and isinstance(source.get("context"), Mapping): + containers.append(source["context"]) + inputs = data.get("inputs") + if isinstance(inputs, Mapping) and isinstance(inputs.get("process_manifest"), Mapping): + containers.append(inputs["process_manifest"]) + outputs = data.get("outputs") + if isinstance(outputs, Mapping) and isinstance(outputs.get("result"), Mapping): + containers.append(outputs["result"]) + + for container in containers: + for key in path_keys: + val = container.get(key) + if isinstance(val, str) and val.strip(): + return val.strip(), None + for container in containers: + for key in slug_keys: + val = container.get(key) + if isinstance(val, str) and "/" in val and not val.startswith("/"): + slug = _parse_origin_slug(val) or val.strip().lower() + return None, slug + + sync = data.get("sync") + if isinstance(sync, Mapping): + gh = sync.get("github") + if isinstance(gh, Mapping): + for key in ("repo", "repository"): + val = gh.get(key) + if isinstance(val, str) and "/" in val: + return None, val.strip().lower() + url = gh.get("url") or gh.get("html_url") + if isinstance(url, str): + url_slug = _parse_origin_slug(url) + if url_slug: + return None, url_slug + + for raw_label in data.get("labels") or []: + label = str(raw_label).strip() + lower = label.lower() + if lower.startswith(("repo:", "repository:")): + candidate_slug = label.split(":", 1)[1].strip().lower() + if "/" in candidate_slug: + return None, candidate_slug + return None, None + + +def resolve_ticket_target_repo( + ticket: Ticket | Mapping[str, Any], + *, + default_repo_dir: Path | None, + workspace_root: Path | None = None, + now: datetime | None = None, + observations: MutableMapping[Path, TargetRepoObservation] | None = None, + slug_index: Mapping[str, Path] | None = None, +) -> tuple[TargetRepoObservation | None, str | None]: + """Resolve and observe the target repository checkout for ``ticket``. + + Returns ``(observation, unobserved_reason)``. When ``unobserved_reason`` is + not ``None``, callers MUST treat the target repository as locally unobserved + and preserve existing ``in_progress`` state rather than guessing. + """ + + cache = observations if observations is not None else {} + + def _observe(path: Path) -> TargetRepoObservation: + key = path if path.is_symlink() else (path.resolve() if path.exists() else path) + if key not in cache: + cache[key] = observe_target_repository(path, now=now) + return cache[key] + + data = _ticket_dict_view(ticket) + explicit_path, explicit_slug = _extract_repo_hints(data) + + if explicit_path is not None: + obs = _observe(Path(explicit_path)) + if not obs.observable: + return obs, obs.error or "target_repository_unobserved" + return obs, None + + default_obs = _observe(default_repo_dir) if default_repo_dir is not None else None + + if explicit_slug is not None: + if ( + default_obs is not None + and default_obs.observable + and default_obs.repository_slug == explicit_slug + ): + return default_obs, None + if slug_index and explicit_slug in slug_index: + indexed_obs = _observe(slug_index[explicit_slug]) + if indexed_obs.observable: + return indexed_obs, None + if workspace_root is not None and not workspace_root.is_symlink(): + parts = explicit_slug.split("/", 1) + candidates = ( + [workspace_root / parts[0] / parts[1], workspace_root / parts[1]] + if len(parts) == 2 + else [workspace_root / explicit_slug] + ) + for candidate in candidates: + cand_obs = _observe(candidate) + if cand_obs.observable and ( + cand_obs.repository_slug in {None, explicit_slug} + ): + return cand_obs, None + return None, f"target_repository_unobserved:{explicit_slug}" + + if default_obs is None: + return None, "target_repository_unspecified" + if not default_obs.observable: + return default_obs, default_obs.error or "target_repository_unobserved" + return default_obs, None + + +@dataclass(frozen=True) +class TicketRepoBindings: + """Extracted identity links between a Planfile ticket and a target repository.""" + + ticket_id: str + assigned_to: str | None + native_tickets: frozenset[str] + pr_numbers: frozenset[int] + direct_merge_candidates: tuple[tuple[str, str], ...] + + +def _extract_ticket_bindings( + ticket: Ticket | Mapping[str, Any], + obs: TargetRepoObservation, +) -> TicketRepoBindings: + data = _ticket_dict_view(ticket) + ticket_id = str(data.get("id") or "").strip() + execution = data.get("execution") if isinstance(data.get("execution"), Mapping) else {} + assigned_raw = execution.get("assigned_to") if isinstance(execution, Mapping) else None + assigned_to = str(assigned_raw).strip() if assigned_raw else None + + native_tickets: set[str] = set() + pr_numbers: set[int] = set() + direct_merges: list[tuple[str, str]] = [] + + if ticket_id.upper() in obs.planfile_to_native: + native_tickets.update(obs.planfile_to_native[ticket_id.upper()]) + norm_self = _normalize_native_ticket(ticket_id) + if norm_self: + native_tickets.add(norm_self) + if assigned_to: + norm_assigned = _normalize_native_ticket(assigned_to) + if norm_assigned: + native_tickets.add(norm_assigned) + + for raw_label in data.get("labels") or []: + norm_lbl = _normalize_native_ticket(str(raw_label)) + if norm_lbl: + native_tickets.add(norm_lbl) + + source = data.get("source") + if isinstance(source, Mapping) and isinstance(source.get("context"), Mapping): + for val in source["context"].values(): + if isinstance(val, str): + norm = _normalize_native_ticket(val) + if norm: + native_tickets.add(norm) + + sync = data.get("sync") + if isinstance(sync, Mapping): + gh = sync.get("github") + if isinstance(gh, Mapping): + issue_num = gh.get("issue_number") or gh.get("number") + if isinstance(issue_num, int) and issue_num in obs.issue_to_native: + native_tickets.update(obs.issue_to_native[issue_num]) + for pr_key in ("pr_number", "pull_request"): + pr_val = gh.get(pr_key) + if isinstance(pr_val, int) and pr_val > 0: + pr_numbers.add(pr_val) + merge_sha = str(gh.get("merge_commit_sha") or "").strip() + if gh.get("merged") is True and _GIT_SHA_RE.fullmatch(merge_sha): + direct_merges.append((merge_sha, f"receipt:github-merge:{merge_sha}")) + + outputs = data.get("outputs") + if isinstance(outputs, Mapping): + for sub_key in ("completion_receipt", "result"): + sub = outputs.get(sub_key) + if not isinstance(sub, Mapping): + continue + for t_key in ("nativeTicketId", "native_ticket", "ticket", "ticketId"): + t_val = sub.get(t_key) + if isinstance(t_val, str): + norm_t = _normalize_native_ticket(t_val) + if norm_t: + native_tickets.add(norm_t) + pr_val = sub.get("pullRequest") or sub.get("pr_number") + if isinstance(pr_val, int) and pr_val > 0: + pr_numbers.add(pr_val) + term_sha = str( + sub.get("terminalSha") or sub.get("merge_commit_sha") or "" + ).strip() + outcome = str(sub.get("outcome") or "").strip().lower() + if (outcome == "merged" or sub.get("merged") is True) and _GIT_SHA_RE.fullmatch( + term_sha + ): + ref = str( + sub.get("terminalReceiptRef") + or sub.get("receiptRef") + or f"receipt:completion:{term_sha}" + ).strip() + direct_merges.append((term_sha, ref)) + + return TicketRepoBindings( + ticket_id=ticket_id, + assigned_to=assigned_to, + native_tickets=frozenset(native_tickets), + pr_numbers=frozenset(pr_numbers), + direct_merge_candidates=tuple(direct_merges), + ) + + +def find_verified_merge_evidence( + ticket: Ticket | Mapping[str, Any], + obs: TargetRepoObservation, +) -> VerifiedMergeEvidence | None: + """Return Git-ancestry-verified merge evidence for ``ticket``, if any.""" + + if not obs.observable or not obs.target_ref or obs.primary_checkout is None: + return None + bindings = _extract_ticket_bindings(ticket, obs) + + for receipt in reversed(obs.merged_receipts): + matched = ( + receipt.ticket_id == bindings.ticket_id + or receipt.ticket_id in bindings.native_tickets + or ( + receipt.planfile_ticket_id is not None + and receipt.planfile_ticket_id.upper() == bindings.ticket_id.upper() + ) + or ( + receipt.pull_request is not None + and receipt.pull_request in bindings.pr_numbers + ) + ) + if not matched: + continue + if receipt.ticket_id in obs.unmerged_ticket_nums: + continue + if _is_git_ancestor(obs, receipt.terminal_sha, obs.target_ref): + return VerifiedMergeEvidence( + terminal_receipt_ref=receipt.receipt_ref, + terminal_sha=receipt.terminal_sha, + head_sha=receipt.head_sha or None, + target_branch=receipt.target_branch or obs.target_branch, + native_ticket_id=( + receipt.ticket_id if receipt.ticket_id.startswith("ticket-") else None + ), + ) + + for cand_sha, cand_ref in bindings.direct_merge_candidates: + if _is_git_ancestor(obs, cand_sha, obs.target_ref): + return VerifiedMergeEvidence( + terminal_receipt_ref=cand_ref, + terminal_sha=cand_sha, + head_sha=None, + target_branch=obs.target_branch, + native_ticket_id=next(iter(sorted(bindings.native_tickets)), None), + ) + + for native_id in sorted(bindings.native_tickets): + if native_id in obs.unmerged_ticket_nums: + continue + has_active_wt = any( + wt.ticket_id == native_id and wt.active for wt in obs.worktrees + ) + if has_active_wt: + continue + cat_rc, _ = _run_git( + obs.primary_checkout, + "cat-file", + "-e", + f"{obs.target_ref}:project/{native_id}/README.md", + ) + if cat_rc != 0: + continue + log_rc, log_out = _run_git( + obs.primary_checkout, + "log", + "-n", + "1", + "--format=%H", + obs.target_ref, + "--", + f"project/{native_id}", + ) + landed_sha = log_out.strip() + if log_rc == 0 and _GIT_SHA_RE.fullmatch(landed_sha): + return VerifiedMergeEvidence( + terminal_receipt_ref=f"receipt:git-landed:{native_id}:{landed_sha}", + terminal_sha=landed_sha, + head_sha=None, + target_branch=obs.target_branch, + native_ticket_id=native_id, + ) + + return None + + +@dataclass(frozen=True) +class LiveBindingStatus: + """Live lease, active worktree, or ambiguous observation result for a ticket.""" + + is_live: bool + ambiguous_error: str | None = None + reason: str = "" + lease_id: str | None = None + worktree_id: str | None = None + + +def find_live_ticket_binding( + ticket: Ticket | Mapping[str, Any], + obs: TargetRepoObservation, + *, + now: datetime | None = None, +) -> LiveBindingStatus: + """Check whether ``ticket`` is bound to a live non-expired lease or active worktree.""" + + current_time = _utc_now(now) + data = _ticket_dict_view(ticket) + bindings = _extract_ticket_bindings(ticket, obs) + ticket_key = bindings.ticket_id.lower() + + if obs.corrupt_lease_files: + for corrupt_name in obs.corrupt_lease_files: + corrupt_markers = _extract_tokens(corrupt_name) + if ( + (ticket_key and ticket_key in corrupt_markers) + or bool(bindings.native_tickets & corrupt_markers) + or ( + bindings.assigned_to is not None + and bindings.assigned_to.lower() in corrupt_markers + ) + ): + return LiveBindingStatus( + is_live=False, + ambiguous_error=f"corrupt_lease_file:{corrupt_name}", + ) + + for wt in obs.worktrees: + wt_matches = ( + (wt.ticket_id is not None and wt.ticket_id == bindings.ticket_id) + or (wt.ticket_id is not None and wt.ticket_id in bindings.native_tickets) + or (ticket_key and ticket_key in wt.tokens) + or (bindings.assigned_to is not None and bindings.assigned_to == wt.worktree_id) + ) + if wt_matches and wt.observation_failed: + return LiveBindingStatus( + is_live=False, + ambiguous_error=f"worktree_observation_failed:{wt.worktree_id}", + ) + + for lease in obs.live_leases: + lease_matches = ( + lease.ticket_id == bindings.ticket_id + or lease.ticket_id in bindings.native_tickets + or (ticket_key and ticket_key in lease.tokens) + or ( + bindings.assigned_to is not None + and bindings.assigned_to + in {lease.lease_id, lease.worktree_id, lease.owner_session} + ) + ) + if lease_matches: + return LiveBindingStatus( + is_live=True, + reason=f"active_lease:{lease.lease_id}", + lease_id=lease.lease_id, + worktree_id=lease.worktree_id, + ) + + for wt in obs.worktrees: + wt_matches = ( + (wt.ticket_id is not None and wt.ticket_id == bindings.ticket_id) + or (wt.ticket_id is not None and wt.ticket_id in bindings.native_tickets) + or (ticket_key and ticket_key in wt.tokens) + or (bindings.assigned_to is not None and bindings.assigned_to == wt.worktree_id) + ) + if wt_matches and wt.active: + return LiveBindingStatus( + is_live=True, + reason=f"active_worktree:{wt.worktree_id}", + worktree_id=wt.worktree_id, + ) + + execution = data.get("execution") + if isinstance(execution, Mapping): + lease_exp = _parse_iso_datetime(execution.get("lease_expires_at")) + if lease_exp is not None and lease_exp > current_time: + return LiveBindingStatus( + is_live=True, + reason=f"active_lease:planfile:{bindings.ticket_id}", + lease_id=f"planfile:{bindings.ticket_id}", + ) + + return LiveBindingStatus(is_live=False) + + +def iter_sprint_tickets(pf: Planfile, sprint: str = "active") -> list[Ticket]: + """Return deduplicated tickets for ``sprint`` (``'active'`` excludes ``history-*``/``archive-*``).""" + + if sprint == "active": + sprint_ids = [ + sid + for sid in pf.store._all_sprint_ids() + if not sid.startswith(("history-", "archive-")) + ] + if "current" in sprint_ids: + sprint_ids = ["current", *[s for s in sprint_ids if s != "current"]] + history_locs = pf.store._history_locations() + seen: set[str] = set() + collected: list[Ticket] = [] + for sid in sprint_ids: + for ticket in pf.list_tickets(sprint=sid): + if ticket.id in seen: + continue + if history_locs.get(ticket.id) not in {None, sid}: + continue + seen.add(ticket.id) + collected.append(ticket) + return collected + return pf.list_tickets(sprint=sprint) + + +def _apply_merge_transition( + pf: Planfile, + ticket: Ticket, + evidence: VerifiedMergeEvidence, + *, + now_iso: str, + actor: str, +) -> tuple[bool, str]: + from planfile.core.store import ( + ImmutableTerminalReopenError, + TicketUpdatedAtConflictError, + ) + + expected_updated_at = ( + ticket.updated_at.isoformat() + if isinstance(ticket.updated_at, datetime) + else str(ticket.updated_at) + ) + receipt_payload: dict[str, Any] = { + "schema": RECONCILE_MERGE_EVIDENCE_SCHEMA, + "outcome": "merged", + "terminalReceiptRef": evidence.terminal_receipt_ref, + "terminalSha": evidence.terminal_sha, + "targetBranch": evidence.target_branch, + "reconciledAt": now_iso, + } + if evidence.head_sha: + receipt_payload["headSha"] = evidence.head_sha + if evidence.native_ticket_id: + receipt_payload["nativeTicketId"] = evidence.native_ticket_id + + try: + updated = pf.complete_ticket( + ticket.id, + note=( + f"Reconciled verified merge ({evidence.terminal_receipt_ref} " + f"@ {evidence.terminal_sha})" + ), + completion_receipt=receipt_payload, + reason="reconcile:verified_merge_receipt", + actor=actor, + expected_updated_at=expected_updated_at, + ) + if updated is None: + return False, "not_found" + pf.append_ticket_evidence( + ticket.id, + idempotency_key=f"reconcile-merged:{ticket.id}:{evidence.terminal_sha}", + collection="reconciliation_receipts", + evidence=receipt_payload, + reason="reconcile:verified_merge_receipt", + actor=actor, + ) + return True, "applied" + except (TicketUpdatedAtConflictError, ImmutableTerminalReopenError): + return False, "cas_conflict" + + +def _apply_reopen_transition( + pf: Planfile, + ticket: Ticket, + *, + actor: str, +) -> tuple[bool, str]: + from planfile.core.store import ( + ImmutableTerminalReopenError, + TicketUpdatedAtConflictError, + ) + + expected_updated_at = ( + ticket.updated_at.isoformat() + if isinstance(ticket.updated_at, datetime) + else str(ticket.updated_at) + ) + exec_data = ( + ticket.execution.model_dump(mode="python", exclude_none=False) + if ticket.execution + else {} + ) + exec_data.update( + state="ready", + assigned_to=None, + lease_expires_at=None, + started_at=None, + finished_at=None, + ) + execution = TicketExecution(**exec_data) + try: + updated = pf.update_ticket( + ticket.id, + status="open", + execution=execution, + reason="reconcile:abandoned_in_progress_without_live_lease_or_worktree", + actor=actor, + expected_updated_at=expected_updated_at, + ) + if updated is None: + return False, "not_found" + return True, "applied" + except (TicketUpdatedAtConflictError, ImmutableTerminalReopenError): + return False, "cas_conflict" + + +def _build_slug_index( + workspace_root: Path | None, + observations: MutableMapping[Path, TargetRepoObservation], + now: datetime, +) -> dict[str, Path]: + if workspace_root is None: + return {} + index: dict[str, Path] = {} + for repo_path in discover_planfile_repositories(workspace_root): + obs = observations.get(repo_path) + if obs is None: + obs = observe_target_repository(repo_path, now=now) + observations[repo_path] = obs + if obs.observable and obs.repository_slug: + index[obs.repository_slug] = repo_path + return index + + +def reconcile_in_progress( + pf_or_path: Planfile | str | Path = ".", + *, + apply: bool = False, + sprint: str = "active", + workspace_root: str | Path | None = None, + now: datetime | None = None, + actor: str = "planfile.reconcile", + observations: MutableMapping[Path, TargetRepoObservation] | None = None, +) -> dict[str, Any]: + """Reconcile Planfile ``in_progress`` tickets against live leases, worktrees, and merge receipts. + + Defaults to dry-run reporting (``apply=False``). When ``apply=True``, verified + merged tickets transition atomically to ``done`` with ``terminalReceiptRef`` and + ``terminalSha``, abandoned tickets without a live lease or active worktree + return to ``open``, and locally unobservable target repositories are preserved + as ``unobserved`` without guessing. + """ + + from planfile import Planfile as PlanfileCls + + pf = ( + pf_or_path + if isinstance(pf_or_path, PlanfileCls) + else PlanfileCls(str(pf_or_path)) + ) + current_time = _utc_now(now) + now_iso = current_time.isoformat().replace("+00:00", "Z") + default_repo = pf.store.primary_project_dir + ws_root = Path(workspace_root) if workspace_root is not None else None + obs_cache: MutableMapping[Path, TargetRepoObservation] = ( + observations if observations is not None else {} + ) + slug_index = _build_slug_index(ws_root, obs_cache, current_time) + + tickets = iter_sprint_tickets(pf, sprint=sprint) + in_progress_tickets = [ + t + for t in tickets + if (t.status.value if hasattr(t.status, "value") else str(t.status)) == "in_progress" + ] + + counts = { + "scanned_in_progress": len(in_progress_tickets), + "merged_to_done": 0, + "abandoned_to_open": 0, + "active_retained": 0, + "unobserved_preserved": 0, + "applied": 0, + "cas_conflicts": 0, + } + decisions: list[dict[str, Any]] = [] + + for ticket in in_progress_tickets: + obs, unobserved_reason = resolve_ticket_target_repo( + ticket, + default_repo_dir=default_repo, + workspace_root=ws_root, + now=current_time, + observations=obs_cache, + slug_index=slug_index, + ) + if obs is None or unobserved_reason is not None: + counts["unobserved_preserved"] += 1 + decisions.append( + { + "id": ticket.id, + "sprint": ticket.sprint, + "classification": "unobserved", + "action": "preserve_unobserved", + "previous_status": "in_progress", + "proposed_status": "in_progress", + "applied": False, + "reason": unobserved_reason or "target_repository_unobserved", + "repo_path": str(obs.repo_dir) if obs is not None else None, + } + ) + continue + + bindings = _extract_ticket_bindings(ticket, obs) + if obs.receipt_registry_corrupt and bindings.native_tickets: + counts["unobserved_preserved"] += 1 + decisions.append( + { + "id": ticket.id, + "sprint": ticket.sprint, + "classification": "unobserved", + "action": "preserve_unobserved", + "previous_status": "in_progress", + "proposed_status": "in_progress", + "applied": False, + "reason": "terminal_receipt_registry_corrupt", + "repo_path": str(obs.repo_dir), + } + ) + continue + + merge_evidence = find_verified_merge_evidence(ticket, obs) + if merge_evidence is not None: + counts["merged_to_done"] += 1 + applied = False + outcome = "dry_run" + if apply: + applied, outcome = _apply_merge_transition( + pf, + ticket, + merge_evidence, + now_iso=now_iso, + actor=actor, + ) + if applied: + counts["applied"] += 1 + elif outcome == "cas_conflict": + counts["cas_conflicts"] += 1 + decisions.append( + { + "id": ticket.id, + "sprint": ticket.sprint, + "classification": "merged", + "action": "close_merged", + "previous_status": "in_progress", + "proposed_status": "done", + "applied": applied, + "outcome": outcome, + "reason": "verified_merge_receipt", + "repo_path": str(obs.repo_dir), + "terminalReceiptRef": merge_evidence.terminal_receipt_ref, + "terminalSha": merge_evidence.terminal_sha, + "nativeTicketId": merge_evidence.native_ticket_id, + } + ) + continue + + live_status = find_live_ticket_binding(ticket, obs, now=current_time) + if live_status.ambiguous_error is not None: + counts["unobserved_preserved"] += 1 + decisions.append( + { + "id": ticket.id, + "sprint": ticket.sprint, + "classification": "unobserved", + "action": "preserve_unobserved", + "previous_status": "in_progress", + "proposed_status": "in_progress", + "applied": False, + "reason": live_status.ambiguous_error, + "repo_path": str(obs.repo_dir), + } + ) + continue + + if live_status.is_live: + counts["active_retained"] += 1 + decisions.append( + { + "id": ticket.id, + "sprint": ticket.sprint, + "classification": "active", + "action": "keep_in_progress", + "previous_status": "in_progress", + "proposed_status": "in_progress", + "applied": False, + "reason": live_status.reason, + "repo_path": str(obs.repo_dir), + "leaseId": live_status.lease_id, + "worktreeId": live_status.worktree_id, + } + ) + continue + + counts["abandoned_to_open"] += 1 + applied = False + outcome = "dry_run" + if apply: + applied, outcome = _apply_reopen_transition(pf, ticket, actor=actor) + if applied: + counts["applied"] += 1 + elif outcome == "cas_conflict": + counts["cas_conflicts"] += 1 + decisions.append( + { + "id": ticket.id, + "sprint": ticket.sprint, + "classification": "abandoned", + "action": "reopen_abandoned", + "previous_status": "in_progress", + "proposed_status": "open", + "applied": applied, + "outcome": outcome, + "reason": "no_live_lease_or_active_worktree", + "repo_path": str(obs.repo_dir), + } + ) + + default_obs = obs_cache.get(default_repo.resolve()) if default_repo.exists() else None + return { + "schema": RECONCILE_REPORT_SCHEMA, + "generated_at": now_iso, + "mode": "apply" if apply else "dry_run", + "project_dir": str(default_repo), + "repository": default_obs.repository_slug if default_obs else None, + "sprint": sprint, + "counts": counts, + "decisions": decisions, + } + + +reconcile = reconcile_in_progress + + +def reconcile_fleet_in_progress( + workspace_root: str | Path, + *, + apply: bool = False, + sprint: str = "active", + now: datetime | None = None, + actor: str = "planfile.reconcile", + max_depth: int = 2, +) -> dict[str, Any]: + """Reconcile ``in_progress`` tickets across all ``.planfile`` repositories under ``workspace_root``.""" + + current_time = _utc_now(now) + now_iso = current_time.isoformat().replace("+00:00", "Z") + ws_path = Path(workspace_root) + obs_cache: dict[Path, TargetRepoObservation] = {} + repos = discover_planfile_repositories(ws_path, max_depth=max_depth) + + totals = { + "repositories_scanned": len(repos), + "scanned_in_progress": 0, + "merged_to_done": 0, + "abandoned_to_open": 0, + "active_retained": 0, + "unobserved_preserved": 0, + "applied": 0, + "cas_conflicts": 0, + } + repo_reports: list[dict[str, Any]] = [] + all_decisions: list[dict[str, Any]] = [] + + for repo_dir in repos: + report = reconcile_in_progress( + repo_dir, + apply=apply, + sprint=sprint, + workspace_root=ws_path, + now=current_time, + actor=actor, + observations=obs_cache, + ) + repo_reports.append(report) + for key in ( + "scanned_in_progress", + "merged_to_done", + "abandoned_to_open", + "active_retained", + "unobserved_preserved", + "applied", + "cas_conflicts", + ): + totals[key] += int(report["counts"][key]) + all_decisions.extend(report["decisions"]) + + return { + "schema": RECONCILE_REPORT_SCHEMA, + "generated_at": now_iso, + "mode": "apply" if apply else "dry_run", + "workspace_root": str(ws_path), + "sprint": sprint, + "counts": totals, + "repositories": repo_reports, + "decisions": all_decisions, + } + + +__all__ = [ + "RECONCILE_MERGE_EVIDENCE_SCHEMA", + "RECONCILE_REPORT_SCHEMA", + "TERMINAL_LEASE_PHASES", + "LiveBindingStatus", + "LiveLeaseInfo", + "TargetRepoObservation", + "TerminalReceiptEntry", + "VerifiedMergeEvidence", + "WorktreeInfo", + "discover_planfile_repositories", + "find_live_ticket_binding", + "find_verified_merge_evidence", + "iter_sprint_tickets", + "observe_target_repository", + "reconcile", + "reconcile_fleet_in_progress", + "reconcile_in_progress", + "resolve_ticket_target_repo", +] + + +class _CallableReconcileModule(types.ModuleType): + def __call__(self, *args: Any, **kwargs: Any) -> dict[str, Any]: + return reconcile_in_progress(*args, **kwargs) + + +sys.modules[__name__].__class__ = _CallableReconcileModule diff --git a/project/ticket-284/README.md b/project/ticket-284/README.md new file mode 100644 index 00000000..b2f84ca7 --- /dev/null +++ b/project/ticket-284/README.md @@ -0,0 +1,34 @@ +# Ticket 284: Reconcile in_progress status with live leases/worktrees and export canonical executable queue + +- **ID**: ticket-284 +- **Owner**: agent:antigravity-aut14 +- **Status**: IN_PROGRESS +- **Workflow state**: PUBLICATION +- **Created**: 2026-11-15 +- **Issue**: semcod/planfile#346 + +SESSION_EXECUTION_AUTHORIZATION: Authorized autonomous implementation, validation, and protected publication for AUT-14 (`semcod/planfile#346`) inside canonical worktree `.worktrees/ticket-284--reconcile-in-progress-executable-queue`, preserving foreign untracked `project/ticket-280/` untouched on primary checkout. + +## Goal and scope + +1. Implement a target-repository-aware `in_progress` reconciliation engine (`reconcile_in_progress` / `reconcile` Python API and CLI commands `planfile reconcile` / `planfile ticket reconcile`): + - Verify `.git/new-project/terminal-receipts.json` (`outcome == "merged"` with Git ancestry on target branch) and landed merge commit receipts, transitioning verified merged `in_progress` tickets to `done` with recorded `terminalReceiptRef` and `terminalSha`. + - Retain `in_progress` when bound to a live non-expired `.subactor/leases/*.json` lease, active worktree with uncommitted or ahead-of-target commits, or live `execution.lease_expires_at`. + - Return abandoned `in_progress` tickets (no live lease and no active worktree) to `open` (`execution.state = "ready"`, clearing stale assignment/lease fields) atomically under `--apply` (`mutation_lock` + `expected_updated_at` CAS), defaulting to dry-run reporting. + - Preserve tickets whose target repository checkout cannot be observed locally as `unobserved` without guessing or mutating. +2. Export one canonical executable pending queue specification and evaluator (`EXECUTABLE_QUEUE_SCHEMA = "planfile.executable-queue/v1"`, `is_executable_candidate`, `evaluate_executable_candidate`, `executable_queue`, `fleet_executable_queue`, and CLI commands `planfile executable-queue` / `planfile ticket executable-queue`) shared across Planfile, Heyasa, and `monag`. + +## Acceptance criteria + +- [x] AC-01: `reconcile_in_progress` / `planfile reconcile` closes verified merged `in_progress` tickets with `terminalReceiptRef`/`terminalSha`, resets abandoned `in_progress` tickets without live lease or active worktree to `open` under `--apply` (dry-run by default), and preserves locally unobservable target repositories as `unobserved`. +- [x] AC-02: Canonical `executable_queue` / `is_executable_candidate` (`planfile.executable-queue/v1`) evaluates open/ready status, non-blocked autonomy state, resolved `blocked_by` across active and archived history, valid target repository, and absence of active non-expired leases. +- [ ] AC-03: Unit/integration tests, Ruff, `./project/governance-check.sh`, and independent exact-head Validator publication pass. + +## Validation and publication + +7 new reconciliation and executable-queue tests plus 53 existing ticket execution and legacy dependency tests passed under `wellman run`; `mypy`, `ruff check`, `wellman check`, and `./project/governance-check.sh` passed with 0 errors. Retaining `IN_PROGRESS` / `PUBLICATION` through exact-head independent Validator approval and merge. + +## Tracking boundary + +This directory contains the minimal reviewed intent. Optional participant prose +and raw command logs are not required delivery output. diff --git a/project/ticket-284/intent.json b/project/ticket-284/intent.json new file mode 100644 index 00000000..e7d4d1d2 --- /dev/null +++ b/project/ticket-284/intent.json @@ -0,0 +1,32 @@ +{ + "schema": "new-project.intent/v3", + "ticket": "ticket-284", + "summary": "Reconcile in_progress status with live leases/worktrees and export canonical executable queue", + "workstream": "application", + "classification": { + "kind": "FEATURE", + "priority": "P1", + "origin": "requested" + }, + "allowedPaths": [ + "project/ticket-284/**", + "TODO.md", + "project/TICKETS.md", + "planfile/__init__.py", + "planfile/cli/extra_commands.py", + "planfile/cli/groups/ticket/__init__.py", + "planfile/cli/groups/ticket/reconcile.py", + "planfile/contracts.py", + "planfile/executable_queue.py", + "planfile/reconcile.py", + "tests/test_executable_queue.py", + "tests/test_reconcile_in_progress.py" + ], + "forbiddenPaths": [ + "project/ticket-*/user-*.md" + ], + "stacks": [], + "dependsOn": [], + "conflictsWith": [], + "integrationTicket": null +} diff --git a/tests/test_executable_queue.py b/tests/test_executable_queue.py new file mode 100644 index 00000000..fd01ff73 --- /dev/null +++ b/tests/test_executable_queue.py @@ -0,0 +1,264 @@ +"""Tests for the canonical ``planfile.executable-queue/v1`` specification & evaluator (AUT-14 / #346).""" + +from __future__ import annotations + +import json +import os +import subprocess +from datetime import datetime, timedelta, timezone +from pathlib import Path + +from typer.testing import CliRunner + +from planfile import ( + EXECUTABLE_QUEUE_SCHEMA, + Planfile, + TicketExecution, + TicketSource, + evaluate_executable_candidate, + executable_queue, + executable_skip_reason, + fleet_executable_queue, + is_executable_candidate, +) +from planfile.cli.commands import _build_app + + +def _git(cwd: Path, *args: str) -> str: + env = {k: v for k, v in os.environ.items() if not k.startswith("GIT_")} + env["GIT_TERMINAL_PROMPT"] = "0" + env.setdefault("GIT_AUTHOR_NAME", "Test Bot") + env.setdefault("GIT_AUTHOR_EMAIL", "bot@example.com") + env.setdefault("GIT_COMMITTER_NAME", "Test Bot") + env.setdefault("GIT_COMMITTER_EMAIL", "bot@example.com") + proc = subprocess.run( + ["git", "-C", str(cwd), *args], + check=True, + capture_output=True, + text=True, + env=env, + ) + return proc.stdout.strip() + + +def _init_git_repo(repo: Path, remote_slug: str = "semcod/demo") -> None: + repo.mkdir(parents=True, exist_ok=True) + _git(repo, "init", "-b", "main") + _git(repo, "remote", "add", "origin", f"https://github.com/{remote_slug}.git") + (repo / "README.md").write_text("# Demo\n", encoding="utf-8") + _git(repo, "add", "README.md") + _git(repo, "commit", "-m", "Initial commit") + + +def _write_live_lease(repo: Path, ticket_id: str, expires_at: str) -> None: + leases_dir = repo / ".subactor" / "leases" + leases_dir.mkdir(parents=True, exist_ok=True) + payload = { + "schema": "wellmanifest.change-lease/v1", + "leaseId": f"lease-{ticket_id}", + "repositoryRef": "semcod/demo", + "targetBranch": "main", + "ticketId": ticket_id, + "workstream": "application", + "scopeHash": "a" * 64, + "branchRef": f"refs/heads/ticket/{ticket_id}", + "worktreeId": f"{ticket_id}--work", + "ownerActor": "agent:codex", + "ownerSession": "session-live", + "phase": "editing", + "leaseRevision": 1, + "fencingToken": 1, + "issuedAt": "2026-11-15T10:00:00Z", + "expiresAt": expires_at, + "heartbeatAt": "2026-11-15T10:00:00Z", + "headSha": "b" * 40, + "pullRequest": None, + "validatorRunId": None, + "publicationFrozen": False, + "planHash": "c" * 64, + "previousReceiptRef": None, + "eventSequence": 1, + } + (leases_dir / f"{ticket_id}--work.json").write_text( + json.dumps(payload), + encoding="utf-8", + ) + + +def test_executable_queue_contract_predicates_and_ordering(tmp_path: Path, monkeypatch) -> None: + monkeypatch.delenv("CURRENT_GOAL", raising=False) + monkeypatch.delenv("PLANFILE_NO_AUTONOMY_FILTER", raising=False) + monkeypatch.delenv("PLANFILE_REQUIRE_PROCESS_ENVELOPE", raising=False) + + repo = tmp_path / "repo" + _init_git_repo(repo, remote_slug="semcod/planfile") + pf = Planfile(repo) + now = datetime(2026, 11, 15, 12, 0, 0, tzinfo=timezone.utc) + future_iso = (now + timedelta(hours=1)).isoformat().replace("+00:00", "Z") + + # Satisfied dependency in current sprint + dep_done = pf.create_ticket(name="Completed prerequisite") + pf.complete_ticket(dep_done.id, note="Done") + + # Satisfied dependency archived in history-* sprint + dep_archived = pf.create_ticket(name="Archived prerequisite", sprint="history-2026-10-01") + pf.complete_ticket(dep_archived.id, note="Archived done") + + # Unsatisfied dependency (still open) + dep_open = pf.create_ticket(name="Open blocker", priority="low") + + # Executable candidates across current + backlog (test ordering: high bug > high feature > normal > low) + cand_feature_high = pf.create_ticket( + name="High feature with resolved deps", + priority="high", + blocked_by=[dep_done.id, dep_archived.id], + ) + cand_bug_high = pf.create_ticket( + name="High priority bug", + priority="high", + labels=["bug"], + ) + cand_backlog = pf.create_ticket( + name="Backlog ready task", + priority="normal", + sprint="backlog", + ) + + # Excluded tickets: + # 1. Blocked by open dependency + excl_dep = pf.create_ticket(name="Blocked by open ticket", blocked_by=[dep_open.id]) + # 2.Blocked by missing dependency + excl_missing_dep = pf.create_ticket(name="Blocked by missing", blocked_by=["PLF-99999"]) + # 3. Autonomy / human-gated + excl_frontier = pf.create_ticket(name="Frontier task", labels=["autonomy-frontier"]) + excl_human = pf.create_ticket(name="Human task", labels=["actor:human"]) + excl_waiting = pf.create_ticket(name="Waiting on GPU", labels=["waiting:gpu"]) + # 4. Non-ready execution state (waiting_input) + excl_waiting_input = pf.create_ticket(name="Needs input") + pf.update_ticket( + excl_waiting_input.id, + execution=TicketExecution(state="waiting_input"), + ) + # 5. Non-open status (in_progress & blocked) + excl_in_progress = pf.create_ticket(name="Currently running") + pf.start_ticket(excl_in_progress.id, assigned_to="agent:worker") + excl_blocked_status = pf.create_ticket(name="Explicitly blocked", sprint="backlog") + pf.block_ticket(excl_blocked_status.id, reason="External outage") + # 6. Invalid / unobservable target repository + excl_bad_repo = pf.create_ticket( + name="Missing repo target", + source=TicketSource( + tool="heyasa", + context={"repository": "ghost-org/missing-repo"}, + ), + ) + # 7. Open ticket held by an active non-expired .subactor writer lease + excl_leased = pf.create_ticket(name="Held by live lease", labels=["ticket-050"]) + _write_live_lease(repo, "ticket-050", expires_at=future_iso) + # 8. Open ticket held by live Planfile claim lease + excl_pf_leased = pf.create_ticket(name="Claimed in Planfile") + pf.update_ticket( + excl_pf_leased.id, + execution=TicketExecution( + state="ready", + assigned_to="koru-1", + lease_expires_at=now + timedelta(minutes=30), + ), + ) + # 9. Historical open ghost in history-* sprint must not leak into active queue + ghost_history = pf.create_ticket(name="History ghost", sprint="history-2026-10-01") + + report = pf.executable_queue(now=now, workspace_root=tmp_path) + assert report["schema"] == EXECUTABLE_QUEUE_SCHEMA + assert report["repository"] == "semcod/planfile" + + expected_order = [ + cand_bug_high.id, + cand_feature_high.id, + cand_backlog.id, + dep_open.id, + ] + assert report["candidate_ids"] == expected_order + assert report["counts"]["executable"] == 4 + + skipped_by_id = {item["id"]: item for item in report["skipped"]} + assert skipped_by_id[excl_dep.id]["reason"] == f"blocked_by:{dep_open.id}" + assert skipped_by_id[excl_missing_dep.id]["reason"] == "blocked_by:PLF-99999" + assert skipped_by_id[excl_frontier.id]["reason"] == "autonomy-frontier" + assert skipped_by_id[excl_human.id]["reason"] == "actor:human" + assert skipped_by_id[excl_waiting.id]["reason"] == "waiting:gpu" + assert skipped_by_id[excl_waiting_input.id]["reason"] == "exec_state:waiting_input" + assert skipped_by_id[excl_in_progress.id]["reason"] == "status:in_progress" + assert skipped_by_id[excl_blocked_status.id]["reason"] == "status:blocked" + assert "target_repository_unobserved" in skipped_by_id[excl_bad_repo.id]["reason"] + assert skipped_by_id[excl_leased.id]["reason"] == "active_lease:lease-ticket-050" + assert skipped_by_id[excl_pf_leased.id]["reason"] == f"active_lease:planfile:{excl_pf_leased.id}" + assert ghost_history.id not in skipped_by_id + assert ghost_history.id not in report["candidate_ids"] + + # Direct Python evaluator checks (both Ticket model and raw dict views) + assert is_executable_candidate(cand_bug_high, pf=pf, now=now) is True + assert executable_skip_reason(cand_bug_high, pf=pf, now=now) == "" + assert is_executable_candidate(excl_leased, pf=pf, now=now) is False + + dict_view = { + "id": "RAW-1", + "name": "Raw dict ticket", + "status": "open", + "sprint": "history-2026-09-01", + } + eval_hist = evaluate_executable_candidate(dict_view, repo_path=repo, now=now) + assert eval_hist.executable is False + assert eval_hist.reason == "archived_sprint" + + +def test_fleet_executable_queue_and_cli_json(tmp_path: Path, monkeypatch) -> None: + monkeypatch.delenv("CURRENT_GOAL", raising=False) + monkeypatch.delenv("PLANFILE_NO_AUTONOMY_FILTER", raising=False) + + ws = tmp_path / "github" + repo_one = ws / "semcod" / "one" + repo_two = ws / "heyasa" / "two" + _init_git_repo(repo_one, remote_slug="semcod/one") + _init_git_repo(repo_two, remote_slug="heyasa/two") + + pf_one = Planfile(repo_one) + pf_two = Planfile(repo_two) + + c1 = pf_one.create_ticket(name="Repo one ready", priority="high") + s1 = pf_one.create_ticket(name="Repo one active") + pf_one.start_ticket(s1.id, assigned_to="worker-1") + + c2 = pf_two.create_ticket(name="Repo two ready", priority="critical") + + fleet = fleet_executable_queue(ws) + assert fleet["schema"] == EXECUTABLE_QUEUE_SCHEMA + assert fleet["repositories_scanned"] == 2 + assert fleet["counts"]["executable"] == 2 + assert fleet["counts"]["in_progress"] == 1 + assert fleet["candidate_ids"] == [c2.id, c1.id] + + single = executable_queue(repo_one) + assert single["schema"] == EXECUTABLE_QUEUE_SCHEMA + assert single["candidate_ids"] == [c1.id] + + runner = CliRunner() + root_app = _build_app(ticket_only=False) + ticket_app = _build_app(ticket_only=True) + + res_fleet = runner.invoke( + root_app, + ["executable-queue", "--workspace-root", str(ws), "--fleet", "--format", "json"], + ) + assert res_fleet.exit_code == 0, res_fleet.output + cli_fleet = json.loads(res_fleet.stdout) + assert cli_fleet["schema"] == EXECUTABLE_QUEUE_SCHEMA + assert cli_fleet["candidate_ids"] == [c2.id, c1.id] + + res_ticket = runner.invoke( + ticket_app, + ["ticket", "executable-queue", "--project", str(repo_one), "--format", "json"], + ) + assert res_ticket.exit_code == 0, res_ticket.output + cli_single = json.loads(res_ticket.stdout) + assert cli_single["candidate_ids"] == [c1.id] diff --git a/tests/test_reconcile_in_progress.py b/tests/test_reconcile_in_progress.py new file mode 100644 index 00000000..9b17e684 --- /dev/null +++ b/tests/test_reconcile_in_progress.py @@ -0,0 +1,337 @@ +"""Tests for target-repository-aware ``in_progress`` reconciliation (AUT-14 / #346).""" + +from __future__ import annotations + +import json +import os +import subprocess +from datetime import datetime, timedelta, timezone +from pathlib import Path + +from typer.testing import CliRunner + +from planfile import ( + RECONCILE_REPORT_SCHEMA, + Planfile, + TicketExecution, + TicketSource, + reconcile_fleet_in_progress, + reconcile_in_progress, +) +from planfile.cli.commands import _build_app + + +def _git(cwd: Path, *args: str) -> str: + env = {k: v for k, v in os.environ.items() if not k.startswith("GIT_")} + env["GIT_TERMINAL_PROMPT"] = "0" + env.setdefault("GIT_AUTHOR_NAME", "Test Bot") + env.setdefault("GIT_AUTHOR_EMAIL", "bot@example.com") + env.setdefault("GIT_COMMITTER_NAME", "Test Bot") + env.setdefault("GIT_COMMITTER_EMAIL", "bot@example.com") + proc = subprocess.run( + ["git", "-C", str(cwd), *args], + check=True, + capture_output=True, + text=True, + env=env, + ) + return proc.stdout.strip() + + +def _init_git_repo(repo: Path, remote_slug: str = "semcod/demo") -> str: + repo.mkdir(parents=True, exist_ok=True) + _git(repo, "init", "-b", "main") + _git(repo, "remote", "add", "origin", f"https://github.com/{remote_slug}.git") + (repo / "README.md").write_text("# Demo\n", encoding="utf-8") + _git(repo, "add", "README.md") + _git(repo, "commit", "-m", "Initial commit") + return _git(repo, "rev-parse", "HEAD") + + +def _write_lease( + repo: Path, + filename: str, + *, + ticket_id: str, + phase: str = "editing", + expires_at: str, + owner_actor: str = "agent:codex", + owner_session: str = "session-1", + worktree_id: str | None = None, +) -> None: + leases_dir = repo / ".subactor" / "leases" + leases_dir.mkdir(parents=True, exist_ok=True) + payload = { + "schema": "wellmanifest.change-lease/v1", + "leaseId": f"lease-{ticket_id}", + "repositoryRef": "semcod/demo", + "targetBranch": "main", + "ticketId": ticket_id, + "workstream": "application", + "scopeHash": "a" * 64, + "branchRef": f"refs/heads/ticket/{ticket_id}", + "worktreeId": worktree_id or f"{ticket_id}--work", + "ownerActor": owner_actor, + "ownerSession": owner_session, + "phase": phase, + "leaseRevision": 1, + "fencingToken": 1, + "issuedAt": "2026-11-15T10:00:00Z", + "expiresAt": expires_at, + "heartbeatAt": "2026-11-15T10:00:00Z", + "headSha": "b" * 40, + "pullRequest": None, + "validatorRunId": None, + "publicationFrozen": False, + "planHash": "c" * 64, + "previousReceiptRef": None, + "eventSequence": 1, + } + (leases_dir / filename).write_text(json.dumps(payload), encoding="utf-8") + + +def test_reconcile_merged_terminal_receipt_closes_ticket_with_evidence(tmp_path: Path) -> None: + repo = tmp_path / "repo" + _init_git_repo(repo) + pf = Planfile(repo) + ticket = pf.create_ticket(name="Ship feature", labels=["ticket-010"]) + pf.start_ticket(ticket.id, assigned_to="agent:worker") + + # Simulate merged commit on main + terminal receipt + ticket_dir = repo / "project" / "ticket-010" + ticket_dir.mkdir(parents=True) + (ticket_dir / "README.md").write_text( + f"# Ticket 010\n\n- **Planfile**: {ticket.id}\n", + encoding="utf-8", + ) + _git(repo, "add", "project/ticket-010/README.md") + _git(repo, "commit", "-m", "Merge ticket-010") + merged_sha = _git(repo, "rev-parse", "HEAD") + + receipts_dir = repo / ".git" / "new-project" + receipts_dir.mkdir(parents=True, exist_ok=True) + (receipts_dir / "terminal-receipts.json").write_text( + json.dumps( + { + "schema": "new-project.terminal-receipt-registry/v1", + "receipts": [ + { + "ticket": "ticket-010", + "outcome": "merged", + "headSha": merged_sha, + "terminalSha": merged_sha, + "targetBranch": "main", + "receiptRef": "receipt:github-pr:semcod/demo:42", + } + ], + } + ), + encoding="utf-8", + ) + + # Dry-run by default: reports merged -> done without mutating storage + dry_report = reconcile_in_progress(pf) + assert dry_report["schema"] == RECONCILE_REPORT_SCHEMA + assert dry_report["mode"] == "dry_run" + assert dry_report["counts"]["merged_to_done"] == 1 + assert dry_report["counts"]["applied"] == 0 + decision = dry_report["decisions"][0] + assert decision["classification"] == "merged" + assert decision["proposed_status"] == "done" + assert decision["terminalReceiptRef"] == "receipt:github-pr:semcod/demo:42" + assert decision["terminalSha"] == merged_sha + assert pf.get_ticket(ticket.id).status.value == "in_progress" + + # --apply mutates atomically and records merge receipt evidence + apply_report = pf.reconcile_in_progress(apply=True) + assert apply_report["mode"] == "apply" + assert apply_report["counts"]["merged_to_done"] == 1 + assert apply_report["counts"]["applied"] == 1 + + closed = pf.get_ticket(ticket.id) + assert closed is not None + assert closed.status.value == "done" + assert closed.execution is not None and closed.execution.state == "done" + assert closed.outputs is not None and closed.outputs.completion_receipt is not None + assert closed.outputs.completion_receipt["terminalReceiptRef"] == "receipt:github-pr:semcod/demo:42" + assert closed.outputs.completion_receipt["terminalSha"] == merged_sha + + +def test_reconcile_rejects_unverified_non_ancestor_terminal_sha(tmp_path: Path) -> None: + repo = tmp_path / "repo" + _init_git_repo(repo) + pf = Planfile(repo) + ticket = pf.create_ticket(name="Unmerged branch work", labels=["ticket-011"]) + pf.start_ticket(ticket.id, assigned_to="agent:worker") + + # Create commit on an unmerged side branch, NOT on main + _git(repo, "checkout", "-b", "side-work") + (repo / "side.txt").write_text("unmerged\n", encoding="utf-8") + _git(repo, "add", "side.txt") + _git(repo, "commit", "-m", "Side commit") + side_sha = _git(repo, "rev-parse", "HEAD") + _git(repo, "checkout", "main") + + receipts_dir = repo / ".git" / "new-project" + receipts_dir.mkdir(parents=True, exist_ok=True) + (receipts_dir / "terminal-receipts.json").write_text( + json.dumps( + { + "schema": "new-project.terminal-receipt-registry/v1", + "receipts": [ + { + "ticket": "ticket-011", + "outcome": "merged", + "headSha": side_sha, + "terminalSha": side_sha, + "targetBranch": "main", + "receiptRef": "receipt:forged:99", + } + ], + } + ), + encoding="utf-8", + ) + + report = reconcile_in_progress(pf, apply=True) + assert report["counts"]["merged_to_done"] == 0 + assert report["counts"]["abandoned_to_open"] == 1 + reopened = pf.get_ticket(ticket.id) + assert reopened is not None and reopened.status.value == "open" + + +def test_reconcile_live_lease_and_active_worktree_vs_abandoned(tmp_path: Path) -> None: + repo = tmp_path / "repo" + base_sha = _init_git_repo(repo) + now = datetime(2026, 11, 15, 12, 0, 0, tzinfo=timezone.utc) + future_iso = (now + timedelta(hours=1)).isoformat().replace("+00:00", "Z") + past_iso = (now - timedelta(hours=2)).isoformat().replace("+00:00", "Z") + + pf = Planfile(repo) + + # 1. Ticket bound to a live non-expired .subactor lease -> stays in_progress + t_leased = pf.create_ticket(name="Leased work", labels=["ticket-020"]) + pf.start_ticket(t_leased.id, assigned_to="agent:codex") + _write_lease( + repo, + "ticket-020--leased.json", + ticket_id="ticket-020", + expires_at=future_iso, + owner_actor="agent:codex", + ) + + # 2. Ticket with expired lease BUT dirty canonical worktree -> stays in_progress + t_worktree = pf.create_ticket(name="Dirty worktree work", labels=["ticket-021"]) + pf.start_ticket(t_worktree.id, assigned_to="agent:codex") + _write_lease( + repo, + "ticket-021--dirty.json", + ticket_id="ticket-021", + expires_at=past_iso, + owner_actor="agent:codex", + ) + wt_path = repo / ".worktrees" / "ticket-021--dirty" + _git(repo, "worktree", "add", "-b", "ticket/021-dirty", str(wt_path), base_sha) + (wt_path / "wip.py").write_text("x = 1\n", encoding="utf-8") + + # 3. Abandoned ticket (same generic actor 'agent:codex', but no bound lease/worktree!) + t_abandoned = pf.create_ticket(name="Abandoned work") + pf.start_ticket(t_abandoned.id, assigned_to="agent:codex") + + # Dry-run first + dry = reconcile_in_progress(pf, now=now) + assert dry["counts"]["active_retained"] == 2 + assert dry["counts"]["abandoned_to_open"] == 1 + assert pf.get_ticket(t_abandoned.id).status.value == "in_progress" + + # Apply + applied = reconcile_in_progress(pf, apply=True, now=now) + assert applied["counts"]["active_retained"] == 2 + assert applied["counts"]["abandoned_to_open"] == 1 + assert applied["counts"]["applied"] == 1 + + assert pf.get_ticket(t_leased.id).status.value == "in_progress" + assert pf.get_ticket(t_worktree.id).status.value == "in_progress" + + reopened = pf.get_ticket(t_abandoned.id) + assert reopened is not None + assert reopened.status.value == "open" + assert reopened.execution is not None + assert reopened.execution.state == "ready" + assert reopened.execution.assigned_to is None + assert reopened.execution.lease_expires_at is None + assert reopened.execution.started_at is None + + +def test_reconcile_preserves_unobserved_target_repositories(tmp_path: Path) -> None: + # Case A: Git repo with a ticket referencing an unobservable external repo + repo = tmp_path / "repo" + _init_git_repo(repo) + pf = Planfile(repo) + t_external = pf.create_ticket( + name="Remote repo ticket", + source=TicketSource( + tool="heyasa", + context={"repository": "other-org/missing-local-checkout"}, + ), + ) + pf.start_ticket(t_external.id, assigned_to="agent:remote") + + report = reconcile_in_progress(pf, apply=True, workspace_root=tmp_path) + assert report["counts"]["unobserved_preserved"] == 1 + assert report["counts"]["applied"] == 0 + assert report["decisions"][0]["classification"] == "unobserved" + assert pf.get_ticket(t_external.id).status.value == "in_progress" + + # Case B: Non-git directory cannot observe worktrees/receipts -> preserved as unobserved + non_git = tmp_path / "non_git_project" + non_git.mkdir() + pf_non_git = Planfile(non_git) + t_local = pf_non_git.create_ticket(name="Non-git in_progress") + pf_non_git.start_ticket(t_local.id, assigned_to="agent:local") + + ng_report = reconcile_in_progress(pf_non_git, apply=True) + assert ng_report["counts"]["unobserved_preserved"] == 1 + assert pf_non_git.get_ticket(t_local.id).status.value == "in_progress" + + +def test_reconcile_cli_and_fleet_json(tmp_path: Path) -> None: + ws = tmp_path / "workspace" + repo_a = ws / "semcod" / "alpha" + _init_git_repo(repo_a, remote_slug="semcod/alpha") + pf_a = Planfile(repo_a) + t1 = pf_a.create_ticket(name="Stale alpha task") + pf_a.update_ticket( + t1.id, + status="in_progress", + execution=TicketExecution(state="running", assigned_to="old-worker"), + ) + + runner = CliRunner() + root_app = _build_app(ticket_only=False) + ticket_only_app = _build_app(ticket_only=True) + + res_dry = runner.invoke( + root_app, + ["reconcile", "--project", str(repo_a), "--format", "json"], + ) + assert res_dry.exit_code == 0, res_dry.output + payload_dry = json.loads(res_dry.stdout) + assert payload_dry["mode"] == "dry_run" + assert payload_dry["counts"]["abandoned_to_open"] == 1 + assert pf_a.get_ticket(t1.id).status.value == "in_progress" + + res_apply = runner.invoke( + ticket_only_app, + ["ticket", "reconcile", "--project", str(repo_a), "--apply", "--format", "json"], + ) + assert res_apply.exit_code == 0, res_apply.output + payload_apply = json.loads(res_apply.stdout) + assert payload_apply["mode"] == "apply" + assert payload_apply["counts"]["applied"] == 1 + assert pf_a.get_ticket(t1.id).status.value == "open" + + # Fleet reconciliation check + fleet_report = reconcile_fleet_in_progress(ws, apply=False) + assert fleet_report["counts"]["repositories_scanned"] == 1 + assert fleet_report["counts"]["scanned_in_progress"] == 0