Finish CUST-WP-0011 and implement STATE-WP-0061 suggestion backlog.

Add persisted Suggestion entities with WSJF ranking, relevance bumps,
REST/MCP write surfaces, /suggestions dashboard page, and daily triage
digest integration. Document the cluster operating model, archive the
completed migration workplan, and seed WARDEN-WP-0012 routing scenarios.

mcp_server/TOOLS.md

@@ -7,12 +7,13 @@ Quick reference for all tools and resources.
 The State Hub is a **read model**. It observes and visualises cross-domain state
 that originates in the projects themselves.
 
-Two write operations are permanently sanctioned:
+Sanctioned writes (cross-cutting coordination — not bootstrap-only):
 
 | Use Case | Tools |
 |---|---|
-| **Resolving Decisions** | `resolve_decision()` — decisions are cross-cutting; resolution must propagate across all domains |
-| **Suggesting Next Steps** | `get_next_steps()` *(v0.2)* — surface what is unblocked; the domain does the work |
+| **Resolving Decisions** | `resolve_decision()` |
+| **Next Steps + demand signals** | `get_next_steps()` — derived steps; bumps relevance on surfaced open suggestions |
+| **Suggestion backlog** | `create_suggestion()`, `vet_suggestion()`, `decline_suggestion()`, `promote_suggestion_to_task()`, `bump_suggestion_relevance()` |
 
 All other mutate tools are **bootstrap-only**: use them during First Session Protocol
 to give a freshly-registered project its initial workstream structure.

mcp_server/server.py

@@ -1139,12 +1139,103 @@ def get_next_steps() -> str:
     Each suggestion includes domain, workstream, task, and a plain-language
     message. The hub surfaces *what* and *where* — the domain owns *how*.
 
-    This is one of the two sanctioned write-side use cases of the State Hub
-    (the other is resolve_decision). Suggestions are derived, not persisted.
+    Derived next steps may include open demand-weighted suggestions from the
+    persisted suggestion backlog (STATE-WP-0061).
     """
     return json.dumps(_get("/state/next_steps"), indent=2)
 
 
+# ---------------------------------------------------------------------------
+# Demand-weighted suggestion backlog (STATE-WP-0061)
+# ---------------------------------------------------------------------------
+
+@mcp.tool()
+def list_suggestions(
+    domain: str | None = None,
+    stage: str | None = None,
+    rank: str | None = None,
+    limit: int = 50,
+) -> str:
+    """List persisted suggestions, optionally ranked by WSJF."""
+    return json.dumps(
+        _get("/suggestions", {
+            "domain": domain,
+            "stage": stage,
+            "rank": rank,
+            "limit": limit,
+        }),
+        indent=2,
+    )
+
+
+@mcp.tool()
+def create_suggestion(
+    domain: str,
+    title: str,
+    description: str | None = None,
+    origin_ref: str | None = None,
+    workplan_id: str | None = None,
+    base_value: float = 3.0,
+    job_size: float = 3.0,
+) -> str:
+    """Record a gated need as a relevance-accruing suggestion."""
+    return json.dumps(_post("/suggestions", {
+        "domain": domain,
+        "title": title,
+        "description": description,
+        "origin_ref": origin_ref,
+        "workplan_id": workplan_id,
+        "base_value": base_value,
+        "job_size": job_size,
+    }), indent=2)
+
+
+@mcp.tool()
+def vet_suggestion(suggestion_id: str, note: str, author: str | None = None) -> str:
+    """Promote a suggestion to a vetted requirement with an append-only note."""
+    return json.dumps(_post(f"/suggestions/{suggestion_id}/vet", {
+        "note": note,
+        "author": author,
+    }), indent=2)
+
+
+@mcp.tool()
+def decline_suggestion(suggestion_id: str, note: str, author: str | None = None) -> str:
+    """Decline a suggestion or requirement."""
+    return json.dumps(_post(f"/suggestions/{suggestion_id}/decline", {
+        "note": note,
+        "author": author,
+    }), indent=2)
+
+
+@mcp.tool()
+def promote_suggestion_to_task(
+    suggestion_id: str,
+    note: str | None = None,
+    task_title: str | None = None,
+    author: str | None = None,
+) -> str:
+    """Promote a vetted requirement into a real Task."""
+    return json.dumps(_post(f"/suggestions/{suggestion_id}/promote", {
+        "note": note,
+        "task_title": task_title,
+        "author": author,
+    }), indent=2)
+
+
+@mcp.tool()
+def bump_suggestion_relevance(
+    suggestion_id: str,
+    reason: str | None = None,
+    author: str | None = None,
+) -> str:
+    """Explicitly bump demand relevance when an agent hits an unmet gated need."""
+    return json.dumps(_post(f"/suggestions/{suggestion_id}/bump-relevance", {
+        "reason": reason,
+        "author": author,
+    }), indent=2)
+
+
 # ---------------------------------------------------------------------------
 # Dependency graph tools (S1.4)
 # ---------------------------------------------------------------------------