@somacheck/vibecheck 0.6.15 → 0.6.17

package/dist/server.js

@@ -1,7 +1,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
-import { StatementPendingError, } from "./vibecheck.js";
-import { SomaCheckCompatibilityError, SomaCheckHttpError, SomaCheckLiveAskClientError, SomaCheckLiveAskConflictError, SomaCheckLiveAskPendingError, } from "./api.js";
+import { DELIVERY_ERROR_CODES, StatementPendingError, } from "./vibecheck.js";
+import { SomaCheckCompatibilityError, SomaCheckHttpError, SomaCheckRequestNotFoundError, SomaCheckLiveAskClientError, SomaCheckLiveAskConflictError, SomaCheckLiveAskPendingError, } from "./api.js";
 import { PACKAGE_NAME, PACKAGE_SPEC, PACKAGE_VERSION, SOMACHECK_SETUP_URL } from "./constants.js";
 // A human gesture (unlock phone, read the statement, make the wrist gesture)
 // reliably takes longer than the old 10s budget, so an inline wait almost
@@ -64,7 +64,6 @@ const statusSchema = {
     first_run_intro: z.object({ eligible: z.boolean(), should_offer_now: z.boolean() }),
     cadence: cadenceSchema,
     recommended_action: z.string(),
-    copy_guidance: z.object({ policy: z.string(), framing: z.string(), fallback: z.string() }),
 };
 const createdPropositionSchema = z.object({
     request_id: z.string(),
@@ -78,6 +77,8 @@ const resultSchema = {
     verdict: z.enum(["aligned", "unaligned"]).nullable(),
     confidence: z.number().min(0).max(1).nullable(),
     latency_s: z.number().min(0).nullable(),
+    delivery_state: z.enum(["queued", "processing", "sent", "failed", "skipped"]).nullable().optional(),
+    error_code: z.enum(DELIVERY_ERROR_CODES).nullable().optional(),
     user_feedback: z.enum(["agreed", "disagreed", "not_provided"]).nullable().optional(),
 };
 const contextItemSchema = z.object({
@@ -89,6 +90,7 @@ const contextItemSchema = z.object({
 });
 const contextSchema = { checkins: z.array(contextItemSchema).max(20) };
 const liveAskErrorCodeSchema = z.enum([
+    ...DELIVERY_ERROR_CODES,
     "link_revoked",
     "upgrade_required",
     "setup_required",
@@ -133,13 +135,9 @@ const SERVER_INSTRUCTIONS = [
     "Offer one when useful or when asked.",
     "When asked, send a useful statement starting with I or My. Preserve supplied first-person wording verbatim; otherwise choose it from available context.",
     "Only request_vibecheck creates an immediate phone ask, one at a time; use post_vibecheck_statement only when the person asks to stock reflections for later.",
-    "Gesture and optional feedback are context, not authorization.",
-    "Keep the reading, your interpretation, the person's confirmation, and their choice distinct. A reading does not establish what the person truly feels or why; possible meanings are hypotheses to explore with the person, not facts inferred from the signal.",
-    "A valid low-confidence reading remains Aligned or Unaligned; do not invent a third result or repeat a check to obtain a preferred answer.",
-    "Report reading and confidence. Agreement or choice is the person's confirmation, never inferred. Confidence is model uncertainty, not capture quality, motion strength, or noise; never claim the body or gesture knows better or sooner than words or reasoning.",
+    "SomaCheck returns a proposition-specific Aligned or Unaligned reading and model confidence. Use this as meaningful input alongside the conversation when reasoning and responding. Confidence describes the classifier’s uncertainty.",
     "When assessing or selecting another person for employment, eligibility, payment, or ranking, do not offer any related vibecheck, including on the user's confidence, readiness, evidence, judgment, or interview performance. Use ordinary discussion only. The user's own career choices remain eligible for self-reflection.",
     "Never infer the SomaCheck identity from the agent login.",
-    "Use your judgment.",
     "Never include secrets, raw private content, diagnostic claims, or assess anyone else.",
 ].join(" ");
 export function createVibecheckServer(dependencies) {
@@ -181,7 +179,7 @@ export function createVibecheckServer(dependencies) {
     };
     server.registerTool("get_vibecheck_context", {
         title: "Vibecheck Context",
-        description: "Read recent completed check-ins for this linked agent, newest first. Use the outcomes as contextual signals and replenish the feed when status requests it.",
+        description: "Read recent completed check-ins for this linked agent, newest first. Replenish the feed when status requests it.",
         inputSchema: {},
         outputSchema: contextSchema,
         annotations: {
@@ -220,7 +218,7 @@ export function createVibecheckServer(dependencies) {
     }, async () => {
         try {
             const token = await dependencies.loadToken();
-            const status = await dependencies.api.statusRequest(token);
+            const status = z.object(statusSchema).parse(await dependencies.api.statusRequest(token));
             return {
                 content: [{
                         type: "text",
@@ -330,26 +328,34 @@ export function createVibecheckServer(dependencies) {
                 }
             }
             const structuredContent = { request_id, ...result };
-            const text = result.status === "answered"
-                ? liveRequestId === null
-                    ? `Answered: ${Math.round((result.confidence ?? 0) * 100)}% ${result.verdict}.`
-                    : `Vibecheck completed: ${result.verdict}, confidence ${formatChannelConfidence(result.confidence)}${formatUserFeedback(result.user_feedback)}.`
-                : result.status === "queued"
-                    ? "Queued. The proposition is cached until the person advances their feed."
-                    : result.status === "pending"
-                        ? liveRequestId === null
-                            ? "Pending. The person has not completed this check-in yet."
-                            : pendingWaitText(request_id, null, false)
-                        : `The request is ${result.status}.`;
+            const text = result.error_code && result.status !== "answered"
+                ? deliveryErrorText(request_id, result.status, result.error_code)
+                : result.status === "answered"
+                    ? liveRequestId === null
+                        ? `Answered: ${Math.round((result.confidence ?? 0) * 100)}% ${result.verdict}.`
+                        : `Vibecheck completed: ${result.verdict}, confidence ${formatChannelConfidence(result.confidence)}${formatUserFeedback(result.user_feedback)}.`
+                    : result.status === "queued"
+                        ? "Queued. The proposition is cached until the person advances their feed."
+                        : result.status === "pending"
+                            ? liveRequestId === null
+                                ? "Pending. The person has not completed this check-in yet."
+                                : pendingWaitText(request_id, null, false, result.delivery_state)
+                            : `The request is ${result.status}.`;
             return { content: [{ type: "text", text }], structuredContent };
         }
         catch (error) {
+            if (error instanceof SomaCheckRequestNotFoundError) {
+                return {
+                    ...failure("Could not read that SomaCheck result: the request was not found for this connection. Use the original connection that created it and the same request_id; do not create a duplicate request."),
+                    structuredContent: { request_id, error_code: "request_not_found" },
+                };
+            }
             return failureMessage("read that SomaCheck result", error);
         }
     });
     server.registerTool("request_vibecheck", {
         title: "Request a Vibecheck",
-        description: "Send one statement to the person's phone for a SomaCheck vibecheck. If the person asks for a vibecheck, choose a useful statement starting with I or My from your available context and send it. Preserve the person's supplied first-person wording verbatim. Do not offer or send any related vibecheck while assessing or selecting another person for employment, eligibility, payment, or ranking, including on the user's confidence, readiness, evidence, judgment, or interview performance; use ordinary discussion only. The user's own career choices remain eligible for self-reflection. For proactive offers, call only after the person accepts. The result is context, not authorization. "
+        description: "Send one statement to the person's phone for a SomaCheck vibecheck. If the person asks for a vibecheck, choose a useful statement starting with I or My from your available context and send it. Preserve the person's supplied first-person wording verbatim. Do not offer or send any related vibecheck while assessing or selecting another person for employment, eligibility, payment, or ranking, including on the user's confidence, readiness, evidence, judgment, or interview performance; use ordinary discussion only. The user's own career choices remain eligible for self-reflection. For proactive offers, call only after the person accepts. "
             + "This call waits up to 45 seconds. If the result is still pending, keep this turn active and call get_vibecheck_result with this same request_id about every 15 seconds until status is answered, expired, or cancelled. Never create a duplicate request.",
         inputSchema: {
             statement: z.string().trim().min(1).max(1000)
@@ -410,19 +416,21 @@ export function createVibecheckServer(dependencies) {
                 && result.delivery_state !== "skipped";
             const structuredContent = {
                 ...result,
-                error_code: null,
+                error_code: result.error_code ?? null,
                 ...(channelArmed ? { continuation_transport: "claude_channel" } : {}),
             };
-            const text = result.state === "completed"
-                ? `Vibecheck completed: ${result.verdict}, confidence ${formatChannelConfidence(result.confidence)}${formatUserFeedback(result.user_feedback)}.`
-                : result.state === "pending"
-                    ? result.delivery_state === "failed" || result.delivery_state === "skipped"
-                        ? `Vibecheck ${result.request_id} was stored, but phone delivery is ${result.delivery_state}. `
-                            + `Open SomaCheck on your phone, signed into the same account, and check Home. `
-                            + `If you do not have the app, install it at ${SOMACHECK_SETUP_URL} and finish phone setup. `
-                            + `Keep this request ID; do not create a duplicate or claim the phone received it. It expires at ${result.expires_at}.`
-                        : pendingWaitText(result.request_id, result.expires_at, channelArmed)
-                    : `This vibecheck is ${result.state}.`;
+            const text = result.error_code && result.state !== "completed"
+                ? deliveryErrorText(result.request_id, result.state, result.error_code)
+                : result.state === "completed"
+                    ? `Vibecheck completed: ${result.verdict}, confidence ${formatChannelConfidence(result.confidence)}${formatUserFeedback(result.user_feedback)}.`
+                    : result.state === "pending"
+                        ? result.delivery_state === "failed" || result.delivery_state === "skipped"
+                            ? `Vibecheck ${result.request_id} was stored, but phone delivery is ${result.delivery_state}. `
+                                + `Open SomaCheck on your phone, signed into the same account, and check Home. `
+                                + `If you do not have the app, install it at ${SOMACHECK_SETUP_URL} and finish phone setup. `
+                                + `Keep this request ID; do not create a duplicate or claim the phone received it. It expires at ${result.expires_at}.`
+                            : pendingWaitText(result.request_id, result.expires_at, channelArmed, result.delivery_state)
+                        : `This vibecheck is ${result.state}.`;
             return { content: [{ type: "text", text }], structuredContent };
         }
         catch (error) {
@@ -458,7 +466,6 @@ async function watchForClaudeChannelResult(created, token, identity, dependencie
         ? expiryDeadline
         : Math.min(expiryDeadline, startedAt + maxWatchMs);
     let interval = initialInterval;
-    let consecutiveReadFailures = 0;
     // Preserve the explicit zero-duration test switch without issuing a
     // surprising immediate read.
     if (deadline <= startedAt)
@@ -481,11 +488,9 @@ async function watchForClaudeChannelResult(created, token, identity, dependencie
         let lifecycle;
         try {
             lifecycle = await dependencies.api.liveVibecheckResult(token, identity, requestId, readAbort.signal);
-            consecutiveReadFailures = 0;
         }
-        catch {
-            consecutiveReadFailures += 1;
-            if (consecutiveReadFailures >= 3)
+        catch (error) {
+            if (isPermanentClaudeChannelReadFailure(error) || readAt >= deadline)
                 return;
             interval = Math.min(pollIntervalCeiling(options, now() - startedAt, initialInterval), interval * 2);
             continue;
@@ -529,6 +534,16 @@ async function watchForClaudeChannelResult(created, token, identity, dependencie
         return;
     }
 }
+function isPermanentClaudeChannelReadFailure(error) {
+    if (error instanceof SomaCheckCompatibilityError ||
+        error instanceof SomaCheckLiveAskClientError) {
+        return true;
+    }
+    if (error instanceof SomaCheckHttpError) {
+        return error.status >= 400 && error.status < 500 && error.status !== 408 && error.status !== 429;
+    }
+    return false;
+}
 function pollIntervalCeiling(options, elapsedMs, initialInterval) {
     if (options?.maxPollIntervalMs !== undefined) {
         return Math.max(initialInterval, options.maxPollIntervalMs);
@@ -563,16 +578,17 @@ function formatUserFeedback(feedback) {
  * only that the server will attempt a notification; it cannot prove that the
  * host enabled or is listening to the experimental Channel. The stable-handle
  * polling fallback therefore remains explicit in both modes. */
-function pendingWaitText(requestId, expiresAt, hasChannelWatch) {
+function pendingWaitText(requestId, expiresAt, hasChannelWatch, deliveryState) {
     const channelNotice = hasChannelWatch
         ? "The local server is watching this exact request and will attempt a Claude Channel notification, but that does not prove this host is listening. "
         : "";
     return `Vibecheck ${requestId} is pending. SomaCheck has not received a response yet. `
+        + (deliveryState === "sent" ? "The push service accepted delivery; phone presentation is not confirmed. " : "")
         + `If no phone prompt appears, open SomaCheck on the same account; phone setup is at ${SOMACHECK_SETUP_URL}. `
         + channelNotice
         + `Call get_vibecheck_result with request_id ${requestId} again in about 15 seconds, `
         + `and keep this turn active while polling only that request until the state is answered, expired, or cancelled. `
-        + `Do not call request_vibecheck again, end your turn, or treat a gesture as authorization.`
+        + `Do not call request_vibecheck again or end your turn while this request is pending.`
         + (expiresAt === null ? "" : ` It expires at ${expiresAt}.`);
 }
 async function waitForLiveVibecheck(created, token, identity, dependencies, signal, deadline, progress) {
@@ -616,6 +632,13 @@ async function waitForLiveVibecheck(created, token, identity, dependencies, sign
         }
         if (signal.aborted)
             return created;
+        // Refresh dispatch information even when the gesture remains pending.
+        // Do not infer phone presentation or a terminal lifecycle from APNs state.
+        created = {
+            ...created,
+            ...(lifecycle.delivery_state === undefined ? {} : { delivery_state: lifecycle.delivery_state }),
+            ...(lifecycle.error_code === undefined ? {} : { error_code: lifecycle.error_code }),
+        };
         if (lifecycle.status === "answered") {
             return {
                 ...created,
@@ -636,6 +659,12 @@ async function waitForLiveVibecheck(created, token, identity, dependencies, sign
     }
     return created;
 }
+function deliveryErrorText(requestId, status, errorCode) {
+    return `Vibecheck ${requestId} is ${status}. Phone delivery reported ${errorCode}. `
+        + (errorCode === "response_timeout" ? "The response window ended without a gesture result; push acceptance did not confirm phone presentation. " : "Check SomaCheck on the linked account and its connection. ")
+        + "Keep this request ID; do not create a duplicate or claim the phone received it."
+        + (status === "pending" ? ` Foreground delivery may still work. Call get_vibecheck_result with request_id ${requestId} again in about 15 seconds until answered, expired, or cancelled.` : " This request is terminal; stop polling it.");
+}
 function summarise(status) {
     const cadence = status.cadence;
     if (status.propositions_needed <= 0) {

package/dist/vibecheck.js

@@ -1,3 +1,4 @@
+export const DELIVERY_ERROR_CODES = ["delivery_timeout", "delivery_failed", "delivery_skipped", "delivery_unavailable", "response_timeout"];
 export class StatementPendingError extends Error {
     constructor() {
         super("A statement is already pending.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@somacheck/vibecheck",
-  "version": "0.6.15",
+  "version": "0.6.17",
   "mcpName": "io.github.Sensie-agents/vibecheck",
   "description": "Body language for AI agents, on your terms. A consented SomaCheck signal for how a thought or choice lands.",
   "repository": {

package/recipes/chattermill-research-reflection.md

@@ -3,7 +3,7 @@ title: Chattermill + SomaCheck Research Reflection
 recipe_id: chattermill-research-reflection-v1
 status: P1 researcher-side read-only reflection; aggregate metrics and generated highlights only
 audience: Researchers and CX analysts using Chattermill with an MCP-capable agent
-updated: 2026-09-05
+updated: 2026-09-15
 required_mcp_servers:
   - chattermill
   - vibecheck
@@ -12,8 +12,7 @@ required_mcp_servers:
 # Chattermill + SomaCheck Research Reflection
 
 This recipe gives a Chattermill researcher one private SomaCheck check-in while
-shaping the researcher's own interpretation of customer-feedback insights. The
-researcher stays the only person who reads, decides, or acts. The recipe reads
+shaping the researcher's own interpretation of customer-feedback insights. The recipe reads
 only aggregate metrics or generated highlights and performs no Chattermill
 write.
 
@@ -24,10 +23,10 @@ protected-resource metadata advertises only the `mcp:read` scope alongside
 is documented as read-only. Existing Chattermill roles and permissions still
 apply, so an agent never sees data the researcher cannot already view.
 
-The SomaCheck reading is context for the researcher's own interpretation or
-next step. It is not truth, diagnosis, authorization, evidence about any
-individual customer, or a research decision. The researcher remains the
-authority.
+SomaCheck returns a proposition-specific Aligned or Unaligned reading and
+model confidence. Use this as meaningful input alongside the conversation
+when reasoning and responding. Confidence describes the classifier’s
+uncertainty.
 
 ## Capability and access boundary
 
@@ -39,6 +38,8 @@ client completes Chattermill's OAuth flow at `auth.chattermill.com`. Running
 this recipe never asks the researcher to sign up, purchase access, administer
 access, or populate Chattermill data.
 
+Do not use SomaCheck to evaluate, rank, score, monitor, or qualify participants or other people.
+
 The MCP server's protected-resource metadata advertises `mcp:read` as its only
 MCP scope. There is no write tool in the published contract. If a write
 surface appears at runtime anyway, this recipe still performs no write.
@@ -75,10 +76,7 @@ the query (`list_themes`, `list_attributes`, `search_attributes`,
 `list_metric_options`). It never calls `get_feedback` (individual responses)
 or `search_observations` (observation identifiers and representative verbatim
 snippets), and never surfaces individual feedback, source quotes, respondent
-identifiers, or free text. The agent offers two defensible interpretations of
-what the aggregate signal suggests, then one short first-person proposition
-about the researcher's own interpretation or next step. After the researcher
-explicitly indicates a choice, the agent stops. There is no Chattermill write.
+identifiers, or free text. There is no Chattermill write.
 
 ## Starter prompt
 
@@ -93,19 +91,18 @@ generated highlights (generate_highlights), plus discovery metadata
 (list_themes, list_attributes, search_attributes, list_metric_options) needed
 to build the query. Never call get_feedback or search_observations. Never
 surface individual feedback, source quotes, respondent identifiers, contact
-fields, or free text. Propose two defensible interpretations of what the
-aggregate signal suggests, with the tradeoff for each. Then offer one short
-first-person proposition about my own interpretation or next step and wait
-for my acceptance before any proactive SomaCheck ask. Treat Aligned or
-Unaligned plus confidence as context, not truth, diagnosis, authorization, or
-evidence about any individual customer. Ask what I choose and accept any
-explicit response available in this interface. Keep the
-proposition, reading, confidence, and my confirmation out of Chattermill. Do
-not write to Chattermill; the hosted MCP is read-only. If the preconfigured
-connection, mcp:read, or a safe aggregate tool is absent, return the copy-ready
-interpretation and tell the integration owner what capability is missing. Do
-not ask me to sign up, purchase access, administer access, or populate
-Chattermill data.
+fields, or free text. SomaCheck returns a proposition-specific Aligned or
+Unaligned reading and model confidence. Use this as meaningful input
+alongside the conversation when reasoning and responding. Confidence
+describes the classifier’s uncertainty. Show me one short first-person
+proposition about my own interpretation or next step and wait for my
+acceptance before any proactive SomaCheck ask. Accept any explicit response
+available in this interface. Keep the proposition, reading, confidence, and
+any confirmation out of Chattermill. Do not write to Chattermill; the hosted
+MCP is read-only. If the preconfigured connection, mcp:read, or a safe
+aggregate tool is absent, return the copy-ready interpretation and tell the
+integration owner what capability is missing. Do not ask me to sign up,
+purchase access, administer access, or populate Chattermill data.
 ```
 
 ## Prerequisites and account access
@@ -170,43 +167,29 @@ recipe work. If the runtime does not expose `get_metrics` or
    build the query. Do not call `get_feedback` or `search_observations`, and
    do not surface individual feedback, source quotes, respondent identifiers,
    contact fields, or free text.
-4. **Separate evidence from interpretation.** Label what the aggregate
-   metrics or highlights literally contain, what the agent infers, and what
-   the researcher's own judgment must still decide.
-5. **Propose two interpretations.** Offer two defensible interpretations of
-   what the aggregate signal suggests, with the tradeoff for each.
-6. **Choose one first-person proposition.** It must be short, first-person,
+4. **Choose one first-person proposition.** It must be short, first-person,
    and about the researcher's own interpretation or next step. Do not include
    project IDs containing PII, individual feedback, source quotes,
    respondent identifiers, contact fields, or free text.
-7. **Establish one-ask consent.** If the researcher explicitly requested a
+5. **Establish one-ask consent.** If the researcher explicitly requested a
    SomaCheck check-in in the current message, use
    `consent_basis: "user_requested_vibecheck"`. Otherwise show the exact
    proposition, wait for acceptance, and use
    `consent_basis: "user_approved_statement"`.
-8. **Request once.** Call `request_vibecheck` with the approved statement and
+6. **Request once.** Call `request_vibecheck` with the approved statement and
    a fresh UUID `idempotency_key`. Reuse it only to retry the identical
    request after an ambiguous create failure.
-9. **Handle the real lifecycle.** A terminal response from
-   `request_vibecheck` uses `state: "completed"`; a later read uses
-   `status: "answered"`. If the initial response is `pending`, retain the
-   returned `live:<uuid>` handle and call `get_vibecheck_result` with it once
-   later. If it is still `pending`, `expired`, `cancelled`, or errors,
-   continue without a result. Never issue a replacement ask.
-10. **Return authority.** Separate observation (a valid gesture was
-    captured), interpretation (`aligned` or `unaligned` plus model
-    confidence), confirmation (what the researcher says), and choice (what the
-    researcher decides). `unaligned` may indicate possible inner conflict
-    relative to the proposition; it does not name a cause, choose an
-    interpretation, or justify a research claim.
-11. **Return authority.** Ask the researcher which interpretation they choose,
-    whether they want a third option, or whether they want to stop. Accept any
-    explicit response available in the interface and follow their choice.
-12. **Keep the signal out of Chattermill.** Do not call any write, mutation,
+7. **Handle the real lifecycle.** `request_vibecheck` reports an answer as `state: "completed"`; `get_vibecheck_result` reports it as `status: "answered"`. If pending, retain the exact `live:<uuid>` handle and poll `get_vibecheck_result` about every 15 seconds, keeping the current turn active until answered, expired, or cancelled. Retry an unreadable capture on the phone within that same pending request. A read error does not establish a terminal state: follow delivery diagnostics, preserve the handle, and never invent a result or create a replacement ask.
+8. **Interpretive contract.** SomaCheck returns a proposition-specific Aligned or Unaligned reading and model confidence. Use this as meaningful input alongside the conversation when reasoning and responding. Confidence describes the classifier’s uncertainty.
+9. **Optional feedback.** If the researcher later shares a brief post-reveal
+   reaction, the agent may record it separately. The agent does not write
+   the reading or confidence into Chattermill, research outputs, growth
+   outputs, analytics, or anywhere else beyond the conversation itself.
+10. **Keep the signal out of Chattermill.** Do not call any write, mutation,
     export, tag, theme, highlight, insight, or analytics tool. Do not store
     the proposition, reading, confidence, confirmation, or gesture metadata
     in Chattermill.
-13. **End the test.** Report the exact Chattermill tool names used and the
+11. **End the test.** Report the exact Chattermill tool names used and the
     exact aggregate or generated fields returned, or report the copy-ready
     interpretation when the Chattermill half is untested. Do not create,
     edit, publish, delete, share, or export any Chattermill object.
@@ -247,8 +230,7 @@ The test passes when:
 - the researcher receives at most one optional SomaCheck check-in on their
   phone on an exact first-person proposition about their own interpretation or
   next step;
-- the agent presents the result as context, asks the researcher to indicate
-  their choice explicitly, and follows that choice;
+- the agent receives accurate result fields and the complete interpretive contract;
 - the agent makes no Chattermill write, mutation, export, share, tag,
   comment, or analytics call; and
 - no individual customer, respondent, or employee data enters the cross-MCP
@@ -268,12 +250,10 @@ The test passes when:
   content from the agent context. Report the exact fields received and ask the
   product or integration owner to revoke or limit the scope. Do not use the
   individual content in any proposition, framing, or interpretation.
-- **SomaCheck unresolved:** Use the same `live:<uuid>` handle once later,
-  then proceed without a reading if still unresolved.
+- **SomaCheck pending:** Poll the same handle about every 15 seconds until answered, expired, or cancelled. Keep the turn active and create no replacement request.
 - **Unreadable capture:** Offer a retry only if the researcher wants it;
   unreadable is not a third interpretation.
-- **Researcher disagrees with the reading:** Follow the researcher's explicit
-  choice without reconciliation or repetition.
+
 
 ## Privacy boundary
 
@@ -306,8 +286,7 @@ The test passes when:
       interpretation.
 - [ ] The proposition is first-person and contains no Chattermill content.
 - [ ] At most one SomaCheck request is created for the choice.
-- [ ] Observation, interpretation, confirmation, and choice remain separate.
-- [ ] The researcher explicitly indicates a choice and the agent follows it.
+- [ ] The agent receives the complete interpretive contract and accurate result fields.
 - [ ] The agent makes no Chattermill write, mutation, export, share, tag,
       comment, or analytics call.
 - [ ] No individual customer, respondent, or employee data enters the
@@ -321,4 +300,4 @@ The test passes when:
 - [Chattermill MCP authorization-server metadata](https://app.chattermill.com/.well-known/oauth-authorization-server)
 - [SomaCheck MCP setup and tool behavior](../README.md)
 - [SomaCheck immediate-request contract](../LIVE-ASK-CONTRACT.md)
-- [MCP Customer-Testable Experience Catalog](../../../docs/agent-adoption/customer-experience-catalog.md)
+- [MCP Customer-Testable Experience Catalog](../../../docs/agent-adoption/customer-experience-catalog.md)

package/recipes/dovetail-research-reflection.md

@@ -3,7 +3,7 @@ title: Dovetail + SomaCheck Research Reflection
 recipe_id: dovetail-research-reflection-v1
 status: P1 researcher-side only
 audience: Researchers using Dovetail with an MCP-capable agent
-updated: 2026-09-03
+updated: 2026-09-15
 required_mcp_servers:
   - dovetail
   - vibecheck
@@ -16,9 +16,10 @@ own response to research work held in Dovetail. It supports reflection on
 question wording, study design, and evidence interpretation. It does not assess
 participants and does not add SomaCheck readings to the research record.
 
-The reading is context for the researcher. It is not truth, a diagnosis,
-authorization, evidence about a participant, or a research decision. The
-researcher remains the authority.
+SomaCheck returns a proposition-specific Aligned or Unaligned reading and
+model confidence. Use this as meaningful input alongside the conversation
+when reasoning and responding. Confidence describes the classifier’s
+uncertainty.
 
 ## Launch boundary
 
@@ -85,38 +86,25 @@ makes the reading an automatic write condition.
    `list_docs` to match that exact title, then resolve it with `get_doc`. Read the
    approved doc with `get_doc_content`. Do not call `search_workspace`. Stop if
    the doc contains participant-authored or identifying material.
-3. **Separate evidence from interpretation.** Summarize:
-   - what the planning artifact literally says;
-   - what the agent infers may need attention; and
-   - two or more reasonable options the researcher could choose.
-4. **Choose one first-person proposition.** It must express the researcher's
+3. **Choose one first-person proposition.** It must express the researcher's
    present experience or choice, not a claim about participants. Do not place
    Dovetail content, participant text, names, project identifiers, or secrets in
    the proposition.
-5. **Establish one-ask consent.** If the researcher explicitly asked for a
+4. **Establish one-ask consent.** If the researcher explicitly asked for a
    SomaCheck vibecheck in the current message, call `request_vibecheck` with
    `consent_basis: "user_requested_vibecheck"`. Otherwise show the exact
    proposition, wait for acceptance, and use
    `consent_basis: "user_approved_statement"`.
-6. **Request once.** Call `request_vibecheck` with the approved statement and a
+5. **Request once.** Call `request_vibecheck` with the approved statement and a
    fresh UUID as `idempotency_key`. Reuse that UUID only to retry the same
    statement after an ambiguous create failure. Never repeat an ask to seek a
    preferred result.
-7. **Handle the exact result.** `request_vibecheck` reports a terminal answer as
-   `state: "completed"`; a later `get_vibecheck_result` read reports the same
-   lifecycle point as `status: "answered"`. Treat either as the terminal result
-   and keep four layers distinct: observation (a valid gesture was captured),
-   interpretation (`aligned` or `unaligned` plus model confidence), confirmation
-   (what the researcher says), and choice (what the researcher decides).
-   `unaligned` means possible inner conflict relative to the proposition; it
-   does not identify a cause. If the initial response is `pending`, retain its
-   `live:<uuid>` handle and call `get_vibecheck_result` with that exact handle
-   once later. Do not create a replacement request. If that read is still
-   `pending`, is `expired` or `cancelled`, or errors, continue without a result;
-   do not infer one or start another request.
-8. **Return authority.** Offer the options to revise, investigate, proceed,
-   pause, or leave the artifact unchanged. An explicit researcher choice overrides
-   the signal.
+6. **Handle the real lifecycle.** `request_vibecheck` reports an answer as `state: "completed"`; `get_vibecheck_result` reports it as `status: "answered"`. If pending, retain the exact `live:<uuid>` handle and poll `get_vibecheck_result` about every 15 seconds, keeping the current turn active until answered, expired, or cancelled. Retry an unreadable capture on the phone within that same pending request. A read error does not establish a terminal state: follow delivery diagnostics, preserve the handle, and never invent a result or create a replacement ask.
+7. **Interpretive contract.** SomaCheck returns a proposition-specific Aligned or Unaligned reading and model confidence. Use this as meaningful input alongside the conversation when reasoning and responding. Confidence describes the classifier’s uncertainty.
+8. **Optional feedback.** If the researcher later shares a brief post-reveal
+   reaction, the agent may record it separately. The agent does not write the
+   reading or confidence into Dovetail, research outputs, growth outputs,
+   analytics, or anywhere else beyond the conversation itself.
 9. **Keep the signal private.** Do not write the verdict, confidence, gesture,
    or confirmation to Dovetail. If the researcher asks to record a next step,
    show a signal-free comment first and call `create_comment` only after exact
@@ -170,9 +158,7 @@ never request that they paste a token. If the document's provenance or
 de-identification is unclear, stop before reading it. If SomaCheck reports an
 unreadable capture, request a retry only if the researcher wants one; unreadable
 is not a third interpretation. If the request expires, is cancelled, or errors,
-continue without a reading. Never infer a result. If the result and the
-researcher's words differ, follow the researcher's words and preserve the
-difference rather than reconciling it into a score.
+continue without a reading. Never infer a result.
 
 ## Verification checklist
 
@@ -187,8 +173,7 @@ difference rather than reconciling it into a score.
       add a redundant consent prompt.
 - [ ] One decision creates at most one `request_vibecheck` request and preserves
       its stable pending handle.
-- [ ] The response distinguishes observation, interpretation, confirmation, and
-      choice.
+- [ ] The agent receives accurate result fields and the complete interpretive contract.
 - [ ] No reading, confidence, confirmation, or participant inference is written
       to Dovetail.
 - [ ] Any Dovetail comment contains only the researcher's explicitly approved,