feat(goals): add domain/repo goal tracking and update_workstream MCP tool

- Migration c5d6e7f8a9b0: domain_goals and repo_goals tables, repo_goal_id FK on workstreams - DomainGoal: one active per domain (partial unique index), status active/archived/superseded - RepoGoal: integer priority, status active/paused/completed/archived, optional domain_goal_id link - WorkstreamUpdate schema and router extended with repo_goal_id and repo_goal_id filter - 6 new MCP goal tools: create_domain_goal, get_domain_goals, activate_domain_goal, create_repo_goal, get_repo_goals, update_repo_goal - update_workstream MCP tool: patch any subset of workstream fields (title, description, owner, due_date, repo_goal_id, status) - get_domain_summary extended with goal_guidance (needs_workplan, alignment_warnings) signals - Dashboard goals.md page and docs/goals.md reference page - CLAUDE.md template updated to act on goal_guidance signals at session start - CUST-WP-0010 workplan for this feature Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-09 00:15:29 +01:00
parent 4ab56494ad
commit 651df73e3a
20 changed files with 1212 additions and 10 deletions
--- a/api/main.py
+++ b/api/main.py
@@ -5,7 +5,7 @@ from fastapi.middleware.cors import CORSMiddleware

 from api.database import engine
 from api.routers import decisions, extension_points, progress, state, tasks, technical_debt, topics, workstreams, workstream_dependencies
-from api.routers import domains, repos, contributions, sbom, policy
+from api.routers import domains, repos, contributions, sbom, policy, domain_goals, repo_goals


@asynccontextmanager
@@ -38,6 +38,8 @@ app.include_router(decisions.router)
 app.include_router(extension_points.router)
 app.include_router(technical_debt.router)
 app.include_router(progress.router)
+app.include_router(domain_goals.router)
+app.include_router(repo_goals.router)
 app.include_router(contributions.router)
 app.include_router(sbom.router)
 app.include_router(state.router)
--- a/api/models/init.py
+++ b/api/models/init.py
@@ -1,6 +1,9 @@
 from api.models.base import Base
 from api.models.domain import Domain
+from api.models.domain_goal import DomainGoal, DomainGoalStatus
 from api.models.topic import Topic, TopicStatus
+from api.models.managed_repo import ManagedRepo
+from api.models.repo_goal import RepoGoal, RepoGoalStatus
 from api.models.workstream import Workstream, WorkstreamStatus
 from api.models.workstream_dependency import WorkstreamDependency
 from api.models.task import Task, TaskStatus, TaskPriority
@@ -8,7 +11,6 @@ from api.models.decision import Decision, DecisionType, DecisionStatus
 from api.models.progress_event import ProgressEvent
 from api.models.extension_point import ExtensionPoint, EPStatus
 from api.models.technical_debt import TechnicalDebt, TDStatus
-from api.models.managed_repo import ManagedRepo
 from api.models.contribution import Contribution, ContributionType, ContributionStatus
 from api.models.sbom_snapshot import SBOMSnapshot
 from api.models.sbom_entry import SBOMEntry, Ecosystem
