@flydocs/cli 0.6.0-alpha.3 → 0.6.0-alpha.30

package/template/.claude/skills/flydocs-workflow/reference/service-descriptor-schema.md

@@ -0,0 +1,260 @@
+# Service Descriptor Schema
+
+Reference for `flydocs/context/service.json` — the dual-purpose descriptor that
+provides cross-repo context AND intra-repo orientation.
+
+## Purpose
+
+The service descriptor serves two roles from a single file:
+
+- **Cross-repo export** — `apis`, `dependencies`, `purpose`, `stack` tell
+  sibling repos what this service does and how it connects. Stored by relay,
+  queried by workspace composite.
+- **Intra-repo orientation** — `structure` section tells THIS repo's agent
+  where things are: entry points, shared types, build system, package boundaries.
+  Not exported cross-repo.
+
+Generated by the user's coding agent during `/flydocs-setup` Phase 1.5, or by the
+server-side AI scanning pipeline (v2).
+
+## Schema
+
+```typescript
+interface ServiceDescriptor {
+  version: 1 | 2;
+  name: string; // Human-readable service name
+  repoSlug: string; // owner/repo format (matches workspace.repoSlug)
+  purpose: string; // One-sentence description of what this service does
+  stack: string[]; // Key technologies: ["next", "convex", "typescript"]
+
+  // Cross-repo export surface (what siblings see)
+  apis: ApiSurface[];
+  dependencies: ServiceDependency[];
+
+  // Intra-repo orientation (what THIS repo's agent uses)
+  structure: ServiceStructure;
+
+  // v2 fields (present when version is 2, optional for backward compat)
+  generatedBy?: "server" | "agent"; // Who generated this descriptor
+  generatedAt?: string; // ISO 8601 timestamp of generation
+}
+
+interface ApiSurface {
+  type: "rest" | "graphql" | "grpc" | "event" | "package";
+  path: string; // Route prefix, event topic, or package path
+  description: string; // What this API surface does
+  methods?: string[]; // HTTP methods for REST (optional)
+}
+
+interface ServiceDependency {
+  service: string; // Repo slug or service name of the dependency
+  interface: string; // What interface is consumed (e.g., "REST /api/relay/*")
+  description: string; // Why this dependency exists
+}
+
+interface ServiceStructure {
+  entryPoints: string[]; // Where request handling or app logic starts
+  sharedTypes: string[]; // Where shared type definitions live
+  buildSystem: string; // "turbo", "nx", "next", "tsup", "vite", "cargo", etc.
+  packages?: PackageInfo[]; // Monorepo only: name, path, purpose per package
+}
+
+interface PackageInfo {
+  name: string; // Package name (e.g., "@flydocs/cli")
+  path: string; // Relative path from repo root
+  purpose: string; // What this package does
+}
+```
+
+## Field Notes
+
+- `version` is `1` (agent-generated, legacy) or `2` (supports server generation).
+  All consumers accept both versions. The v2 fields are additive — v1 descriptors
+  remain valid and fully functional.
+- `repoSlug` must match the slug registered in the workspace dashboard.
+- `structure` is local-only — not pushed to relay or included in workspace composite.
+- `apis` and `dependencies` create PROVIDES/CONSUMES edges in the graph.
+- `stack` is a flat array of lowercase identifiers (framework names, languages).
+- `generatedBy` distinguishes server-generated (AI scanning pipeline) from
+  agent-generated (local `/flydocs-setup`) descriptors. Absent on v1 descriptors.
+- `generatedAt` tracks freshness for server-generated descriptors. ISO 8601 format.
+
+## Examples
+
+### Example 1: Single-App CLI Tool (Type 1)
+
+```json
+{
+  "version": 1,
+  "name": "FlyDocs CLI",
+  "repoSlug": "plastrlab/flydocs-core",
+  "purpose": "CLI tool that installs and manages FlyDocs skill templates, hooks, and configuration in user projects",
+  "stack": ["typescript", "node", "commander"],
+  "apis": [
+    {
+      "type": "package",
+      "path": "@flydocs/cli",
+      "description": "npm package providing the flydocs CLI binary"
+    }
+  ],
+  "dependencies": [
+    {
+      "service": "plastrlab/flydocs-app",
+      "interface": "REST /api/relay/*",
+      "description": "Cloud tier pushes config, descriptors, and issue operations to relay API"
+    }
+  ],
+  "structure": {
+    "entryPoints": ["src/cli.ts"],
+    "sharedTypes": ["src/lib/types.ts"],
+    "buildSystem": "tsup"
+  }
+}
+```
+
+### Example 2: Full-Stack Web App (Type 1)
+
+```json
+{
+  "version": 1,
+  "name": "FlyDocs App",
+  "repoSlug": "plastrlab/flydocs-app",
+  "purpose": "Web dashboard and relay API for FlyDocs cloud tier — workspace management, issue relay, and service descriptor storage",
+  "stack": ["next", "react", "convex", "typescript", "tailwind"],
+  "apis": [
+    {
+      "type": "rest",
+      "path": "/api/relay",
+      "description": "Relay API for CLI operations — config generation, issue proxy, service descriptors",
+      "methods": ["GET", "POST", "PUT", "PATCH"]
+    },
+    {
+      "type": "rest",
+      "path": "/api/auth",
+      "description": "Authentication endpoints for CLI and dashboard login",
+      "methods": ["GET", "POST"]
+    }
+  ],
+  "dependencies": [
+    {
+      "service": "linear",
+      "interface": "GraphQL API",
+      "description": "Issue tracker backend — all issue CRUD proxied through relay"
+    },
+    {
+      "service": "convex",
+      "interface": "Convex functions",
+      "description": "Real-time database for workspaces, repos, user state"
+    }
+  ],
+  "structure": {
+    "entryPoints": ["src/app/api/", "convex/"],
+    "sharedTypes": ["src/types/", "convex/schema.ts"],
+    "buildSystem": "next"
+  }
+}
+```
+
+### Example 3: Monorepo Multi-Service (Type 3)
+
+```json
+{
+  "version": 1,
+  "name": "Acme Platform",
+  "repoSlug": "acme/platform",
+  "purpose": "Monorepo containing API server, worker service, and shared packages for the Acme SaaS platform",
+  "stack": ["typescript", "express", "prisma", "redis", "turborepo"],
+  "apis": [
+    {
+      "type": "rest",
+      "path": "/api/v2",
+      "description": "Public REST API for client applications",
+      "methods": ["GET", "POST", "PUT", "DELETE"]
+    },
+    {
+      "type": "event",
+      "path": "jobs.*",
+      "description": "Redis pub/sub events consumed by worker service"
+    },
+    {
+      "type": "package",
+      "path": "@acme/sdk",
+      "description": "Published TypeScript SDK for API consumers"
+    }
+  ],
+  "dependencies": [
+    {
+      "service": "stripe",
+      "interface": "REST API + webhooks",
+      "description": "Payment processing and subscription management"
+    },
+    {
+      "service": "acme/marketing-site",
+      "interface": "REST /api/v2/pricing",
+      "description": "Marketing site fetches pricing data from API"
+    }
+  ],
+  "structure": {
+    "entryPoints": ["apps/api/src/server.ts", "apps/worker/src/index.ts"],
+    "sharedTypes": ["packages/shared/src/types/"],
+    "buildSystem": "turbo",
+    "packages": [
+      {
+        "name": "@acme/api",
+        "path": "apps/api",
+        "purpose": "Express API server — handles all client requests"
+      },
+      {
+        "name": "@acme/worker",
+        "path": "apps/worker",
+        "purpose": "Background job processor — email, billing, data sync"
+      },
+      {
+        "name": "@acme/shared",
+        "path": "packages/shared",
+        "purpose": "Shared types, utilities, and validation schemas"
+      },
+      {
+        "name": "@acme/sdk",
+        "path": "packages/sdk",
+        "purpose": "Published TypeScript SDK for external API consumers"
+      }
+    ]
+  }
+}
+```
+
+## Graph Integration
+
+When `graph_build.py` processes `service.json`:
+
+1. Creates a `repo:{repoSlug}` node with `purpose` and `stack` as properties
+2. For each entry in `apis`: creates a PROVIDES edge from this repo to any
+   repo that lists it in their `dependencies`
+3. For each entry in `dependencies`: creates a CONSUMES edge from this repo
+   to the dependency's repo node
+4. Edge properties include `interface` and `description` from the source data
+
+Cross-repo edges are only created when both repos have service descriptors in
+the graph (either from local sibling reads or relay workspace composite).
+
+## Relay Integration
+
+- **Push:** `push_service.py` sends this repo's descriptor via
+  `PUT /api/relay/workspace/service` (excludes `structure` section)
+- **Pull:** `pull_services.py` fetches workspace composite via
+  `GET /api/relay/workspace/services` (returns all repos with descriptors)
+- **Local fallback:** Read sibling `flydocs/context/service.json` files directly
+
+## Topology Context
+
+The service descriptor works alongside topology detection (stored in config).
+Topology tells the agent HOW repos are laid out; the descriptor tells it WHAT
+each repo does and how they connect.
+
+| Topology Type | Layout                  | Detection Signal                             |
+| ------------- | ----------------------- | -------------------------------------------- |
+| 1             | Single repo, single app | One `.git`, no workspace config              |
+| 2             | Monorepo, single app    | One `.git`, one root app                     |
+| 3             | Monorepo, multi-service | One `.git`, workspace config (pnpm/nx/turbo) |
+| 4             | Sibling repos           | Parent dir has multiple `.git` children      |

