draft-board 0.1.0-beta.0

package/app/backend/app/schemas/review.py

@@ -0,0 +1,137 @@
+"""Pydantic schemas for Review entities (comments and summaries)."""
+
+from datetime import datetime
+from enum import StrEnum
+
+from pydantic import BaseModel, Field
+
+
+class AuthorType(StrEnum):
+    """Enum representing the type of author for a review comment."""
+
+    HUMAN = "human"
+    AGENT = "agent"
+    SYSTEM = "system"
+
+
+class ReviewDecision(StrEnum):
+    """Enum representing the review decision."""
+
+    APPROVED = "approved"
+    CHANGES_REQUESTED = "changes_requested"
+
+
+# Review Comment Schemas
+
+
+class ReviewCommentCreate(BaseModel):
+    """Schema for creating a review comment."""
+
+    file_path: str = Field(..., min_length=1, max_length=500)
+    line_number: int = Field(..., ge=1)
+    body: str = Field(..., min_length=1)
+    author_type: AuthorType = Field(default=AuthorType.HUMAN)
+    # Optional: client can provide hunk_header for anchor calculation
+    hunk_header: str | None = Field(
+        None,
+        description="Diff hunk header (e.g., '@@ -10,5 +10,7 @@') for anchor stability",
+    )
+    line_content: str | None = Field(
+        None, description="Content of the line being commented on for anchor stability"
+    )
+
+
+class ReviewCommentResponse(BaseModel):
+    """Schema for review comment response."""
+
+    id: str
+    revision_id: str
+    file_path: str
+    line_number: int
+    anchor: str
+    body: str
+    author_type: AuthorType
+    resolved: bool
+    created_at: datetime
+    line_content: str | None = None
+
+    model_config = {"from_attributes": True}
+
+
+class ReviewCommentListResponse(BaseModel):
+    """Schema for list of review comments."""
+
+    comments: list[ReviewCommentResponse]
+    total: int
+    unresolved_count: int
+
+
+# Review Summary Schemas
+
+
+class ReviewSubmit(BaseModel):
+    """Schema for submitting a review decision."""
+
+    decision: ReviewDecision
+    summary: str = Field(
+        default="", description="High-level review feedback (optional)"
+    )
+    auto_run_fix: bool = Field(
+        default=True,
+        description="If changes_requested, automatically trigger new agent execution",
+    )
+    create_pr: bool = Field(
+        default=False,
+        description="If approved, create a GitHub PR instead of merging directly to main",
+    )
+
+
+class ReviewSummaryResponse(BaseModel):
+    """Schema for review summary response."""
+
+    id: str
+    revision_id: str
+    decision: ReviewDecision
+    body: str
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+# Feedback Bundle Schema
+
+
+class FeedbackComment(BaseModel):
+    """Schema for a comment in the feedback bundle."""
+
+    file_path: str
+    line_number: int
+    anchor: str
+    body: str
+    line_content: str | None = Field(
+        default=None,
+        description="Content of the line being commented on, helps agent locate the issue",
+    )
+    orphaned: bool = Field(
+        default=False,
+        description="True if this comment's anchor cannot be found in the current diff",
+    )
+
+
+class FeedbackBundle(BaseModel):
+    """Schema for the feedback bundle sent to the agent.
+
+    This is the structured feedback that gets injected into the agent prompt
+    when creating a new revision after changes are requested.
+    """
+
+    ticket_id: str
+    revision_id: str
+    revision_number: int
+    decision: str
+    summary: str
+    comments: list[FeedbackComment]
+    orphaned_comment_count: int = Field(
+        default=0,
+        description="Number of comments that could not be anchored to the current diff",
+    )

package/app/backend/app/schemas/revision.py

