fix(goal): close research goal lifecycle

Author: warren618

agent/api_server.py

@@ -27,6 +27,7 @@
 from fastapi.middleware.cors import CORSMiddleware
 from rich.console import Console
 
+from src.goal.context import default_goal_criteria
 from src.ui_services import build_run_analysis, load_run_context
 
 # UTF-8 on Windows
@@ -251,6 +252,15 @@ class CreateGoalRequest(BaseModel):
     time_budget_seconds: Optional[int] = Field(None, ge=1)
 
 
+class UpdateGoalRequest(BaseModel):
+    """Edit mutable finance research goal fields."""
+
+    goal_id: str = Field(..., min_length=1)
+    expected_goal_id: str = Field(..., min_length=1)
+    objective: Optional[str] = Field(None, min_length=1, max_length=5000)
+    ui_summary: Optional[str] = Field(None, max_length=500)
+
+
 class AddGoalEvidenceRequest(BaseModel):
     """Append evidence to a finance research goal."""
 
@@ -295,6 +305,39 @@ class AddGoalEvidenceResponse(BaseModel):
     snapshot: GoalSnapshotResponse
 
 
+class GoalAuditRowRequest(BaseModel):
+    """One criterion row for goal status audits."""
+
+    criterion_id: str = Field(..., min_length=1)
+    result: str = Field(..., min_length=1)
+    evidence_ids: List[str] = Field(default_factory=list)
+    notes: str = ""
+
+
+class UpdateGoalStatusRequest(BaseModel):
+    """Update a finance research goal status."""
+
+    goal_id: str = Field(..., min_length=1)
+    expected_goal_id: str = Field(..., min_length=1)
+    status: str = Field(..., min_length=1)
+    audit: List[GoalAuditRowRequest] = Field(default_factory=list)
+    recap: Optional[str] = None
+
+
+class UpdateGoalStatusResponse(BaseModel):
+    """Response after changing a goal status."""
+
+    goal: Dict[str, Any]
+    snapshot: GoalSnapshotResponse
+
+
+class UpdateGoalResponse(BaseModel):
+    """Response after editing a goal."""
+
+    goal: Dict[str, Any]
+    snapshot: GoalSnapshotResponse
+
+
 
 # ============================================================================
 # FastAPI Application
@@ -1502,7 +1545,7 @@ async def create_session_goal(session_id: str, req: CreateGoalRequest):
 
     criteria = [item.strip() for item in req.criteria if item.strip()]
     if not criteria:
-        criteria = ["Define research thesis", "Record at least one supporting or contradicting evidence row"]
+        criteria = default_goal_criteria()
     try:
         risk_tier = RiskTier(req.risk_tier)
     except ValueError as exc:
@@ -1548,6 +1591,41 @@ async def get_session_goal(session_id: str):
     return snapshot
 
 