package/template/.claude/skills/flydocs-workflow/reference/status-workflow.md

@@ -10,41 +10,41 @@ BACKLOG ──→ READY ──→ IMPLEMENTING ──→ REVIEW ──→ TESTIN
 
 ## State Meanings
 
-| FlyDocs State | Intent | Assignment Required |
-|---------------|--------|---------------------|
-| BACKLOG | Raw capture, not yet refined | No |
-| READY | Refined spec, ready to pick up | No |
-| IMPLEMENTING | Active work in progress | **Yes** |
-| BLOCKED | Cannot proceed, waiting on resolution | Yes |
-| REVIEW | Code complete, awaiting quality review | Yes |
-| TESTING | Review passed, awaiting user acceptance | Yes |
-| COMPLETE | All stages passed, work delivered | Yes |
+| FlyDocs State | Intent                                  | Assignment Required |
+| ------------- | --------------------------------------- | ------------------- |
+| BACKLOG       | Raw capture, not yet refined            | No                  |
+| READY         | Refined spec, ready to pick up          | No                  |
+| IMPLEMENTING  | Active work in progress                 | **Yes**             |
+| BLOCKED       | Cannot proceed, waiting on resolution   | Yes                 |
+| REVIEW        | Code complete, awaiting quality review  | Yes                 |
+| TESTING       | Review passed, awaiting user acceptance | Yes                 |
+| COMPLETE      | All stages passed, work delivered       | Yes                 |
 
 ## Valid Transitions
 