@@ -16,7 +18,10 @@ from api.models.sbom_entry import SBOMEntry, Ecosystem
 __all__ = [
    "Base",
    "Domain",
+    "DomainGoal", "DomainGoalStatus",
    "Topic", "TopicStatus",
+    "ManagedRepo",
+    "RepoGoal", "RepoGoalStatus",
    "Workstream", "WorkstreamStatus",
    "WorkstreamDependency",
    "Task", "TaskStatus", "TaskPriority",
@@ -24,7 +29,6 @@ __all__ = [
    "ProgressEvent",
    "ExtensionPoint", "EPStatus",
    "TechnicalDebt", "TDStatus",
-    "ManagedRepo",
    "Contribution", "ContributionType", "ContributionStatus",
    "SBOMSnapshot",
    "SBOMEntry", "Ecosystem",
--- a/api/models/domain.py
+++ b/api/models/domain.py
@@ -24,3 +24,6 @@ class Domain(Base, TimestampMixin):
    repos: Mapped[list["ManagedRepo"]] = relationship(  # noqa: F821
        "ManagedRepo", back_populates="domain", lazy="selectin"
    )
+    goals: Mapped[list["DomainGoal"]] = relationship(  # noqa: F821
+        "DomainGoal", back_populates="domain", lazy="selectin"
+    )
--- a/api/models/domain_goal.py
+++ b/api/models/domain_goal.py
@@ -0,0 +1,41 @@
+import enum
+import uuid
+
+from sqlalchemy import ForeignKey, String, Text
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from api.models.base import Base, TimestampMixin, new_uuid
+
+
+class DomainGoalStatus(str, enum.Enum):
+    active = "active"
+    archived = "archived"
+    superseded = "superseded"
+
+
+class DomainGoal(Base, TimestampMixin):
+    __tablename__ = "domain_goals"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), primary_key=True, default=new_uuid
+    )
+    domain_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("domains.id", ondelete="RESTRICT"), nullable=False, index=True
+    )
+    title: Mapped[str] = mapped_column(String(500), nullable=False)
+    description: Mapped[str] = mapped_column(Text, nullable=False)
+    status: Mapped[str] = mapped_column(
+        String(20), nullable=False, default=DomainGoalStatus.active.value, server_default="active"
+    )
+
+    domain: Mapped["Domain"] = relationship(  # noqa: F821
+        "Domain", back_populates="goals", lazy="selectin"
+    )
+    repo_goals: Mapped[list["RepoGoal"]] = relationship(  # noqa: F821
+        "RepoGoal", back_populates="domain_goal", lazy="selectin"
+    )
+
+    @property
+    def domain_slug(self) -> str:
+        return self.domain.slug if self.domain is not None else ""
--- a/api/models/managed_repo.py
+++ b/api/models/managed_repo.py
@@ -35,6 +35,10 @@ class ManagedRepo(Base, TimestampMixin):
        "Domain", back_populates="repos", lazy="selectin"
    )

+    goals: Mapped[list["RepoGoal"]] = relationship(  # noqa: F821
+        "RepoGoal", back_populates="repo", lazy="selectin"
+    )
+
    @property
    def domain_slug(self) -> str:
        return self.domain.slug if self.domain is not None else ""
--- a/api/models/repo_goal.py
+++ b/api/models/repo_goal.py
@@ -0,0 +1,49 @@
+import enum
+import uuid
+
+from sqlalchemy import ForeignKey, Integer, String, Text
+from sqlalchemy.dialects.postgresql import UUID
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from api.models.base import Base, TimestampMixin, new_uuid
+
+
+class RepoGoalStatus(str, enum.Enum):
+    active = "active"
+    paused = "paused"
+    completed = "completed"
+    archived = "archived"
+
+
+class RepoGoal(Base, TimestampMixin):
+    __tablename__ = "repo_goals"
+
+    id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), primary_key=True, default=new_uuid
+    )
+    repo_id: Mapped[uuid.UUID] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("managed_repos.id", ondelete="RESTRICT"), nullable=False, index=True
+    )
+    domain_goal_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True), ForeignKey("domain_goals.id", ondelete="SET NULL"), nullable=True, index=True
+    )
+    title: Mapped[str] = mapped_column(String(500), nullable=False)
+    description: Mapped[str] = mapped_column(Text, nullable=False)
+    priority: Mapped[int] = mapped_column(Integer, nullable=False, default=100, server_default="100")
+    status: Mapped[str] = mapped_column(
+        String(20), nullable=False, default=RepoGoalStatus.active.value, server_default="active"
+    )
+
+    repo: Mapped["ManagedRepo"] = relationship(  # noqa: F821
+        "ManagedRepo", back_populates="goals", lazy="selectin"
+    )
+    domain_goal: Mapped["DomainGoal"] = relationship(  # noqa: F821
+        "DomainGoal", back_populates="repo_goals", lazy="selectin"
+    )
+    workstreams: Mapped[list["Workstream"]] = relationship(  # noqa: F821
+        "Workstream", back_populates="repo_goal", lazy="selectin"
+    )
+
+    @property
+    def repo_slug(self) -> str:
+        return self.repo.slug if self.repo is not None else ""
--- a/api/models/workstream.py
+++ b/api/models/workstream.py
@@ -40,9 +40,16 @@ class Workstream(Base, TimestampMixin):
        nullable=True,
        index=True,
    )
