@elixium.ai/mcp-server 0.4.0 → 0.6.0

package/dist/index.js

@@ -5,6 +5,10 @@ import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import axios from "axios";
 import * as http from "node:http";
+import { CREATE_STORY_INPUT_SCHEMA, UPDATE_STORY_INPUT_SCHEMA, GET_STAKEHOLDERS_INPUT_SCHEMA, PROPOSE_FIELD_DRAFT_INPUT_SCHEMA, ENDORSE_PROPOSAL_INPUT_SCHEMA, REJECT_PROPOSAL_INPUT_SCHEMA, DRAFT_HYPOTHESIS_INPUT_SCHEMA, GET_TRUST_LEAKAGE_INPUT_SCHEMA, } from "./toolSchemas.js";
+import { deriveStakeholders } from "./stakeholders.js";
+import { formatWorkflowModelLine } from "./constants/workflowModelLabels.js";
+import { MCP_FEATURE_CONFIG_ERROR_FALLBACK } from "./constants/featureConfigFallback.js";
 const API_KEY = process.env.ELIXIUM_API_KEY;
 const API_URL = process.env.ELIXIUM_API_URL || "https://elixium.ai/api";
 const BOARD_SLUG = process.env.ELIXIUM_BOARD_SLUG;
@@ -311,25 +315,8 @@ const fetchFeatureConfig = async () => {
         return response.data;
     }
     catch (error) {
-        console.error("Failed to fetch feature config, defaulting to all enabled:", error);
-        return {
-            features: {
-                balancedTeam: true,
-                learningLoop: true,
-                tddWorkflow: true,
-                aiTools: true,
-                teamDecisions: false,
-                ragKnowledgeBase: false,
-            },
-            source: {
-                balancedTeam: "error-fallback",
-                learningLoop: "error-fallback",
-                tddWorkflow: "error-fallback",
-                aiTools: "error-fallback",
-                teamDecisions: "error-fallback",
-                ragKnowledgeBase: "error-fallback",
-            },
-        };
+        console.error("Failed to fetch feature config, using error fallback:", error);
+        return MCP_FEATURE_CONFIG_ERROR_FALLBACK;
     }
 };
 // Helper functions to check individual features
@@ -643,52 +630,8 @@ const createServer = () => {
             },
             {
                 name: "create_story",
-                description: "Create a new story on the Elixium board",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        title: { type: "string", description: "Title of the story" },
-                        description: {
-                            type: "string",
-                            description: "Description of the story",
-                        },
-                        acceptanceCriteria: {
-                            type: "string",
-                            description: "Acceptance criteria in Given/When/Then format",
-                        },
-                        lane: {
-                            type: "string",
-                            description: "Lane to add the story to (case-insensitive)",
-                            enum: [
-                                "Backlog",
-                                "Icebox",
-                                "Current",
-                                "Done",
-                                "BACKLOG",
-                                "ICEBOX",
-                                "CURRENT",
-                                "DONE",
-                            ],
-                        },
-                        points: {
-                            type: "number",
-                            description: "Points (0, 1, 2, 3, 5, 8)",
-                        },
-                        requester: {
-                            type: "string",
-                            description: "Email of the person requesting this story. Defaults to ELIXIUM_USER_EMAIL env var or API key owner.",
-                        },
-                        epicId: {
-                            type: "string",
-                            description: "Epic ID to link this story to (optional). Use list_epics to find epic IDs.",
-                        },
-                        testPlan: {
-                            type: "string",
-                            description: "Markdown test plan describing test strategy (optional). Sets the test_plan field without changing workflow_stage.",
-                        },
-                    },
-                    required: ["title"],
-                },
+                description: "Create a story on the active board. New stories enter the Backlog lane and are attributed to the user bound to your API key. Stories you create without current board context risk duplicating in-flight work or contradicting recent decisions. Ensure you are grounded before writing — if you haven't grounded this session, call `get_board_context` (optionally with `intent` set to the user's request for similar-story matching). This is the normal path when a user asks you to draft a story; it is not a bypass of human review, which happens at downstream workflow gates. Accepts storyType (feature/bug/chore/platform) at create time. Use `propose_field_draft` for asynchronous suggestions on fields of an existing story.",
+                inputSchema: CREATE_STORY_INPUT_SCHEMA,
             },
             {
                 name: "get_iteration_context",
@@ -698,6 +641,19 @@ const createServer = () => {
                     properties: {},
                 },
             },