-| From | To | Trigger |
-|------|----|---------|
-| BACKLOG | READY | Refine stage completes |
-| READY | IMPLEMENTING | Activate stage completes |
-| IMPLEMENTING | REVIEW | Implement stage completes |
-| IMPLEMENTING | BLOCKED | Blocker identified |
-| BLOCKED | IMPLEMENTING | Blocker resolved |
-| REVIEW | TESTING | Code review passes |
-| REVIEW | IMPLEMENTING | Code review finds issues |
-| TESTING | COMPLETE | QE approves, PM closes |
-| TESTING | IMPLEMENTING | QE finds issues |
+| From         | To           | Trigger                   |
+| ------------ | ------------ | ------------------------- |
+| BACKLOG      | READY        | Refine stage completes    |
+| READY        | IMPLEMENTING | Activate stage completes  |
+| IMPLEMENTING | REVIEW       | Implement stage completes |
+| IMPLEMENTING | BLOCKED      | Blocker identified        |
+| BLOCKED      | IMPLEMENTING | Blocker resolved          |
+| REVIEW       | TESTING      | Code review passes        |
+| REVIEW       | IMPLEMENTING | Code review finds issues  |
+| TESTING      | COMPLETE     | QE approves, PM closes    |
+| TESTING      | IMPLEMENTING | QE finds issues           |
 
 ## Terminal States
 
-| State | When |
-|-------|------|
+| State           | When                        |
+| --------------- | --------------------------- |
 | COMPLETE (Done) | Work delivered and verified |
-| ARCHIVED | Deferred — may return later |
-| CANCELED | Not pursuing |
-| DUPLICATE | See referenced issue |
+| ARCHIVED        | Deferred — may return later |
+| CANCELED        | Not pursuing                |
+| DUPLICATE       | See referenced issue        |
 
 ## Provider Mapping
 