+@app.patch(
+    "/sessions/{session_id}/goal",
+    response_model=UpdateGoalResponse,
+    dependencies=[Depends(require_auth)],
+)
+async def update_session_goal(session_id: str, req: UpdateGoalRequest):
+    """Edit the current finance research goal without replacing the session."""
+    _validate_path_param(session_id, "session_id")
+    svc, _session = _get_existing_session_or_404(session_id)
+    from src.goal import StaleGoalError
+
+    if req.objective is None and req.ui_summary is None:
+        raise HTTPException(status_code=400, detail="objective or ui_summary is required")
+
+    goal_store = _get_goal_store()
+    try:
+        goal = goal_store.update_goal(
+            session_id=session_id,
+            goal_id=req.goal_id,
+            expected_goal_id=req.expected_goal_id,
+            objective=req.objective,
+            ui_summary=req.ui_summary,
+        )
+    except StaleGoalError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    snapshot = goal_store.get_goal_snapshot(goal.goal_id)
+    if snapshot is None:
+        raise HTTPException(status_code=500, detail="Goal snapshot could not be reloaded")
+    svc.event_bus.emit(session_id, "goal.updated", {"goal": snapshot["goal"], "snapshot": snapshot})
+    return {"goal": snapshot["goal"], "snapshot": snapshot}
+
+
 @app.post(
     "/sessions/{session_id}/goal/evidence",
     response_model=AddGoalEvidenceResponse,
@@ -1606,6 +1684,52 @@ async def add_session_goal_evidence(session_id: str, req: AddGoalEvidenceRequest
     return {"evidence": asdict(evidence), "snapshot": snapshot}
 
 
+@app.patch(
+    "/sessions/{session_id}/goal/status",
+    response_model=UpdateGoalStatusResponse,
+    dependencies=[Depends(require_auth)],
+)
+async def update_session_goal_status(session_id: str, req: UpdateGoalStatusRequest):
+    """Update the current finance research goal status."""
+    _validate_path_param(session_id, "session_id")
+    svc, _session = _get_existing_session_or_404(session_id)
+    from src.goal import AuditRow, GoalStatus, StaleGoalError
+
+    try:
+        next_status = GoalStatus(req.status)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=f"invalid goal status: {req.status}") from exc
+
+    goal_store = _get_goal_store()
+    try:
+        goal = goal_store.update_status(
+            session_id=session_id,
+            goal_id=req.goal_id,
+            expected_goal_id=req.expected_goal_id,
+            status=next_status,
+            audit=[
+                AuditRow(
+                    criterion_id=row.criterion_id,
+                    result=row.result,
+                    evidence_ids=row.evidence_ids,
+                    notes=row.notes,
+                )
+                for row in req.audit
+            ],
+            recap=req.recap,
+        )
+    except StaleGoalError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+
+    snapshot = goal_store.get_goal_snapshot(goal.goal_id)
+    if snapshot is None:
+        raise HTTPException(status_code=500, detail="Goal snapshot could not be reloaded")
+    svc.event_bus.emit(session_id, "goal.updated", {"goal": snapshot["goal"], "snapshot": snapshot})
+    return {"goal": snapshot["goal"], "snapshot": snapshot}
+
+
 @app.delete("/sessions/{session_id}", dependencies=[Depends(require_auth)])
 async def delete_session(session_id: str):
     """Delete a session."""

agent/cli/commands/goal.py

@@ -13,6 +13,7 @@
 from rich.text import Text
 
 from cli.theme import get_console
+from src.goal.context import default_goal_criteria
 
 _goal_store = None
 
@@ -34,11 +35,7 @@ def _get_goal_store():
 
 def _default_criteria() -> list[str]:
     """Return the MVP finance protocol checklist."""
-    return [
-        "Define the research-only thesis and symbol universe",
-        "Collect fresh market or benchmark evidence",
-        "Record caveats, contradictions, and non-advice boundary",
-    ]
+    return default_goal_criteria()
 
 
 def _criterion_is_covered(criterion: dict, evidence: list[dict]) -> bool:
@@ -263,6 +260,98 @@ def cmd_evidence(ctx: Any = None, *args: str) -> int:
     return 0
 
 
+def cmd_cancel(ctx: Any = None, *args: str) -> int:
+    """Cancel the current research goal."""
+    session_id = _session_id(ctx, create=False)
+    if session_id is None:
+        _resolve_console().print(Text("No current goal. Use /goal <objective> first.", style="dim"))
+        return 0
+    snapshot = _get_goal_store().get_current_snapshot(session_id)
+    if snapshot is None:
+        _resolve_console().print(Text("No current goal. Use /goal <objective> first.", style="dim"))
+        return 0
+
+    recap = " ".join(args).strip() or "Cancelled from CLI."
+    try:
+        from src.goal import GoalStatus
+
+        updated = _get_goal_store().update_status(
+            session_id=session_id,
+            goal_id=snapshot["goal"]["goal_id"],
+            expected_goal_id=snapshot["goal"]["goal_id"],
+            status=GoalStatus.CANCELLED,
+            recap=recap,
+        )
+    except Exception as exc:  # noqa: BLE001
+        _resolve_console().print(Text(f"/goal cancel failed: {exc}", style="bold red"))
+        return 1
+
+    terminal_snapshot = _get_goal_store().get_goal_snapshot(updated.goal_id)
+    if terminal_snapshot is not None:
+        _render_snapshot(terminal_snapshot, title="/goal cancelled")
+    return 0
+
+
+def cmd_complete(ctx: Any = None, *args: str) -> int:  # noqa: ARG001
+    """Complete the current research goal after auditing verified evidence."""
+    session_id = _session_id(ctx, create=False)
+    if session_id is None:
+        _resolve_console().print(Text("No current goal. Use /goal <objective> first.", style="dim"))
+        return 0
+    snapshot = _get_goal_store().get_current_snapshot(session_id)
+    if snapshot is None:
+        _resolve_console().print(Text("No current goal. Use /goal <objective> first.", style="dim"))
+        return 0
+
+    evidence = snapshot.get("evidence") or []
+    audit_rows = []
+    for criterion in snapshot.get("criteria") or []:
+        criterion_evidence = [
+            item
+            for item in evidence
+            if item.get("criterion_id") == criterion["criterion_id"]
+            and item.get("verification_status") == "verified"
+        ]
+        if not criterion_evidence:
+            _resolve_console().print(
+                Text(
+                    "Cannot complete: every criterion needs verified run/artifact evidence.",
+                    style="bold red",
+                )
+            )
+            return 1
+        from src.goal import AuditRow
+
+        audit_rows.append(
+            AuditRow(
+                criterion_id=criterion["criterion_id"],
+                result="satisfied",
+                evidence_ids=[item["evidence_id"] for item in criterion_evidence],
+                notes="Verified evidence attached from CLI audit.",
+            )
+        )
+
+    try:
+        from src.goal import GoalStatus
+
+        updated = _get_goal_store().update_status(
+            session_id=session_id,
+            goal_id=snapshot["goal"]["goal_id"],
+            expected_goal_id=snapshot["goal"]["goal_id"],
+            status=GoalStatus.COMPLETE,
+            audit=audit_rows,
+            recap=" ".join(args).strip() or "Completed from CLI audit.",
+        )
+    except Exception as exc:  # noqa: BLE001
+        _resolve_console().print(Text(f"/goal complete failed: {exc}", style="bold red"))
+        return 1
+
+    terminal_snapshot = _get_goal_store().get_goal_snapshot(updated.goal_id)
+    if terminal_snapshot is not None:
+        _render_snapshot(terminal_snapshot, title="/goal completed")
+    return 0
+
+
 def cmd_help() -> int:
     """Render /goal usage."""
     body = Text()
@@ -272,6 +361,10 @@ def cmd_help() -> int:
     body.append("  show the current goal snapshot\n", style="dim")
     body.append("/goal evidence <criterion-index-or-id> <note>", style="bold")
     body.append("  append manual evidence\n", style="dim")
+    body.append("/goal complete [recap]", style="bold")
+    body.append("  complete after verified evidence audit\n", style="dim")
+    body.append("/goal cancel [recap]", style="bold")
+    body.append("  cancel the current goal\n", style="dim")
     _resolve_console().print(Panel(body, title="/goal", border_style="dim", padding=(1, 2)))
     return 0
 
@@ -290,6 +383,10 @@ def run(ctx: Any = None, *args: str) -> int:
         return cmd_start(ctx, *args[1:])
     if command == "evidence":
         return cmd_evidence(ctx, *args[1:])
+    if command == "complete":
+        return cmd_complete(ctx, *args[1:])
+    if command in {"cancel", "cancelled"}:
+        return cmd_cancel(ctx, *args[1:])
     return cmd_start(ctx, *args)
 
 
@@ -298,4 +395,6 @@ def run(ctx: Any = None, *args: str) -> int:
     "cmd_start",
     "cmd_status",
     "cmd_evidence",
+    "cmd_complete",
+    "cmd_cancel",
 ]