@@ -0,0 +1,114 @@
+"""Pydantic schemas for Revision entity."""
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+# Import RevisionStatus from models to avoid duplication
+from app.models.revision import RevisionStatus
+
+
+class RevisionResponse(BaseModel):
+    """Schema for revision response."""
+
+    id: str
+    ticket_id: str
+    job_id: str
+    number: int
+    status: RevisionStatus
+    diff_stat_evidence_id: str | None
+    diff_patch_evidence_id: str | None
+    created_at: datetime
+    unresolved_comment_count: int = Field(
+        default=0, description="Number of unresolved review comments"
+    )
+
+    model_config = {"from_attributes": True}
+
+
+class RevisionDetailResponse(RevisionResponse):
+    """Schema for detailed revision response with diff content."""
+
+    diff_stat: str | None = Field(None, description="Git diff stat output")
+    diff_patch: str | None = Field(None, description="Full git diff patch")
+
+
+class RevisionListResponse(BaseModel):
+    """Schema for list of revisions."""
+
+    revisions: list[RevisionResponse]
+    total: int
+
+
+class RevisionDiffResponse(BaseModel):
+    """Schema for revision diff content (both stat and patch - heavyweight)."""
+
+    revision_id: str
+    diff_stat: str | None = Field(None, description="Git diff stat output")
+    diff_patch: str | None = Field(None, description="Full git diff patch")
+    files: list["DiffFile"] = Field(
+        default_factory=list, description="Parsed diff files"
+    )
+
+
+class DiffSummaryResponse(BaseModel):
+    """Schema for lightweight diff summary (stat + file list only).
+
+    Use this endpoint for initial load - no heavy patch content.
+    """
+
+    revision_id: str
+    diff_stat: str | None = Field(None, description="Git diff stat output")
+    files: list["DiffFile"] = Field(
+        default_factory=list, description="Parsed diff files"
+    )
+
+
+class DiffPatchResponse(BaseModel):
+    """Schema for heavyweight diff patch content.
+
+    Only fetch this when user actually opens the diff viewer.
+    """
+
+    revision_id: str
+    diff_patch: str | None = Field(None, description="Full git diff patch")
+
+
+class DiffFile(BaseModel):
+    """Schema for a single file in the diff."""
+
+    path: str
+    old_path: str | None = None
+    additions: int = 0
+    deletions: int = 0
+    status: str = Field(
+        default="modified",
+        description="File status: added, deleted, modified, renamed",
+    )
+
+
+class TimelineEvent(BaseModel):
+    """Schema for a single event in the revision timeline."""
+
+    id: str
+    event_type: str = Field(
+        description="Event type: revision_created, comment_added, review_submitted, job_queued, job_completed"
+    )
+    actor: str = Field(description="Who triggered this event (human, agent, system)")
+    message: str = Field(description="Human-readable description of the event")
+    created_at: datetime
+    metadata: dict | None = Field(
+        default=None, description="Additional event-specific data"
+    )
+
+
+class RevisionTimelineResponse(BaseModel):
+    """Schema for revision timeline (audit trail of events)."""
+
+    revision_id: str
+    events: list[TimelineEvent]
+
+
+# For forward reference
+RevisionDiffResponse.model_rebuild()
+DiffSummaryResponse.model_rebuild()

package/app/backend/app/schemas/ticket.py

