@skeletiq/mcp 0.1.2 → 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`. |
+| `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.1.2";
+var SERVER_VERSION = "0.3.0";
 var DEFAULT_API_URL = "https://api.skeletiq.com";
 var TOKEN_PREFIX = "skq_";
 var ConfigError = class extends Error {
@@ -322,6 +322,88 @@ var ArchitectureJsonSchema = z.looseObject({
   assumptions: z.array(GapEntrySchema).nullable().optional(),
   open_questions: z.array(GapEntrySchema).nullable().optional()
 });
+var RequirementLedgerRowSchema = z.looseObject({
+  id: z.string(),
+  text: z.string().optional(),
+  kind: z.string().optional(),
+  source: z.string().optional(),
+  /** `unmet` | `uncited` | `unchecked` | `cited` — deliberately never `met`. Left as a string: a
+   * 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(),
+  /** 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(),
+  user_supplied: z.number().optional(),
+  llm_inferred: z.number().optional(),
+  unmet: z.number().optional(),
+  uncited: z.number().optional(),
+  unchecked: 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`. */
+  grounding_state: z.string().optional(),
+  /** `ran` | `partial` | `not_run`. */
+  verification_state: z.string().optional(),
+  verified_version: z.number().nullable().optional(),
+  counts: RequirementLedgerCountsSchema.nullable().optional()
+});
 var ArchitectureSchema = z.looseObject({
   id: z.string(),
   project_id: z.string(),
@@ -332,7 +414,8 @@ var ArchitectureSchema = z.looseObject({
   created_at: z.string().optional(),
   updated_at: z.string().optional(),
   is_released: z.boolean().optional(),
-  released_at: z.string().nullable().optional()
+  released_at: z.string().nullable().optional(),
+  requirement_ledger: RequirementLedgerSchema.nullable().optional()
 });
 var ArchitecturePageSchema = z.looseObject({
   items: z.array(ArchitectureSchema),
@@ -365,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(),
@@ -403,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(),
@@ -412,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(),
@@ -430,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(),
@@ -460,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(),
@@ -478,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(),
@@ -546,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;
@@ -575,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;
@@ -584,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. */
@@ -624,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);
@@ -722,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({
@@ -858,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(),
@@ -897,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";
@@ -931,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"));
@@ -1048,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()
@@ -1124,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 }
@@ -1238,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}`,
@@ -1369,32 +1570,83 @@ async function describeCreated(resolver, architectureId) {
 import * as z5 from "zod/v4";
 
 // src/lib/slice.ts
-function sliceComponent(design, componentId) {
+function sliceComponent(design, componentId, ledger) {
   const components = design.components ?? [];
   const component = components.find((c) => c.id === componentId) ?? components.find((c) => normalize(c.name) === normalize(componentId));
   if (!component) return null;
   const connections = design.connections ?? [];
+  const related = relatedDecisions(design, component);
   return {
     component,
     outgoing: connections.filter((c) => c.source === component.id),
     incoming: connections.filter((c) => c.target === component.id),
-    related_decisions: relatedDecisions(design, component)
+    related_decisions: related,
+    assumed_decisions: assumedAmong(design, related),
+    ...ledger ? {
+      cited_requirements: citedRequirements(ledger, component.id),
+      withdrawn_requirements: withdrawnRequirements(ledger, component.id)
+    } : {}
   };
 }
+function citedRequirements(ledger, componentId) {
+  return orderRequirementRows(
+    (ledger.rows ?? []).filter((row) => (row.cited_by_components ?? []).includes(componentId))
+  );
+}
+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) => verdictRank(a) - verdictRank(b));
+}
+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) {
-  const seen = /* @__PURE__ */ new Set();
+  return decisionEntries(design).map((entry) => entry.text);
+}
+function decisionEntries(design) {
+  const byText = /* @__PURE__ */ new Map();
   const out = [];
-  const push2 = (text) => {
+  const push2 = (text, assumption) => {
     if (typeof text !== "string") return;
     const trimmed = text.trim();
-    if (trimmed.length === 0 || seen.has(trimmed)) return;
-    seen.add(trimmed);
-    out.push(trimmed);
+    if (trimmed.length === 0) return;
+    const existing = byText.get(trimmed);
+    if (existing) {
+      existing.assumption = existing.assumption || assumption;
+      return;
+    }
+    const entry = { text: trimmed, assumption };
+    byText.set(trimmed, entry);
+    out.push(entry);
   };
-  for (const decision of design.design_decisions ?? []) push2(decision);
-  for (const decision of design.grounded_decisions ?? []) push2(decision?.text);
+  for (const decision of design.design_decisions ?? []) push2(decision, false);
+  for (const decision of design.grounded_decisions ?? []) push2(decision?.text, decision?.assumption === true);
   return out;
 }
+function assumedAmong(design, texts) {
+  const assumed = new Set(
+    decisionEntries(design).filter((entry) => entry.assumption).map((entry) => entry.text)
+  );
+  return texts.filter((text) => assumed.has(text));
+}
 function relatedDecisions(design, component) {
   const needles = [component.name, component.technology].filter((value) => typeof value === "string" && value.trim().length > 2).map((value) => value.toLowerCase());
   if (needles.length === 0) return [];
@@ -1403,14 +1655,24 @@ function relatedDecisions(design, component) {
     return needles.some((needle) => haystack.includes(needle));
   });
 }
-function overview(design) {
+function overview(design, ledger) {
+  const decisions = decisionTexts(design);
   return {
     title: design.title ?? "Untitled design",
     description: design.description ?? "",
     components: design.components ?? [],
     connections: design.connections ?? [],
-    design_decisions: decisionTexts(design),
-    trade_offs: design.trade_offs ?? []
+    design_decisions: decisions,
+    // A subset of `design_decisions`, not a second list of decisions: which of them the design
+    // marks as resting on no cited source. Additive, so `design_decisions` stays the plain
+    // strings every existing caller reads.
+    assumed_decisions: assumedAmong(design, decisions),
+    trade_offs: design.trade_offs ?? [],
+    // Carried verbatim, rows in the server's order, and only when the version has one. This is
+    // a rebuild from named keys, so anything not named here is dropped without a trace — which
+    // is how `grounded_decisions` went missing for two releases. Re-sorting the rows on the way
+    // past would make "verbatim" untrue; the grouping belongs to the text that prints them.
+    ...ledger ? { requirement_ledger: ledger } : {}
   };
 }
 function normalize(value) {
@@ -1418,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. component: one component, its connections in both directions, and the decisions that mention it. 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.")
@@ -1438,12 +1700,19 @@ var output3 = z5.object({
   /** Mode-shaped. Deliberately loose: six modes cannot share one strict schema honestly. */
   data: z5.unknown()
 });
+function decisionsHeading(assumed, settled, withAssumptions) {
+  return assumed.length > 0 ? withAssumptions : settled;
+}
+function decisionLines(decisions, assumed) {
+  const marked = new Set(assumed);
+  return decisions.map((decision) => `- ${decision}${marked.has(decision) ? " (assumption)" : ""}`);
+}
 function registerGetDesign(server, client, resolver) {
   server.registerTool(
     "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. 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 }
@@ -1459,7 +1728,7 @@ function registerGetDesign(server, client, resolver) {
       switch (mode) {
         case "overview": {
           const design = await resolver.design(resolved.architectureId);
-          const data = overview(design.architecture_json);
+          const data = overview(design.architecture_json, design.requirement_ledger);
           const facts = factsFrom(resolved);
           return ok({ ...base, ...facts, data }, [
             `# ${data.title}`,
@@ -1469,6 +1738,10 @@ function registerGetDesign(server, client, resolver) {
             ...data.components.map(
               (c) => `- ${c.id} \u2014 ${c.name} (${c.type}${c.technology ? `, ${c.technology}` : ""})`
             ),
+            // Above the decisions because the two answer different questions, in
+            // this order: requirements are what was asked for, decisions are how
+            // the design answered.
+            ...requirementBlock(data.requirement_ledger),
             // The design's own reasoning, which this text used to omit entirely
             // while carrying it in the structured half — so an agent working from
             // what it was shown rebuilt every choice from scratch, and could
@@ -1476,8 +1749,12 @@ function registerGetDesign(server, client, resolver) {
             // like this", and the overview is where that gets asked.
             ...data.design_decisions.length ? [
               "",
-              "Decisions taken \u2014 these are settled, build to them:",
-              ...data.design_decisions.map((decision) => `- ${decision}`)
+              decisionsHeading(
+                data.assumed_decisions,
+                "Decisions taken \u2014 these are settled, build to them:",
+                "Decisions taken \u2014 build to them; confirm the ones marked (assumption) first, they rest on no cited source:"
+              ),
+              ...decisionLines(data.design_decisions, data.assumed_decisions)
             ] : [],
             ...data.trade_offs.length ? [
               "",
@@ -1493,7 +1770,7 @@ function registerGetDesign(server, client, resolver) {
             return failure('mode "component" needs a component_id. Use mode "overview" or "build_order" to see the ids.');
           }
           const design = await resolver.design(resolved.architectureId);
-          const slice = sliceComponent(design.architecture_json, component_id);
+          const slice = sliceComponent(design.architecture_json, component_id, design.requirement_ledger);
           if (!slice) {
             const known = (design.architecture_json.components ?? []).map((c) => c.id).join(", ");
             return failure(
@@ -1509,6 +1786,14 @@ function registerGetDesign(server, client, resolver) {
             "",
             outgoing.length ? `Calls: ${outgoing.map((c) => `${c.target}${c.protocol ? ` (${c.protocol})` : ""}`).join(", ")}` : "Calls nothing.",
             incoming.length ? `Called by: ${incoming.map((c) => c.source).join(", ")}` : "Called by nothing in the design.",
+            // 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
@@ -1516,8 +1801,12 @@ function registerGetDesign(server, client, resolver) {
             // with no reasoning rather than as a decision that names other boxes.
             ...slice.related_decisions.length ? [
               "",
-              "Decisions that mention it:",
-              ...slice.related_decisions.map((decision) => `- ${decision}`)
+              decisionsHeading(
+                slice.assumed_decisions,
+                "Decisions that mention it:",
+                "Decisions that mention it \u2014 confirm the ones marked (assumption) first, they rest on no cited source:"
+              ),
+              ...decisionLines(slice.related_decisions, slice.assumed_decisions)
             ] : [
               "",
               "No decision in this design names this component. That is not the same as",
@@ -1551,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);
@@ -1558,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:`;
@@ -1566,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
@@ -1585,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"));
         }
@@ -1644,6 +1972,70 @@ function registerGetDesign(server, client, resolver) {
     })
   );
 }
+function requirementBlock(ledger) {
+  const rows = orderRequirementRows(ledger?.rows ?? []);
+  if (!ledger || rows.length === 0) return [];
+  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),
+    "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.
+    ...ledger.grounding_state === "not_grounded" ? [
+      "This version records no citations at all, so `uncited` here means nothing recorded what",
+      "addresses the requirement \u2014 not that nothing in the design does."
+    ] : [],
+    ...ledger.verification_state === "partial" ? [
+      "The verifier did not check every requirement in this set, so an `unchecked` row is",
+      "neither confirmed nor flagged."
+    ] : ledger.verification_state === "not_run" ? [
+      "The verifier did not run on this version, so an `unchecked` row is neither confirmed",
+      "nor flagged."
+    ] : [],
+    ...ledger.analysis_degraded ? ["The requirements analysis for this version ran degraded. Treat the list as incomplete."] : []
+  ];
+}
+function requirementsServed(rows) {
+  if (!rows?.length) return [];
+  return [
+    "",
+    "Requirements the design cites this component for:",
+    ...rows.map(requirementLine),
+    "`fails` \u2014 a named check measured the design as not meeting it; `not_checked` \u2014 nobody",
+    "established either way; `no_gap_found` \u2014 nothing contradicted it, which is not the same as proven."
+  ];
+}
+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 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();
+  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();
   if (gap.adr_id) {
@@ -1654,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.1.2",
+  "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",