@skeletiq/mcp 0.2.0 → 0.4.0

package/README.md

@@ -85,8 +85,8 @@ change your provider keys, see billing, or delete your account, whatever scopes
 | Tool | What it does |
 |---|---|
 | `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`. `overview` and `component` resolve the design's `R`-ids to the requirements they name, and what became of each. |
-| `generate_architecture` | Design a system from a prompt. Spends credits and takes minutes. |
+| `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. 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.2.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": {
@@ -331,10 +337,49 @@ var RequirementLedgerRowSchema = z.looseObject({
    * value added server-side must not stop an older connector parsing the row. */
   status: z.string().optional(),
   verifier_checked: z.boolean().optional(),
+  /** Which check answered this line: `simulation` | `cost` | `rules` | `structure` | `verifier`.
+   * Four are deterministic; `verifier` is the model check, and it only owns a row when it gave a
+   * reason. A string rather than a union, for the reason `status` is one. Absent from older APIs. */
+  check_method: z.string().nullable().optional(),
+  /** What that check said: `fails` | `passes` | `no_gap_found` | `not_checkable` | `not_checked`.
+   * `passes` is only ever a measurement; `no_gap_found` is the weaker "nothing contradicted it".
+   * Reported beside `status`, which stays populated. Absent from older APIs. */
+  verdict: z.string().nullable().optional(),
+  /** Why, in one sentence, with the figure or the finding behind it. */
+  verdict_reason: z.string().nullable().optional(),
+  /** 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(),
-  added_in_version: z.number().nullable().optional()
+  added_in_version: z.number().nullable().optional(),
+  /** Set only on a row under `RequirementLedger.superseded`: an instruction an earlier analysis
+   * recorded as a requirement, now the change request it names (`CR5`). Absent from older APIs. */
+  superseded_by_change_request: z.string().nullable().optional(),
+  superseded_in_version: z.number().nullable().optional(),
+  /** What a person said about this line: `confirmed` ("yes, that one is real") or `removed`
+   * ("that is not a requirement"). Null or absent means nobody has said, which is neither. A
+   * `removed` row is listed under `RequirementLedger.removed` and never in `rows`, so a design
+   * is not held to it; it keeps its id so a citation naming it still resolves. `confirmed`
+   * changes no count and no verdict. Absent from older APIs. */
+  decision: z.string().nullable().optional(),
+  /** The version that was on screen when that decision was recorded. */
+  decided_in_version: z.number().nullable().optional()
 });
 var RequirementLedgerCountsSchema = z.looseObject({
   total: z.number().optional(),
@@ -343,10 +388,33 @@ var RequirementLedgerCountsSchema = z.looseObject({
   unmet: z.number().optional(),
   uncited: z.number().optional(),
   unchecked: z.number().optional(),
-  cited: z.number().optional()
+  cited: z.number().optional(),
+  /** Rows citing no component and no decision (overlaps `unmet`). Absent from older APIs. */
+  untraced: z.number().optional(),
+  /** The verdict partition, which sums to `total` exactly as the status partition above does —
+   * two readings of one set of rows, not two sets. Absent from older APIs. */
+  fails: z.number().optional(),
+  passes: z.number().optional(),
+  no_gap_found: z.number().optional(),
+  not_checkable: z.number().optional(),
+  not_checked: z.number().optional(),
+  /** Rows a person has confirmed are real requirements. In no partition — it overlaps all of
+   * them, because confirming a line says nothing about whether the design meets it. */
+  confirmed: z.number().optional(),
+  /** Ids a person said are **not** requirements. Not part of `total`: those rows are not in
+   * `rows` at all. Absent from older APIs. */
+  removed: z.number().optional()
 });
 var RequirementLedgerSchema = z.looseObject({
   rows: z.array(RequirementLedgerRowSchema).nullable().optional(),
+  /** Ids that were instructions, not requirements. Counted nowhere; listed so an id a component
+   * or decision still cites resolves to what became of it. Absent from older APIs. */
+  superseded: z.array(RequirementLedgerRowSchema).nullable().optional(),
+  /** Ids a person said are not requirements, so the design is not held to them. Kept apart from
+   * `superseded` because it is a different statement by a different author. Counted nowhere;
+   * listed for the same reason, so a citation naming one still resolves. Absent from older
+   * APIs. */
+  removed: z.array(RequirementLedgerRowSchema).nullable().optional(),
   analysis_version: z.number().nullable().optional(),
   analysis_degraded: z.boolean().optional(),
   /** `grounded` | `not_grounded` | `diverged`. */
@@ -400,6 +468,12 @@ var BuildOrderSchema = z.looseObject({
   steps: z.array(BuildStepSchema),
   release: ReleaseFactsSchema
 });
+var UnavailableSourceSchema = z.looseObject({
+  source: z.string(),
+  reason: z.string(),
+  /** `failed` | `missing`. A string, not a union: a value added server-side must still parse. */
+  kind: z.string().optional()
+});
 var ReadinessRowSchema = z.looseObject({
   key: z.string(),
   label: z.string(),
@@ -409,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(),
@@ -438,7 +518,16 @@ var ReadinessSchema = z.looseObject({
    * Optional here only so a server that predates the field still parses — it is required on the
    * wire, and an empty array is the server saying it looked and found nothing.
    */
-  release_warnings: z.array(z.string()).optional()
+  release_warnings: z.array(z.string()).optional(),
+  /**
+   * Sources this checklist could not speak for, exactly as `/todo` reports them.
+   *
+   * A failed read reaches each row builder as that source's own empty value — no questions, no
+   * decisions, no ledger — and every one of those empties reads as *clear*, so an outage could
+   * answer `ready: true` with `release_warnings: []`. Each one also has a row of its own now;
+   * this is the same fact in the shape a caller showing both lists can join on.
+   */
+  unavailable_sources: z.array(UnavailableSourceSchema).optional()
 });
 var DesignGapSchema = z.looseObject({
   gap_id: z.string(),
@@ -447,7 +536,21 @@ var DesignGapSchema = z.looseObject({
   resolved: z.boolean(),
   action: z.string().nullable().optional(),
   note: z.string().nullable().optional(),
-  adr_id: z.string().nullable().optional()
+  adr_id: z.string().nullable().optional(),
+  /** `gap:{gap_id}` — the identity the review, the advisor and the decision suggestions share,
+   * and the key a dismissal is recorded against. Absent from servers before 0.3.0. */
+  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(),
+  /** 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(),
@@ -465,29 +568,6 @@ var DesignGapListSchema = z.looseObject({
   /** Answers whose question is not in this version — recorded, not silently dropped. */
   orphaned_answers: z.array(OrphanedAnswerSchema).optional()
 });
-var ComponentRefSchema = z.looseObject({
-  id: z.string(),
-  name: z.string(),
-  type: z.string()
-});
-var UnknownIdSchema = z.looseObject({
-  id: z.string(),
-  suggestions: z.array(ComponentRefSchema).optional()
-});
-var DriftSchema = z.looseObject({
-  architecture_id: z.string(),
-  version: z.number(),
-  in_sync: z.boolean(),
-  missing: z.array(ComponentRefSchema),
-  unreported: z.array(ComponentRefSchema),
-  partial: z.array(ComponentRefSchema),
-  elsewhere: z.array(ComponentRefSchema),
-  unknown_ids: z.array(UnknownIdSchema),
-  extra_components: z.array(z.looseObject({ name: z.string() })),
-  extra_connections: z.array(z.looseObject({ source: z.string(), target: z.string() })),
-  counts: z.record(z.string(), z.number()),
-  release: ReleaseFactsSchema
-});
 var CritiqueFindingSchema = z.looseObject({
   message: z.string(),
   pattern_id: z.string(),
@@ -495,7 +575,17 @@ var CritiqueFindingSchema = z.looseObject({
   severity: z.string().optional(),
   affected_components: z.array(z.string()).optional(),
   evidence: z.string().optional(),
-  remediation: z.string().optional()
+  remediation: z.string().optional(),
+  /** Reported in full and never charged against the score — advice, not a problem to fix. */
+  advisory_only: z.boolean().optional(),
+  /**
+   * The problem this finding is about. Stable across rewording, and shared with the advisor
+   * suggestion and decision record raised by the same problem — the key a dismissal is recorded
+   * against.
+   */
+  problem_key: z.string().optional(),
+  /** The project set this problem aside, with a reason. Still reported; never set on an unsaved payload. */
+  dismissed: z.boolean().optional()
 });
 var PayloadCritiqueSchema = z.looseObject({
   architecture_score: z.number(),
@@ -513,13 +603,119 @@ var PayloadCritiqueSchema = z.looseObject({
   compliance_note: z.string().nullable().optional(),
   exposure_assessed: z.string().optional()
 });
+var TodoDecisionContextSchema = z.looseObject({
+  context: z.string().nullable().optional(),
+  consequences: z.string().nullable().optional(),
+  alternatives: z.string().nullable().optional(),
+  /** `records` | `open` | `tradeoff`. A string, not a union: a value added server-side must still parse. */
+  disposition: z.string(),
+  supersedes_adr_id: z.string().nullable().optional(),
+  source_version: z.number()
+});
+var TodoSourceSchema = z.looseObject({
+  source: z.string(),
+  message: z.string(),
+  detail: z.string().nullable().optional(),
+  /** A handle to act on through that source: a suggestion id, a gap id, an R-id. */
+  reference_id: z.string().nullable().optional(),
+  /** Present on a `critique` or `compliance` source; null on every other kind. */
+  finding: CritiqueFindingSchema.nullable().optional(),
+  /** Present on a `decisions` source; null on every other kind. */
+  decision: TodoDecisionContextSchema.nullable().optional()
+});
+var TodoActionSchema = z.looseObject({
+  action: z.string(),
+  available: z.boolean(),
+  reason: z.string().nullable().optional(),
+  reference_id: z.string().nullable().optional()
+});
+var TodoItemSchema = z.looseObject({
+  problem_key: z.string(),
+  group: z.string(),
+  /** `problem` | `question` | `assumption` | `decision` | `verdict`. A string, not a union: a
+   * value added server-side must not stop an older connector parsing the card. */
+  kind: z.string(),
+  title: z.string(),
+  severity: z.string(),
+  detail: z.string().nullable().optional(),
+  components: z.array(z.string()).optional(),
+  sources: z.array(TodoSourceSchema).optional(),
+  actions: z.array(TodoActionSchema).optional(),
+  carried: z.boolean().optional(),
+  /** The oldest earlier version known to have had this problem. Null with `carried: true` means
+   * 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(),
+  /** 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(),
+  label: z.string(),
+  items: z.array(TodoItemSchema),
+  bulk_action: TodoActionSchema.nullable().optional()
+});
+var TodoSchema = z.looseObject({
+  architecture_id: z.string(),
+  version: z.number(),
+  groups: z.array(TodoGroupSchema),
+  dismissed: z.array(TodoItemSchema).optional(),
+  counts: z.record(z.string(), z.number()).optional(),
+  /** Rows the sources raised before grouping. The gap between this and `counts.total` is the
+   * duplication the endpoint removes, reported so the claim stays checkable. */
+  raw_row_count: z.number().optional(),
+  unavailable_sources: z.array(UnavailableSourceSchema).optional(),
+  generation_running: z.boolean().optional(),
+  can_edit: z.boolean().optional(),
+  /** The project's newest version. Above `version` when this list is for an older one — a
+   * release resolved behind newer drafts, or a version asked for by number. Null when unread. */
+  latest_version: z.number().nullable().optional()
+});
+var ComponentRefSchema = z.looseObject({
+  id: z.string(),
+  name: z.string(),
+  type: z.string()
+});
+var UnknownIdSchema = z.looseObject({
+  id: z.string(),
+  suggestions: z.array(ComponentRefSchema).optional()
+});
+var DriftSchema = z.looseObject({
+  architecture_id: z.string(),
+  version: z.number(),
+  in_sync: z.boolean(),
+  missing: z.array(ComponentRefSchema),
+  unreported: z.array(ComponentRefSchema),
+  partial: z.array(ComponentRefSchema),
+  elsewhere: z.array(ComponentRefSchema),
+  unknown_ids: z.array(UnknownIdSchema),
+  extra_components: z.array(z.looseObject({ name: z.string() })),
+  extra_connections: z.array(z.looseObject({ source: z.string(), target: z.string() })),
+  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(),
@@ -581,7 +777,9 @@ var PROJECT_PAGE_SIZE = 50;
 var ARCHITECTURE_PAGE_SIZE = 100;
 var DesignResolver = class {
   client;
+  /** Version summaries per project — enough to choose a version, never to describe one. */
   versions = /* @__PURE__ */ new Map();
+  /** Full records from the single-version read, the requirements ledger included. */
   designs = /* @__PURE__ */ new Map();
   constructor(client) {
     this.client = client;
@@ -610,7 +808,11 @@ var DesignResolver = class {
     if (exact.length === 1) return exact[0];
     throw new AmbiguousProjectError(idOrQuery, candidates);
   }
-  /** Every version of a project, newest first. Cached: one call serves a whole session. */
+  /**
+   * Every version of a project, newest first. Cached: one call serves a whole session.
+   *
+   * These are summaries. They seed nothing in `designs` — see the file header for why.
+   */
   async versionsFor(projectId) {
     const cached = this.versions.get(projectId);
     if (cached) return cached;
@@ -619,7 +821,6 @@ var DesignResolver = class {
     });
     const items = [...ArchitecturePageSchema.parse(body).items].sort((a, b) => b.version - a.version);
     this.versions.set(projectId, items);
-    for (const item of items) this.designs.set(item.id, item);
     return items;
   }
   /** The version rule. */
@@ -659,10 +860,10 @@ var DesignResolver = class {
     };
   }
   /**
-   * The full design for one version.
+   * The full design for one version, from the single-version read.
    *
-   * The list response already carries `architecture_json`, so the cache seeded by
-   * `versionsFor` usually answers this without a second request.
+   * One request per version a session actually describes, not one per version in the list:
+   * an overview and any number of component slices of the same version share it.
    */
   async design(architectureId) {
     const cached = this.designs.get(architectureId);
@@ -757,7 +958,9 @@ var input = z2.object({
       target: z2.string().max(255),
       protocol: z2.string().max(64).optional()
     })
-  ).max(500).optional().describe("Edges in the code the design does not have. Endpoints may be component ids or names.")
+  ).max(500).optional().describe(
+    "Edges in the code the design does not have, each from the caller to the callee: the component that holds the client is the source, including a consumer reading a queue. Endpoints may be component ids or names."
+  )
 });
 var refs = z2.array(z2.object({ id: z2.string(), name: z2.string(), type: z2.string() }));
 var output = z2.object({
@@ -872,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."
@@ -893,7 +1096,10 @@ var output2 = z3.object({
       category: z3.string(),
       message: z3.string(),
       affected_components: z3.array(z3.string()),
-      remediation: z3.string()
+      remediation: z3.string(),
+      advisory_only: z3.boolean().describe(
+        "True for advice: reported and never charged against the score \u2014 a framework nobody named, or a check too uncertain to count. Not a problem to fix."
+      )
     })
   ),
   finding_count: z3.number(),
@@ -932,7 +1138,9 @@ function registerCritique(server, client) {
         category: finding.category,
         message: finding.message,
         affected_components: finding.affected_components ?? [],
-        remediation: finding.remediation ?? ""
+        remediation: finding.remediation ?? "",
+        // A server too old to send the flag predates it, and counted every finding.
+        advisory_only: finding.advisory_only ?? false
       }));
       const complianceAssessed = critique.compliance_assessed ?? false;
       const exposureAssessed = critique.exposure_assessed ?? "public_internet";
@@ -966,8 +1174,12 @@ function registerCritique(server, client) {
         "",
         findings.length === 0 ? "No findings." : `${findings.length} finding(s):`,
         ...findings.map(
-          (finding) => `- [${finding.severity}] ${finding.message}` + (finding.affected_components.length ? ` (${finding.affected_components.join(", ")})` : "") + (finding.remediation ? `
+          (finding) => (
+            // Said on the line, because a severity alone reads as a blocker: an
+            // advisory critical is one the score and the app's verdict both ignore.
+            `- [${finding.severity}${finding.advisory_only ? " \xB7 advisory, not scored" : ""}] ${finding.message}` + (finding.affected_components.length ? ` (${finding.affected_components.join(", ")})` : "") + (finding.remediation ? `
   Fix: ${finding.remediation}` : "")
+          )
         )
       ];
       return ok(structured, lines.join("\n"));