+    repo_goal_id: Mapped[uuid.UUID | None] = mapped_column(
+        UUID(as_uuid=True),
+        ForeignKey("repo_goals.id", ondelete="SET NULL"),
+        nullable=True,
+        index=True,
+    )

    topic: Mapped["Topic"] = relationship("Topic", back_populates="workstreams")  # noqa: F821
    repo: Mapped["ManagedRepo"] = relationship("ManagedRepo", lazy="selectin")  # noqa: F821
+    repo_goal: Mapped["RepoGoal"] = relationship("RepoGoal", back_populates="workstreams", lazy="selectin")  # noqa: F821
    tasks: Mapped[list["Task"]] = relationship(  # noqa: F821
        "Task", back_populates="workstream", lazy="selectin"
    )
--- a/api/routers/domain_goals.py
+++ b/api/routers/domain_goals.py
@@ -0,0 +1,114 @@
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from api.database import get_session
+from api.models.domain import Domain
+from api.models.domain_goal import DomainGoal, DomainGoalStatus  # noqa: F401 (DomainGoalStatus used in activate)
+from api.schemas.domain_goal import DomainGoalCreate, DomainGoalRead, DomainGoalUpdate
+
+router = APIRouter(prefix="/domain-goals", tags=["domain-goals"])
+
+
+async def _resolve_domain(domain_slug: str, session: AsyncSession) -> Domain:
+    result = await session.execute(select(Domain).where(Domain.slug == domain_slug))
+    domain = result.scalar_one_or_none()
+    if domain is None:
+        raise HTTPException(status_code=404, detail=f"Domain '{domain_slug}' not found")
+    return domain
+
+
+@router.get("/", response_model=list[DomainGoalRead])
+async def list_domain_goals(
+    domain_slug: str | None = None,
+    status: str | None = None,
+    session: AsyncSession = Depends(get_session),
+) -> list[DomainGoal]:
+    q = select(DomainGoal)
+    if domain_slug:
+        domain = await _resolve_domain(domain_slug, session)
+        q = q.where(DomainGoal.domain_id == domain.id)
+    if status:
+        q = q.where(DomainGoal.status == status)
+    q = q.order_by(DomainGoal.created_at.desc())
+    result = await session.execute(q)
+    return list(result.scalars().all())
+
+
+@router.post("/", response_model=DomainGoalRead, status_code=status.HTTP_201_CREATED)
+async def create_domain_goal(
+    body: DomainGoalCreate,
+    session: AsyncSession = Depends(get_session),
+) -> DomainGoal:
+    if body.status == DomainGoalStatus.active:
+        # Archive any existing active goal for this domain
+        existing = await session.execute(
+            select(DomainGoal).where(
+                DomainGoal.domain_id == body.domain_id,
+                DomainGoal.status == DomainGoalStatus.active,
+            )
+        )
+        for old in existing.scalars().all():
+            old.status = DomainGoalStatus.superseded
+
+    goal = DomainGoal(**body.model_dump())
+    session.add(goal)
+    await session.commit()
+    await session.refresh(goal)
+    return goal
+
+
+@router.get("/{goal_id}", response_model=DomainGoalRead)
+async def get_domain_goal(
+    goal_id: uuid.UUID,
+    session: AsyncSession = Depends(get_session),
+) -> DomainGoal:
+    goal = await session.get(DomainGoal, goal_id)
+    if goal is None:
+        raise HTTPException(status_code=404, detail="Domain goal not found")
+    return goal
+
+
+@router.patch("/{goal_id}", response_model=DomainGoalRead)
+async def update_domain_goal(
+    goal_id: uuid.UUID,
+    body: DomainGoalUpdate,
+    session: AsyncSession = Depends(get_session),
+) -> DomainGoal:
+    goal = await session.get(DomainGoal, goal_id)
+    if goal is None:
+        raise HTTPException(status_code=404, detail="Domain goal not found")
+    for field, value in body.model_dump(exclude_unset=True).items():
+        setattr(goal, field, value)
+    await session.commit()
+    await session.refresh(goal)
+    return goal
+
+
+@router.post("/{goal_id}/activate", response_model=DomainGoalRead)
+async def activate_domain_goal(
+    goal_id: uuid.UUID,
+    session: AsyncSession = Depends(get_session),
+) -> DomainGoal:
+    """Set this goal as the active domain goal, superseding any currently active one."""
+    goal = await session.get(DomainGoal, goal_id)
+    if goal is None:
+        raise HTTPException(status_code=404, detail="Domain goal not found")
+
+    # Supersede any other active goal for this domain
+    existing = await session.execute(
+        select(DomainGoal).where(
+            DomainGoal.domain_id == goal.domain_id,
+            DomainGoal.status == DomainGoalStatus.active,
+            DomainGoal.id != goal_id,
+        )
+    )
+    for old in existing.scalars().all():
+        old.status = DomainGoalStatus.superseded
+
+    goal.status = DomainGoalStatus.active
+    await session.commit()
+    await session.refresh(goal)
+    return goal
--- a/api/routers/repo_goals.py
+++ b/api/routers/repo_goals.py
@@ -0,0 +1,79 @@
+import uuid
+
+from fastapi import APIRouter, Depends, HTTPException, status
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from api.database import get_session
+from api.models.managed_repo import ManagedRepo
+from api.models.repo_goal import RepoGoal, RepoGoalStatus
+from api.schemas.repo_goal import RepoGoalCreate, RepoGoalRead, RepoGoalUpdate
+
+router = APIRouter(prefix="/repo-goals", tags=["repo-goals"])
+
+
+async def _resolve_repo(repo_slug: str, session: AsyncSession) -> ManagedRepo:
+    result = await session.execute(select(ManagedRepo).where(ManagedRepo.slug == repo_slug))
+    repo = result.scalar_one_or_none()
+    if repo is None:
+        raise HTTPException(status_code=404, detail=f"Repo '{repo_slug}' not found")
+    return repo
+
+
+@router.get("/", response_model=list[RepoGoalRead])
+async def list_repo_goals(
+    repo_slug: str | None = None,
+    domain_goal_id: uuid.UUID | None = None,
+    status: str | None = None,
+    session: AsyncSession = Depends(get_session),
+) -> list[RepoGoal]:
+    q = select(RepoGoal)
+    if repo_slug:
+        repo = await _resolve_repo(repo_slug, session)
+        q = q.where(RepoGoal.repo_id == repo.id)
+    if domain_goal_id:
+        q = q.where(RepoGoal.domain_goal_id == domain_goal_id)
+    if status:
+        q = q.where(RepoGoal.status == status)
+    q = q.order_by(RepoGoal.priority.asc(), RepoGoal.created_at.asc())
+    result = await session.execute(q)
+    return list(result.scalars().all())
+
+
+@router.post("/", response_model=RepoGoalRead, status_code=status.HTTP_201_CREATED)
+async def create_repo_goal(
+    body: RepoGoalCreate,
+    session: AsyncSession = Depends(get_session),
+) -> RepoGoal:
+    goal = RepoGoal(**body.model_dump())
+    session.add(goal)
+    await session.commit()
+    await session.refresh(goal)
+    return goal
+
+
+@router.get("/{goal_id}", response_model=RepoGoalRead)
+async def get_repo_goal(
+    goal_id: uuid.UUID,
+    session: AsyncSession = Depends(get_session),
+) -> RepoGoal:
+    goal = await session.get(RepoGoal, goal_id)
+    if goal is None:
+        raise HTTPException(status_code=404, detail="Repo goal not found")
+    return goal
+
+
+@router.patch("/{goal_id}", response_model=RepoGoalRead)
+async def update_repo_goal(
+    goal_id: uuid.UUID,
+    body: RepoGoalUpdate,
+    session: AsyncSession = Depends(get_session),
+) -> RepoGoal:
+    goal = await session.get(RepoGoal, goal_id)
+    if goal is None:
+        raise HTTPException(status_code=404, detail="Repo goal not found")
+    for field, value in body.model_dump(exclude_unset=True).items():
+        setattr(goal, field, value)
+    await session.commit()
+    await session.refresh(goal)
+    return goal
--- a/api/routers/workstreams.py
+++ b/api/routers/workstreams.py
@@ -15,6 +15,7 @@ router = APIRouter(prefix="/workstreams", tags=["workstreams"])
 async def list_workstreams(
    topic_id: uuid.UUID | None = None,
    repo_id: uuid.UUID | None = None,
+    repo_goal_id: uuid.UUID | None = None,
    status: WorkstreamStatus | None = None,
    session: AsyncSession = Depends(get_session),
 ) -> list[Workstream]:
