sad-mcp 2.0.0 → 2.1.0

package/dist/tools.js

@@ -8,6 +8,7 @@ import { extractText, isExtractable } from "./text-extract.js";
 import { loadTextCache, saveTextEntry } from "./text-cache.js";
 import { trackToolCall } from "./tracking.js";
 import { renderBPMN, parseAndValidate, formatIssues, } from "./bpmn/index.js";
+import { parseAndValidate as ucParseAndValidate, formatIssues as ucFormatIssues, } from "./usecase/index.js";
 const __tools_filename = fileURLToPath(import.meta.url);
 const __tools_dirname = dirname(__tools_filename);
 const PKG = JSON.parse(readFileSync(join(__tools_dirname, "..", "package.json"), "utf-8"));
@@ -363,6 +364,20 @@ export function registerToolHandlers(server) {
                     properties: {},
                 },
             },
+            {
+                name: "uml_usecase_validate_model",
+                description: "Validate a use-case diagramModel JSON BEFORE generating the HTML file. Catches the §4/§4.4/CR violations the prompt cannot fully enforce: include target with actor association (CR #4), single-incoming include (CR #4), send-only UC names (CR #10), physical-verb names (CR #8), missing primary actor (§4.4), broken references in scenario flow steps, orphaned UCs, and unsafe wireframe HTML. Returns either 'Model valid' (optionally with warnings) or a list of specific errors to fix. Call iteratively — fix errors, call again — until valid. This check runs locally; no API cost.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        model_json: {
+                            type: "string",
+                            description: "The diagramModel JSON as a string (the same object assigned to `diagramModel` in the generated HTML). See skills/_shared/model-shape.md for the required shape.",
+                        },
+                    },
+                    required: ["model_json"],
+                },
+            },
         ],
     }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -689,6 +704,27 @@ export function registerToolHandlers(server) {
             trackToolCall(name, toolArgs, { success: true, responseChars: text.length }, Date.now() - startTime);
             return { content: [{ type: "text", text }] };
         }
+        if (name === "uml_usecase_validate_model") {
+            const modelJson = args?.model_json;
+            if (typeof modelJson !== "string" || modelJson.trim() === "") {
+                const text = "Error: model_json is required and must be a JSON string.";
+                trackToolCall(name, toolArgs, { success: false, responseChars: text.length }, Date.now() - startTime);
+                return { content: [{ type: "text", text }] };
+            }
+            const vr = ucParseAndValidate(modelJson);
+            if (vr.ok) {
+                const warnPart = vr.warnings.length > 0
+                    ? `\n\nWarnings (non-blocking):\n${ucFormatIssues(vr.warnings)}`
+                    : "";
+                const text = `✓ Model valid.${warnPart}\n\nYou may proceed to generate the HTML file (see skills/uml-use-case-diagram/SKILL.md §11).`;
+                trackToolCall(name, toolArgs, { success: true, responseChars: text.length }, Date.now() - startTime);
+                return { content: [{ type: "text", text }] };
+            }
+            const allWarnings = vr.warnings.length > 0 ? `\n\nWarnings (non-blocking):\n${ucFormatIssues(vr.warnings)}` : "";
+            const text = `✗ Model invalid — fix the following errors and call uml_usecase_validate_model again:\n\n${ucFormatIssues(vr.issues)}${allWarnings}`;
+            trackToolCall(name, toolArgs, { success: false, responseChars: text.length }, Date.now() - startTime);
+            return { content: [{ type: "text", text }] };
+        }
         throw new Error(`Unknown tool: ${name}`);
     });
 }

package/dist/usecase/index.d.ts

@@ -0,0 +1,2 @@
+export { validateModel, parseAndValidate, formatIssues } from "./validate.js";
+export type { ValidateResult, ValidationIssue } from "./validate.js";

package/dist/usecase/index.js

@@ -0,0 +1 @@
+export { validateModel, parseAndValidate, formatIssues } from "./validate.js";