@@ -1041,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"
 };
@@ -1054,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);
   }
@@ -1083,11 +1299,21 @@ var constraintsInput = z4.strictObject({
   preferred_cloud: z4.enum(["aws", "gcp", "azure", "any"]).optional(),
   preferred_technologies: z4.array(z4.string()).optional(),
   max_components: z4.number().int().positive().optional(),
-  read_write_mix: z4.enum(["read_heavy", "balanced", "write_heavy"]).optional().describe("Nothing reads this from the prompt. Unset, the design assumes 80% reads."),
-  burstiness: z4.enum(["steady", "daily_peaks", "spiky"]).optional().describe("Nothing reads this from the prompt. Unset, the design assumes the tier default peak."),
+  read_write_mix: z4.enum(["read_heavy", "balanced", "write_heavy"]).optional().describe(
+    "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 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."),
@@ -1096,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."
@@ -1112,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
@@ -1159,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: whatever the prompt leaves out is assumed, and a prompt that names no system at all comes back as clarification_required with the questions to answer.",
+      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 }
@@ -1203,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) {
@@ -1221,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.`;
@@ -1237,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."
       ];
@@ -1266,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 names no system to design. 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(
     {
@@ -1294,6 +1539,7 @@ function clarificationResult(questions) {
       component_count: null,
       assistant_message: null,
       degradations: [],
+      prompt_trim_note: null,
       clarifying_questions: structured
     },
     lines.join("\n")
@@ -1314,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.`
@@ -1362,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(
     {
@@ -1374,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: []
     },
     [
@@ -1383,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")
   );
 }
@@ -1416,7 +1666,10 @@ function sliceComponent(design, componentId, ledger) {
     incoming: connections.filter((c) => c.target === component.id),
     related_decisions: related,
     assumed_decisions: assumedAmong(design, related),
-    ...ledger ? { cited_requirements: citedRequirements(ledger, component.id) } : {}
+    ...ledger ? {
+      cited_requirements: citedRequirements(ledger, component.id),
+      withdrawn_requirements: withdrawnRequirements(ledger, component.id)
+    } : {}
   };
 }
 function citedRequirements(ledger, componentId) {
@@ -1424,13 +1677,51 @@ function citedRequirements(ledger, componentId) {
     (ledger.rows ?? []).filter((row) => (row.cited_by_components ?? []).includes(componentId))
   );
 }