@@ -23,9 +24,11 @@ async def list_workstreams(
        q = q.where(Workstream.topic_id == topic_id)
    if repo_id:
        q = q.where(Workstream.repo_id == repo_id)
+    if repo_goal_id:
+        q = q.where(Workstream.repo_goal_id == repo_goal_id)
    if status:
        q = q.where(Workstream.status == status)
-    q = q.order_by(Workstream.created_at)
+    q = q.order_by(Workstream.updated_at.desc())
    result = await session.execute(q)
    return list(result.scalars().all())

--- a/api/schemas/domain_goal.py
+++ b/api/schemas/domain_goal.py
@@ -0,0 +1,31 @@
+import uuid
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+from api.models.domain_goal import DomainGoalStatus
+
+
+class DomainGoalCreate(BaseModel):
+    domain_id: uuid.UUID
+    title: str
+    description: str
+    status: str = DomainGoalStatus.active.value
+
+
+class DomainGoalUpdate(BaseModel):
+    title: str | None = None
+    description: str | None = None
+    status: str | None = None
+
+
+class DomainGoalRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    id: uuid.UUID
+    domain_id: uuid.UUID
+    domain_slug: str
+    title: str
+    description: str
+    status: str
+    created_at: datetime
+    updated_at: datetime
--- a/api/schemas/repo_goal.py
+++ b/api/schemas/repo_goal.py
@@ -0,0 +1,37 @@
+import uuid
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict
+
+from api.models.repo_goal import RepoGoalStatus
+
+
+class RepoGoalCreate(BaseModel):
+    repo_id: uuid.UUID
+    domain_goal_id: uuid.UUID | None = None
+    title: str
+    description: str
+    priority: int = 100
+    status: str = RepoGoalStatus.active.value
+
+
+class RepoGoalUpdate(BaseModel):
+    title: str | None = None
+    description: str | None = None
+    priority: int | None = None
+    status: str | None = None
+    domain_goal_id: uuid.UUID | None = None
+
+
+class RepoGoalRead(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    id: uuid.UUID
+    repo_id: uuid.UUID
+    repo_slug: str
+    domain_goal_id: uuid.UUID | None = None
+    title: str
+    description: str
+    priority: int
+    status: str
+    created_at: datetime
+    updated_at: datetime
--- a/api/schemas/workstream.py
+++ b/api/schemas/workstream.py
@@ -16,6 +16,7 @@ class WorkstreamCreate(BaseModel):
    owner: str | None = None
    due_date: date | None = None
    repo_id: uuid.UUID | None = None  # GEMS primary: the owning repository
+    repo_goal_id: uuid.UUID | None = None


 class WorkstreamUpdate(BaseModel):
@@ -25,6 +26,7 @@ class WorkstreamUpdate(BaseModel):
    owner: str | None = None
    due_date: date | None = None
    repo_id: uuid.UUID | None = None
+    repo_goal_id: uuid.UUID | None = None


 class WorkstreamRead(BaseModel):
@@ -32,6 +34,7 @@ class WorkstreamRead(BaseModel):
    id: uuid.UUID
    topic_id: uuid.UUID
    repo_id: uuid.UUID | None = None
+    repo_goal_id: uuid.UUID | None = None
    slug: str
    title: str
    description: str | None = None