@@ -0,0 +1,238 @@
+"""Pydantic schemas for Ticket entity."""
+
+from datetime import datetime
+
+from pydantic import BaseModel, Field
+
+from app.state_machine import ActorType, TicketState
+
+
+class TicketCreate(BaseModel):
+    """Schema for creating a new ticket."""
+
+    goal_id: str = Field(..., description="UUID of the parent goal")
+    title: str = Field(..., min_length=1, max_length=255)
+    description: str | None = None
+    priority: int | None = Field(None, ge=0, le=100)
+    blocked_by_ticket_id: str | None = Field(
+        None,
+        description="UUID of a ticket that blocks this one. This ticket cannot be executed until the blocker is DONE.",
+    )
+    actor_type: ActorType = Field(
+        default=ActorType.HUMAN,
+        description="Type of actor creating the ticket",
+    )
+    actor_id: str | None = Field(
+        None, description="ID of the actor creating the ticket"
+    )
+
+
+class TicketUpdate(BaseModel):
+    """Schema for updating an existing ticket."""
+
+    title: str | None = Field(None, min_length=1, max_length=255)
+    description: str | None = None
+    priority: int | None = Field(None, ge=0, le=100)
+
+
+class TicketResponse(BaseModel):
+    """Schema for ticket response."""
+
+    id: str
+    goal_id: str
+    title: str
+    description: str | None
+    state: TicketState
+    priority: int | None
+    sort_order: int | None = Field(
+        None, description="Manual sort order within state column"
+    )
+    blocked_by_ticket_id: str | None = Field(
+        None, description="UUID of ticket blocking this one"
+    )
+    blocked_by_ticket_title: str | None = Field(
+        None, description="Title of the ticket blocking this one (if loaded)"
+    )
+    goal_title: str | None = Field(
+        None, description="Title of the parent goal (if loaded)"
+    )
+    created_at: datetime
+    updated_at: datetime
+
+    model_config = {"from_attributes": True}
+
+
+class TicketDetailResponse(TicketResponse):
+    """Schema for detailed ticket response with additional context."""
+
+    goal_title: str | None = None
+    goal_description: str | None = None
+    priority_label: str | None = None
+    state_display: str
+    blocked_by_ticket_title: str | None = Field(
+        None, description="Title of the ticket blocking this one"
+    )
+    is_blocked: bool = Field(
+        False, description="True if this ticket is blocked by an incomplete dependency"
+    )
+
+    @staticmethod
+    def get_priority_label(priority: int | None) -> str | None:
+        """Convert numeric priority to human-readable label."""
+        if priority is None:
+            return None
+        if priority >= 80:
+            return "High"
+        elif priority >= 50:
+            return "Medium"
+        elif priority >= 20:
+            return "Low"
+        else:
+            return "Very Low"
+
+    @staticmethod
+    def get_state_display(state: TicketState) -> str:
+        """Convert state enum to human-readable display text."""
+        display_map = {
+            TicketState.PROPOSED: "Proposed",
+            TicketState.PLANNED: "Planned",
+            TicketState.EXECUTING: "Executing",
+            TicketState.VERIFYING: "Verifying",
+            TicketState.NEEDS_HUMAN: "Needs Human",
+            TicketState.BLOCKED: "Blocked",
+            TicketState.DONE: "Done",
+            TicketState.ABANDONED: "Abandoned",
+        }
+        return display_map.get(state, state.value.title())
+
+
+class TicketTransition(BaseModel):
+    """Schema for requesting a ticket state transition."""
+
+    to_state: TicketState = Field(..., description="Target state for the transition")
+    actor_type: ActorType = Field(
+        ..., description="Type of actor performing the transition"
+    )
+    actor_id: str | None = Field(
+        None, description="ID of the actor performing the transition"
+    )
+    reason: str | None = Field(None, description="Reason for the state transition")
+
+
+class TicketWithGoal(TicketResponse):
+    """Schema for ticket response including goal information."""
+
+    goal_title: str | None = None
+
+
+class TicketsByState(BaseModel):
+    """Schema for tickets grouped by state."""
+
+    state: TicketState
+    tickets: list[TicketResponse]
+
+
+class BoardResponse(BaseModel):
+    """Schema for the board view - tickets grouped by state."""
+
+    columns: list[TicketsByState]
+    total_tickets: int
+
+
+class BulkAcceptRequest(BaseModel):
+    """Schema for bulk accepting proposed tickets."""
+
+    ticket_ids: list[str] = Field(
+        ..., min_length=1, description="List of ticket IDs to accept"
+    )
+    goal_id: str | None = Field(
+        None,
+        description="If provided, validates all tickets belong to this goal",
+    )
+    actor_type: ActorType = Field(
+        default=ActorType.HUMAN, description="Actor performing the accept"
+    )
+    actor_id: str | None = Field(None, description="ID of the actor")
+    reason: str | None = Field(
+        default="Accepted from AI-generated proposal",
+        description="Reason for acceptance",
+    )
+    queue_first: bool = Field(
+        default=False,
+        description="If true, queue the first accepted ticket for execution",
+    )
+
+
+class BulkAcceptResult(BaseModel):
+    """Result for a single ticket in bulk accept."""
+
+    ticket_id: str
+    success: bool
+    error: str | None = None
+
+
+class BulkAcceptResponse(BaseModel):
+    """Response for bulk accept operation."""
+
+    accepted_ids: list[str] = Field(default_factory=list)
+    rejected: list[BulkAcceptResult] = Field(default_factory=list)
+    accepted_count: int
+    failed_count: int
+    queued_job_id: str | None = Field(
+        None,
+        description="Job ID if queue_first was true and first ticket was queued",
+    )
+    queued_ticket_id: str | None = Field(
+        None,
+        description="Ticket ID that was queued (first in request order)",
+    )
+
+
+class BulkTransitionRequest(BaseModel):
+    """Schema for bulk state transition of multiple tickets."""
+
+    ticket_ids: list[str] = Field(
+        ..., min_length=1, description="List of ticket IDs to transition"
+    )
+    target_state: TicketState = Field(..., description="Target state for all tickets")
+    reason: str = Field(
+        default="Bulk transition",
+        description="Reason for the state transition",
+    )
+    actor_type: ActorType = Field(
+        default=ActorType.HUMAN,
+        description="Type of actor performing the transition",
+    )
+    actor_id: str | None = Field(
+        None, description="ID of the actor performing the transition"
+    )
+
+
+class BulkTransitionResult(BaseModel):
+    """Result for a single ticket in a bulk transition."""
+
+    ticket_id: str
+    success: bool
+    error: str | None = None
+    from_state: str | None = None
+    to_state: str | None = None
+
+
+class BulkTransitionResponse(BaseModel):
+    """Response for bulk state transition operation."""
+
+    results: list[BulkTransitionResult]
+    transitioned_count: int
+    failed_count: int
+
+
+class TicketReorderRequest(BaseModel):
+    """Schema for reordering a ticket within a column."""
+
+    ticket_id: str = Field(..., description="Ticket ID to reorder")
+    new_index: int = Field(
+        ..., ge=0, description="New position index (0-based) within the column"
+    )
+    column_state: TicketState = Field(
+        ..., description="State column in which to reorder"
+    )

