@skeletiq/mcp 0.3.0 → 0.4.0

package/README.md

@@ -86,7 +86,7 @@ change your provider keys, see billing, or delete your account, whatever scopes
 |---|---|
 | `list_projects` | Find a project by name. Returns the candidates rather than guessing between them. |
 | `get_design` | Read a design, in one of six modes: `overview`, `component`, `brief`, `readiness`, `build_order`, `gaps`. Where a version records its requirements, `overview` and `component` resolve the design's `R`-ids to the requirements they name, and say what became of each. |
-| `generate_architecture` | Design a system from a prompt. Spends credits and takes minutes. |
+| `generate_architecture` | Design a system from a prompt. Spends credits and takes minutes. A prompt that states no load comes back with a question instead, and nothing is charged: ask your human, and answer "Not sure yet" when they do not know rather than guessing. |
 | `get_generation_status` | Poll a generation started with `wait: false`. |
 | `critique_architecture` | Check a design against SkeletIQ's rules. Deterministic, free, stores nothing. Tell it the `domain` and the `exposure`. |
 | `check_drift` | Report what you built; hear what is missing, half done, or not in the design. |
@@ -114,8 +114,9 @@ unknown ids with suggestions, they are suggestions — put them to a person rath
 mapping.
 
 **`critique_architecture`'s optional inputs are not neutral.** Omitting one does not skip a
-question; it answers it. With no `domain` and `secondary_domains`, no compliance framework applies,
-so no compliance finding is possible and the score comes back higher than the SkeletIQ app shows
+question; it answers it. With no `domain`, no compliance framework applies (`secondary_domains`
+select none — they add that domain's design checks as advice — so name a framework when it must
+apply), so no compliance finding is possible and the score comes back higher than the SkeletIQ app shows
 for the same design — by up to 15 points. With no `exposure`, the design is assessed as
 internet-facing, which is how an air-gapped system gets told to add a CDN and a WAF. The response
 says what was actually used — `frameworks_checked` and `exposure_assessed` — and the text output

package/dist/index.js

@@ -5,7 +5,7 @@ import { serveStdio } from "@modelcontextprotocol/server/stdio";
 
 // src/config.ts
 var SERVER_NAME = "skeletiq";
