docs: define Sprint Management Dashboard MVP scope (#14)

profile/README.md

@@ -1,3 +1,10 @@
 # UbiquityOS
 
-The operating system for the organizations of tomorrow. We host plugins which extend the capabilities of the UbiquityOS system at the [UbiquityOS Marketplace](https://github.com/ubiquity-os-marketplace).
+The operating system for the organizations of tomorrow. We host plugins which extend the capabilities of the UbiquityOS system at the [UbiquityOS Marketplace](https://github.com/ubiquity-os-marketplace).
+
+## Planning Docs
+
+- [Sprint Management Dashboard MVP (Issue #14)](./sprint-management-dashboard-mvp.md)
+- [PR-1 Implementation Scaffold](./pr1-scaffold/README.md)
+- [PR-2 Core Scaffold](./pr2-core/README.md)
+- [PR-3 Dashboard Contract Scaffold](./pr3-dashboard/README.md)

profile/pr1-scaffold/README.md

@@ -0,0 +1,25 @@
+# PR-1 Implementation Scaffold (Issue #14)
+
+This scaffold is the implementation baseline for:
+
+- Landing page conversion flow
+- GitHub OAuth + organization connect
+- Initial ingestion job skeleton
+
+## What this scaffold provides
+
+1. **API contract draft** (`openapi.yaml`)
+2. **Database schema draft** (`schema.sql`)
+3. **Delivery checklist** (`checklist.md`)
+
+## Proposed stack (suggested)
+
+- Frontend: Next.js + Tailwind
+- Backend API: Next.js route handlers or Node/Fastify
+- DB: PostgreSQL
+- Queue: Redis + BullMQ (or equivalent)
+- Auth: GitHub OAuth App
+
+## Implementation target
+
+A manager should complete first setup in < 10 minutes and trigger the first ingestion job in one flow.

profile/pr1-scaffold/checklist.md

@@ -0,0 +1,26 @@
+# PR-1 Delivery Checklist
+
+## A. Landing + conversion
+- [ ] Hero section with clear manager-focused value prop
+- [ ] Single primary CTA: Sign in with GitHub
+- [ ] Lightweight metrics/social proof placeholders
+
+## B. Authentication
+- [ ] GitHub OAuth app configured
+- [ ] `/auth/github/start` + `/auth/github/callback` implemented
+- [ ] Session token issuance and secure cookie handling
+
+## C. Organization connect
+- [ ] Load authenticated user's GitHub orgs
+- [ ] Multi-select repositories for first ingestion
+- [ ] Trigger ingestion job and show job state
+
+## D. Ingestion skeleton
+- [ ] Queue worker receives org/repo payload
+- [ ] Fetch open issues metadata from GitHub API
+- [ ] Persist issue snapshot and member signals
+
+## E. Definition of done
+- [ ] New user can go from landing to job queued without manual DB/API steps
+- [ ] Basic logs and error handling exist for each onboarding step
+- [ ] README includes local run instructions

profile/pr1-scaffold/openapi.yaml

@@ -0,0 +1,140 @@
+openapi: 3.1.0
+info:
+  title: UbiquityOS Sprint Dashboard API (PR-1 Scaffold)
+  version: 0.1.0
+servers:
+  - url: https://api.example.com
+paths:
+  /auth/github/start:
+    get:
+      summary: Start GitHub OAuth login
+      responses:
+        '302':
+          description: Redirect to GitHub authorization page
+
+  /auth/github/callback:
+    get:
+      summary: OAuth callback endpoint
+      parameters:
+        - in: query
+          name: code
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Auth successful
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AuthSession'
+
+  /orgs:
+    get:
+      summary: List organizations available to current user
+      responses:
+        '200':
+          description: Organization list
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Organization'
+
+  /orgs/{orgId}/connect:
+    post:
+      summary: Connect organization and select repositories for ingestion
+      parameters:
+        - in: path
+          name: orgId
+          required: true
+          schema:
+            type: string
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              required: [repositories]
+              properties:
+                repositories:
+                  type: array
+                  items:
+                    type: string
+      responses:
+        '202':
+          description: Connection accepted and ingestion enqueued
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/JobAck'
+
+  /ingestion/jobs/{jobId}:
+    get:
+      summary: Poll ingestion job status
+      parameters:
+        - in: path
+          name: jobId
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Job status
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IngestionJobStatus'
+
+components:
+  schemas:
+    AuthSession:
+      type: object
+      required: [userId, accessToken]
+      properties:
+        userId:
+          type: string
+        accessToken:
+          type: string
+        expiresAt:
+          type: string
+          format: date-time
+
+    Organization:
+      type: object
+      required: [id, login, name]
+      properties:
+        id:
+          type: string
+        login:
+          type: string
+        name:
+          type: string
+
+    JobAck:
+      type: object
+      required: [jobId, status]
+      properties:
+        jobId:
+          type: string
+        status:
+          type: string
+          enum: [queued]
+
+    IngestionJobStatus:
+      type: object
+      required: [jobId, status, progress]
+      properties:
+        jobId:
+          type: string
+        status:
+          type: string
+          enum: [queued, running, completed, failed]
+        progress:
+          type: number
+          minimum: 0
+          maximum: 100
+        message:
+          type: string

profile/pr1-scaffold/schema.sql

@@ -0,0 +1,46 @@
+-- PR-1 scaffold schema for Sprint Dashboard onboarding
+
+create table if not exists users (
+  id uuid primary key,
+  github_user_id text unique not null,
+  github_login text not null,
+  created_at timestamptz default now()
+);
+
+create table if not exists organizations (
+  id uuid primary key,
+  github_org_id text unique not null,
+  github_login text not null,
+  display_name text,
+  created_at timestamptz default now()
+);
+
+create table if not exists organization_memberships (
+  id uuid primary key,
+  user_id uuid not null references users(id) on delete cascade,
+  organization_id uuid not null references organizations(id) on delete cascade,
+  role text not null default 'member',
+  created_at timestamptz default now(),
+  unique(user_id, organization_id)
+);
+
+create table if not exists repositories (
+  id uuid primary key,
+  organization_id uuid not null references organizations(id) on delete cascade,
+  github_repo_id text unique not null,
+  owner_login text not null,
+  name text not null,
+  full_name text not null,
+  created_at timestamptz default now()
+);
+
+create table if not exists ingestion_jobs (
+  id uuid primary key,
+  organization_id uuid not null references organizations(id) on delete cascade,
+  requested_by uuid not null references users(id) on delete cascade,
+  status text not null check (status in ('queued','running','completed','failed')),
+  progress numeric(5,2) not null default 0,
+  message text,
+  created_at timestamptz default now(),
+  updated_at timestamptz default now()
+);

profile/pr2-core/README.md

@@ -0,0 +1,9 @@
+# PR-2 Core Scaffold (Issue #14)
+
+This package defines the **implementation-ready core** for:
+
+1. ingestion pipeline,
+2. sprint planning engine,
+3. dashboard-facing output contracts.
+
+It is intentionally framework-agnostic so implementation can happen in the most suitable runtime repo.

profile/pr2-core/contracts.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "SprintPlanItem",
+  "type": "object",
+  "required": [
+    "issueId",
+    "repository",
+    "title",
+    "priority",
+    "effortHours",
+    "recommendedAssignee",
+    "confidence",
+    "reasons"
+  ],
+  "properties": {
+    "issueId": { "type": "string" },
+    "repository": { "type": "string" },
+    "title": { "type": "string" },
+    "priority": {
+      "type": "string",
+      "enum": ["low", "normal", "high", "urgent"]
+    },
+    "effortHours": { "type": "number", "minimum": 0 },
+    "recommendedAssignee": { "type": "string" },
+    "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+    "reasons": {
+      "type": "array",
+      "items": { "type": "string" },
+      "minItems": 1
+    }
+  }
+}

profile/pr2-core/ingestion-pipeline.md

@@ -0,0 +1,38 @@
+# Ingestion Pipeline Spec (PR-2)
+
+## Objective
+
+Transform raw GitHub org/repo data into normalized planning inputs.
+
+## Input
+
+- Organization ID
+- Selected repositories
+- Optional date window
+
+## Steps
+
+1. **Fetch repositories metadata**
+   - default branch
+   - active contributors (recent 90d)
+2. **Fetch open issues**
+   - title/body/labels/assignees/milestones
+   - created/updated timestamps
+3. **Fetch PR activity signals**
+   - merged PR counts by author
+   - review activity
+4. **Normalize and persist snapshots**
+5. **Emit planning trigger event**
+
+## Failure Handling
+
+- retry transient GitHub API failures with exponential backoff
+- partial-success mode when one repo fails
+- write structured error records per repository
+
+## Required Outputs
+
+- `issue_snapshot`
+- `member_signal_snapshot`
+- `repo_health_snapshot`
+- planning trigger job id

profile/pr2-core/planning-engine.md

@@ -0,0 +1,39 @@
+# Sprint Planning Engine Spec (PR-2)
+
+## Objective
+
+Produce first-pass assignment and priority recommendations for a 1-week sprint horizon.
+
+## Inputs
+
+- normalized issue snapshots
+- team member activity signals
+- repo label/milestone context
+
+## Output per issue
+
+- `priority`: low | normal | high | urgent
+- `effort_hours`: numeric estimate
+- `recommended_assignee`: member handle
+- `confidence`: 0..1
+- `reasons`: human-readable rationale list
+
+## Heuristics (v1)
+
+1. **Priority seed**
+   - labels (`critical`,`bug`,`security`,`urgent`) => high/urgent bias
+   - stale/low-impact labels => low bias
+2. **Effort estimate**
+   - title/body token length + labels + historical merge cadence
+3. **Assignee recommendation**
+   - contributor familiarity score
+   - recent review/merge ownership
+   - availability proxy (recent load)
+4. **Confidence score**
+   - data completeness + signal agreement
+
+## Constraints
+
+- never overwrite explicit human assignee/priority without user action
+- expose reasons for every recommendation
+- low confidence (<0.45) should be visually flagged

profile/pr3-dashboard/README.md

@@ -0,0 +1,7 @@
+# PR-3 Dashboard Contract Scaffold (Issue #14)
+
+This package completes the MVP contract set with dashboard-facing payloads:
+
+- calendar view contract,
+- value metrics contract,
+- override/replan interaction contract.