package/dist/usecase/validate.d.ts

@@ -0,0 +1,17 @@
+export interface ValidationIssue {
+    severity: "error" | "warning";
+    code: string;
+    path: string;
+    message: string;
+}
+export type ValidateResult = {
+    ok: true;
+    warnings: ValidationIssue[];
+} | {
+    ok: false;
+    issues: ValidationIssue[];
+    warnings: ValidationIssue[];
+};
+export declare function validateModel(model: unknown): ValidateResult;
+export declare function parseAndValidate(jsonText: string): ValidateResult;
+export declare function formatIssues(issues: ValidationIssue[]): string;

package/dist/usecase/validate.js

@@ -0,0 +1,384 @@
+// Structural validator for UML use-case diagramModel JSON.
+//
+// Purpose: catch the business-rule violations the SKILL prompts for but cannot
+// enforce on its own — overeager «include», send-only UCs, physical-verb
+// labels, missing primary actor, broken references in scenario flows, etc.
+//
+// Returns ALL issues at once so the calling LLM can self-correct in a single
+// pass rather than iterating error-by-error.
+// ── Name heuristics (CR #8 and CR #10) ──────────────────────────────────
+// Send-only / output-only verbs that on their own do not constitute a UC.
+// Pattern allows "Record sending" etc. — only bare send-verbs flag.
+const SEND_ONLY_PATTERNS = [
+    /^(send|notify|email|sms|alert|push|broadcast)\b/i,
+    /^(print)\s+\w+\s+(label|receipt|ticket|slip)\b/i,
+    /^שליחת\s/,
+    /^הודעה\s/,
+    /^התראה\s/,
+    /^הפצת\s/,
+];
+// Physical verbs that describe actions outside the IS. Allowed only when
+// wrapped by a system verb (רישום / הזנה / עדכון / סימון / Record / Enter / ...).
+const PHYSICAL_VERBS = [
+    /^(perform|do|execute|conduct)\b/i,
+    /^(pick|pack|ship|deliver|receive|count|pay|collect)\b/i,
+    /^(ביצוע|הכנת|קבלת|מסירת|ספירת|תשלום|איסוף)\s/,
+];
+const SYSTEM_VERB_WRAPPERS = [
+    /^(record|register|enter|log|capture|mark|update|create|save)\b/i,
+    /^(רישום|הזנת|עדכון|סימון|יצירת|שמירת|קליטת|תיעוד)\s/,
+];
+function looksSendOnly(name) {
+    return SEND_ONLY_PATTERNS.some((rx) => rx.test(name.trim()));
+}
+function looksPhysical(name) {
+    const n = name.trim();
+    if (SYSTEM_VERB_WRAPPERS.some((rx) => rx.test(n)))
+        return false;
+    return PHYSICAL_VERBS.some((rx) => rx.test(n));
+}
+// CR #11 — narrative UC docs must be in Hebrew. We accept "contains at least
+// one Hebrew character" as a cheap heuristic; trivial strings (empty, whitespace,
+// pure punctuation) are treated as missing-content rather than English.
+const HEBREW_RANGE = /[\u0590-\u05FF]/;
+function hasHebrew(text) {
+    return typeof text === "string" && HEBREW_RANGE.test(text);
+}
+function isMeaningful(text) {
+    return typeof text === "string" && text.trim().length >= 2;
+}
+function asArray(v) {
+    return Array.isArray(v) ? v : [];
+}
+function getParts(model) {
+    if (!model || typeof model !== "object")
+        return [];
+    const parts = asArray(model.parts);
+    return parts.map((p) => {
+        const obj = (p && typeof p === "object") ? p : {};
+        return {
+            elements: asArray(obj.elements),
+            relationships: asArray(obj.relationships),
+        };
+    });
+}
+// ── Main validator ──────────────────────────────────────────────────────
+export function validateModel(model) {
+    const errors = [];
+    const warnings = [];
+    const err = (code, path, message) => {
+        errors.push({ severity: "error", code, path, message });
+    };
+    const warn = (code, path, message) => {
+        warnings.push({ severity: "warning", code, path, message });
+    };
+    // --- Root shape ---
+    if (!model || typeof model !== "object") {
+        err("not-object", "(root)", "diagramModel must be a JSON object.");
+        return { ok: false, issues: errors, warnings };
+    }
+    const root = model;
+    if (root.kind !== "use-case") {
+        err("wrong-kind", "kind", `Expected kind: "use-case", got ${JSON.stringify(root.kind)}.`);
+    }
+    const parts = getParts(root);
+    if (parts.length === 0) {
+        err("no-parts", "parts", "parts[] is empty — at least one part (tab) is required.");
+        return { ok: false, issues: errors, warnings };
+    }
+    // Collect everything across all parts for cross-part id lookup.
+    const allElements = [];
+    const allRelationships = [];
+    parts.forEach((p, i) => {
+        p.elements.forEach((el) => allElements.push({ part: i, el }));
+        p.relationships.forEach((rel) => allRelationships.push({ part: i, rel }));
+    });
+    const ucs = allElements.filter((x) => x.el.kind === "useCase").map((x) => x.el);
+    const actors = allElements.filter((x) => x.el.kind === "actor").map((x) => x.el);
+    const ucIds = new Set(ucs.map((u) => String(u.id)));
+    const actorIds = new Set(actors.map((a) => String(a.id)));
+    // --- Element shape checks ---
+    ucs.forEach((uc) => {
+        const id = String(uc.id ?? "");
+        const path = `useCase[${id || "?"}]`;
+        if (!id)
+            err("uc-missing-id", path, "useCase is missing an id.");
+        if (!uc.name)
+            err("uc-missing-name", path, "useCase is missing a name.");
+        if (uc.name && typeof uc.name === "string") {
+            if (looksSendOnly(uc.name)) {
+                err("send-only-uc", `${path}.name`, `UC name "${uc.name}" looks send-only (CR #10). Fold into the UC that decided to send.`);
+            }
+            if (looksPhysical(uc.name)) {
+                warn("physical-verb", `${path}.name`, `UC name "${uc.name}" starts with a physical verb (CR #8). Prefer "Record X" / "Enter X" / "Register X" to describe the IS action.`);
+            }
+        }
+    });
+    actors.forEach((a) => {
+        const id = String(a.id ?? "");
+        const path = `actor[${id || "?"}]`;
+        if (!id)
+            err("actor-missing-id", path, "actor is missing an id.");
+        if (!a.name)
+            err("actor-missing-name", path, "actor is missing a name.");
+    });
+    // --- Relationship cross-references + CR #4 + single-include + orphaned UC ---
+    const actorAssocsByUc = new Map();
+    const includeIntoByUc = new Map();
+    const initiatorByUc = new Map();
+    allRelationships.forEach(({ rel }, i) => {
+        const path = `relationships[${i}]`;
+        const kind = rel.kind;
+        if (kind === "actorAssoc") {
+            const actorId = String(rel.actorId ?? "");
+            const ucId = String(rel.ucId ?? "");
+            if (!actorIds.has(actorId))
+                err("unknown-actor", path, `actorAssoc.actorId "${actorId}" does not exist in actors[].`);
+            if (!ucIds.has(ucId))
+                err("unknown-uc", path, `actorAssoc.ucId "${ucId}" does not exist in use cases.`);
+            if (actorIds.has(actorId) && ucIds.has(ucId)) {
+                if (!actorAssocsByUc.has(ucId))
+                    actorAssocsByUc.set(ucId, []);
+                actorAssocsByUc.get(ucId).push(rel);
+                if (rel.role === "initiator") {
+                    if (!initiatorByUc.has(ucId))
+                        initiatorByUc.set(ucId, new Set());
+                    initiatorByUc.get(ucId).add(actorId);
+                }
+            }
+        }
+        else if (kind === "include") {
+            const from = String(rel.from ?? "");
+            const to = String(rel.to ?? "");
+            if (!ucIds.has(from))
+                err("unknown-uc", path, `include.from "${from}" does not exist.`);
+            if (!ucIds.has(to))
+                err("unknown-uc", path, `include.to "${to}" does not exist.`);
+            if (ucIds.has(to)) {
+                if (!includeIntoByUc.has(to))
+                    includeIntoByUc.set(to, []);
+                includeIntoByUc.get(to).push(rel);
+            }
+        }
+        else if (kind === "extend") {
+            const from = String(rel.from ?? "");
+            const to = String(rel.to ?? "");
+            if (!ucIds.has(from))
+                err("unknown-uc", path, `extend.from "${from}" does not exist.`);
+            if (!ucIds.has(to))
+                err("unknown-uc", path, `extend.to "${to}" does not exist.`);
+        }
+        else if (kind === "generalization") {
+            const from = String(rel.from ?? "");
+            const to = String(rel.to ?? "");
+            if (!ucIds.has(from) && !actorIds.has(from))
+                err("unknown-endpoint", path, `generalization.from "${from}" is neither a UC nor an actor.`);
+            if (!ucIds.has(to) && !actorIds.has(to))
+                err("unknown-endpoint", path, `generalization.to "${to}" is neither a UC nor an actor.`);
+        }
+    });
+    // CR #4 — include target checks
+    for (const [ucId, includes] of includeIntoByUc) {
+        const path = `useCase[${ucId}]`;
+        if (includes.length < 2) {
+            err("include-single-base", path, `UC "${ucId}" is the target of only ${includes.length} «include» arrow — an include target requires ≥2 bases (CR #4). Fold into the parent UC.`);
+        }
+        if ((actorAssocsByUc.get(ucId) || []).length > 0) {
+            err("include-target-has-actor", path, `UC "${ucId}" is an «include» target AND has a direct actor association — forbidden (CR #4). An include target must have ZERO actor associations.`);
+        }
+    }
+    // §4.1 — every UC must have ≥1 initiator (unless it's purely an include target)
+    ucs.forEach((uc) => {
+        const id = String(uc.id ?? "");
+        if (!id)
+            return;
+        const path = `useCase[${id}]`;
+        const isIncludeTarget = (includeIntoByUc.get(id) || []).length >= 2;
+        const hasInitiator = (initiatorByUc.get(id)?.size ?? 0) > 0;
+        const hasAnyActor = (actorAssocsByUc.get(id) || []).length > 0;
+        if (!isIncludeTarget && !hasAnyActor) {
+            err("uc-no-actor", path, `UC "${id}" has no actor association and is not an include target. Either connect an actor or remove the UC.`);
+        }
+        if (!isIncludeTarget && hasAnyActor && !hasInitiator) {
+            err("uc-no-initiator", path, `UC "${id}" has actor associations but none with role: "initiator" (§4.1). Every UC needs at least one initiator.`);
+        }
+    });
+    // §4.4 — per-UC documentation checks (only for non-include-target UCs; include
+    // targets are sub-behaviors and can use lighter docs in practice, but we still
+    // require description + at least one scenario if any doc is present).
+    ucs.forEach((uc) => {
+        const id = String(uc.id ?? "");
+        if (!id)
+            return;
+        const path = `useCase[${id}]`;
+        const isIncludeTarget = (includeIntoByUc.get(id) || []).length >= 2;
+        const primaryActor = uc.primaryActor;
+        if (!isIncludeTarget) {
+            if (!primaryActor) {
+                err("uc-missing-primary-actor", path, `UC "${id}" is missing primaryActor (§4.4).`);
+            }
+            else if (!actorIds.has(primaryActor)) {
+                err("uc-primary-actor-unknown", path, `UC "${id}" primaryActor "${primaryActor}" is not an actor.`);
+            }
+            else if (!(initiatorByUc.get(id)?.has(primaryActor))) {
+                err("uc-primary-actor-not-initiator", path, `UC "${id}" primaryActor "${primaryActor}" is not connected with role: "initiator". The primary actor must be an initiator.`);
+            }
+        }
+        const scenarios = asArray(uc.scenarios);
+        if (!isIncludeTarget && scenarios.length === 0) {
+            err("uc-no-scenarios", path, `UC "${id}" has no scenarios. At least one scenario with a flow is required (§4.4).`);
+        }
+        scenarios.forEach((sc, si) => {
+            const sco = (sc && typeof sc === "object") ? sc : {};
+            const scPath = `${path}.scenarios[${si}]`;
+            const flow = asArray(sco.flow);
+            if (flow.length === 0) {
+                err("scenario-no-flow", scPath, `Scenario has no flow steps. At least one step is required.`);
+            }
+            flow.forEach((step, stepIdx) => {
+                const s = (step && typeof step === "object") ? step : {};
+                const sPath = `${scPath}.flow[${stepIdx}]`;
+                const k = s.kind;
+                if (k === "actor") {
+                    const aId = String(s.actor ?? "");
+                    if (!actorIds.has(aId))
+                        err("flow-unknown-actor", sPath, `Flow step references unknown actor id "${aId}".`);
+                }
+                else if (k === "include") {
+                    const uId = String(s.uc ?? "");
+                    if (!ucIds.has(uId))
+                        err("flow-unknown-uc", sPath, `Flow step «include» references unknown UC id "${uId}".`);
+                    // Also require a matching include relationship to exist.
+                    const targets = includeIntoByUc.get(uId) || [];
+                    const hasMatching = targets.some((rel) => String(rel.from) === id);
+                    if (ucIds.has(uId) && !hasMatching) {
+                        err("flow-include-mismatch", sPath, `Flow step «include» ${uId} from UC "${id}" does not have a matching include relationship in relationships[]. Add { kind: "include", from: "${id}", to: "${uId}" } or remove this step.`);
+                    }
+                }
+                else if (k === "system" || k === "extension") {
+                    // no refs to check
+                }
+                else if (k) {
+                    err("flow-unknown-kind", sPath, `Flow step kind "${String(k)}" is not one of: actor, system, include, extension.`);
+                }
+            });
+            const extensions = asArray(sco.extensions);
+            extensions.forEach((ext, ei) => {
+                const e = (ext && typeof ext === "object") ? ext : {};
+                const at = Number(e.at);
+                if (!Number.isFinite(at) || at < 1 || at > flow.length) {
+                    err("extension-bad-at", `${scPath}.extensions[${ei}]`, `Extension.at=${String(e.at)} does not reference a valid flow step (1..${flow.length}).`);
+                }
+            });
+        });
+        if (!isIncludeTarget) {
+            const pre = asArray(uc.preconditions);
+            const post = asArray(uc.postconditions);
+            const stories = asArray(uc.userStories);
+            if (pre.length === 0)
+                warn("uc-no-preconditions", path, `UC "${id}" has no preconditions — recommended.`);
+            if (post.length === 0)
+                warn("uc-no-postconditions", path, `UC "${id}" has no postconditions — recommended.`);
+            if (stories.length === 0)
+                err("uc-no-user-stories", path, `UC "${id}" has no userStories (§4.4). Add as many as the UC warrants — one per distinct user goal.`);
+            else if (stories.length === 1)
+                warn("uc-single-user-story", path, `UC "${id}" has only 1 user story. Add one per distinct stakeholder goal behind the UC; a single token story is usually incomplete.`);
+            // CR #11 — narrative content must be in Hebrew.
+            if (isMeaningful(uc.description) && !hasHebrew(uc.description)) {
+                err("non-hebrew-text", `${path}.description`, `UC description must be written in Hebrew (CR #11).`);
+            }
+            pre.forEach((p, i) => {
+                if (isMeaningful(p) && !hasHebrew(p))
+                    err("non-hebrew-text", `${path}.preconditions[${i}]`, `Precondition must be written in Hebrew (CR #11).`);
+            });
+            post.forEach((p, i) => {
+                if (isMeaningful(p) && !hasHebrew(p))
+                    err("non-hebrew-text", `${path}.postconditions[${i}]`, `Postcondition must be written in Hebrew (CR #11).`);
+            });
+            stories.forEach((s, i) => {
+                const obj = (s && typeof s === "object") ? s : {};
+                const combined = `${obj.role ?? ""} ${obj.want ?? ""} ${obj.so ?? ""}`;
+                if (isMeaningful(combined) && !hasHebrew(combined))
+                    err("non-hebrew-text", `${path}.userStories[${i}]`, `User story must be written in Hebrew (role/want/so — CR #11).`);
+            });
+            scenarios.forEach((sc, si) => {
+                const sco = (sc && typeof sc === "object") ? sc : {};
+                const scPath = `${path}.scenarios[${si}]`;
+                asArray(sco.flow).forEach((step, stepIdx) => {
+                    const s = (step && typeof step === "object") ? step : {};
+                    if (isMeaningful(s.text) && !hasHebrew(s.text))
+                        err("non-hebrew-text", `${scPath}.flow[${stepIdx}].text`, `Flow step text must be written in Hebrew (CR #11).`);
+                });
+                asArray(sco.extensions).forEach((ext, ei) => {
+                    const e = (ext && typeof ext === "object") ? ext : {};
+                    if (isMeaningful(e.text) && !hasHebrew(e.text))
+                        err("non-hebrew-text", `${scPath}.extensions[${ei}].text`, `Extension text must be written in Hebrew (CR #11).`);
+                });
+            });
+            // Wireframe safety pre-check (regex-only; defense in depth — the HTML runtime
+            // also re-checks via wireframeSafe()).
+            const wf = uc.wireframe;
+            if (typeof wf === "string" && wf.length > 0) {
+                const forbidden = [
+                    /<script\b/i,
+                    /\son\w+\s*=/i,
+                    /<iframe\b/i,
+                    /src\s*=\s*["']https?:/i,
+                    /href\s*=\s*["']https?:/i,
+                    /@import\b/i,
+                    /<style\b/i,
+                ];
+                const hit = forbidden.find((rx) => rx.test(wf));
+                if (hit) {
+                    err("wireframe-unsafe", `${path}.wireframe`, `Wireframe HTML contains a forbidden pattern (${hit}). Remove scripts / on*= / iframe / external URLs / @import / <style>.`);
+                }
+                // CR #11 — the visible text inside the wireframe (labels, buttons, headings)
+                // must be in Hebrew since the product is Hebrew. A wireframe with zero
+                // Hebrew characters is an English UI mock.
+                if (!hasHebrew(wf)) {
+                    err("wireframe-non-hebrew", `${path}.wireframe`, `Wireframe contains no Hebrew characters. Visible labels, headings, and buttons inside the wireframe must be in Hebrew (CR #11). Identifier/class names (wf-*) stay ASCII.`);
+                }
+            }
+        }
+    });
+    // CR #11 — assumptions / openQuestions must be Hebrew (they live at the model root).
+    asArray(root.assumptions).forEach((s, i) => {
+        if (isMeaningful(s) && !hasHebrew(s))
+            err("non-hebrew-text", `assumptions[${i}]`, `Assumption must be written in Hebrew (CR #11).`);
+    });
+    asArray(root.openQuestions).forEach((s, i) => {
+        if (isMeaningful(s) && !hasHebrew(s))
+            err("non-hebrew-text", `openQuestions[${i}]`, `Open question must be written in Hebrew (CR #11).`);
+    });
+    // --- Warn on too many includes (diagrams with 3+ usually have a design smell) ---
+    const totalIncludes = allRelationships.filter((r) => r.rel.kind === "include").length;
+    const totalExtends = allRelationships.filter((r) => r.rel.kind === "extend").length;
+    if (totalIncludes + totalExtends > 2) {
+        warn("many-include-extend", "relationships", `Diagram has ${totalIncludes} «include» and ${totalExtends} «extend» relationships. Most UC diagrams need ≤2 combined — review each against the §4 gate.`);
+    }
+    if (errors.length > 0)
+        return { ok: false, issues: errors, warnings };
+    return { ok: true, warnings };
+}
+export function parseAndValidate(jsonText) {
+    let parsed;
+    try {
+        parsed = JSON.parse(jsonText);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            issues: [{ severity: "error", code: "invalid-json", path: "(root)", message: `JSON parse failed: ${msg}` }],
+            warnings: [],
+        };
+    }
+    return validateModel(parsed);
+}
+export function formatIssues(issues) {
+    if (issues.length === 0)
+        return "(no issues)";
+    return issues
+        .map((i) => `- [${i.severity === "error" ? "ERROR" : "warn"}] [${i.code}] ${i.path}: ${i.message}`)
+        .join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sad-mcp",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "MCP server for Software Analysis and Design course materials at BGU",
   "type": "module",
   "bin": {

package/skills/uml-use-case-diagram/SKILL.md

@@ -31,6 +31,7 @@ The shared files prepended to this prompt define the layout recipes, model shape
 8. **UC labels describe actions WITH the information system, not physical real-world actions.** See §3 for the full rule and verb list.
 9. **Every system-time / cron actor association MUST carry a timing label** (e.g., "פעם ביום", "כל 5 דקות"). See §2 and §8 for rendering.
 10. **No "send-only" use cases.** If a UC's entire behavior is sending a message / notification / alert / email / SMS, it is not a UC — it is a step inside the UC that *decided* to send it. See §3.
+11. **All narrative UC documentation must be in Hebrew.** Description, preconditions, postconditions, every scenario flow-step text and extension text, user stories (role / want / so), assumptions, and open questions must all contain Hebrew. Identifier strings (`id`, `primaryActor: 'customer'`) stay ASCII. The validator (§12) rejects narrative fields that contain zero Hebrew characters.
 
 ---
 
@@ -172,8 +173,10 @@ UC documentation: [uc-id]
         4a. if ___________ then ___________
     - id: sc-alt-1, name: "מסלול חלופי: ___" (optional additional scenarios)
 
-  userStories:
+  userStories:   (as many as the UC warrants — one per distinct stakeholder need; not a fixed number)
     - As a [role], I want [want], so that [benefit].
+    - As a [different role OR same role different goal], I want [...], so that [...].
+    - ... (keep adding until every user-facing goal tied to this UC is represented)
 
   wireframe?:  (optional — only where the UC benefits from a UI mock; see §WF)
 ```
@@ -184,7 +187,7 @@ UC documentation: [uc-id]
 - Every `[actor:id]` in a flow step references a real actor id.
 - Every `[include:id]` in a flow step references a real UC id AND corresponds to an `«include»` relationship that passed §4.2.
 - Every `Na` extension references a valid step number `N` in the same scenario's flow.
-- At least one user story per UC.
+- As many user stories as the UC warrants (minimum one) — cover every distinct user goal / role / scenario that motivates the UC. Do not stop at one.
 
 ### Quick disqualifiers
 
@@ -853,7 +856,7 @@ The `wireframeSafe()` regex rejects any of the following. A failing wireframe re
 - Keep each wireframe under ~200 lines of HTML. If the UC really needs more, split by scenario with `<h3 class="wf-heading">` dividers inside one `.wf-screen`.
 - Wireframes are static visual mocks. Form fields use `disabled` so the cursor shows they are illustrative.
 - Buttons are not wired to anything — `onclick` is forbidden. They communicate affordance, not behavior.
-- Hebrew RTL is inherited from `<body dir="rtl">`. Do not override `direction`.
+- **Visible text is Hebrew (CR #11).** Every heading, label, button, table header, and hint the user sees must be in Hebrew — the product is Hebrew. Class names (`wf-*`) and identifiers stay ASCII. RTL is inherited from `<body dir="rtl">`; do not override `direction`. The validator rejects a wireframe containing zero Hebrew characters (`wireframe-non-hebrew` error).
 
 ### When NOT to include a wireframe
 
@@ -1149,13 +1152,38 @@ body.uc-modal-open { overflow: hidden; }
 
 ## 12. Output
 
-- Save as `[system_name]_use_case_diagram.html`.
-- Briefly state: actor count, use case count, include/extend relationships (with the justification line for each), whether split (and which trigger fired).
+**Mandatory validator step — call before writing the HTML.**
+
+After assembling `diagramModel` and before generating any HTML, serialize it to JSON and call the MCP tool `uml_usecase_validate_model`:
+
+```
+uml_usecase_validate_model(model_json = JSON.stringify(diagramModel))
+```
+
+The validator runs locally (no API cost) and catches what the §4 and CR gates cannot enforce from prose:
+- Include target with an actor association (CR #4) → ERROR
+- Single-incoming «include» (CR #4) → ERROR
+- Send-only UC names like `Print Shipping Label` / `שליחת X` (CR #10) → ERROR
+- Physical-verb UC names (`Perform X`, `ביצוע X`) not wrapped with a system verb (CR #8) → WARNING
+- Primary actor missing, unknown, or not connected as initiator (§4.1/§4.4) → ERROR
+- Flow step references to unknown actor/UC ids, or `«include»` steps without a matching `include` relationship → ERROR
+- Extensions referencing invalid step numbers → ERROR
+- Narrative text missing Hebrew characters (description, preconditions, postconditions, flow/extension text, user stories, assumptions, openQuestions) → ERROR
+- Unsafe wireframe HTML (script / on*= / iframe / external URL / @import / inline style) → ERROR
+- Warnings: fewer than 2 user stories on a UC, no preconditions/postconditions, overall >2 include+extend relationships
+
+If the response is `✗ Model invalid`, fix every listed error and call the validator again. **Do not write the HTML file until the validator returns `✓ Model valid`.**
+
+After the validator passes, save the HTML as `[system_name]_use_case_diagram.html`.
+Briefly report: actor count, use case count, include/extend count, whether split, and any warnings the validator surfaced.
 
 ---
 
 ## 13. Pre-Delivery Checklist
 
+- [ ] `uml_usecase_validate_model` was called and returned `✓ Model valid` on the final model (§12). Warnings may remain but every ERROR is fixed.
+- [ ] All narrative UC documentation (description, preconditions, postconditions, flow-step text, extension text, user stories, assumptions, open questions) is in Hebrew (CR #11). Identifier strings remain ASCII.
+- [ ] User stories cover every distinct stakeholder goal behind the UC — not a single token story. If the UC serves multiple roles or scenarios, each gets its own story.
 - [ ] Every UC has a filled §4.4 documentation block AND a matching `useCaseDocs[id]` entry with `primaryActor`, ≥1 scenario, ≥1 flow step, `preconditions`, `postconditions`, and `userStories`.
 - [ ] Every `primaryActor` id exists in `actors[]` AND has an association with `role: 'initiator'` on that UC (aligning §4.1 with §4.4).
 - [ ] Every flow step of `kind: 'actor'` references a real actor id; every `kind: 'include'` references a real UC id; every `extension.at` references a valid step number in its scenario's flow.