@1mancompany/onemancompany 0.7.20 → 0.7.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@1mancompany/onemancompany",
-  "version": "0.7.20",
+  "version": "0.7.25",
   "description": "The AI Operating System for One-Person Companies",
   "bin": {
     "onemancompany": "bin/cli.js"

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "onemancompany"
-version = "0.7.20"
+version = "0.7.25"
 description = "A one-man company simulation with pixel art visualization and LangChain AI agents"
 requires-python = ">=3.12"
 dependencies = [

package/src/onemancompany/agents/product_tools.py

@@ -11,7 +11,7 @@ from langchain_core.tools import tool
 from loguru import logger
 
 from onemancompany.core import product as prod
-from onemancompany.core.models import IssueResolution, IssuePriority, IssueStatus
+from onemancompany.core.models import IssueRelation, IssueResolution, IssuePriority, IssueStatus
 
 
 # ---------------------------------------------------------------------------
@@ -21,6 +21,7 @@ from onemancompany.core.models import IssueResolution, IssuePriority, IssueStatu
 _RESOLUTION_MAP = {r.value: r for r in IssueResolution}
 _PRIORITY_MAP = {p.value: p for p in IssuePriority}
 _STATUS_MAP = {s.value: s for s in IssueStatus}
+_RELATION_MAP = {r.value: r for r in IssueRelation}
 
 
 def _resolve_caller_id() -> str:
@@ -297,6 +298,270 @@ async def update_kr_progress_tool(
         return f"Error: {e}"
 
 
+# ---------------------------------------------------------------------------
+# Sprint tools
+# ---------------------------------------------------------------------------
+
+
+@tool
+async def create_sprint_tool(
+    product_slug: str,
+    name: str,
+    start_date: str,
+    end_date: str,
+    goal: str = "",
+    capacity: str = "",
+) -> str:
+    """Create a new sprint for a product.
+
+    Args:
+        product_slug: The product slug
+        name: Sprint name (e.g. "Sprint 3")
+        start_date: Start date in YYYY-MM-DD format
+        end_date: End date in YYYY-MM-DD format
+        goal: Sprint goal description
+        capacity: Optional capacity in story points
+    """
+    try:
+        cap = int(capacity) if capacity else None
+        sprint = prod.create_sprint(
+            slug=product_slug,
+            name=name,
+            start_date=start_date,
+            end_date=end_date,
+            goal=goal,
+            capacity=cap,
+        )
+        logger.debug("create_sprint_tool: {} in {}", sprint["id"], product_slug)
+        return f"Created sprint '{name}' ({sprint['id']}) for {product_slug}: {start_date} → {end_date}"
+    except (ValueError, FileNotFoundError) as e:
+        return f"Error: {e}"
+
+
+@tool
+async def close_sprint_tool(
+    product_slug: str,
+    sprint_id: str = "",
+) -> str:
+    """Close the active sprint for a product. Calculates velocity, carries over unfinished issues, generates retrospective.
+
+    Args:
+        product_slug: The product slug
+        sprint_id: Sprint ID to close. If empty, closes the active sprint.
+    """
+    try:
+        if not sprint_id:
+            active = prod.get_active_sprint(product_slug)
+            if not active:
+                return f"No active sprint found for {product_slug}"
+            sprint_id = active["id"]
+        result = prod.close_sprint(product_slug, sprint_id)
+        vel = result.get("velocity", 0)
+        rate = result.get("completion_rate", 0)
+        carry = result.get("carry_over_count", 0)
+        logger.debug("close_sprint_tool: {} closed — vel={}", sprint_id, vel)
+        return (
+            f"Sprint closed: velocity={vel} pts, completion={rate}%, "
+            f"carry_over={carry} issues\n\n{result.get('retrospective', '')}"
+        )
+    except (ValueError, FileNotFoundError) as e:
+        return f"Error: {e}"
+
+
+@tool
+async def get_sprint_info_tool(
+    product_slug: str,
+    sprint_id: str = "",
+) -> str:
+    """Get sprint information. Defaults to the active sprint if no ID given.
+
+    Args:
+        product_slug: The product slug
+        sprint_id: Sprint ID. If empty, returns the active sprint.
+    """
+    try:
+        if sprint_id:
+            sprint = prod.load_sprint(product_slug, sprint_id)
+        else:
+            sprint = prod.get_active_sprint(product_slug)
+
+        if not sprint:
+            # List all sprints as fallback
+            all_sprints = prod.list_sprints(product_slug)
+            if not all_sprints:
+                return f"No sprints found for {product_slug}"
+            lines = [f"No active sprint. All sprints for {product_slug}:"]
+            for s in all_sprints:
+                lines.append(f"- [{s['status']}] {s['name']} ({s['id']}) {s['start_date']}→{s['end_date']}")
+            return "\n".join(lines)
+
+        # Show sprint details
+        issues = prod.list_issues(product_slug, sprint=sprint["id"])
+        done = [i for i in issues if i.get("status") in ("done", "released")]
+        vel = sum(i.get("story_points") or 0 for i in done)
+        total_pts = sum(i.get("story_points") or 0 for i in issues)
+
+        lines = [
+            f"**{sprint['name']}** ({sprint['id']})",
+            f"Status: {sprint['status']}",
+            f"Goal: {sprint.get('goal') or 'N/A'}",
+            f"Period: {sprint['start_date']} → {sprint['end_date']}",
+            f"Issues: {len(done)}/{len(issues)} done",
+            f"Points: {vel}/{total_pts}",
+        ]
+        if sprint.get("capacity"):
+            lines.append(f"Capacity: {sprint['capacity']} pts")
+
+        suggestion = prod.suggest_capacity(product_slug)
+        if suggestion is not None:
+            lines.append(f"Suggested capacity (avg last 3): {suggestion} pts")
+
+        return "\n".join(lines)
+    except (ValueError, FileNotFoundError) as e:
+        return f"Error: {e}"
+
+
+# ---------------------------------------------------------------------------
+# Issue link tools
+# ---------------------------------------------------------------------------
+
+
+@tool
+async def link_issues_tool(
+    product_slug: str,
+    issue_id: str,
+    target_id: str,
+    relation: str,
+) -> str:
+    """Link two issues with a dependency or relation.
+
+    Args:
+        product_slug: The product slug
+        issue_id: Source issue ID
+        target_id: Target issue ID
+        relation: blocks, blocked_by, or relates_to
+    """
+    rel = _RELATION_MAP.get(relation)
+    if rel is None:
+        return f"Error: invalid relation '{relation}'. Must be one of: {', '.join(_RELATION_MAP)}"
+    try:
+        prod.add_issue_link(product_slug, issue_id, target_id, rel)
+        logger.debug("link_issues_tool: {} —{}→ {}", issue_id, relation, target_id)
+        return f"Linked {issue_id} —{relation}→ {target_id}"
+    except ValueError as e:
+        return f"Error: {e}"
+
+
+@tool
+async def unlink_issues_tool(
+    product_slug: str,
+    issue_id: str,
+    target_id: str,
+) -> str:
+    """Remove all links between two issues.
+
+    Args:
+        product_slug: The product slug
+        issue_id: First issue ID
+        target_id: Second issue ID
+    """
+    prod.remove_issue_link(product_slug, issue_id, target_id)
+    logger.debug("unlink_issues_tool: {} ↔ {}", issue_id, target_id)
+    return f"Unlinked {issue_id} ↔ {target_id}"
+
+
+@tool
+async def check_blocked_issues_tool(
+    product_slug: str,
+) -> str:
+    """List all issues that are currently blocked by unfinished dependencies.
+
+    Args:
+        product_slug: The product slug
+    """
+    all_issues = prod.list_issues(product_slug)
+    blocked = []
+    for issue in all_issues:
+        if issue.get("status") in (IssueStatus.DONE.value, IssueStatus.RELEASED.value):
+            continue
+        if prod.is_blocked(product_slug, issue["id"]):
+            blockers = [
+                l["issue_id"] for l in issue.get("issue_links", [])
+                if l["relation"] == IssueRelation.BLOCKED_BY.value
+            ]
+            blocked.append(f"- [{issue.get('priority', '?')}] {issue['title']} ({issue['id']}) blocked by: {', '.join(blockers)}")
+    if not blocked:
+        return "No blocked issues found"
+    return f"Blocked issues ({len(blocked)}):\n" + "\n".join(blocked)
+
+
+@tool
+async def manage_review_tool(
+    product_slug: str,
+    action: str,
+    review_id: str = "",
+    item_key: str = "",
+    checked: str = "",
+) -> str:
+    """Manage product review checklists: list, view, check items, or complete.
+
+    Args:
+        product_slug: The product slug
+        action: list, view, check, uncheck, or complete
+        review_id: Review ID (required for view/check/uncheck/complete)
+        item_key: Checklist item key (required for check/uncheck)
+        checked: 'true' or 'false' (for check/uncheck, overrides action)
+    """
+    try:
+        if action == "list":
+            reviews = prod.list_reviews(product_slug)
+            if not reviews:
+                return "No reviews found"
+            lines = []
+            for r in reviews:
+                checked_count = sum(1 for i in r.get("items", []) if i.get("checked"))
+                total = len(r.get("items", []))
+                lines.append(f"- [{r['status']}] {r['id']} ({r['trigger']}) {checked_count}/{total} items checked")
+            return "\n".join(lines)
+
+        if not review_id:
+            return "Error: review_id is required for this action"
+
+        if action == "view":
+            review = prod.load_review(product_slug, review_id)
+            if not review:
+                return f"Review '{review_id}' not found"
+            lines = [
+                f"**Review {review['id']}**",
+                f"Status: {review['status']}",
+                f"Trigger: {review['trigger']} ({review.get('trigger_ref', '')})",
+                f"Owner: {review['owner']}",
+                "",
+                "Checklist:",
+            ]
+            for item in review.get("items", []):
+                mark = "✓" if item.get("checked") else "○"
+                lines.append(f"  {mark} [{item['key']}] {item['label']}")
+            return "\n".join(lines)
+
+        if action in ("check", "uncheck"):
+            if not item_key:
+                return "Error: item_key is required for check/uncheck"
+            is_checked = action == "check"
+            if checked:
+                is_checked = checked.lower() == "true"
+            prod.update_review_item(product_slug, review_id, item_key, checked=is_checked)
+            return f"{'Checked' if is_checked else 'Unchecked'} item '{item_key}' in review {review_id}"
+
+        if action == "complete":
+            review = prod.complete_review(product_slug, review_id)
+            return f"Review {review_id} completed at {review['completed_at']}"
+
+        return f"Error: unknown action '{action}'. Use: list, view, check, uncheck, complete"
+    except ValueError as e:
+        return f"Error: {e}"
+
+
 # ---------------------------------------------------------------------------
 # Export
 # ---------------------------------------------------------------------------
@@ -309,4 +574,11 @@ PRODUCT_TOOLS = [
     get_product_context_tool,
     list_product_issues_tool,
     update_kr_progress_tool,
+    create_sprint_tool,
+    close_sprint_tool,
+    get_sprint_info_tool,
+    link_issues_tool,
+    unlink_issues_tool,
+    check_blocked_issues_tool,
+    manage_review_tool,
 ]

package/src/onemancompany/api/routes.py

@@ -7331,11 +7331,27 @@ async def api_product_detail(slug: str) -> dict:
     all_projects = list_projects()
     linked_projects = [p for p in all_projects if p.get("product_id") == product.get("id")]
 
+    # Sprints
+    sprints = prod.list_sprints(slug)
+    active_sprint = prod.get_active_sprint(slug)
+    suggested_capacity = prod.suggest_capacity(slug)
+
+    # Reviews
+    reviews = prod.list_reviews(slug)
+
+    # Blocked issues count
+    blocked_count = sum(1 for i in issues if prod.is_blocked(slug, i["id"]))
+
     return {
         "product": product,
         "issues": issues,
         "versions": versions,
         "projects": linked_projects,
+        "sprints": sprints,
+        "active_sprint": active_sprint,
+        "suggested_capacity": suggested_capacity,
+        "reviews": reviews,
+        "blocked_issues_count": blocked_count,
     }
 
 
@@ -7415,3 +7431,217 @@ async def api_start_product_planning(slug: str) -> dict:
         product_id=product["id"],
     )
     return {"conversation_id": conv.id, "existing": False}
+
+
+# ── Sprints ──────────────────────────────────────────────────────────────────
+
+
+@router.post("/api/product/{slug}/sprint")
+async def api_create_sprint(slug: str, request: Request) -> dict:
+    """Create a sprint for a product."""
+    from onemancompany.core import product as prod
+
+    body = await request.json()
+    name = body.get("name")
+    start_date = body.get("start_date")
+    end_date = body.get("end_date")
+    if not name or not start_date or not end_date:
+        raise HTTPException(status_code=400, detail="Missing required fields: name, start_date, end_date")
+    try:
+        result = prod.create_sprint(
+            slug=slug,
+            name=name,
+            start_date=start_date,
+            end_date=end_date,
+            goal=body.get("goal", ""),
+            capacity=int(body["capacity"]) if body.get("capacity") else None,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=404, detail=str(exc))
+    return result
+
+
+@router.get("/api/product/{slug}/sprints")
+async def api_list_sprints(slug: str, status: str = "") -> list[dict]:
+    """List sprints for a product, optionally filtered by status."""
+    from onemancompany.core import product as prod
+
+    return prod.list_sprints(slug, status=status or None)
+
+
+@router.get("/api/product/{slug}/sprint/{sprint_id}")
+async def api_get_sprint(slug: str, sprint_id: str) -> dict:
+    """Get a single sprint by ID."""
+    from onemancompany.core import product as prod
+
+    sprint = prod.load_sprint(slug, sprint_id)
+    if not sprint:
+        raise HTTPException(status_code=404, detail=f"Sprint '{sprint_id}' not found")
+    return sprint
+
+
+@router.put("/api/product/{slug}/sprint/{sprint_id}")
+async def api_update_sprint(slug: str, sprint_id: str, request: Request) -> dict:
+    """Update sprint fields (name, goal, start_date, end_date, capacity, status)."""
+    from onemancompany.core import product as prod
+
+    body = await request.json()
+    SPRINT_MUTABLE_FIELDS = {"name", "goal", "start_date", "end_date", "capacity", "status"}
+    filtered = {k: v for k, v in body.items() if k in SPRINT_MUTABLE_FIELDS}
+    if "capacity" in filtered and filtered["capacity"] is not None:
+        filtered["capacity"] = int(filtered["capacity"])
+    try:
+        result = prod.update_sprint(slug, sprint_id, **filtered)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return result
+
+
+@router.post("/api/product/{slug}/sprint/{sprint_id}/close")
+async def api_close_sprint(slug: str, sprint_id: str) -> dict:
+    """Close a sprint: calculate velocity, carry over unfinished issues, generate retrospective."""
+    from onemancompany.core import product as prod
+
+    try:
+        result = prod.close_sprint(slug, sprint_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return result
+
+
+@router.get("/api/product/{slug}/sprint/suggest-capacity")
+async def api_suggest_sprint_capacity(slug: str) -> dict:
+    """Suggest sprint capacity based on historical velocity (sliding average of last 3)."""
+    from onemancompany.core import product as prod
+
+    suggestion = prod.suggest_capacity(slug)
+    return {"suggested_capacity": suggestion}
+
+
+# ---------------------------------------------------------------------------
+# Issue Links
+# ---------------------------------------------------------------------------
+
+
+@router.post("/api/product/{slug}/issue/{issue_id}/link")
+async def api_add_issue_link(slug: str, issue_id: str, request: Request) -> dict:
+    """Add a link between two issues."""
+    from onemancompany.core import product as prod
+    from onemancompany.core.models import IssueRelation
+
+    body = await request.json()
+    target_id = body.get("target_id", "")
+    relation = body.get("relation", "")
+
+    if not target_id or not relation:
+        raise HTTPException(status_code=400, detail="target_id and relation are required")
+
+    rel_map = {r.value: r for r in IssueRelation}
+    rel = rel_map.get(relation)
+    if not rel:
+        raise HTTPException(status_code=400, detail=f"Invalid relation. Must be one of: {', '.join(rel_map)}")
+
+    try:
+        prod.add_issue_link(slug, issue_id, target_id, rel)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+    return {"linked": True, "issue_id": issue_id, "target_id": target_id, "relation": relation}
+
+
+@router.delete("/api/product/{slug}/issue/{issue_id}/link/{target_id}")
+async def api_remove_issue_link(slug: str, issue_id: str, target_id: str) -> dict:
+    """Remove all links between two issues."""
+    from onemancompany.core import product as prod
+
+    prod.remove_issue_link(slug, issue_id, target_id)
+    return {"unlinked": True, "issue_id": issue_id, "target_id": target_id}
+
+
+@router.get("/api/product/{slug}/issue/{issue_id}/links")
+async def api_get_issue_links(slug: str, issue_id: str) -> list[dict]:
+    """Get all links for an issue."""
+    from onemancompany.core import product as prod
+
+    return prod.get_issue_links(slug, issue_id)
+
+
+@router.get("/api/product/{slug}/blocked-issues")
+async def api_blocked_issues(slug: str) -> list[dict]:
+    """List all blocked issues for a product."""
+    from onemancompany.core import product as prod
+
+    all_issues = prod.list_issues(slug)
+    blocked = []
+    for issue in all_issues:
+        if prod.is_blocked(slug, issue["id"]):
+            blocked.append(issue)
+    return blocked
+
+
+# ---------------------------------------------------------------------------
+# Reviews
+# ---------------------------------------------------------------------------
+
+
+@router.post("/api/product/{slug}/review")
+async def api_create_review(slug: str, request: Request) -> dict:
+    """Create a review checklist."""
+    from onemancompany.core import product as prod
+
+    body = await request.json()
+    trigger = body.get("trigger", "manual")
+    trigger_ref = body.get("trigger_ref", "")
+    owner = body.get("owner", "")
+
+    review = prod.create_review(
+        slug=slug,
+        trigger=trigger,
+        trigger_ref=trigger_ref,
+        owner=owner,
+    )
+    return review
+
+
+@router.get("/api/product/{slug}/reviews")
+async def api_list_reviews(slug: str, status: str = "") -> list[dict]:
+    """List reviews for a product, optionally filtered by status."""
+    from onemancompany.core import product as prod
+
+    return prod.list_reviews(slug, status=status or None)
+
+
+@router.get("/api/product/{slug}/review/{review_id}")
+async def api_get_review(slug: str, review_id: str) -> dict:
+    """Get a single review."""
+    from onemancompany.core import product as prod
+
+    review = prod.load_review(slug, review_id)
+    if not review:
+        raise HTTPException(status_code=404, detail=f"Review '{review_id}' not found")
+    return review
+
+
+@router.put("/api/product/{slug}/review/{review_id}/item/{item_key}")
+async def api_update_review_item(slug: str, review_id: str, item_key: str, request: Request) -> dict:
+    """Check or uncheck a review checklist item."""
+    from onemancompany.core import product as prod
+
+    body = await request.json()
+    checked = body.get("checked", False)
+
+    try:
+        return prod.update_review_item(slug, review_id, item_key, checked=checked)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+
+
+@router.post("/api/product/{slug}/review/{review_id}/complete")
+async def api_complete_review(slug: str, review_id: str) -> dict:
+    """Complete a review (all items must be checked)."""
+    from onemancompany.core import product as prod
+
+    try:
+        return prod.complete_review(slug, review_id)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))

package/src/onemancompany/core/config.py

@@ -61,6 +61,8 @@ VESSEL_YAML_FILENAME = "vessel.yaml"
 PRODUCT_YAML_FILENAME = "product.yaml"
 ISSUES_DIR_NAME = "issues"
 VERSIONS_DIR_NAME = "versions"
+SPRINTS_DIR_NAME = "sprints"
+REVIEWS_DIR_NAME = "reviews"
 TALENT_PERSONA_FILENAME = "talent_persona.md"
 MCP_CONFIG_FILENAME = "mcp_config.json"
 CONVERSATIONS_DIR_NAME = "conversations"

package/src/onemancompany/core/models.py

@@ -162,6 +162,10 @@ class EventType(str, Enum):
     ISSUE_ASSIGNED = "issue_assigned"
     KR_UPDATED = "kr_updated"
     VERSION_RELEASED = "version_released"
+    SPRINT_CREATED = "sprint_created"
+    SPRINT_CLOSED = "sprint_closed"
+    REVIEW_CREATED = "review_created"
+    REVIEW_COMPLETED = "review_completed"
 
 
 class ProductStatus(str, Enum):
@@ -197,6 +201,20 @@ class IssueResolution(str, Enum):
     BY_DESIGN = "by_design"
 
 
+class IssueRelation(str, Enum):
+    """Relationship type between two issues."""
+    BLOCKS = "blocks"
+    BLOCKED_BY = "blocked_by"
+    RELATES_TO = "relates_to"
+
+
+class SprintStatus(str, Enum):
+    """Sprint lifecycle status."""
+    PLANNING = "planning"
+    ACTIVE = "active"
+    CLOSED = "closed"
+
+
 # ---------------------------------------------------------------------------
 # Performance
 # ---------------------------------------------------------------------------

package/src/onemancompany/core/product.py

@@ -1,7 +1,8 @@
-"""Product management — product records, key results, and issues.
+"""Product management — product records, key results, issues, and sprints.
 
 Products stored at: PRODUCTS_DIR/{slug}/product.yaml
 Issues stored at:   PRODUCTS_DIR/{slug}/issues/{issue_id}.yaml
+Sprints stored at:  PRODUCTS_DIR/{slug}/sprints/{sprint_id}.yaml
 
 All YAML I/O through store._read_yaml / _write_yaml.
 Disk is the single source of truth — no in-memory caching.
@@ -20,14 +21,18 @@ from onemancompany.core.config import (
     ISSUES_DIR_NAME,
     PRODUCT_YAML_FILENAME,
     PRODUCTS_DIR,
+    REVIEWS_DIR_NAME,
+    SPRINTS_DIR_NAME,
     VERSIONS_DIR_NAME,
     DirtyCategory,
 )
 from onemancompany.core.models import (
+    IssueRelation,
     IssueResolution,
     IssuePriority,
     IssueStatus,
     ProductStatus,
+    SprintStatus,
 )
 from onemancompany.core.store import _read_yaml, _write_yaml, mark_dirty
 
@@ -296,7 +301,7 @@ def create_issue(
         "labels": labels or [],
         "assignee_id": assignee_id,
         "linked_task_ids": [],
-        "linked_issue_ids": [],
+        "issue_links": [],
         "milestone_version": milestone_version,
         "created_at": now,
         "created_by": created_by,
@@ -318,10 +323,26 @@ def create_issue(
 
 
 def load_issue(slug: str, issue_id: str) -> dict | None:
-    """Load a single issue by ID. Returns None if not found."""
+    """Load a single issue by ID. Returns None if not found.
+
+    Auto-migrates old ``linked_issue_ids`` format to ``issue_links``.
+    """
     path = _issues_dir(slug) / f"{issue_id}.yaml"
     data = _read_yaml(path)
-    return data if data else None
+    if not data:
+        return None
+
+    # Auto-migrate: linked_issue_ids → issue_links
+    if "linked_issue_ids" in data and "issue_links" not in data:
+        old_ids = data.pop("linked_issue_ids", [])
+        data["issue_links"] = [
+            {"issue_id": iid, "relation": IssueRelation.RELATES_TO.value}
+            for iid in old_ids
+        ]
+        _write_yaml(path, data)
+        logger.debug("Migrated linked_issue_ids → issue_links for {}", issue_id)
+
+    return data
 
 
 def list_issues(
@@ -330,6 +351,7 @@ def list_issues(
     status: IssueStatus | None = None,
     priority: IssuePriority | None = None,
     labels: list[str] | None = None,
+    sprint: str | None = None,
 ) -> list[dict]:
     """List issues for a product, optionally filtered."""
     issues_path = _issues_dir(slug)
@@ -351,6 +373,8 @@ def list_issues(
             issue_labels = set(data.get("labels", []))
             if not set(labels).intersection(issue_labels):
                 continue
+        if sprint is not None and data.get("sprint") != sprint:
+            continue
         results.append(data)
     return results
 
@@ -418,6 +442,226 @@ def reopen_issue(slug: str, issue_id: str) -> dict | None:
     return data
 
 
+# ---------------------------------------------------------------------------
+# Issue Links
+# ---------------------------------------------------------------------------
+
+_REVERSE_RELATION = {
+    IssueRelation.BLOCKS.value: IssueRelation.BLOCKED_BY.value,
+    IssueRelation.BLOCKED_BY.value: IssueRelation.BLOCKS.value,
+    IssueRelation.RELATES_TO.value: IssueRelation.RELATES_TO.value,
+}
+
+
+def add_issue_link(
+    slug: str,
+    issue_id: str,
+    target_id: str,
+    relation: IssueRelation,
+) -> None:
+    """Add a bidirectional link between two issues.
+
+    Raises ValueError on self-reference or if either issue is not found.
+    Idempotent — re-adding the same link is a no-op.
+    """
+    if issue_id == target_id:
+        raise ValueError("Cannot link an issue to itself (self-reference)")
+
+    issue = load_issue(slug, issue_id)
+    if not issue:
+        raise ValueError(f"Issue '{issue_id}' not found in '{slug}'")
+    target = load_issue(slug, target_id)
+    if not target:
+        raise ValueError(f"Issue '{target_id}' not found in '{slug}'")
+
+    rel_value = relation.value if hasattr(relation, "value") else relation
+    reverse_rel = _REVERSE_RELATION[rel_value]
+
+    # Add forward link (idempotent)
+    _add_link_entry(slug, issue_id, target_id, rel_value)
+    # Add reverse link
+    _add_link_entry(slug, target_id, issue_id, reverse_rel)
+
+    mark_dirty(DirtyCategory.PRODUCTS)
+    logger.debug("Linked {} —{}→ {}", issue_id, rel_value, target_id)
+
+
+def _add_link_entry(slug: str, issue_id: str, target_id: str, relation: str) -> None:
+    """Add a single link entry to an issue (idempotent)."""
+    with _get_slug_lock(slug):
+        path = _issues_dir(slug) / f"{issue_id}.yaml"
+        data = _read_yaml(path)
+        if not data:
+            return
+        links = data.setdefault("issue_links", [])
+        # Idempotent check
+        if any(l["issue_id"] == target_id and l["relation"] == relation for l in links):
+            return
+        links.append({
+            "issue_id": target_id,
+            "relation": relation,
+            "created_at": datetime.now().isoformat(),
+        })
+        _write_yaml(path, data)
+
+
+def remove_issue_link(slug: str, issue_id: str, target_id: str) -> None:
+    """Remove all links between two issues (both directions). Silently ignores missing links."""
+    _remove_link_entry(slug, issue_id, target_id)
+    _remove_link_entry(slug, target_id, issue_id)
+    mark_dirty(DirtyCategory.PRODUCTS)
+    logger.debug("Unlinked {} ↔ {}", issue_id, target_id)
+
+
+def _remove_link_entry(slug: str, issue_id: str, target_id: str) -> None:
+    """Remove all link entries from issue_id to target_id."""
+    with _get_slug_lock(slug):
+        path = _issues_dir(slug) / f"{issue_id}.yaml"
+        data = _read_yaml(path)
+        if not data:
+            return
+        links = data.get("issue_links", [])
+        data["issue_links"] = [l for l in links if l["issue_id"] != target_id]
+        _write_yaml(path, data)
+
+
+def get_issue_links(slug: str, issue_id: str) -> list[dict]:
+    """Return the issue_links list for an issue."""
+    issue = load_issue(slug, issue_id)
+    if not issue:
+        return []
+    return issue.get("issue_links", [])
+
+
+def is_blocked(slug: str, issue_id: str) -> bool:
+    """Check if an issue is blocked by any unfinished blocker."""
+    issue = load_issue(slug, issue_id)
+    if not issue:
+        return False
+    links = issue.get("issue_links", [])
+    for link in links:
+        if link["relation"] != IssueRelation.BLOCKED_BY.value:
+            continue
+        blocker = load_issue(slug, link["issue_id"])
+        if blocker and blocker.get("status") not in _DONE_STATUSES:
+            return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Review Checklist
+# ---------------------------------------------------------------------------
+
+_DEFAULT_REVIEW_ITEMS = [
+    {"key": "update_kr", "label": "更新 KR 进度", "checked": False},
+    {"key": "review_issues", "label": "Review open issues", "checked": False},
+    {"key": "assign_backlog", "label": "安排 backlog 优先级", "checked": False},
+    {"key": "create_issues", "label": "创建新 issues", "checked": False},
+]
+
+
+def _reviews_dir(slug: str) -> Path:
+    return _product_dir(slug) / REVIEWS_DIR_NAME
+
+
+def create_review(
+    slug: str,
+    *,
+    trigger: str,
+    trigger_ref: str = "",
+    owner: str,
+    items: list[dict] | None = None,
+) -> dict:
+    """Create a review checklist for a product. Returns the review dict."""
+    review_id = _gen_id("rev_")
+    now = datetime.now().isoformat()
+
+    data = {
+        "id": review_id,
+        "product_slug": slug,
+        "trigger": trigger,
+        "trigger_ref": trigger_ref,
+        "created_at": now,
+        "owner": owner,
+        "status": "open",
+        "items": items if items is not None else [dict(i) for i in _DEFAULT_REVIEW_ITEMS],
+        "completed_at": None,
+    }
+
+    rdir = _reviews_dir(slug)
+    rdir.mkdir(parents=True, exist_ok=True)
+    with _get_slug_lock(slug):
+        _write_yaml(rdir / f"{review_id}.yaml", data)
+    mark_dirty(DirtyCategory.PRODUCTS)
+    logger.debug("[PRODUCT] Review created: {} in {}", review_id, slug)
+    return data
+
+
+def load_review(slug: str, review_id: str) -> dict | None:
+    """Load a single review by ID."""
+    path = _reviews_dir(slug) / f"{review_id}.yaml"
+    if not path.exists():
+        return None
+    return _read_yaml(path)
+
+
+def list_reviews(slug: str, status: str | None = None) -> list[dict]:
+    """List all reviews for a product, optionally filtered by status."""
+    rdir = _reviews_dir(slug)
+    if not rdir.exists():
+        return []
+    reviews = []
+    for f in sorted(rdir.iterdir()):
+        if f.suffix == ".yaml":
+            data = _read_yaml(f)
+            if data and (status is None or data.get("status") == status):
+                reviews.append(data)
+    return reviews
+
+
+def update_review_item(slug: str, review_id: str, item_key: str, *, checked: bool) -> dict:
+    """Check or uncheck a review item. Returns updated review dict.
+
+    Raises ValueError if review or item key not found.
+    """
+    with _get_slug_lock(slug):
+        path = _reviews_dir(slug) / f"{review_id}.yaml"
+        data = _read_yaml(path)
+        if not data:
+            raise ValueError(f"Review '{review_id}' not found in '{slug}'")
+        for item in data.get("items", []):
+            if item["key"] == item_key:
+                item["checked"] = checked
+                _write_yaml(path, data)
+                mark_dirty(DirtyCategory.PRODUCTS)
+                return data
+    raise ValueError(f"Item key '{item_key}' not found in review '{review_id}'")
+
+
+def complete_review(slug: str, review_id: str) -> dict:
+    """Mark a review as completed. All items must be checked.
+
+    Raises ValueError if review not found, already completed, or has unchecked items.
+    """
+    with _get_slug_lock(slug):
+        path = _reviews_dir(slug) / f"{review_id}.yaml"
+        data = _read_yaml(path)
+        if not data:
+            raise ValueError(f"Review '{review_id}' not found in '{slug}'")
+        if data.get("status") == "completed":
+            raise ValueError(f"Review '{review_id}' is already completed")
+        unchecked = [i for i in data.get("items", []) if not i.get("checked")]
+        if unchecked:
+            keys = ", ".join(i["key"] for i in unchecked)
+            raise ValueError(f"Cannot complete review: unchecked items: {keys}")
+        data["status"] = "completed"
+        data["completed_at"] = datetime.now().isoformat()
+        _write_yaml(path, data)
+    mark_dirty(DirtyCategory.PRODUCTS)
+    logger.debug("[PRODUCT] Review completed: {}", review_id)
+    return data
+
+
 # ---------------------------------------------------------------------------
 # Product Versioning
 # ---------------------------------------------------------------------------
@@ -806,3 +1050,237 @@ def sync_issue_statuses(slug: str) -> list[dict]:
             logger.debug("[PRODUCT] Issue {} status derived: {} → {}", issue["id"], current, derived.value)
 
     return changed
+
+
+# ---------------------------------------------------------------------------
+# Sprint management
+# ---------------------------------------------------------------------------
+
+_DONE_STATUSES = {IssueStatus.DONE.value, IssueStatus.RELEASED.value}
+
+
+def _sprints_dir(slug: str) -> Path:
+    return PRODUCTS_DIR / slug / SPRINTS_DIR_NAME
+
+
+def create_sprint(
+    *,
+    slug: str,
+    name: str,
+    start_date: str,
+    end_date: str,
+    goal: str = "",
+    capacity: int | None = None,
+) -> dict:
+    """Create a sprint for a product. Returns the sprint dict."""
+    product = load_product(slug)
+    if not product:
+        raise ValueError(f"Product '{slug}' not found")
+
+    sprint_id = _gen_id("sprint_")
+    now = datetime.now().isoformat()
+
+    data = {
+        "id": sprint_id,
+        "product_id": product["id"],
+        "name": name,
+        "goal": goal,
+        "status": SprintStatus.PLANNING.value,
+        "start_date": start_date,
+        "end_date": end_date,
+        "capacity": capacity,
+        "velocity": None,
+        "carry_over_count": 0,
+        "completion_rate": None,
+        "retrospective": None,
+        "created_at": now,
+        "closed_at": None,
+    }
+
+    sdir = _sprints_dir(slug)
+    sdir.mkdir(parents=True, exist_ok=True)
+    with _get_slug_lock(slug):
+        _write_yaml(sdir / f"{sprint_id}.yaml", data)
+    mark_dirty(DirtyCategory.PRODUCTS)
+    logger.debug("[PRODUCT] Sprint created: {} in {}", sprint_id, slug)
+    return data
+
+
+def load_sprint(slug: str, sprint_id: str) -> dict | None:
+    """Load a single sprint by ID."""
+    path = _sprints_dir(slug) / f"{sprint_id}.yaml"
+    if not path.exists():
+        return None
+    return _read_yaml(path)
+
+
+def list_sprints(slug: str, status: str | None = None) -> list[dict]:
+    """List all sprints for a product, optionally filtered by status."""
+    sdir = _sprints_dir(slug)
+    if not sdir.exists():
+        return []
+    sprints = []
+    for f in sorted(sdir.iterdir()):
+        if f.suffix == ".yaml":
+            data = _read_yaml(f)
+            if data and (status is None or data.get("status") == status):
+                sprints.append(data)
+    return sprints
+
+
+def update_sprint(slug: str, sprint_id: str, **fields) -> dict:
+    """Update sprint fields. Enforces single-active-sprint constraint."""
+    sprint = load_sprint(slug, sprint_id)
+    if not sprint:
+        raise ValueError(f"Sprint '{sprint_id}' not found in '{slug}'")
+
+    # Enforce: only one active sprint per product
+    new_status = fields.get("status")
+    if new_status == SprintStatus.ACTIVE.value:
+        existing_active = get_active_sprint(slug)
+        if existing_active and existing_active["id"] != sprint_id:
+            raise ValueError(f"Product '{slug}' already has an active sprint: {existing_active['id']}")
+
+    sprint.update(fields)
+    with _get_slug_lock(slug):
+        _write_yaml(_sprints_dir(slug) / f"{sprint_id}.yaml", sprint)
+    mark_dirty(DirtyCategory.PRODUCTS)
+    return sprint
+
+
+def get_active_sprint(slug: str) -> dict | None:
+    """Return the current active sprint for a product, or None."""
+    active = list_sprints(slug, status=SprintStatus.ACTIVE.value)
+    return active[0] if active else None
+
+
+def get_sprint_velocity(slug: str, sprint_id: str) -> int:
+    """Calculate velocity: sum of story_points for done/released issues in this sprint."""
+    issues = list_issues(slug, sprint=sprint_id)
+    total = 0
+    for issue in issues:
+        if issue.get("status") in _DONE_STATUSES:
+            total += issue.get("story_points") or 0
+    return total
+
+
+def close_sprint(slug: str, sprint_id: str) -> dict:
+    """Close a sprint: calculate velocity, carry-over, generate retrospective."""
+    sprint = load_sprint(slug, sprint_id)
+    if not sprint:
+        raise ValueError(f"Sprint '{sprint_id}' not found in '{slug}'")
+    if sprint.get("status") != SprintStatus.ACTIVE.value:
+        raise ValueError(f"Sprint '{sprint_id}' is not active")
+
+    # 1. Calculate velocity
+    velocity = get_sprint_velocity(slug, sprint_id)
+
+    # 2. Identify unfinished issues
+    all_issues = list_issues(slug, sprint=sprint_id)
+    done_count = sum(1 for i in all_issues if i.get("status") in _DONE_STATUSES)
+    total_count = len(all_issues)
+    unfinished = [i for i in all_issues if i.get("status") not in _DONE_STATUSES]
+
+    # 3. Carry-over: find next planning sprint
+    planning_sprints = list_sprints(slug, status=SprintStatus.PLANNING.value)
+    next_sprint = planning_sprints[0] if planning_sprints else None
+
+    for issue in unfinished:
+        if next_sprint:
+            update_issue(slug, issue["id"], sprint=next_sprint["id"], carried_over=True)
+        else:
+            update_issue(slug, issue["id"], sprint="", status=IssueStatus.BACKLOG.value, carried_over=True)
+
+    # 4. Completion rate
+    completion_rate = round((done_count / total_count) * 100, 2) if total_count > 0 else 0.0
+
+    # 5. Retrospective
+    retrospective = build_sprint_retrospective(slug, sprint_id)
+
+    # 6. Update sprint record
+    now = datetime.now().isoformat()
+    updated = update_sprint(
+        slug, sprint_id,
+        status=SprintStatus.CLOSED.value,
+        velocity=velocity,
+        carry_over_count=len(unfinished),
+        completion_rate=completion_rate,
+        retrospective=retrospective,
+        closed_at=now,
+    )
+
+    logger.debug(
+        "[PRODUCT] Sprint {} closed — velocity={}, completion={}%, carry_over={}",
+        sprint_id, velocity, completion_rate, len(unfinished),
+    )
+    return updated
+
+
+def suggest_capacity(slug: str) -> int | None:
+    """Suggest sprint capacity based on sliding average of last 3 closed sprints.
+
+    Returns None if fewer than 3 closed sprints exist.
+    """
+    closed = list_sprints(slug, status=SprintStatus.CLOSED.value)
+    if len(closed) < 3:
+        return None
+    # Take last 3 by closed_at
+    recent = sorted(closed, key=lambda s: s.get("closed_at") or "")[-3:]
+    velocities = [s.get("velocity") or 0 for s in recent]
+    return round(sum(velocities) / len(velocities))
+
+
+def build_sprint_retrospective(slug: str, sprint_id: str) -> str:
+    """Generate a sprint retrospective report string."""
+    sprint = load_sprint(slug, sprint_id)
+    if not sprint:
+        return ""
+
+    issues = list_issues(slug, sprint=sprint_id)
+    done = [i for i in issues if i.get("status") in _DONE_STATUSES]
+    unfinished = [i for i in issues if i.get("status") not in _DONE_STATUSES]
+    velocity = sum(i.get("story_points") or 0 for i in done)
+    total_points = sum(i.get("story_points") or 0 for i in issues)
+    total_count = len(issues)
+    done_count = len(done)
+
+    # Compare with previous sprint velocity
+    closed = list_sprints(slug, status=SprintStatus.CLOSED.value)
+    closed_sorted = sorted(closed, key=lambda s: s.get("closed_at") or "")
+    prev_velocity = None
+    for cs in closed_sorted:
+        if cs["id"] != sprint_id and cs.get("velocity") is not None:
+            prev_velocity = cs["velocity"]
+
+    lines = [
+        f"## Sprint Retrospective: {sprint['name']}",
+        f"**Goal**: {sprint.get('goal') or 'N/A'}",
+        f"**Period**: {sprint.get('start_date')} → {sprint.get('end_date')}",
+        "",
+        f"### Metrics",
+        f"- **Velocity**: {velocity} story points",
+        f"- **Completion**: {done_count}/{total_count} issues ({round(done_count / total_count * 100, 1) if total_count else 0}%)",
+        f"- **Story points completed**: {velocity}/{total_points}",
+        f"- **Carry-over**: {len(unfinished)} issues",
+    ]
+
+    if prev_velocity is not None:
+        delta = velocity - prev_velocity
+        direction = "↑" if delta > 0 else ("↓" if delta < 0 else "→")
+        lines.append(f"- **vs Previous Sprint**: {direction} {abs(delta)} points ({prev_velocity} → {velocity})")
+
+    if done:
+        lines.append("")
+        lines.append("### Completed")
+        for i in done:
+            pts = f" ({i.get('story_points') or 0}pts)" if i.get("story_points") else ""
+            lines.append(f"- ✓ {i['title']}{pts}")
+
+    if unfinished:
+        lines.append("")
+        lines.append("### Carried Over")
+        for i in unfinished:
+            pts = f" ({i.get('story_points') or 0}pts)" if i.get("story_points") else ""
+            lines.append(f"- ○ {i['title']}{pts}")
+
+    return "\n".join(lines)

package/src/onemancompany/core/product_triggers.py

@@ -12,6 +12,7 @@ from loguru import logger
 from onemancompany.core.events import CompanyEvent, event_bus
 from onemancompany.core.models import (
     EventType,
+    IssueRelation,
     IssuePriority,
     IssueResolution,
     IssueStatus,
@@ -469,7 +470,74 @@ async def run_product_check(product_slug: str) -> dict:
             actions_taken.append(f"Created issue for KR: {kr_title}")
             all_issues.append(issue)  # prevent duplicate creation in same cycle
 
-    # --- Step 3: Check if owner review is needed ---
+    # --- Step 3: Sprint expiry check ---
+    from datetime import date as _date
+
+    active_sprint = prod.get_active_sprint(product_slug)
+    if active_sprint:
+        end_date_str = active_sprint.get("end_date", "")
+        try:
+            end_date = _date.fromisoformat(end_date_str)
+            if _date.today() > end_date:
+                actions_taken.append(f"Sprint '{active_sprint['name']}' expired on {end_date_str}")
+        except (ValueError, TypeError):
+            logger.debug("[PRODUCT_CHECK] Invalid end_date '{}' on sprint {}", end_date_str, active_sprint.get("id"))
+
+    # --- Step 4: Backlog grooming reminder ---
+    _BACKLOG_GROOMING_THRESHOLD = 5
+    unscheduled_low = [
+        i for i in all_issues
+        if i.get("priority") in (IssuePriority.P2.value, IssuePriority.P3.value)
+        and not i.get("sprint")
+        and i.get("status") not in (IssueStatus.DONE.value, IssueStatus.RELEASED.value)
+    ]
+    if len(unscheduled_low) >= _BACKLOG_GROOMING_THRESHOLD:
+        actions_taken.append(f"{len(unscheduled_low)} P2/P3 issues unscheduled — backlog grooming needed")
+
+    # --- Step 5: Stale review check (open > 24h) ---
+    from datetime import datetime as _datetime, timedelta as _timedelta
+
+    open_reviews = prod.list_reviews(product_slug, status="open")
+    _STALE_REVIEW_HOURS = 24
+    stale_reviews = []
+    for rev in open_reviews:
+        try:
+            created = _datetime.fromisoformat(rev.get("created_at", ""))
+            if _datetime.now() - created > _timedelta(hours=_STALE_REVIEW_HOURS):
+                stale_reviews.append(rev)
+        except (ValueError, TypeError):
+            logger.debug("[PRODUCT_CHECK] Invalid created_at on review {}", rev.get("id"))
+    if stale_reviews:
+        actions_taken.append(f"{len(stale_reviews)} stale review(s) open > {_STALE_REVIEW_HOURS}h")
+
+    # --- Step 6: Blocked issue check (blocked > 7 days) ---
+    _BLOCKED_DAYS_THRESHOLD = 7
+    for issue in all_issues:
+        if issue.get("status") in (IssueStatus.DONE.value, IssueStatus.RELEASED.value):
+            continue
+        links = issue.get("issue_links", [])
+        blocked_links = [
+            link for link in links
+            if link["relation"] == IssueRelation.BLOCKED_BY.value
+            and _is_blocker_unresolved(product_slug, link["issue_id"])
+        ]
+        if not blocked_links:
+            continue
+        # Use the oldest blocked_by link's created_at to determine how long blocked
+        oldest_blocked_at = None
+        for link in blocked_links:
+            try:
+                link_created = _datetime.fromisoformat(link.get("created_at", ""))
+                if oldest_blocked_at is None or link_created < oldest_blocked_at:
+                    oldest_blocked_at = link_created
+            except (ValueError, TypeError):
+                logger.debug("[PRODUCT_CHECK] Invalid created_at on link in issue {}", issue.get("id"))
+        if oldest_blocked_at and _datetime.now() - oldest_blocked_at > _timedelta(days=_BLOCKED_DAYS_THRESHOLD):
+            actions_taken.append(
+                f"Issue '{issue['title']}' blocked for >{_BLOCKED_DAYS_THRESHOLD} days"
+            )
+
+    # --- Step 7: Check if owner review is needed ---
     # Conditions: backlog issues with no one working, or KRs at 0% with completed projects
     needs_review = False
     review_reasons = []
@@ -491,6 +559,26 @@ async def run_product_check(product_slug: str) -> dict:
         needs_review = True
         review_reasons.append(f"{len(stale_krs)} KRs at 0% despite {len(completed_projects)} completed projects")
 
+    # Sprint expired → needs owner review
+    if active_sprint:
+        try:
+            end_date = _date.fromisoformat(active_sprint.get("end_date", ""))
+            if _date.today() > end_date:
+                needs_review = True
+                review_reasons.append(f"Sprint '{active_sprint['name']}' expired")
+        except (ValueError, TypeError):
+            logger.debug("[PRODUCT_CHECK] Invalid end_date on sprint {} for review check", active_sprint.get("id"))
+
+    # Backlog grooming threshold → needs owner review
+    if len(unscheduled_low) >= _BACKLOG_GROOMING_THRESHOLD:
+        needs_review = True
+        review_reasons.append(f"{len(unscheduled_low)} P2/P3 issues need sprint assignment")
+
+    # Stale reviews → needs owner review
+    if stale_reviews:
+        needs_review = True
+        review_reasons.append(f"{len(stale_reviews)} stale review(s) pending")
+
     if needs_review:
         reason = "; ".join(review_reasons)
         notified = await notify_owner(product_slug, reason=reason)
@@ -581,6 +669,38 @@ async def handle_issue_assigned(event: CompanyEvent) -> None:
         )
 
 
+def _is_blocker_unresolved(slug: str, issue_id: str) -> bool:
+    """Check if a blocker issue is still unresolved (not done/released)."""
+    blocker = prod.load_issue(slug, issue_id)
+    if not blocker:
+        return False
+    return blocker.get("status") not in (IssueStatus.DONE.value, IssueStatus.RELEASED.value)
+
+
+async def handle_sprint_closed(event: CompanyEvent) -> None:
+    """When a sprint is closed, auto-create a review checklist for the product owner."""
+    slug = event.payload.get("product_slug", "")
+    sprint_id = event.payload.get("sprint_id", "")
+
+    if not slug:
+        logger.debug("[PRODUCT_TRIGGER] handle_sprint_closed: no product_slug, skip")
+        return
+
+    product = prod.load_product(slug)
+    if not product:
+        logger.warning("[PRODUCT_TRIGGER] handle_sprint_closed: product '{}' not found", slug)
+        return
+
+    owner_id = product.get("owner_id", "")
+    prod.create_review(
+        slug=slug,
+        trigger="sprint_closed",
+        trigger_ref=sprint_id,
+        owner=owner_id,
+    )
+    logger.info("[PRODUCT_TRIGGER] Auto-created review for sprint {} in {}", sprint_id, slug)
+
+
 # ---------------------------------------------------------------------------
 # Registration
 # ---------------------------------------------------------------------------
@@ -610,6 +730,8 @@ def register_product_triggers() -> "asyncio.Task":
                     # Only handle if it has product context
                     if event.payload.get("product_slug"):
                         await handle_project_complete(event)
+                elif event.type == EventType.SPRINT_CLOSED:
+                    await handle_sprint_closed(event)
             except Exception:
                 logger.exception(
                     "[PRODUCT_TRIGGER] Error handling event {}", event.type