-var STATUS_ORDER = ["unmet", "uncited", "unchecked", "cited"];
+function withdrawnRequirements(ledger, componentId) {
+  return [...ledger.removed ?? [], ...ledger.superseded ?? []].filter(
+    (row) => (row.cited_by_components ?? []).includes(componentId)
+  );
+}
+var VERDICT_ORDER = ["fails", "unmet", "not_checked", "not_checkable", "unchecked", "no_gap_found", "passes", "cited"];
+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" || 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) => statusRank(a) - statusRank(b));
+  return [...rows].sort((a, b) => verdictRank(a) - verdictRank(b));
 }
-function statusRank(row) {
-  const index = STATUS_ORDER.indexOf(row.status ?? "");
-  return index === -1 ? STATUS_ORDER.length : index;
+function verdictRank(row) {
+  const verdict = requirementVerdict(row);
+  if (verdict === "fails" || verdict === "unmet") return 0;
+  if (isUnconfirmedRequirement(row)) return 1;
+  if (!isCitedRequirement(row)) return 2;
+  const index = VERDICT_ORDER.indexOf(verdict);
+  return index === -1 ? VERDICT_ORDER.length + 2 : index + 3;
 }
 function decisionTexts(design) {
   return decisionEntries(design).map((entry) => entry.text);
@@ -1494,11 +1785,11 @@ function normalize(value) {
 }
 
 // src/tools/get-design.ts
-var MODES = ["overview", "component", "brief", "readiness", "build_order", "gaps"];
+var MODES = ["overview", "component", "brief", "todo", "readiness", "build_order", "gaps"];
 var input3 = z5.object({
   project_id: z5.string().describe("A SkeletIQ project id, or its exact name."),
   mode: z5.enum(MODES).describe(
-    "overview: the whole design, and the requirements it was built from with what became of each. component: one component, its connections in both directions, the decisions that mention it, and the requirements the design cites it for. brief: the fenced markdown block to write into AGENTS.md. readiness: what still has to be decided before this design is worth building. build_order: the order to build components in, and why. gaps: the open questions and unconfirmed assumptions in the design."
+    "overview: the whole design and, where the version records them, the requirements it was built from with what became of each. component: one component, its connections in both directions (the source calls the target), the decisions that mention it, and the requirements the design cites it for. brief: the fenced markdown block to write into AGENTS.md. todo: everything still to do on this version, one card per problem \u2014 what blocks a handoff, what is recommended, and what is waiting to be accepted. readiness: the verdict, gate by gate, on whether this design is worth building yet. build_order: the order to build components in, and why. gaps: the open questions and unconfirmed assumptions in the design."
   ),
   component_id: z5.string().optional().describe('Required for mode "component". The component id, or its name.'),
   version: z5.number().int().positive().optional().describe("A specific version. Defaults to the latest released version, or the latest version if none is released.")
@@ -1526,7 +1817,7 @@ function registerGetDesign(server, client, resolver) {
     "get_design",
     {
       title: "Read a SkeletIQ design",
-      description: 'Read a SkeletIQ architecture. Start with mode "brief" to orient \u2014 it returns a fenced block to write into AGENTS.md \u2014 then "build_order" for the sequence and "component" for each piece as you build it. "overview" and "component" also resolve the R-ids the design carries to the requirements they name, and say what became of each. Every answer states which version it came from and whether that version is a release.',
+      description: 'Read a SkeletIQ architecture. Start with mode "brief" to orient \u2014 it returns a fenced block to write into AGENTS.md \u2014 then "todo" for what the design still needs, "build_order" for the sequence and "component" for each piece as you build it. Where a version records its requirements, "overview" and "component" also resolve the R-ids the design carries to the requirements they name, and say what became of each. Every answer states which version it came from and whether that version is a release.',
       inputSchema: input3,
       outputSchema: output3,
       annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true }
@@ -1603,6 +1894,11 @@ function registerGetDesign(server, client, resolver) {
             // Same order as the overview: what was asked for, then how the design
             // answered.
             ...requirementsServed(slice.cited_requirements),
+            // Said only when the design still carries the id. A component's
+            // `requirement_ids` are never rewritten when a requirement is
+            // withdrawn, so without this the row would leave the answer in
+            // silence and the id on the box would resolve to nothing again.
+            ...requirementsWithdrawn(slice.withdrawn_requirements),
             // Labelled, and only when there are any. These bullets used to be
             // printed bare under "Called by:", so a decision about the component
             // read as a continuation of its edge list — and a design with no
@@ -1649,6 +1945,33 @@ function registerGetDesign(server, client, resolver) {
             versionLine(facts)
           ].filter(Boolean).join("\n"));
         }
+        case "todo": {
+          const body = await client.request(`/architectures/${resolved.architectureId}/todo`);
+          const todo = TodoSchema.parse(body);
+          const facts = factsFrom(resolved);
+          const groups = todo.groups ?? [];
+          const blocking = groups.find((group) => group.key === "blocks_handoff");
+          const total = groups.reduce((count, group) => count + group.items.length, 0);
+          return ok({ ...base, ...facts, data: todo }, [
+            total === 0 ? "Nothing is outstanding on this version." : `${total} thing(s) still to do on this version` + (blocking?.items.length ? `, ${blocking.items.length} of which block a handoff:` : ", none of which block a handoff:"),
+            ...groups.flatMap(todoGroupBlock),
+            // A source that could not be read is stated, never left to look like a
+            // shorter list. An agent acting on "nothing is outstanding" when the
+            // simulation results failed to load is the exact harm this prevents.
+            ...todo.unavailable_sources?.length ? [
+              "",
+              "Some of this version could not be read, so the list above is incomplete:",
+              ...todo.unavailable_sources.map((entry) => `- ${entry.source}: ${entry.reason}`)
+            ] : [],
+            "",
+            // The actions are the person's. An agent that "accepts" an assumption
+            // has decided something on their behalf, which is the one thing this
+            // surface must never do — and the server refuses it anyway, because an
+            // agent token reaches no write route.
+            "Fix what you can in the design. Answering, accepting and dismissing are the person's to do \u2014 ask, do not decide for them.",
+            versionLine(facts)
+          ].join("\n"));
+        }
         case "readiness": {
           const body = await client.request(`/architectures/${resolved.architectureId}/readiness`);
           const readiness = ReadinessSchema.parse(body);
@@ -1656,7 +1979,11 @@ 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 advisories = readiness.rows.filter((row) => row.category !== "gate");
+          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"
+          );
           const unrun = new Set(readiness.unrun_checks ?? []);
           const verdict = readiness.verdict ?? (readiness.ready ? "ready" : "outstanding");
           const headline = verdict === "ready" ? "Every gate is clear \u2014 this design is ready to build." : verdict === "unanswered" ? `Nothing is undecided, but ${unanswered.length} check(s) could not be answered for this version:` : `${open.length} of ${gates.length} gate(s) still open:`;
@@ -1664,13 +1991,27 @@ 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):",
+              ...accepts.map((row) => `- ${row.label}: ${describeRow(row)}`)
+            ] : [],
             "",
             "Advisory checks (they never block, and some need a paid plan to clear):",
-            // An advisory that never ran is marked, not counted. "The advisor has
-            // not looked at this design" is a fact an agent being handed work is
-            // entitled to, and it is invisible in a bare count of open items.
+            // An advisory with no result is marked, not counted — "nothing to count
+            // here" is a fact an agent being handed work is entitled to, and it is
+            // invisible in a bare count of open items. The mark claims no more than
+            // that: an advisory can be unanswered because no result is *stored* for
+            // this version (the advisor row since the server stopped writing on
+            // read), not only because nothing ever ran, and the server's own
+            // sentence, when it sends one, says which.
             ...advisories.map(
-              (row) => `- ${row.label}: ${describeRow(row)}${unrun.has(row.key) ? " (never run on this version)" : ""}`
+              (row) => `- ${row.label}: ${describeRow(row)}${unrun.has(row.key) && !row.detail ? " (no result for this version)" : ""}`
             ),
             // The same list, under the same heading, as the app shows beside its
             // Release button. A person clicking Release is told what the release
@@ -1683,7 +2024,7 @@ function registerGetDesign(server, client, resolver) {
               ...readiness.release_warnings.map((warning) => `- ${warning}`)
             ] : [],
             "",
-            "Only a person can clear a gate. Ask; do not decide on their behalf.",
+            'Only a person can clear a gate. Ask; do not decide on their behalf. Use mode "todo" for the same work item by item.',
             versionLine(facts)
           ].join("\n"));
         }
