# Priority Forge Roadmap

> This is the canonical list of past, current, and planned development phases. The [README roadmap table](../README.md#roadmap) is a one-line summary of what's here.
>
> Related docs: [FEATURE_EXTRACTION.md](FEATURE_EXTRACTION.md), [ML_ARCHITECTURE.md](ML_ARCHITECTURE.md).

---

## Shipped

### V1 — Foundations
- JSON storage, REST API, MCP JSON-RPC endpoint.
- Static P0–P3 priorities, no scoring.

### V2 — Weighted scoring
- Heap-based priority queue.
- Deterministic scoring formula over `blockingCount`, `crossProjectImpact`, `timeSensitivity`, `effortValueRatio`, `dependencyDepth`.

### V2.1 — Universal coverage
- MCP Resources and Prompts so any MCP-speaking client gets auto-capture guidance without custom rules.

### V3 — Dynamic rebalancing + training data
- Graph-aware rebalance when `dependsOn` changes.
- Event logging: `PriorityChangeEvent`, `TaskSelectionEvent`, `QueueRebalanceEvent`, completion records.

### V4 — Workspaces + global training data
- Per-user workspaces with isolated task stores.
- Cross-workspace training data so a single XGBoost run benefits from all users.
- Cursor becomes a first-class client with `alwaysApply` rule, `sessionStart` hook, plugin bundle, persistent services by default.

---

## Current

### V5 — Goal-conditioned learning
**Status:** planned / in design.

**Goal:** extend the scoring function to condition on active objectives (e.g., "ship v2 by Friday", "reduce on-call load"). Today's scoring is objective-agnostic.

**Shape of the change:**
- Add an `objectives` collection with deadlines, progress, and owning projects.
- Extend feature vector: `goal_count`, `closest_deadline`, `avg_progress`, `task_to_goal_distance`.
- Retrain XGBoost on the extended feature vector.
- Longer-term transition path to a neural scorer documented in [ML_ARCHITECTURE.md](ML_ARCHITECTURE.md#transition-plan-xgboost--neural).

**Prerequisites:** clean V3/V4 event logs (currently accumulating), minimum of ~10 completions with `actualWorkTime` per user.

---

## Planned

### V6 — Learned feature extractor

**Status:** planned.

**Goal:** replace (or augment) agent-driven feature extraction with a trained classifier / regressor, so the prose-to-features step no longer depends on an LLM for every call.

This is the other half of the intelligence chain described in [FEATURE_EXTRACTION.md](FEATURE_EXTRACTION.md). Today the math is deterministic but extraction is agent-driven; V6 makes extraction partially deterministic too.

#### Why not earlier

See [FEATURE_EXTRACTION.md § "Why not train a classifier today?"](FEATURE_EXTRACTION.md#why-not-train-a-classifier-today). The short version:

1. Cold start — new users have zero training data.
2. Explainability at capture time — agents emit rationales, classifiers don't.
3. Missing labels — current events give us "the agent was wrong", not "the correct value was X".
4. Distribution shift — per-user language varies.

V6 is the workstream that fixes all four.

#### Scope

**Models:**
- Per-field extractors, not one monolithic model. Each field in [FEATURE_EXTRACTION.md § "Fields owned by the agent"](FEATURE_EXTRACTION.md#fields-owned-by-the-agent) gets its own head:
  - `priority` — ordinal classifier over `{P0, P1, P2, P3}`.
  - `effort` — ordinal classifier over `{low, medium, high}`.
  - `timeSensitivity` — regressor over `[0, 10]`.
  - `blockingCount` — two-stage: (a) detect blocking language, (b) NER over task references + lookup against the current queue.
  - `crossProjectImpact` — binary classifier conditioned on project metadata.
  - `dependsOn` — NER + entity resolution against `list_projects` / `get_priorities`.
- Encoder shared across heads (likely a small sentence-transformer fine-tuned on captured prose). Classifier heads are cheap.

**Data pipeline — synthesizing labels from the events we already log:**

We don't have labeled (prose → features) pairs, but we have:

- Original prose and the agent's extracted features (stored on the task).
- `PriorityChangeEvent` — user's corrected priority.
- User-modified effort on update.
- Added `dependsOn` after the fact.
- Completion record with `actualWorkTime`.

Relabeling procedure:
1. For each task, take the *final* feature values after all corrections as the ground-truth label.
2. Pair those labels with the *original* prose the agent saw (stored in the task's `description` / conversation context).
3. Exclude tasks where the user never corrected anything (the agent's guess is unlabeled — we can't distinguish "agent was right" from "user didn't bother").
4. Bootstrap-augment with LLM-generated paraphrases of corrected prose to avoid overfitting to exact wording.

This gives us a supervised dataset without needing a separate labeling pass.

**Deployment shape:**
- V6a: extractor runs **alongside** the agent. Agent still does extraction; extractor's predictions logged as shadow. When agent and extractor disagree, log an `ExtractorDisagreementEvent`. No user-visible change.
- V6b: extractor runs **before** the agent. Agent sees the extractor's predictions as defaults and only adjusts what's clearly wrong. Reduces LLM token cost per capture.
- V6c (optional): extractor runs **instead of** the agent for confident predictions, with an explicit fallback to agent extraction when confidence is low. This is the "mostly offline" mode.

**Cold-start strategy:**
- Day 0 for a new user: extractor starts as a global model trained on all consented users' data.
- Fine-tune per-user once they accumulate >N corrections (N TBD, likely ~50).
- Always keep the agent in the loop as a fallback — V6 is additive, not replacing.

**Explainability:**
- Each extractor head returns the top-K input tokens (attention or SHAP) that drove its prediction, rendered in the UI alongside the value. Matches the agent's "I set this because you said X" behavior.

**Open questions:**
- Where does the extractor run? Client-side (small ONNX bundle) keeps prose local. Server-side is simpler but means prose leaves the user's machine. Likely client-side for the sentence encoder, server-side for the ranker/rebalancer.
- How do we version extractors? Probably the same way we version heuristic weights today (`heuristic-weights.json` with a `version` field).
- Do we expose extractor confidence to the agent rule files so agents know when to second-guess? Probably yes — low extractor confidence is exactly when the agent adds value.

**Success criteria:**
- V6a: extractor agreement with agent >80% on high-confidence predictions.
- V6b: median token cost per `create_task` drops ≥50% without a regression in user-override rate.
- V6c: <5% of captures fall back to the agent for confident predictions.

**Data requirements before starting:**
- ≥1000 corrected tasks across all users (current baseline: single-digits).
- ≥100 users opted into cross-workspace training data (V4 requirement, already in place).
- Audit trail that lets us reconstruct the prose → final-features pair for each task.

---

## Speculative (not scheduled)

### V7 — Hybrid offline extractor + agent
- Ship the extractor as a small on-device model that runs without an LLM for the common case.
- Agent is only invoked for ambiguous captures or when the user explicitly asks for suggestions.
- Depends on V6c landing cleanly.

### V8 — Learned rebalancer
- Today's rebalance is a graph walk. Explore whether a learned policy (imitation learning on `QueueRebalanceEvent` history) produces orderings users agree with more often.
- Risk: learned rebalancers are hard to audit; users may lose trust in the queue order if they can't explain why a task moved.

### V9 — Multi-user collaboration
- Shared workspaces, assignment semantics, inter-user dependency edges.
- Significant schema work. Probably warrants its own phase planning doc when the time comes.

---

## How phases get promoted

1. Sketched as a section in this file under **Speculative**.
2. Promoted to **Planned** once there's a concrete prerequisite list and a success criterion.
3. Promoted to **Current** once someone is actively working on it.
4. Moved to **Shipped** once the feature is released and the event/data contract is documented in [ML_ARCHITECTURE.md](ML_ARCHITECTURE.md) or [FEATURE_EXTRACTION.md](FEATURE_EXTRACTION.md).

The README table is kept in sync with this file's top-level phase names; anything more granular lives here.
