Tighten Scattermind rank feedback contract

README.md

@@ -39,6 +39,46 @@ Tables:
 - `milestones` — name, description, horizon, color, position, active
 - `activity` — small append-only UX feed
 
+## Scattermind → Ranker bridge
+
+Ranker's continuation job is narrow:
+
+`Snapshot / Concept Map → candidate feature/action set → Rank-ready build order`
+
+`POST /api/rank-feedback` accepts a `prioritix-feature-set-v1`-style payload from Scattermind and returns ranked items plus `buildOrder.doFirst / validateNext / defer / park`. Keep this contract action-first; do not use it as a reason to add generic dashboard, auth, billing, or workspace layers before the bridge has proof.
+
+Recommended payload shape:
+
+```json
+{
+  "schema": "prioritix-feature-set-v1",
+  "sourceName": "Scattermind",
+  "artifactId": "snapshot_or_concept_map_id",
+  "snapshotTitle": "Plain idea title",
+  "conceptMapId": "optional_concept_map_id",
+  "originalPrompt": "The user's starting prompt, trimmed for provenance",
+  "idea": "What Scattermind clarified",
+  "context": "Important constraints: solo builder, non-AI-native user, avoid dashboard swamp, etc.",
+  "mode": "mvp",
+  "featureSet": {
+    "features": [
+      {
+        "id": "build-order-preview",
+        "title": "Build order preview",
+        "description": "Show do first, validate next, defer, and park with reasons.",
+        "userValue": "A tired builder sees the next move without opening a dashboard.",
+        "evidenceNeeded": "Can 3 non-AI-native users understand the first recommended action?",
+        "proofSteps": ["Show a static result screen to 3 people"],
+        "dependencies": [],
+        "risk": "May become generic roadmap UI if the source context is lost.",
+        "recommendedLane": "validate-next",
+        "sourceSection": "concept-map.nextMoves"
+      }
+    ]
+  }
+}
+```
+
 ## Commands
 
 ```bash