@skeletiq/mcp 0.2.0 → 0.3.0

package/README.md

@@ -85,7 +85,7 @@ 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. |
+| `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. |
 | `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`. |

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.3.0";
 var DEFAULT_API_URL = "https://api.skeletiq.com";
 var TOKEN_PREFIX = "skq_";
 var ConfigError = class extends Error {
@@ -331,10 +331,35 @@ 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(),
   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 +368,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 +448,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(),
@@ -438,7 +492,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 +510,13 @@ 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()
 });
 var OrphanedAnswerSchema = z.looseObject({
   gap_id: z.string(),
@@ -465,29 +534,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 +541,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,6 +569,96 @@ 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()
+});
+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 ClarifyingQuestionSchema = z.looseObject({
   id: z.string(),
   question: z.string(),
@@ -581,7 +727,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 +758,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 +771,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 +810,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 +908,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({
@@ -893,7 +1046,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 +1088,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 +1124,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"));
@@ -1083,8 +1245,12 @@ 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 the tier default peak.'
+  ),
   data_retention: z4.enum(["days", "months", "years", "indefinite"]).optional(),
   consistency: z4.enum(["strict", "eventual", "mixed"]).optional(),
   data_residency: z4.enum(["any", "us", "eu"]).optional()
@@ -1159,7 +1325,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, 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.",
       inputSchema: generateInput,
       outputSchema: generateOutput,
       annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true }
@@ -1273,7 +1439,7 @@ function clarificationResult(questions) {
     options: (question.options ?? []).filter((option) => !(question.decline_options ?? []).includes(option))
   }));
   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 scale it runs at. Nothing was generated and nothing was charged.",
     "",
     ...structured.flatMap((question) => [
       `${question.id}: ${question.question}`,
@@ -1416,7 +1582,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 +1593,30 @@ 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";
+function requirementVerdict(row) {
+  const verdict = (row.verdict ?? row.status ?? "").trim();
+  if (verdict === "fails" && (row.check_method ?? "").trim() === CITATION_ONLY_METHOD) return "";
+  return verdict;
+}
 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 (!isCitedRequirement(row)) return 1;
+  const index = VERDICT_ORDER.indexOf(verdict);
+  return index === -1 ? VERDICT_ORDER.length + 1 : index + 2;
 }
 function decisionTexts(design) {
   return decisionEntries(design).map((entry) => entry.text);
@@ -1494,11 +1680,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 +1712,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 +1789,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 +1840,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 +1874,10 @@ 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 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 +1885,22 @@ function registerGetDesign(server, client, resolver) {
           return ok({ ...base, ...facts, data: readiness }, [
             headline,
             ...listed.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 +1913,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"));
         }
@@ -1745,14 +1975,20 @@ 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 attention = [
+    [rows.filter((row) => requirementVerdict(row) === "fails").length, "failing"],
+    [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.",
     // 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.
@@ -1776,14 +2012,29 @@ function requirementsServed(rows) {
     "",
     "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."
+  ];
+}
+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 marks = [verdict, ...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 +2046,20 @@ 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 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") return `not checked${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.3.0",
   "description": "Design in SkeletIQ, build with your coding agent. MCP server for the SkeletIQ architecture platform.",
   "license": "MIT",
   "author": "Sabhahith Works Private Limited",