-var SERVER_VERSION = "0.3.0";
+var SERVER_VERSION = "0.4.0";
 var DEFAULT_API_URL = "https://api.skeletiq.com";
 var TOKEN_PREFIX = "skq_";
 var ConfigError = class extends Error {
@@ -60,12 +60,12 @@ var SkeletiqApiError = class extends Error {
   /**
    * A `GET` may be retried after a 429; a `POST` that may have spent credits may not.
    *
-   * A spent daily allowance is the one 429 that is *not* retryable: it refills on a clock
-   * measured in hours, so a caller backing off and trying again is burning its budget on a
-   * call that cannot succeed today.
+   * A spent daily allowance is the 429 that is *not* retryable — the account's, or a runtime's
+   * shared one: each refills on a clock measured in hours, so a caller backing off and trying
+   * again is burning its budget on a call that cannot succeed today.
    */
   get isRetryable() {
-    if (this.code === "DAILY_LIMIT_REACHED") return false;
+    if (this.code === "DAILY_LIMIT_REACHED" || this.code === "RUNTIME_ALLOWANCE_SPENT") return false;
     return this.status === 429 || this.code === "IDEMPOTENCY_UNAVAILABLE";
   }
 };
@@ -138,6 +138,12 @@ function describeApiError(error) {
       if (upgradeUrl) lines.push(`A larger plan raises the daily limit: ${upgradeUrl}`);
       break;
     }
+    case "RUNTIME_ALLOWANCE_SPENT": {
+      lines.push(error.message);
+      const resetAt = asString(detail?.reset_at);
+      if (resetAt) lines.push(`The allowance resets at ${resetAt}.`);
+      break;
+    }
     case "PLAN_LIMIT_EXCEEDED":
     case "FEATURE_NOT_AVAILABLE":
     case "VERSION_LOCKED": {
@@ -344,6 +350,20 @@ var RequirementLedgerRowSchema = z.looseObject({
   /** The model behind a `verifier` verdict. Null on every deterministic row — naming a model
    * beside a number the server computed would be a false attribution. */
   checked_by: z.string().nullable().optional(),
+  /** Whether this row holds a handoff back: a `fails` a measurement reached (capacity, cost, the
+   * review's rules). A model check's `fails` does not block. Absent from older APIs, where
+   * `requirementBlocksHandoff` falls back to the method. */
+  blocks_handoff: z.boolean().optional(),
+  /** Why a `fails` does not block: `model_check` — only the model check failed it, nothing
+   * measured it; `unstated_input` — a shortfall that turns on an input nobody gave (an unstated
+   * split, or an assumed load — told apart by `unstated_input`); `advisory_finding` — only review
+   * advice failed it. Null on every other row. A string, for the reason `status` is one. Absent
+   * from older APIs. */
+  unconfirmed_reason: z.string().nullable().optional(),
+  /** True on a review-rules `fails` whose every finding is advice (`advisory_finding`). */
+  advisory_only: z.boolean().optional(),
+  /** The assumption an `unstated_input` row turns on, as a clause. Absent from older APIs. */
+  unstated_input: z.string().nullable().optional(),
   cited_by_components: z.array(z.string()).nullable().optional(),
   /** Indices into `architecture_json.grounded_decisions`, the raw array — blanks are not compacted. */
   cited_by_decisions: z.array(z.number()).nullable().optional(),
@@ -463,7 +483,13 @@ var ReadinessRowSchema = z.looseObject({
   state: z.string(),
   category: z.string(),
   gating: z.boolean(),
-  detail: z.string().nullable().optional()
+  detail: z.string().nullable().optional(),
+  /** On a row that could not be answered: what would answer it ("Saving a change runs the
+   * check on the new version."). Absent on a row that has an answer. */
+  clears: z.string().nullable().optional(),
+  /** True when stating the expected load is what would answer this row — `clears` then says
+   * how. Optional so a server that predates the field still parses. */
+  clears_by_load: z.boolean().optional()
 });
 var ReadinessSchema = z.looseObject({
   architecture_id: z.string(),
@@ -516,7 +542,15 @@ var DesignGapSchema = z.looseObject({
   problem_key: z.string().optional(),
   /** An answer is recorded and this version was not built with it, so iterating the design
    * would change something. False once a generation has been handed the answer. */
-  answer_pending: z.boolean().optional()
+  answer_pending: z.boolean().optional(),
+  /** The read/write mix or peak this assumption states that the design is not sized on. Null when
+   * the two agree; absent from older servers. */
+  sizing_conflict: z.looseObject({
+    dimension: z.string(),
+    assumed: z.string(),
+    sized: z.string(),
+    resize_to: z.string().nullable().optional()
+  }).nullable().optional()
 });
 var OrphanedAnswerSchema = z.looseObject({
   gap_id: z.string(),
@@ -612,7 +646,10 @@ var TodoItemSchema = z.looseObject({
    * it goes back further than the server looked — "an earlier version", never version zero. */
   carried_from_version: z.number().nullable().optional(),
   dismissed: z.boolean().optional(),
-  dismissed_reason: z.string().nullable().optional()
+  dismissed_reason: z.string().nullable().optional(),
+  /** The key of the one readiness row this card is counted on, so the readiness counts can be
+   * traced to cards. Null on a card no row counts. */
+  counts_toward: z.string().nullable().optional()
 });
 var TodoGroupSchema = z.looseObject({
   key: z.string(),
@@ -659,13 +696,26 @@ var DriftSchema = z.looseObject({
   counts: z.record(z.string(), z.number()),
   release: ReleaseFactsSchema
 });
+var ClarifyingOptionDetailSchema = z.looseObject({
+  value: z.string(),
+  label: z.string(),
+  detail: z.string().optional()
+});
 var ClarifyingQuestionSchema = z.looseObject({
   id: z.string(),
   question: z.string(),
   why: z.string().optional(),
   kind: z.string().optional(),
   options: z.array(z.string()).nullable().optional(),
-  decline_options: z.array(z.string()).nullable().optional()
+  decline_options: z.array(z.string()).nullable().optional(),
+  /** Options that withdraw the instruction to be rewritten, not answer it ("I'll name the parts"). */
+  dismiss_options: z.array(z.string()).nullable().optional(),
+  /** Each option's label and what it means, keyed by the value in `options`. */
+  option_details: z.array(ClarifyingOptionDetailSchema).nullable().optional(),
+  /** Whether more than one option may be picked at once. */
+  multiple: z.boolean().optional(),
+  /** What leaving the question unanswered does, in the product's words. */
+  skip_effect: z.string().nullable().optional()
 });
 var IntentDecisionSchema = z.looseObject({
   intent: z.string().optional(),
@@ -1025,7 +1075,7 @@ var input2 = z3.object({
     "The design's domain \u2014 e-commerce, fintech, healthcare, saas, social, iot, gaming, infrastructure, streaming, logistics, ai-ml, search, data-analytics, content-platform, internal-tool. Worth sending: the domain is what selects the compliance frameworks to check against, and without it none apply, so no compliance finding is possible and the score comes back higher than the SkeletIQ app would show for the same design \u2014 by up to 15 points."
   ),
   secondary_domains: z3.array(z3.string()).max(8).optional().describe(
-    "Further domains the design spans, when it spans more than one \u2014 a multi-tenant shop that takes payments is e-commerce plus fintech and saas. These select frameworks on top of the primary domain's, so leaving them off is why a design already checked against SOC2 and SOX in the app comes back here checked against neither, and scored higher for it. frameworks_checked says which were actually used."
+    "Further domains the design spans, when it spans more than one \u2014 a multi-tenant shop that takes payments is e-commerce plus fintech and saas. These add the design checks that domain usually needs, as advice; they select no compliance frameworks. Only the primary domain's frameworks and the ones the user named are checked, so name a framework in the prompt when it must apply. frameworks_checked says which were used."
   ),
   exposure: z3.enum(["public_internet", "private_network", "air_gapped"]).optional().describe(
     "Where the design runs. Worth sending: four checks \u2014 CDN, WAF, rate limiting and multi-region \u2014 ask whether traffic arriving from the public internet is handled safely, and they only apply to a system that takes any. Left unset, the design is assessed as internet-facing, which is why an air-gapped design comes back told to add a CDN. exposure_assessed says which exposure was actually used."
@@ -1203,9 +1253,10 @@ var PROGRESS_LABELS = {
   refining: "Refining the design"
 };
 var PROGRESS_TOTAL = Object.keys(PROGRESS_LABELS).length + 1;
+var LOAD_NOT_SURE = "Not sure yet";
 var PROVENANCE_LABELS = {
-  user_supplied: "stated",
-  llm_inferred: "inferred",
+  user_supplied: "you set this",
+  llm_inferred: "read from your prompt",
   tier_default: "assumed",
   guardrail_clamped: "adjusted"
 };
@@ -1216,16 +1267,19 @@ function asText(value) {
   if (typeof value === "number" && Number.isFinite(value)) return String(value);
   return typeof value === "string" && value.trim() && value !== "unknown" ? value.trim() : void 0;
 }
+var BARE_FIGURE = /^~?\d[\d,]*(\.\d+)?$/;
 function frameDetail(frame) {
   const data = asRecord2(frame.pipeline_step);
   if (!data) return void 0;
   const parts = [];
   const domain = asText(data.domain);
   if (domain) parts.push(domain);
-  const rps = asText(data.requests_per_second);
-  const figure = rps ? `${rps} rps` : asText(data.scale);
+  const rawRps = asText(data.requests_per_second);
+  const zeroRate = rawRps !== void 0 && Number(rawRps.replace(/[~,]/g, "")) === 0;
+  const rps = zeroRate ? void 0 : rawRps;
+  const figure = rps ? BARE_FIGURE.test(rps) ? `${rps}/s` : rps : asText(data.scale);
   if (figure) {
-    const source = asText(data.scale_source);
+    const source = zeroRate ? void 0 : asText(data.scale_source);
     const label = source ? PROVENANCE_LABELS[source] ?? source : void 0;
     parts.push(label ? `${figure} (${label})` : figure);
   }
@@ -1249,11 +1303,17 @@ var constraintsInput = z4.strictObject({
     "Wins over any share stated in the prompt, which the server also reads. Unset and unstated, the design assumes 80% reads. It sizes components and weights read replicas, so on a read-heavy design it changes the instance counts and the cost."
   ),
   burstiness: z4.enum(["steady", "daily_peaks", "spiky"]).optional().describe(
-    'Wins over a peak the prompt states ("peaking at 2,000 per second"), which the server also reads. Unset and unstated, the design assumes the tier default peak.'
+    'Wins over a peak the prompt states ("peaking at 2,000 per second"), which the server also reads. Unset and unstated, the design assumes a typical peak for its scale.'
   ),
   data_retention: z4.enum(["days", "months", "years", "indefinite"]).optional(),
   consistency: z4.enum(["strict", "eventual", "mixed"]).optional(),
-  data_residency: z4.enum(["any", "us", "eu"]).optional()
+  data_residency: z4.enum(["any", "us", "eu"]).optional(),
+  transfer_band: z4.enum(["light", "moderate", "heavy", "very_heavy", "massive"]).optional().describe(
+    "How much data the system sends out to its users a month: light ~100 GB, moderate ~1 TB, heavy ~10 TB, very_heavy ~100 TB, massive ~1 PB. Priced at the cloud's published per-GB rates. Unset, data transfer is left out of the price and the estimate says so. Set this or monthly_transfer_gb, not both."
+  ),
+  monthly_transfer_gb: z4.number().min(0).max(1e8).optional().describe(
+    "The same thing as a figure: GB a month sent out to users. Set this or transfer_band, not both."
+  )
 });
 var generateInput = z4.object({
   prompt: z4.string().min(1).max(2e4).describe("What to design. Describe the system, its scale and its constraints in prose."),
@@ -1262,7 +1322,7 @@ var generateInput = z4.object({
     "Default true: run inline and return the finished design (this takes several minutes). False queues it as a background job and returns a job_id to poll \u2014 not available on every deployment."
   ),
   clarification_answers: z4.record(z4.string(), z4.string()).optional().describe(
-    'Answers to the questions a previous call returned with status "clarification_required", keyed by their ids. Treated as authoritative requirements, so send what the user told you \u2014 ask them rather than guessing.'
+    'Answers to the questions a previous call returned with status "clarification_required", keyed by their ids. Treated as authoritative requirements, so send what the user told you \u2014 ask them rather than guessing. "Not sure yet" is a real answer to the load question and to the data-sent-out question when they do not know the figure.'
   ),
   constraints: constraintsInput.optional().describe(
     "Facts about the design that the prose does not have to carry. Anything omitted is assumed by SkeletIQ, and the design says which values were assumed."
@@ -1278,6 +1338,12 @@ var generateOutput = z4.object({
   component_count: z4.number().nullable(),
   assistant_message: z4.string().nullable(),
   degradations: z4.array(z4.string()),
+  /**
+   * The server's sentence when part of what the model was given had to be cut to fit its input
+   * window — a source left out, or the current design summarised — and null otherwise. The design
+   * is still complete; this says what it was written without.
+   */
+  prompt_trim_note: z4.string().nullable(),
   /**
    * Present, and non-empty, only on `status: "clarification_required"`. A refusal is a
    * *result* here rather than an error: an error result may carry no `structuredContent` at
@@ -1325,7 +1391,7 @@ function registerGenerate(server, client, resolver) {
     "generate_architecture",
     {
       title: "Generate a SkeletIQ architecture",
-      description: "Design a system architecture from a prompt. This spends the account holder's credits and takes several minutes, so do not call it speculatively \u2014 if a design already exists, read it with get_design instead. Which model runs it is the account holder's stored setting; you do not choose it. Describe the system, what it must do, and the scale and constraints it runs under. A prompt that names no system to design comes back as clarification_required, and so does one that names a system but no scale to build it for \u2014 how many users or requests it has to serve. Answer with clarification_answers; there is no way to skip the questions, because a design built on an invented scale is sized, priced and judged against a number nobody chose.",
+      description: `Design a system architecture from a prompt. This spends the account holder's credits and takes several minutes, so do not call it speculatively \u2014 if a design already exists, read it with get_design instead. Which model runs it is the account holder's stored setting; you do not choose it. Describe the system, what it must do, the load it carries and the constraints it runs under. A prompt that names no system to design comes back as clarification_required, and so does one that states no load: a request rate ("about 300 requests a second"), a fleet (how many devices, and how often each one reports) or a volume ("2 million orders a day"). A headcount alone is not a load. Answer with clarification_answers, keyed by the question ids. Ask your human for the load first. If they do not know it, answer the load question "Not sure yet": the design is then sized on a typical load for its kind of system and marked assumed. Never guess a load or pick a band on their behalf \u2014 a design sized on an invented load is priced and judged against a number nobody chose.`,
       inputSchema: generateInput,
       outputSchema: generateOutput,
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
@@ -1369,7 +1435,7 @@ function registerGenerate(server, client, resolver) {
         error: job.error ?? null,
         queue_state: job.queue_state ?? null,
         refusal_code: refusal?.code ?? null,
-        clarifying_questions: questions
+        clarifying_questions: questions.map(structuredQuestion)
       };
       const lines = refusal ? refusalLines(job.job_id, refusal, questions) : [`Generation ${job.job_id} is ${job.status}.`];
       if (job.status === "completed" && job.project_id) {
@@ -1387,14 +1453,39 @@ function decisionRefusal(progress) {
   return refusal.success ? refusal.data : void 0;
 }
 function refusalQuestions(refusal) {
-  return (refusal?.clarifying_questions ?? []).map((question) => ({
+  return (refusal?.clarifying_questions ?? []).map(offeredQuestion);
+}
+function offeredQuestion(question) {
+  const options = answerOptions(question);
+  const details = new Map((question.option_details ?? []).map((detail) => [detail.value, detail]));
+  return {
     id: question.id,
     question: question.question,
     why: question.why ?? "",
-    options: (question.options ?? []).filter(
-      (option) => !(question.decline_options ?? []).includes(option)
-    )
-  }));
+    options,
+    explained: options.flatMap((option) => {
+      const detail = details.get(option);
+      if (!detail) return [];
+      const said = detail.label && detail.label !== option ? `${option} (${detail.label})` : option;
+      return [detail.detail ? `${said}: ${detail.detail}` : said];
+    }),
+    skipEffect: question.skip_effect ?? ""
+  };
+}
+function structuredQuestion(question) {
+  return { id: question.id, question: question.question, why: question.why, options: question.options };
+}
+function questionLines(questions) {
+  return questions.flatMap((question) => [
+    `${question.id}: ${question.question}`,
+    ...question.why ? [`  Why it matters: ${question.why}`] : [],
+    ...question.explained.length > 0 ? ["  Answers:", ...question.explained.map((line) => `  - ${line}`)] : question.options.length > 0 ? [`  For example: ${question.options.join(" \xB7 ")}`] : [],
+    ...question.skipEffect ? [`  If it is left unanswered: ${question.skipEffect}`] : []
+  ]);
+}
+function answerOptions(question) {
+  const excluded = /* @__PURE__ */ new Set([...question.decline_options ?? [], ...question.dismiss_options ?? []]);
+  return (question.options ?? []).filter((option) => !excluded.has(option));
 }
 function refusalLines(jobId, refusal, questions) {
   const preamble = `Generation ${jobId} was declined before it ran. Nothing was generated and nothing was charged.`;
@@ -1403,11 +1494,7 @@ function refusalLines(jobId, refusal, questions) {
       return [
         preamble,
         "",
-        ...questions.flatMap((question) => [
-          `${question.id}: ${question.question}`,
-          ...question.why ? [`  Why it matters: ${question.why}`] : [],
-          ...question.options.length > 0 ? [`  For example: ${question.options.join(" \xB7 ")}`] : []
-        ]),
+        ...questionLines(questions),
         "",
         "Call generate_architecture again with the same prompt and clarification_answers keyed by those ids. Take the answers from the user rather than inventing them."
       ];
@@ -1432,22 +1519,14 @@ function clarifyingQuestions(error) {
   return questions && questions.length > 0 ? questions : void 0;
 }
 function clarificationResult(questions) {
-  const structured = questions.map((question) => ({
-    id: question.id,
-    question: question.question,
-    why: question.why ?? "",
-    options: (question.options ?? []).filter((option) => !(question.decline_options ?? []).includes(option))
-  }));
+  const offered = questions.map(offeredQuestion);
+  const structured = offered.map(structuredQuestion);
   const lines = [
-    "SkeletIQ will not design from this prompt yet \u2014 it is missing something the design would otherwise have to invent, such as the system itself or the scale it runs at. Nothing was generated and nothing was charged.",
+    "SkeletIQ will not design from this prompt yet \u2014 it is missing something the design would otherwise have to invent, such as the system itself or the load it carries. Nothing was generated and nothing was charged.",
     "",
-    ...structured.flatMap((question) => [
-      `${question.id}: ${question.question}`,
-      ...question.why ? [`  Why it matters: ${question.why}`] : [],
-      ...question.options.length > 0 ? [`  For example: ${question.options.join(" \xB7 ")}`] : []
-    ]),
+    ...questionLines(offered),
     "",
-    "Call generate_architecture again with the same prompt and clarification_answers keyed by those ids. The answers are used as authoritative requirements, so take them from the user rather than inventing them \u2014 and put anything you already know into constraints instead, where it is used as a fact rather than as prose to interpret."
+    "Call generate_architecture again with the same prompt and clarification_answers keyed by those ids. The answers are used as authoritative requirements, so take them from the user rather than inventing them \u2014 and put anything you already know into constraints instead, where it is used as a fact rather than as prose to interpret." + (offered.some((question) => question.options.includes(LOAD_NOT_SURE)) ? ` If they do not know a figure asked for, answer "${LOAD_NOT_SURE}" rather than picking one.` : "")
   ];
   return ok(
     {
@@ -1460,6 +1539,7 @@ function clarificationResult(questions) {
       component_count: null,
       assistant_message: null,
       degradations: [],
+      prompt_trim_note: null,
       clarifying_questions: structured
     },
     lines.join("\n")
@@ -1480,6 +1560,7 @@ async function queueGeneration(client, body) {
       component_count: null,
       assistant_message: null,
       degradations: [],
+      prompt_trim_note: null,
       clarifying_questions: []
     },
     `Queued as job ${queued.job_id}. Poll it with get_generation_status.`
@@ -1528,6 +1609,7 @@ async function streamGeneration(client, body, ctx, resolver) {
   const architectureId = typeof finished.architecture_id === "string" ? finished.architecture_id : null;
   const version = typeof finished.architecture_version === "number" ? finished.architecture_version : null;
   const degradations = Array.isArray(finished.degradations) ? finished.degradations.filter((d) => typeof d === "string") : [];
+  const trimNote = asText(asRecord2(finished.run_summary)?.prompt_trim_note) ?? null;
   const created = architectureId ? await describeCreated(resolver, architectureId) : void 0;
   return ok(
     {
@@ -1540,6 +1622,7 @@ async function streamGeneration(client, body, ctx, resolver) {
       component_count: created?.componentCount ?? null,
       assistant_message: null,
       degradations,
+      prompt_trim_note: trimNote,
       clarifying_questions: []
     },
     [
@@ -1549,7 +1632,8 @@ async function streamGeneration(client, body, ctx, resolver) {
         'Check get_design(mode: "readiness") before building \u2014 a fresh design is a draft, and',
         "its open questions are the ones worth asking now."
       ] : ["SkeletIQ answered in prose rather than producing a design."],
-      ...degradations.map((d) => `Degraded: ${d}`)
+      ...degradations.map((d) => `Degraded: ${d}`),
+      ...trimNote ? [`Input trimmed: ${trimNote}`] : []
     ].join("\n")
   );
 }
@@ -1603,10 +1687,30 @@ function isCitedRequirement(row) {
   return (row.cited_by_components?.length ?? 0) > 0 || (row.cited_by_decisions?.length ?? 0) > 0;
 }
 var CITATION_ONLY_METHOD = "structure";
+var MEASURED_METHODS = ["simulation", "cost", "rules"];
+var UNCONFIRMED_WORDS = {
+  model_check: "unconfirmed (model check)",
+  unstated_input: "unconfirmed (unstated split)",
+  advisory_finding: "unconfirmed (review advice)"
+};
+var ASSUMED_LOAD_INPUT = "the load, which was assumed";
+var ASSUMED_LOAD_WORD = "unconfirmed (assumed load)";
+var UNCONFIRMED_ADVICE = "verify before building for it";
+function requirementBlocksHandoff(row) {
+  if (typeof row.blocks_handoff === "boolean") return row.blocks_handoff;
+  return (row.verdict ?? "").trim() === "fails" && MEASURED_METHODS.includes((row.check_method ?? "").trim());
+}
 function requirementVerdict(row) {
   const verdict = (row.verdict ?? row.status ?? "").trim();
-  if (verdict === "fails" && (row.check_method ?? "").trim() === CITATION_ONLY_METHOD) return "";
-  return verdict;
+  if (verdict !== "fails" || requirementBlocksHandoff(row)) return verdict;
+  const method = (row.check_method ?? "").trim();
+  if (method === CITATION_ONLY_METHOD) return "";
+  const reason = row.unconfirmed_reason ?? "model_check";
+  if (reason === "unstated_input" && row.unstated_input?.trim() === ASSUMED_LOAD_INPUT) return ASSUMED_LOAD_WORD;
+  return UNCONFIRMED_WORDS[reason] ?? "unconfirmed";
+}
+function isUnconfirmedRequirement(row) {
+  return requirementVerdict(row).startsWith("unconfirmed");
 }
 function orderRequirementRows(rows) {
   return [...rows].sort((a, b) => verdictRank(a) - verdictRank(b));
@@ -1614,9 +1718,10 @@ function orderRequirementRows(rows) {
 function verdictRank(row) {
   const verdict = requirementVerdict(row);
   if (verdict === "fails" || verdict === "unmet") return 0;
-  if (!isCitedRequirement(row)) return 1;
+  if (isUnconfirmedRequirement(row)) return 1;
+  if (!isCitedRequirement(row)) return 2;
   const index = VERDICT_ORDER.indexOf(verdict);
-  return index === -1 ? VERDICT_ORDER.length + 1 : index + 2;
+  return index === -1 ? VERDICT_ORDER.length + 2 : index + 3;
 }
 function decisionTexts(design) {
   return decisionEntries(design).map((entry) => entry.text);
@@ -1874,6 +1979,7 @@ function registerGetDesign(server, client, resolver) {
           const gates = readiness.rows.filter((row) => row.category === "gate");
           const open = gates.filter((row) => row.gating);
           const unanswered = gates.filter((row) => row.state === "unknown");
+          const unconfirmedGates = gates.filter((row) => row.state === "unconfirmed");
           const accepts = readiness.rows.filter((row) => row.category === "accept");
           const advisories = readiness.rows.filter(
             (row) => row.category !== "gate" && row.category !== "accept"
@@ -1885,6 +1991,11 @@ function registerGetDesign(server, client, resolver) {
           return ok({ ...base, ...facts, data: readiness }, [
             headline,
             ...listed.map((row) => `- ${row.label}: ${describeRow(row)}`),
+            ...unconfirmedGates.length ? [
+              "",
+              "Unconfirmed (the check ran, but its answer turns on an input nobody stated; never blocks):",
+              ...unconfirmedGates.map((row) => `- ${row.label}: ${describeRow(row)}`)
+            ] : [],
             ...accepts.length ? [
               "",
               "To accept (the person agrees to these rather than fixing them; accepting is free and never blocks):",
@@ -1945,11 +2056,11 @@ function registerGetDesign(server, client, resolver) {
           const orphaned = gaps.orphaned_answers ?? [];
           return ok({ ...base, ...facts, data: gaps }, [
             unresolved.length === 0 ? "Every open question and assumption in this design has been dealt with." : `${unresolved.length} unresolved:`,
-            ...unresolved.map((gap) => `- [${gap.kind}] ${gap.text}`),
+            ...unresolved.map((gap) => `- [${gap.kind}] ${gap.text}${sizingNote(gap)}`),
             ...settled.length > 0 ? [
               "",
               `${settled.length} settled during review \u2014 treat these as decided:`,
-              ...settled.map((gap) => `- [${gap.kind}] ${gap.text} \u2192 ${settledAnswer(gap)}`)
+              ...settled.map((gap) => `- [${gap.kind}] ${gap.text} \u2192 ${settledAnswer(gap)}${sizingNote(gap)}`)
             ] : [],
             // A gap is identified by a hash of its own text, so a regeneration that
             // re-words a question strands the answer that settled it. The server
@@ -1975,8 +2086,10 @@ function registerGetDesign(server, client, resolver) {
 function requirementBlock(ledger) {
   const rows = orderRequirementRows(ledger?.rows ?? []);
   if (!ledger || rows.length === 0) return [];
+  const unconfirmed = rows.filter(isUnconfirmedRequirement).length;
   const attention = [
     [rows.filter((row) => requirementVerdict(row) === "fails").length, "failing"],
+    [unconfirmed, "unconfirmed"],
     [rows.filter((row) => !isCitedRequirement(row)).length, "cited by nothing"],
     [rows.filter((row) => requirementVerdict(row) === "not_checked" || requirementVerdict(row) === "not_checkable").length, "unchecked"]
   ].filter(([count]) => count > 0).map(([count, word]) => `${count} ${word}`);
@@ -1989,6 +2102,7 @@ function requirementBlock(ledger) {
     "contradicted it, which is not the same as proven; `not_checked` / `not_checkable` \u2014 nobody",
     "established either way, and neither is fine. `cited by nothing` means no component and no",
     "decision in the design claims to address it.",
+    ...unconfirmedLegend(rows),
     // Two facts about how far the statuses can be trusted, said only when the server states
     // them. An absent `verification_state` is an older server, not a verifier that did not run,
     // and claiming the second would be this package inventing a fact about someone's design.
@@ -2006,6 +2120,34 @@ function requirementBlock(ledger) {
     ...ledger.analysis_degraded ? ["The requirements analysis for this version ran degraded. Treat the list as incomplete."] : []
   ];
 }
+function unconfirmedLegend(rows) {
+  const words = new Set(rows.filter(isUnconfirmedRequirement).map(requirementVerdict));
+  const reasons = new Set(
+    rows.filter((row) => isUnconfirmedRequirement(row) && requirementVerdict(row) !== "unconfirmed (assumed load)").map((row) => row.unconfirmed_reason ?? "model_check")
+  );
+  return [
+    ...reasons.has("model_check") ? [
+      "`unconfirmed (model check)` \u2014 only a model check says the design may not meet it. Nothing",
+      `measured it, so it does not block handoff: ${UNCONFIRMED_ADVICE} rather than adding a part.`
+    ] : [],
+    ...reasons.has("unstated_input") ? [
+      "`unconfirmed (unstated split)` \u2014 capacity falls short only under an assumption nobody stated",
+      "(the rate split evenly between entrances, or traffic weights that do not add up). Its reason",
+      "names the split the design would need \u2014 judge whether that is realistic. It does not block",
+      "handoff: ask how the traffic divides."
+    ] : [],
+    ...reasons.has("advisory_finding") ? [
+      "`unconfirmed (review advice)` \u2014 only advice from the design review fails it: the findings it",
+      "rests on are reported, not scored, so it does not block handoff. Read the advice and decide",
+      "whether the design should take it."
+    ] : [],
+    ...words.has("unconfirmed (assumed load)") ? [
+      "`unconfirmed (assumed load)` \u2014 the verdict rests on the load, which was assumed: nobody said how",
+      "much traffic to expect, so the design was sized and priced on the typical load for this kind of",
+      "system. It does not block handoff: ask your human for their load rather than guessing one."
+    ] : []
+  ];
+}
 function requirementsServed(rows) {
   if (!rows?.length) return [];
   return [
@@ -2013,7 +2155,8 @@ function requirementsServed(rows) {
     "Requirements the design cites this component for:",
     ...rows.map(requirementLine),
     "`fails` \u2014 a named check measured the design as not meeting it; `not_checked` \u2014 nobody",
-    "established either way; `no_gap_found` \u2014 nothing contradicted it, which is not the same as proven."
+    "established either way; `no_gap_found` \u2014 nothing contradicted it, which is not the same as proven.",
+    ...unconfirmedLegend(rows)
   ];
 }
 function requirementsWithdrawn(rows) {
@@ -2028,7 +2171,8 @@ function requirementsWithdrawn(rows) {
 }
 function requirementLine(row) {
   const verdict = requirementVerdict(row);
-  const marks = [verdict, ...isCitedRequirement(row) ? [] : ["cited by nothing"]].filter(Boolean);
+  const shown = isUnconfirmedRequirement(row) ? `${verdict} \u2014 ${UNCONFIRMED_ADVICE}` : verdict;
+  const marks = [shown, ...isCitedRequirement(row) ? [] : ["cited by nothing"]].filter(Boolean);
   const label = marks.length > 0 ? ` [${marks.join(" \xB7 ")}]` : "";
   const text = (row.text ?? "").replace(/\s+/g, " ").trim();
   const reason = (row.verdict_reason ?? "").replace(/\s+/g, " ").trim();
@@ -2046,6 +2190,10 @@ function settledAnswer(gap) {
   if (gap.action === "confirmed") return "confirmed as it stands";
   return "answered, but no wording was recorded \u2014 ask before relying on it";
 }
+function sizingNote(gap) {
+  const conflict = gap.sizing_conflict;
+  return conflict ? ` (this design is sized for ${conflict.sized}, not ${conflict.assumed})` : "";
+}
 function todoGroupBlock(group) {
   if (group.items.length === 0) return [];
   return ["", `${group.label} (${group.items.length}):`, ...group.items.map(todoLine)];
@@ -2059,7 +2207,12 @@ function todoLine(item) {
   return `- ${severity}${item.title.replace(/\s+/g, " ").trim()}${components}${raised}${carried}`;
 }
 function describeRow(row) {
-  if (row.state === "unknown") return `not checked${row.detail ? ` \u2014 ${row.detail}` : ""}`;
+  if (row.state === "unknown") {
+    const clears = row.clears ? ` ${row.clears}` : "";
+    const detail = row.detail ? ` \u2014 ${row.detail}${clears && !/[.!?]$/.test(row.detail) ? "." : ""}` : clears ? " \u2014" : "";
+    return `not checked${detail}${clears}`;
+  }
+  if (row.state === "unconfirmed") return `unconfirmed${row.detail ? ` \u2014 ${row.detail}` : ""}`;
   return `${row.count}${row.detail ? ` \u2014 ${row.detail}` : ""}`;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skeletiq/mcp",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Design in SkeletIQ, build with your coding agent. MCP server for the SkeletIQ architecture platform.",
   "license": "MIT",
   "author": "Sabhahith Works Private Limited",