@ratifia/mcp 0.13.0 → 0.13.2

package/README.md

@@ -132,11 +132,11 @@ request_decision(
 )
 ```
 
-### Conversational Approvals — propose a draft, get it refined
+### Propose a draft, get it refined
 
 Pass `proposed_output` to attach an **editable draft** (e.g. an email you want to
-send). The human refines it in conversation — in the dashboard or by replying in the
-Slack thread — and you get **their** final version back:
+send). The human can edit it in the Ratifia app (Slack can only approve or reject
+it), and you get **their** final version back:
 
 ```
 request_decision(

package/dist/server.js

@@ -15,8 +15,9 @@ const formatDecision = (d) => ({
     ...(d.responseSpec ? { response_spec: d.responseSpec } : {}),
     ...(d.responseValue ? { response_value: d.responseValue } : {}),
     // FN-185: if you sent a proposed_output (e.g. a draft email), the human may
-    // have refined it (in the dashboard or a Slack thread). `output.content` is the
-    // effective final text to act on — use it over your original draft.
+    // have edited it in the Ratifia app (Slack can only approve or reject it).
+    // `output.content` is the effective final text to act on — use it over your
+    // original draft.
     ...(d.output ? { output: d.output, refined: Boolean(d.refinedOutput) } : {}),
     decided_by: d.decidedBy,
     decided_at: d.decidedAt,
@@ -97,12 +98,13 @@ export function createRatifiaServer(cfg, opts) {
             'When to use request_decision: before a consequential or irreversible action (prod deploy, delete/drop, data migration, spending, sending something externally, credential rotation), or when a requirement is ambiguous and guessing wrong would be costly. Skip it for trivial, reversible, or clearly-authorized steps — that is just friction.',
             '',
             'Workflow:',
+            '0. At the start of a run, call list_pending_decisions first: it picks up decisions answered while you were away or before your context was reset.',
             '1. Call request_decision with a short title, a precise question, and enough context to decide (the command/diff/options + tradeoffs). Set timeout_minutes if it is time-sensitive.',
             'Filing: set `workflow` to the project or ongoing effort the decision belongs to (e.g. the repo name, "billing-refunds") so a human can see related decisions together in the dashboard, and reuse the exact same string every time. Put what is specific to this decision (the release, record, environment) in `step`, e.g. "deploy-v2.3-prod". Without them every decision lands in one "ratifia-mcp" bucket.',
             '2. It returns a decision_id (+ url). The human is notified and may be away from their keyboard, so a verdict can take a while. (If the org policy auto-resolved that no approval was needed, it returns approval_required=false — just proceed.)',
-            '3. Wait for the verdict: prefer await_decision (it blocks until answered) over polling check_decision in a loop. Either way, "approved"/"rejected" comes with a note — the note is the human\'s actual answer/input, so read and follow it. If you asked for a choice/typed value (response_type select/text), the answer is in response_value (selected option ids — map them back via response_spec.options — or text), not just the note.',
+            '3. Wait for the verdict: prefer await_decision (it blocks until answered) over polling check_decision in a loop. If await_decision returns timed_out=true, call it again; that is normal. Do not end your turn while a decision is still pending unless something will read the verdict back: a verdict does not wake you, so start a background watcher or scheduled wake-up that calls check_decision, or save the decision_id where your next run will find it. Saying "still pending" and stopping drops the task. Either way, "approved"/"rejected" comes with a note — the note is the human\'s actual answer/input, so read and follow it. If you asked for a choice/typed value (response_type select/text), the answer is in response_value (selected option ids — map them back via response_spec.options — or text), not just the note.',
             '4. Do NOT perform the gated action until it resolves approved. On rejected or expired, do not proceed — adapt or ask again.',
-            'Refining content: to have a human review/edit a draft (e.g. an email you want to send), pass proposed_output.content. They can refine it (in the dashboard or by replying in the Slack thread); once approved, use output.content as the final text — it may differ from what you sent.',
+            'Refining content: to have a human review/edit a draft (e.g. an email you want to send), pass proposed_output.content. They can edit it in the Ratifia app (Slack can only approve or reject it); once approved, use output.content as the final text — it may differ from what you sent.',
             'Evidence: if your ask rests on material the human should see — a Slack conversation, an email, a policy excerpt — attach it (the `evidence` array on request_decision, or attach_evidence afterwards). Send the text, not just a link: the snapshot is what the audit trail keeps, and a link can change. Evidence can only be attached while the decision is pending; once it resolves the set is sealed, so attach before you await.',
             'Prefer one well-scoped decision with rich context over many small ones.',
         ].join('\n'),
@@ -144,7 +146,7 @@ export function createRatifiaServer(cfg, opts) {
                 content: z.string().describe('The draft the human can edit before approving (e.g. the email text).'),
             })
                 .optional()
-                .describe('A draft artifact the human can refine before approving — e.g. an email you propose to send. They can edit it (in the dashboard or by replying in the Slack thread); on approval the final text comes back in `output.content`. Use this when you want a human to review/refine content, not just say yes/no.'),
+                .describe('A draft artifact the human can refine before approving — e.g. an email you propose to send. They can edit it in the Ratifia app (Slack can only approve or reject it); on approval the final text comes back in `output.content`. Use this when you want a human to review/refine content, not just say yes/no.'),
             tool_name: z
                 .string()
                 .optional()

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@ratifia/mcp",
-  "version": "0.13.0",
+  "version": "0.13.2",
   "type": "module",
-  "description": "Ratifia MCP server \u2014 let an AI agent request a human decision/approval (HITL) mid-task and resume once it's answered. The agent becomes a Ratifia 'engine'.",
+  "description": "Ratifia MCP server — let an AI agent request a human decision/approval (HITL) mid-task and resume once it's answered. The agent becomes a Ratifia 'engine'.",
   "keywords": [
     "mcp",
     "model-context-protocol",