package/app/backend/app/schemas/ticket_event.py

@@ -0,0 +1,72 @@
+"""Pydantic schemas for TicketEvent entity."""
+
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel, computed_field
+
+from app.state_machine import ActorType, EventType, TicketState
+
+
+class TicketEventResponse(BaseModel):
+    """Schema for ticket event response."""
+
+    id: str
+    ticket_id: str
+    event_type: EventType
+    from_state: TicketState | None
+    to_state: TicketState | None
+    actor_type: ActorType
+    actor_id: str | None
+    reason: str | None
+    payload: dict[str, Any] | None
+    created_at: datetime
+
+    model_config = {"from_attributes": True}
+
+    @computed_field
+    @property
+    def event_type_display(self) -> str:
+        """Human-readable event type."""
+        display_map = {
+            EventType.CREATED: "Created",
+            EventType.TRANSITIONED: "Transitioned",
+            EventType.UPDATED: "Updated",
+            EventType.COMMENT: "Comment",
+        }
+        return display_map.get(self.event_type, self.event_type.value.title())
+
+    @computed_field
+    @property
+    def actor_type_display(self) -> str:
+        """Human-readable actor type."""
+        display_map = {
+            ActorType.HUMAN: "Human",
+            ActorType.PLANNER: "AI Planner",
+            ActorType.EXECUTOR: "AI Executor",
+            ActorType.SYSTEM: "System",
+        }
+        return display_map.get(self.actor_type, self.actor_type.value.title())
+
+    @computed_field
+    @property
+    def from_state_display(self) -> str | None:
+        """Human-readable from state."""
+        if self.from_state is None:
+            return None
+        return self.from_state.value.replace("_", " ").title()
+
+    @computed_field
+    @property
+    def to_state_display(self) -> str | None:
+        """Human-readable to state."""
+        if self.to_state is None:
+            return None
+        return self.to_state.value.replace("_", " ").title()
+
+
+class TicketEventListResponse(BaseModel):
+    """Schema for list of ticket events response."""
+
+    events: list[TicketEventResponse]
+    total: int

package/app/backend/app/schemas/workspace.py

@@ -0,0 +1,19 @@
+"""Pydantic schemas for Workspace API responses."""
+
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+
+class WorkspaceResponse(BaseModel):
+    """Response model for workspace information."""
+
+    model_config = ConfigDict(from_attributes=True)
+
+    id: str
+    ticket_id: str
+    worktree_path: str
+    branch_name: str
+    created_at: datetime
+    cleaned_up_at: datetime | None = None
+    is_active: bool

package/app/backend/app/services/__init__.py

@@ -0,0 +1,31 @@
+"""Service layer for Draft business logic."""
+
+from app.services.board_service import BoardService
+from app.services.cleanup_service import CleanupService
+from app.services.context_gatherer import ContextGatherer
+from app.services.goal_service import GoalService
+from app.services.job_service import JobService
+from app.services.llm_service import LLMService
+from app.services.merge_service import MergeService
+from app.services.planner_service import PlannerService
+from app.services.review_service import ReviewService
+from app.services.revision_service import RevisionService
+from app.services.ticket_generation_service import TicketGenerationService
+from app.services.ticket_service import TicketService
+from app.services.workspace_service import WorkspaceService
+
+__all__ = [
+    "BoardService",
+    "CleanupService",
+    "ContextGatherer",
+    "GoalService",
+    "JobService",
+    "LLMService",
+    "MergeService",
+    "PlannerService",
+    "ReviewService",
+    "RevisionService",
+    "TicketGenerationService",
+    "TicketService",
+    "WorkspaceService",
+]