sdd_validate

Instructions

Implementation Reference

• src/tools/sdd-contracts.ts:14-84 (handler)

  The handler function for the sdd_validate tool. It parses a JSON SDD contract string, validates it against SddContractSchema via safeParse, returns validation errors if invalid, otherwise returns valid=true along with phase, confidence, threshold, meets_confidence, allowed_next_phases, and warnings.

  server.tool(
    "sdd_validate",
    "Validate an SDD contract against the phase schema. Returns validation result with confidence check and allowed transitions.",
    {
      contract: z
        .string()
        .max(131072)
        .describe("JSON string of the SDD contract to validate"),
    },
    async ({ contract }) => {
      try {
        const parsed = JSON.parse(contract);
        const result = SddContractSchema.safeParse(parsed);
  
        if (!result.success) {
          return {
            content: [
              {
                type: "text" as const,
                text: JSON.stringify({
                  valid: false,
                  errors: result.error.issues.map((i) => ({
                    path: i.path.join("."),
                    message: i.message,
                  })),
                }),
              },
            ],
          };
        }
  
        const data = result.data;
        const threshold = CONFIDENCE_THRESHOLDS[data.phase];
        const meetsConfidence = data.confidence >= threshold;
        const allowedNext = PHASE_TRANSITIONS[data.phase];
  
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify({
                valid: true,
                phase: data.phase,
                confidence: data.confidence,
                threshold,
                meets_confidence: meetsConfidence,
                allowed_next_phases: allowedNext,
                warnings: !meetsConfidence
                  ? [
                      `Confidence ${data.confidence} is below threshold ${threshold} for phase "${data.phase}"`,
                    ]
                  : [],
              }),
            },
          ],
        };
      } catch (e) {
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify({
                valid: false,
                errors: [{ path: "root", message: `Invalid JSON: ${e}` }],
              }),
            },
          ],
        };
      }
    }
  );

• src/types/index.ts:54-66 (schema)

  The Zod schema used to validate SDD contracts. Defines shape with phase, change_name, project, status, confidence, executive_summary, artifacts_saved, next_recommended, risks, and data fields.

  export const SddContractSchema = z.object({
    schema_version: z.string().max(32).default("1.0"),
    phase: z.enum(SDD_PHASES),
    change_name: z.string().min(1).max(256),
    project: z.string().min(1).max(256),
    status: z.enum(["success", "partial", "failed", "blocked"]),
    confidence: z.number().min(0).max(1),
    executive_summary: z.string().min(10).max(65536),
    artifacts_saved: z.array(ArtifactSchema).max(50).default([]),
    next_recommended: z.array(z.enum(SDD_PHASES)).max(9).default([]),
    risks: z.array(RiskSchema).max(50).default([]),
    data: z.record(z.unknown()).default({}),
  });

• src/tools/sdd-contracts.ts:12-13 (registration)

  Registration of all SDD tools including sdd_validate, via server.tool() inside registerSddTools() which is exported to be called from the main server entry point.

  export function registerSddTools(server: McpServer): void {
    // ── Validate SDD Contract ───────────────────────────

• src/types/index.ts:18-40 (helper)

  Supporting constants used by sdd_validate: PHASE_TRANSITIONS (maps each phase to allowed next phases) and CONFIDENCE_THRESHOLDS (minimum confidence per phase).

  export const PHASE_TRANSITIONS: Record<SddPhase, SddPhase[]> = {
    init: ["explore", "propose"],
    explore: ["propose", "spec"],
    propose: ["spec", "design", "init"],
    spec: ["design", "tasks"],
    design: ["tasks", "spec"],
    tasks: ["apply"],
    apply: ["verify", "tasks"],
    verify: ["archive", "apply"],
    archive: [],
  };
  
  export const CONFIDENCE_THRESHOLDS: Record<SddPhase, number> = {
    init: 0.5,
    explore: 0.5,
    propose: 0.7,
    spec: 0.8,
    design: 0.7,
    tasks: 0.8,
    apply: 0.6,
    verify: 0.9,
    archive: 0.9,
  };