-FlyDocs states are provider-agnostic. The mechanism skill maps them to provider-specific
+FlyDocs states are provider-agnostic. The workflow scripts map them to provider-specific
 state names via `statusMapping` in `.flydocs/config.json`. The workflow never references
 provider-specific names directly.

package/template/.claude/skills/{flydocs-local/scripts/flydocs_api.py → flydocs-workflow/scripts/_local/file_store.py}

@@ -1,11 +1,15 @@
-"""FlyDocs Local API — filesystem-based issue management."""
+"""FlyDocs Local Backend — filesystem-based issue management.
+
+All local tier operations are implemented here. The unified client
+delegates to this module when tier is "local".
+"""
 
 import json
-import os
 import re
 from datetime import datetime
 from pathlib import Path
 
+
 # Status directories map to workflow states
 STATUSES = {
     "BACKLOG": "backlog",
@@ -23,33 +27,28 @@ STATUSES = {
 ISSUE_TYPES = {"feature", "bug", "chore", "idea"}
 
 
-def _issues_root() -> Path:
-    """Find flydocs/issues/ relative to repo root."""
-    cwd = Path.cwd()
-    # Walk up to find .flydocs/config.json
-    for parent in [cwd, *cwd.parents]:
-        if (parent / ".flydocs" / "config.json").exists():
-            root = parent / "flydocs" / "issues"
-            root.mkdir(parents=True, exist_ok=True)
-            return root
-    raise RuntimeError("Not in a FlyDocs project (no .flydocs/config.json found)")
+def _issues_root(project_root: Path) -> Path:
+    """Find flydocs/issues/ relative to project root."""
+    root = project_root / "flydocs" / "issues"
+    root.mkdir(parents=True, exist_ok=True)
+    return root
 
 
-def _ensure_dirs() -> Path:
+def _ensure_dirs(project_root: Path) -> Path:
     """Ensure all status directories exist."""
-    root = _issues_root()
+    root = _issues_root(project_root)
     for dirname in set(STATUSES.values()):
         (root / dirname).mkdir(exist_ok=True)
     return root
 
 
-def _counter_path() -> Path:
-    return _issues_root().parent.parent / ".flydocs" / "issues.counter"
+def _counter_path(project_root: Path) -> Path:
+    return project_root / ".flydocs" / "issues.counter"
 
 
-def _next_id() -> str:
+def _next_id(project_root: Path) -> str:
     """Auto-increment and return next FD-XXX identifier."""
-    path = _counter_path()
+    path = _counter_path(project_root)
     path.parent.mkdir(parents=True, exist_ok=True)
     current = int(path.read_text().strip()) if path.exists() else 0
     next_num = current + 1
@@ -76,7 +75,6 @@ def _parse_issue(filepath: Path) -> dict:
         if ":" in line:
             key, val = line.split(":", 1)
             val = val.strip()
-            # Handle numeric values
             if val.isdigit():
                 val = int(val)
             frontmatter[key.strip()] = val
@@ -96,9 +94,9 @@ def _parse_issue(filepath: Path) -> dict:
     return {**frontmatter, "description": description, "comments": comments, "_path": filepath}
 
 
-def _find_issue(ref: str) -> Path:
-    """Find an issue file by its identifier (e.g., FD-001) across all directories."""
-    root = _issues_root()
+def _find_issue(project_root: Path, ref: str) -> Path:
+    """Find an issue file by its identifier across all directories."""
+    root = _issues_root(project_root)
     prefix = ref.upper() + "-"
     for dirname in set(STATUSES.values()):
         dirpath = root / dirname
@@ -128,11 +126,14 @@ def _write_issue(filepath: Path, frontmatter: dict, description: str, comments:
     filepath.write_text("".join(parts) + "\n")
 
 
-def create_issue(title: str, issue_type: str, description: str = "",
+# --- Public API (matches relay backend interface) ---
+
+
+def create_issue(project_root: Path, title: str, issue_type: str, description: str = "",
                  priority: int = 3, estimate: int = 0,
-                 assignee: str = "", triage: bool = False) -> dict:
-    root = _ensure_dirs()
-    identifier = _next_id()
+                 assignee: str = "", triage: bool = False, **_kwargs: object) -> dict:
+    root = _ensure_dirs(project_root)
+    identifier = _next_id(project_root)
     slug = _slugify(title)
     filename = f"{identifier}-{slug}.md"
     now = datetime.now().strftime("%Y-%m-%d")
@@ -152,22 +153,22 @@ def create_issue(title: str, issue_type: str, description: str = "",
         frontmatter["triage"] = "true"
 
     _write_issue(filepath, frontmatter, description or f"## Context\n\n{title}", [])
-    return {"id": identifier, "identifier": identifier, "title": title}
+    return {"id": identifier, "identifier": identifier, "title": title, "url": ""}
 
 
-def transition(ref: str, new_status: str, comment: str) -> dict:
-    filepath = _find_issue(ref)
+def transition(project_root: Path, ref: str, status: str, comment: str) -> dict:
+    filepath = _find_issue(project_root, ref)
     data = _parse_issue(filepath)
     prev_status = _status_from_path(filepath)
 
+    new_status = status.upper()
     if new_status not in STATUSES:
         raise ValueError(f"Invalid status: {new_status}. Valid: {', '.join(STATUSES.keys())}")
 
-    target_dir = _issues_root() / STATUSES[new_status]
+    target_dir = _issues_root(project_root) / STATUSES[new_status]
     target_dir.mkdir(exist_ok=True)
     new_path = target_dir / filepath.name
 
-    # Append transition comment
     now = datetime.now().strftime("%Y-%m-%d %H:%M")
     data["comments"].append(f"**{new_status}** — {comment}\n_{now}_")
     data["updated"] = datetime.now().strftime("%Y-%m-%d")
@@ -180,11 +181,11 @@ def transition(ref: str, new_status: str, comment: str) -> dict:
     return {"success": True, "issue": ref, "previousStatus": prev_status, "newStatus": new_status}
 
 
-def add_comment(ref: str, comment: str) -> dict:
-    filepath = _find_issue(ref)
+def add_comment(project_root: Path, ref: str, body: str) -> dict:
+    filepath = _find_issue(project_root, ref)
     data = _parse_issue(filepath)
     now = datetime.now().strftime("%Y-%m-%d %H:%M")
-    data["comments"].append(f"{comment}\n_{now}_")
+    data["comments"].append(f"{body}\n_{now}_")
     data["updated"] = datetime.now().strftime("%Y-%m-%d")
 
     fm = {k: v for k, v in data.items() if k not in ("description", "comments", "_path")}
@@ -192,9 +193,10 @@ def add_comment(ref: str, comment: str) -> dict:
     return {"success": True, "commentId": len(data["comments"])}
 
 
-def list_issues(status: str = "", assignee: str = "", limit: int = 50) -> list[dict]:
-    root = _issues_root()
-    results = []
+def list_issues(project_root: Path, status: str = "", assignee: str = "",
+                limit: int = 50, **_kwargs: object) -> list[dict]:
+    root = _issues_root(project_root)
+    results: list[dict] = []
     dirs_to_scan = [STATUSES[status]] if status and status in STATUSES else list(set(STATUSES.values()))
 
     for dirname in dirs_to_scan:
@@ -220,8 +222,8 @@ def list_issues(status: str = "", assignee: str = "", limit: int = 50) -> list[d
     return results
 
 
-def get_issue(ref: str) -> dict:
-    filepath = _find_issue(ref)
+def get_issue(project_root: Path, ref: str, **_kwargs: object) -> dict:
+    filepath = _find_issue(project_root, ref)
     data = _parse_issue(filepath)
     return {
         "id": data.get("id", ""),
@@ -236,10 +238,13 @@ def get_issue(ref: str) -> dict:
     }
 
 
-def assign_issue(ref: str, assignee: str) -> dict:
-    filepath = _find_issue(ref)
+def assign_issue(project_root: Path, ref: str, assignee: str | None) -> dict:
+    filepath = _find_issue(project_root, ref)
     data = _parse_issue(filepath)
-    data["assignee"] = assignee
+    if assignee is None:
+        data.pop("assignee", None)
+    else:
+        data["assignee"] = assignee
     data["updated"] = datetime.now().strftime("%Y-%m-%d")
 
     fm = {k: v for k, v in data.items() if k not in ("description", "comments", "_path")}
@@ -247,8 +252,8 @@ def assign_issue(ref: str, assignee: str) -> dict:
     return {"success": True, "issue": ref, "assignee": assignee}
 
 
-def update_description(ref: str, text: str) -> dict:
-    filepath = _find_issue(ref)
+def update_description(project_root: Path, ref: str, text: str) -> dict:
+    filepath = _find_issue(project_root, ref)
     data = _parse_issue(filepath)
     data["updated"] = datetime.now().strftime("%Y-%m-%d")
 
@@ -257,9 +262,94 @@ def update_description(ref: str, text: str) -> dict:
     return {"success": True, "issue": ref}
 
 
-def status_summary() -> dict:
-    root = _issues_root()
-    counts = {}
+def update_issue(project_root: Path, ref: str, **fields: object) -> dict:
+    """Bulk update — set multiple fields on an issue."""
+    filepath = _find_issue(project_root, ref)
+    data = _parse_issue(filepath)
+    updated: list[str] = []
+
+    # Handle state transition separately
+    state = fields.get("state")
+    comment = fields.get("comment")
+    if state and isinstance(state, str):
+        result = transition(project_root, ref, state, str(comment or f"Transitioned to {state}"))
+        updated.append("state")
+        # Re-find the file after transition (it may have moved)
+        filepath = _find_issue(project_root, ref)
+        data = _parse_issue(filepath)
+
+    # Handle comment separately (if no state transition already handled it)
+    if comment and isinstance(comment, str) and "state" not in updated:
+        add_comment(project_root, ref, comment)
+        updated.append("comment")
+        data = _parse_issue(filepath)
+
+    # Update simple fields
+    for field in ("title", "priority", "estimate", "assignee"):
+        val = fields.get(field)
+        if val is not None:
+            data[field] = val
+            updated.append(field)
+
+    # Update description
+    desc = fields.get("description")
+    if desc and isinstance(desc, str):
+        data["description"] = desc
+        updated.append("description")
+
+    data["updated"] = datetime.now().strftime("%Y-%m-%d")
+    fm = {k: v for k, v in data.items() if k not in ("description", "comments", "_path")}
+    _write_issue(filepath, fm, data.get("description", ""), data.get("comments", []))
+
+    return {"success": True, "issue": ref, "updated": updated}
+
+
+def estimate_issue(project_root: Path, ref: str, estimate: int) -> dict:
+    filepath = _find_issue(project_root, ref)
+    data = _parse_issue(filepath)
+    data["estimate"] = estimate
+    data["updated"] = datetime.now().strftime("%Y-%m-%d")
+
+    fm = {k: v for k, v in data.items() if k not in ("description", "comments", "_path")}
+    _write_issue(filepath, fm, data["description"], data.get("comments", []))
+    return {"success": True, "issue": ref, "estimate": estimate}
+
+
+def priority_issue(project_root: Path, ref: str, priority: int) -> dict:
+    filepath = _find_issue(project_root, ref)
+    data = _parse_issue(filepath)
+    data["priority"] = priority
+    data["updated"] = datetime.now().strftime("%Y-%m-%d")
+
+    fm = {k: v for k, v in data.items() if k not in ("description", "comments", "_path")}
+    _write_issue(filepath, fm, data["description"], data.get("comments", []))
+    return {"success": True, "issue": ref, "priority": priority}
+
+
+def link_issues(project_root: Path, ref: str, related_ref: str, link_type: str) -> dict:
+    add_comment(project_root, ref, f"Linked ({link_type}): {related_ref}")
+    add_comment(project_root, related_ref, f"Linked ({link_type}): {ref}")
+    return {"success": True, "type": link_type}
+
+
+def project_update(project_root: Path, health: str, body: str, **_kwargs: object) -> dict:
+    """Write a project update as a markdown file."""
+    updates_dir = project_root / "flydocs" / "updates"
+    updates_dir.mkdir(parents=True, exist_ok=True)
+
+    now = datetime.now()
+    timestamp = now.strftime("%Y%m%d-%H%M%S")
+    filename = f"{timestamp}.md"
+
+    content = f"---\nhealth: {health}\ndate: {now.strftime('%Y-%m-%d')}\n---\n\n{body}\n"
+    (updates_dir / filename).write_text(content)
+
+    return {"success": True, "id": timestamp}
+
+
+def status_summary(project_root: Path) -> dict:
+    root = _issues_root(project_root)
+    counts: dict[str, int] = {}
     total = 0
     for status, dirname in STATUSES.items():
         dirpath = root / dirname