+            {
+                name: "get_board_context",
+                description: "Get a snapshot of the workspace's board state for grounding before drafting or updating content. Returns time-balanced sections: inFlight (Current lane + in_progress epics), queued (Backlog + next/soon epics), icebox (Icebox + someday epics), recentlyCompleted (Done + archived epics), decisions, objectives, learnings, plus configuration (feature flags, workflow stages). Pass `intent` (free-form text of what you're about to do; the user's verbatim request is fine) to additionally receive `similar` — existing stories ranked by relevance. Stories you create or update without current board context risk duplicating in-flight work or contradicting recent decisions; ensure you are grounded before writing.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        intent: {
+                            type: "string",
+                            description: "Optional free-form text describing what you're about to do (e.g., the user's verbatim request, or a short topic phrase). When provided, the response additionally includes a `similar` section ranked by relevance.",
+                        },
+                    },
+                },
+            },
             {
                 name: "list_objectives",
                 description: "List objectives for the current workspace",
@@ -716,7 +672,7 @@ const createServer = () => {
             },
             {
                 name: "create_epic",
-                description: "Create a new epic for the current board",
+                description: "Create an epic for the active board. Epics group related stories around an outcome hypothesis. Before creating, ensure you are grounded — call `get_board_context` to surface existing epics, workspace objectives, and recent decisions; duplicate or overlapping epics are easy to introduce without that context. Epics are attributed to the user bound to your API key. Use `update_epic` to revise an existing epic rather than duplicating.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -741,7 +697,7 @@ const createServer = () => {
             },
             {
                 name: "update_epic",
-                description: "Update an epic (title, description, stage, or outcome fields)",
+                description: "Update an epic's title, description, stage, or outcome fields (hypothesis, success metrics, outcome status, target date). Before updating, ensure you are grounded — call `get_board_context` for current board state and recent decisions that may affect this epic. Updates are attributed to the user bound to your API key.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -767,58 +723,38 @@ const createServer = () => {
             },
             {
                 name: "update_story",
-                description: "Update fields on an existing story",
-                inputSchema: {
-                    type: "object",
-                    properties: {
-                        storyId: { type: "string", description: "ID of the story" },
-                        title: { type: "string", description: "Updated title" },
-                        description: { type: "string", description: "Updated description" },
-                        lane: {
-                            type: "string",
-                            description: "Lane to move the story to (case-insensitive)",
-                            enum: [
-                                "Backlog",
-                                "Icebox",
-                                "Current",
-                                "Done",
-                                "BACKLOG",
-                                "ICEBOX",
-                                "CURRENT",
-                                "DONE",
-                            ],
-                        },
-                        points: {
-                            type: "number",
-                            description: "Updated points (0, 1, 2, 3, 5, 8)",
-                        },
-                        state: {
-                            type: "string",
-                            description: "Story state (unstarted, started, finished, delivered, accepted, rejected)",
-                        },
-                        outcome_summary: {
-                            type: "string",
-                            description: "Learning outcome summary",
-                        },
-                        acceptanceCriteria: {
-                            type: "string",
-                            description: "Acceptance criteria in Given/When/Then format",
-                        },
-                        sortOrder: {
-                            type: "number",
-                            description: "Sort order within the lane (lower = higher priority)",
-                        },
-                        epicId: {
-                            type: "string",
-                            description: "Epic ID to link this story to. Set to empty string to unlink.",
-                        },
-                        testPlan: {
-                            type: "string",
-                            description: "Markdown test plan. Updates test_plan field without changing workflow_stage.",
-                        },
-                    },
-                    required: ["storyId"],
-                },
+                description: "Update fields on an existing story. Accepts Learning Loop fields (hypothesis, confidence_score, hidden_unknowns, risk_profile) and storyType in addition to the basics. Before updating, call `get_story` to inspect current state, and `get_board_context` if your update relates to a topic that may be governed by a recent team decision. Updates are attributed to the user bound to your API key.",
+                inputSchema: UPDATE_STORY_INPUT_SCHEMA,
+            },
+            {
+                name: "get_stakeholders",
+                description: "Derive the set of trust audiences this story needs to earn trust with. Returns an array of {audience, reason} entries based on the story's risk_profile, its linked epic's hypothesis/successMetrics, and the workspace's compliance frameworks. Pure derivation — no mutations, no AI calls.",
+                inputSchema: GET_STAKEHOLDERS_INPUT_SCHEMA,
+            },
+            {
+                name: "propose_field_draft",
+                description: "Submit an AI-drafted value for a Learning Loop field as a pending proposal. The draft does NOT change the story until a human endorses via endorse_proposal. Caller should disclose `provider` (LLM model) and `agent` (client+version) for trust attribution. Stories whose fields you propose without current board context risk contradicting recent decisions in this area. Ensure you are grounded before drafting — call `get_board_context` if you haven't grounded this session.",
+                inputSchema: PROPOSE_FIELD_DRAFT_INPUT_SCHEMA,
+            },
+            {
+                name: "endorse_proposal",
+                description: "Endorse a pending field proposal. Updates the underlying story field with the proposal's draft_value and emits a proposal.endorsed audit event. Only humans should endorse — the agent should never call this on its own draft.",
+                inputSchema: ENDORSE_PROPOSAL_INPUT_SCHEMA,
+            },
+            {
+                name: "reject_proposal",
+                description: "Reject a pending field proposal with a required reason. Story field is unchanged; reason is captured for agent learning + audit.",
+                inputSchema: REJECT_PROPOSAL_INPUT_SCHEMA,
+            },
+            {
+                name: "draft_hypothesis",
+                description: "Generate an AI-drafted hypothesis for the given story and submit it as a pending proposal. The backend calls the configured AI_PROVIDER, drafts the hypothesis text, and creates a proposal that a human must endorse via `endorse_proposal` before the story's hypothesis field is updated. The draft does not change the story until endorsed.",
+                inputSchema: DRAFT_HYPOTHESIS_INPUT_SCHEMA,
+            },
+            {
+                name: "get_trust_leakage",
+                description: "Return the tenant's off-system decision report: commits authored since `since` on the workspace's configured Git provider (GitHub, GitHub Enterprise, GitLab, or Gitea) whose messages do NOT reference any story on the board. Nudge signal, not a gate. Requires workspace_git_provider to be configured via POST /workspace/git-provider first.",
+                inputSchema: GET_TRUST_LEAKAGE_INPUT_SCHEMA,
             },
             {
                 name: "prepare_implementation",
@@ -938,7 +874,7 @@ const createServer = () => {
             },
             {
                 name: "propose_test_plan",
-                description: "Submit a test plan for human review. Sets workflow_stage to tests_proposed. Implementation is BLOCKED until human approves.",
+                description: "Submit a test plan for human review. Sets workflow_stage to tests_proposed. Implementation is BLOCKED until human approves. Before proposing, call `get_story` to inspect the story's hypothesis, hidden_unknowns, and risk_profile (the test plan should ground in those fields). Use `draft_test_plan` first for a scaffold seeded from the story's premortem assumptions.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -959,6 +895,20 @@ const createServer = () => {
                     required: ["storyId", "testPlan"],
                 },
             },
+            {
+                name: "draft_test_plan",
+                description: "Return a starter test plan scaffold seeded from the story's hidden_unknowns and hypothesis. The agent edits this scaffold and calls propose_test_plan with the final version. Makes Icebox premortem assumptions load-bearing at test authoring time.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        storyId: {
+                            type: "string",
+                            description: "ID of the story to draft a test plan for",
+                        },
+                    },
+                    required: ["storyId"],
+                },
+            },
             {
                 name: "approve_tests",
                 description: "Approve a proposed test plan so implementation can proceed. Transitions workflow from tests_proposed to tests_approved. This is the human approval gate in the TDD workflow.",
@@ -1032,7 +982,7 @@ const createServer = () => {
         const learningLoopTools = learningLoopEnabled ? [
             {
                 name: "create_hypothesis",
-                description: "Create a new assumption/hypothesis in the Icebox for validation",
+                description: "Create a new assumption/hypothesis in the Icebox for validation. Before creating, ensure you are grounded — call `get_board_context` to check for existing related hypotheses and recent decisions in this area. The hypothesis is attributed to the user bound to your API key.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -1050,7 +1000,7 @@ const createServer = () => {
             },
             {
                 name: "record_learning",
-                description: "Record a learning outcome for a completed story",
+                description: "Record a learning outcome for a completed story (sets the story's outcome_summary field). The learning is visible in the workspace's recent-learnings surface. Before recording, call `get_story` to inspect the story's current state, and `get_board_context` to surface recently-recorded learnings on related stories that may already capture the same insight.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -1068,7 +1018,7 @@ const createServer = () => {
         const teamDecisionsTools = teamDecisionsEnabled ? [
             {
                 name: "record_decision",
-                description: "Record a team decision, meeting outcome, or architectural choice. These are shared across all team members' AI sessions.",
+                description: "Record a team decision, meeting outcome, or architectural choice. These are shared across all team members' AI sessions. Before recording, ensure you are grounded — call `get_board_context` to check whether a recent decision already covers this area; duplicate or contradictory decisions are exactly what this tool exists to prevent.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -1149,7 +1099,7 @@ const createServer = () => {
         try {
             const toolName = request.params.name;
             // Check TDD workflow tools
-            const tddWorkflowTools = ["start_story", "propose_test_plan", "get_test_plan", "submit_for_review", "review_pr"];
+            const tddWorkflowTools = ["start_story", "propose_test_plan", "draft_test_plan", "get_test_plan", "submit_for_review", "review_pr"];
             if (tddWorkflowTools.includes(toolName)) {
                 const enabled = await isTddWorkflowEnabled();
                 if (!enabled) {
@@ -1411,6 +1361,58 @@ ${config.infrastructureProfile?.provider ? `- Provider: ${config.infrastructureP
                         ],
                     };
                 }
+                case "get_board_context": {
+                    // Thin wrapper around GET /api/board-context. The backend composes
+                    // the response; this handler forwards the optional `intent` query
+                    // param and wraps the response in MCP content format.
+                    //
+                    // Note: the backend also supports a `since` parameter for conditional
+                    // return (sentinel when workspace state hasn't shifted), but it is
+                    // intentionally NOT exposed at the MCP layer until the
+                    // context_version invariant ships (separate follow-on story:
+                    // "Wire context_version invariant with chosen atomicity pattern").
+                    // Without per-write version bumps, the sentinel would be unreliable
+                    // (stale `unchanged: true` for state that did change).
+                    //
+                    // Graceful 404 fallback: if the backend is older than 2026-05-17
+                    // (or a self-hosted release that doesn't include this endpoint),
+                    // return a structured message pointing the agent at the existing
+                    // multi-tool orchestration path rather than throwing an opaque
+                    // error. Version skew between mcp-server and backend is the most
+                    // common failure mode for new MCP tools; surfacing it well here
+                    // is cheaper than every customer filing the same bug report.
+                    const args = request.params.arguments ?? {};
+                    const params = {};
+                    if (typeof args.intent === "string" && args.intent.trim()) {
+                        params.intent = args.intent.trim();
+                    }
+                    try {
+                        const response = await client.get("/board-context", { params });
+                        return {
+                            content: [
+                                { type: "text", text: JSON.stringify(response.data, null, 2) },
+                            ],
+                        };
+                    }
+                    catch (err) {
+                        if (err?.response?.status === 404) {
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: JSON.stringify({
+                                            error: "get_board_context is not available on this backend",
+                                            reason: "The backend does not expose GET /api/board-context. This is likely a version-skew issue: the tool was added in mcp-server 0.6.0 (2026-05-17) and requires a backend release that includes the matching endpoint.",
+                                            fallback: "Until the backend is updated, orchestrate grounding manually: call `get_iteration_context` (in-flight work), `list_epics` (queued and in-progress epics), `list_decisions` (recent team decisions in the workspace), and `get_feature_config` (workspace configuration). The trade-offs are more tool calls and no time-balanced sections or similar-story matching, but the agent still gets the underlying grounding data.",
+                                            action: "Self-hosted: update the backend to a release that includes GET /api/board-context. SaaS (elixium.ai-hosted): contact support — the endpoint should already be live on hosted backends.",
+                                        }, null, 2),
+                                    },
+                                ],
+                            };
+                        }
+                        throw err;
+                    }
+                }
                 case "create_hypothesis": {
                     const args = request.params.arguments;
                     const normalizedLane = await normalizeLane("Icebox");
@@ -1540,6 +1542,134 @@ ${config.infrastructureProfile?.provider ? `- Provider: ${config.infrastructureP
                         ],
                     };
                 }
+                case "get_stakeholders": {
+                    const args = request.params.arguments;
+                    const { storyId } = args;
+                    assertUUID(storyId, "storyId");
+                    // Fetch story + feature config in parallel; the story tells us
+                    // whether to fetch a linked epic.
+                    const [storyResponse, featureConfig] = await Promise.all([
+                        client.get(`/stories/${storyId}`),
+                        fetchFeatureConfig(),
+                    ]);
+                    const story = storyResponse.data;
+                    // If the story is linked to an epic, fetch the epic too.
+                    let epic = null;
+                    if (story.epic_id) {
+                        try {
+                            const epicResponse = await client.get(`/epics/${story.epic_id}`);
+                            epic = epicResponse.data;
+                        }
+                        catch {
+                            // Epic fetch failure is non-fatal — derivation simply won't
+                            // add the `execs` audience in this case.
+                            epic = null;
+                        }
+                    }
+                    // Read from canonical field name `complianceFrameworks` (per
+                    // types.ts InfrastructureProfile); fall back to `compliance` for
+                    // any shipped callers that use the older name. Values are
+                    // normalized case-insensitively in deriveStakeholders.
+                    const infra = featureConfig.infrastructureProfile ?? {};
+                    const workspaceCompliance = Array.isArray(infra.complianceFrameworks)
+                        ? infra.complianceFrameworks
+                        : Array.isArray(infra.compliance)
+                            ? infra.compliance
+                            : [];
+                    const stakeholders = deriveStakeholders({
+                        story: {
+                            story_type: story.story_type ?? null,
+                            title: story.title ?? null,
+                            risk_profile: story.risk_profile ?? null,
+                            epic_id: story.epic_id ?? null,
+                        },
+                        epic: epic
+                            ? {
+                                hypothesis: epic.hypothesis ?? null,
+                                successMetrics: epic.successMetrics ?? null,
+                            }
+                            : null,
+                        workspaceCompliance,
+                    });
+                    const payload = {
+                        storyId: story.id,
+                        stakeholders,
+                        derived_from: {
+                            story_type: story.story_type ?? null,
+                            risk_profile: story.risk_profile ?? null,
+                            epic_id: story.epic_id ?? null,
+                            compliance_frameworks: workspaceCompliance,
+                        },
+                    };
+                    return {
+                        content: [
+                            { type: "text", text: JSON.stringify(payload, null, 2) },
+                        ],
+                    };
+                }
+                case "propose_field_draft": {
+                    const args = request.params.arguments;
+                    const { storyId, fieldName, draftValue, provider, agent } = args;
+                    assertUUID(storyId, "storyId");
+                    const response = await client.post(`/stories/${storyId}/proposals`, {
+                        field_name: fieldName,
+                        draft_value: draftValue,
+                        ...(provider ? { provider } : {}),
+                        ...(agent ? { agent } : {}),
+                    });
+                    return {
+                        content: [
+                            { type: "text", text: JSON.stringify(response.data, null, 2) },
+                        ],
+                    };
+                }
+                case "endorse_proposal": {
+                    const args = request.params.arguments;
+                    const { proposalId } = args;
+                    assertUUID(proposalId, "proposalId");
+                    const response = await client.post(`/proposals/${proposalId}/endorse`, {});
+                    return {
+                        content: [
+                            { type: "text", text: JSON.stringify(response.data, null, 2) },
+                        ],
+                    };
+                }
+                case "reject_proposal": {
+                    const args = request.params.arguments;
+                    const { proposalId, reason } = args;
+                    assertUUID(proposalId, "proposalId");
+                    const response = await client.post(`/proposals/${proposalId}/reject`, { reason });
+                    return {
+                        content: [
+                            { type: "text", text: JSON.stringify(response.data, null, 2) },
+                        ],
+                    };
+                }
+                case "draft_hypothesis": {
+                    const args = request.params.arguments;
+                    const { storyId, context } = args;
+                    assertUUID(storyId, "storyId");
+                    const response = await client.post(`/stories/${storyId}/proposals/draft`, { field_name: "hypothesis", ...(context ? { context } : {}) });
+                    return {
+                        content: [
+                            { type: "text", text: JSON.stringify(response.data, null, 2) },
+                        ],
+                    };
+                }
+                case "get_trust_leakage": {
+                    const args = (request.params.arguments ?? {});
+                    const query = {};
+                    if (args.since)
+                        query.since = String(args.since);
+                    if (args.repo)
+                        query.repo = String(args.repo);
+                    const response = await client.get(`/trust-leakage`, { params: query });
+                    return {
+                        content: [
+                            { type: "text", text: JSON.stringify(response.data, null, 2) },
+                        ],
+                    };
+                }
                 case "prepare_implementation": {
                     const args = request.params.arguments;
                     const { storyId } = args;
@@ -1680,6 +1810,9 @@ Here’s the smallest change that will validate it:
                     const dorWarnings = formatDorWarnings(boardSettings, result.dorChecklist);
                     const isTrunk = result.trunkBased;
                     const isAutoMerge = result.autoMerge;
+                    const workflowModelLine = formatWorkflowModelLine({
+                        useDeliveredState: teamConfig.features.useDeliveredState,
+                    });
                     let formattedResult;
                     if (isTrunk && !isAutoMerge) {
                         formattedResult = `
@@ -1688,6 +1821,7 @@ Here’s the smallest change that will validate it:
 **Mode:** Direct to main (trunk-based development)
 **Feature Flag:** \`${result.featureFlagName || "none"}\`
 **Workflow Stage:** ${result.workflow_stage}
+**Workflow Model:** ${workflowModelLine}
 
 ## Acceptance Criteria
 ${result.acceptance_criteria || "No specific AC provided."}
@@ -1714,6 +1848,7 @@ ${dorWarnings}`;
 **Branch:** \`${result.branch}\`
 **Feature Flag:** \`${result.featureFlagName || "none"}\`
 **Workflow Stage:** ${result.workflow_stage}
+**Workflow Model:** ${workflowModelLine}
 
 ## Acceptance Criteria
 ${result.acceptance_criteria || "No specific AC provided."}
@@ -1738,6 +1873,7 @@ ${dorWarnings}`;
 
 **Branch:** \`${result.branch}\`
 **Workflow Stage:** ${result.workflow_stage}
+**Workflow Model:** ${workflowModelLine}
 
 ## Acceptance Criteria
 ${result.acceptance_criteria || "No specific AC provided."}
@@ -1844,6 +1980,30 @@ ${(result.test_file_paths || []).map((p) => `- \`${p}\``).join("\n") || "No test
 ${result.message}
 
 > 🛑 **BLOCKED:** Implementation cannot proceed until a human approves this test plan.
+`;
+                    return {
+                        content: [{ type: "text", text: formattedResult.trim() }],
+                    };
+                }
+                case "draft_test_plan": {
+                    const args = request.params.arguments;
+                    const { storyId } = args;
+                    if (!storyId) {
+                        throw new Error("storyId is required");
+                    }
+                    assertUUID(storyId, "storyId");
+                    const response = await client.get(`/stories/${storyId}/draft-test-plan`);
+                    const result = response.data;
+                    const formattedResult = `
+# Drafted Test Plan
+
+**Story ID:** ${storyId}
+
+> This is a scaffold seeded from the story's \`hidden_unknowns\` and \`hypothesis\`. Edit freely, then call \`propose_test_plan\` with the final version.
+
+---
+
+${result.testPlan}
 `;
                     return {
                         content: [{ type: "text", text: formattedResult.trim() }],
@@ -1880,13 +2040,20 @@ ${result.message}
                         throw new Error("storyId is required");
                     }
                     assertUUID(storyId, "storyId");
-                    const response = await client.post(`/stories/${storyId}/submit-review`, {
-                        commitHash,
-                        testResults,
-                        implementationNotes,
-                    });
+                    const [response, submitFeatureConfig] = await Promise.all([
+                        client.post(`/stories/${storyId}/submit-review`, {
+                            commitHash,
+                            testResults,
+                            implementationNotes,
+                        }),
+                        fetchFeatureConfig(),
+                    ]);
                     const result = response.data;
                     const isAutoMerge = result.autoMerge;
+                    const submitWorkflowModelLine = formatWorkflowModelLine({
+                        useDeliveredState: submitFeatureConfig.features.useDeliveredState,
+                        state: result.state,
+                    });
                     let autoMergeSection = "";
                     if (isAutoMerge && result.autoMergeInstructions) {
                         const instr = result.autoMergeInstructions;
@@ -1920,6 +2087,7 @@ git branch -d ${instr.sourceBranch}
 **Status:** ${result.status}
 **Workflow Stage:** ${result.workflow_stage}
 **State:** ${result.state}
+**Workflow Model:** ${submitWorkflowModelLine}
 ${result.trunkBased ? `**Mode:** Trunk-based${isAutoMerge ? " + Auto-merge" : ""}` : ""}
 ${result.featureFlagName ? `**Feature Flag:** \`${result.featureFlagName}\`` : ""}
 
@@ -2335,7 +2503,17 @@ ${depList || "No dependencies detected."}
             if (error.response?.status) {
                 errorText += ` (HTTP ${error.response.status})`;
             }
-            if (error.response?.data) {
+            // Enhanced 403 handling for RBAC and API key scope errors
+            if (error.response?.status === 403 && error.response?.data) {
+                const data = error.response.data;
+                if (data.required && data.currentScopes) {
+                    errorText = `🔑 API key missing scope: ${data.required}\n\nYour key has scopes: [${data.currentScopes.join(", ")}]\nRegenerate your API key with the required scope to use this tool.\n\nIn Elixium → Integrations → Generate API Key (with scopes)`;
+                }
+                else if (data.required && data.currentLevel) {
+                    errorText = `🔒 Insufficient permissions: ${data.required}\n\nYour access level is "${data.currentLevel}". This operation requires a higher access level.\nContact your workspace owner to update your role.`;
+                }
+            }
+            else if (error.response?.data) {
                 const data = error.response.data;
                 const detail = typeof data === "string" ? data : JSON.stringify(data);
                 errorText += `\nDetails: ${detail}`;