@@ -1715,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
@@ -1745,14 +2086,23 @@ function registerGetDesign(server, client, resolver) {
 function requirementBlock(ledger) {
   const rows = orderRequirementRows(ledger?.rows ?? []);
   if (!ledger || rows.length === 0) return [];
-  const attention = ["unmet", "uncited", "unchecked"].map((status) => [rows.filter((row) => row.status === status).length, status]).filter(([count]) => count > 0).map(([count, status]) => `${count} ${status}`);
+  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}`);
   return [
     "",
     `Requirements \u2014 ${rows.length} total${attention.length ? `; ${attention.join(", ")}` : ""}:`,
     ...rows.map(requirementLine),
-    "Statuses: `unmet` \u2014 the verifier judged the design does not satisfy it; `uncited` \u2014 nothing",
-    "in the design claims to address it; `unchecked` \u2014 something cites it and the verifier did not",
-    "check it; `cited` \u2014 cited with no gap found, which is not the same as proven.",
+    "Verdicts: `fails` \u2014 a named check measured the design as not meeting it, and says which and why;",
+    "`passes` \u2014 a check measured it against a figure the person stated; `no_gap_found` \u2014 nothing",
+    "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.
@@ -1770,20 +2120,65 @@ 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 [
     "",
     "Requirements the design cites this component for:",
     ...rows.map(requirementLine),
-    "`unmet` \u2014 the verifier judged the design does not satisfy it; `unchecked` \u2014 the verifier did",
-    "not check it; `cited` \u2014 no gap found, which is not the same as proven."
+    "`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.",
+    ...unconfirmedLegend(rows)
+  ];
+}
+function requirementsWithdrawn(rows) {
+  if (!rows?.length) return [];
+  return [
+    "",
+    "This component still cites these ids, and they are no longer requirements \u2014 do not build to them:",
+    ...rows.map(
+      (row) => `- ${row.id} ${(row.text ?? "").replace(/\s+/g, " ").trim() || "(no text recorded)"} [${row.decision === "removed" ? "removed by a person" : `was an instruction, now ${row.superseded_by_change_request ?? "a change request"}`}]`
+    )
   ];
 }
 function requirementLine(row) {
-  const status = row.status ? ` [${row.status}]` : "";
+  const verdict = requirementVerdict(row);
+  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();
-  return `- ${row.id}${status} ${text || "(no text recorded for this requirement)"}`;
+  const reason = (row.verdict_reason ?? "").replace(/\s+/g, " ").trim();
+  const by = (row.checked_by ?? "").trim();
+  const because = reason ? ` \u2014 ${reason}${by ? ` (checked by ${by})` : ""}` : by ? ` \u2014 checked by ${by}` : "";
+  return `- ${row.id}${label} ${text || "(no text recorded for this requirement)"}${because}`;
 }
 function settledAnswer(gap) {
   const note = (gap.note ?? "").trim();
@@ -1795,8 +2190,29 @@ 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)];
+}
+function todoLine(item) {
+  const severity = item.severity && item.severity !== "none" ? `[${item.severity}] ` : "";
+  const raisedBy = [...new Set((item.sources ?? []).map((source) => source.source))];
+  const raised = raisedBy.length > 0 ? ` \u2014 raised by ${raisedBy.join(", ")}` : "";
+  const carried = item.carried ? item.carried_from_version ? ` \u2014 carried from v${item.carried_from_version}` : " \u2014 carried from an earlier version" : "";
+  const components = item.components?.length ? ` \u2014 affects ${item.components.join(", ")}` : "";
+  return `- ${severity}${item.title.replace(/\s+/g, " ").trim()}${components}${raised}${carried}`;
+}
 function describeRow(row) {
-  if (row.state === "unknown") return "not checked";
+  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.2.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",