sad-mcp 2.0.0 → 2.1.1

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,393 @@
+// 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;
+            // §WF — a UC initiated by a human actor must have a wireframe.
+            if (primaryActor && actorIds.has(primaryActor)) {
+                const pa = actors.find((a) => String(a.id) === primaryActor);
+                const isHuman = !pa || pa.actorType !== "system";
+                const wfMissing = typeof wf !== "string" || wf.trim() === "";
+                if (isHuman && wfMissing) {
+                    err("wireframe-missing", `${path}.wireframe`, `UC "${id}" has a human primary actor ("${primaryActor}") but no wireframe. Every human-initiated UC requires a wireframe per §WF. Add one, or explicitly use a placeholder describing what info is missing.`);
+                }
+            }
+            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.1",
   "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
 
@@ -786,9 +789,15 @@ The `connections` entry for a timed link looks like:
 
 ---
 
-## §WF. Wireframe Authoring (Per-UC, Optional)
+## §WF. Wireframe Authoring (Mandatory for Human-Initiated UCs)
 
-Where a UC benefits from a visual mock of the UI the user sees, emit a wireframe as an inline HTML fragment and attach it to `useCaseDocs[ucId].wireframe`. The modal renderer (§8a) injects the fragment after passing a safety check (see `wireframeSafe()` in §8a).
+**A wireframe is required for every UC whose `primaryActor.actorType === 'human'`.** The user sees a screen; a use case without a visual mock of that screen is incomplete documentation. The validator (§12) errors on any human-initiated UC missing a wireframe.
+
+Wireframe is **optional** (and usually omitted) only for:
+- UCs whose primary actor is a system or cron (`actorType: 'system'`) — no human sees a screen.
+- Pure include-target UCs (sub-behaviors with no actor association).
+
+For every other UC, emit a wireframe as an inline HTML fragment and attach it to `useCaseDocs[ucId].wireframe`. The modal renderer (§8a) injects the fragment after passing a safety check (see `wireframeSafe()` in §8a).
 
 Claude authors the wireframe using its own UI-generation judgment — there is no DSL. But the skill enforces a consistent look and safe sandbox via a scoped CSS theme and a set of forbidden patterns.
 
@@ -853,13 +862,14 @@ 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
 
-- The UC has no user-facing screen (e.g., a back-end cron job, an automated reconciliation).
-- The UI is trivial (e.g., a single "Approve" confirmation prompt) — prose in the scenario flow is enough.
-- You cannot author the wireframe without making up details the spec does not support — put those in `diagramModel.openQuestions` instead.
+- Primary actor is a system / cron (`actorType: 'system'`) — e.g., a back-end reconciliation triggered by the clock.
+- The UC is purely an `«include»` target (a sub-behavior, not a user-visible goal).
+
+**"The UI is trivial" is not a valid reason to skip.** A single approval prompt still deserves a mock — it shows the reader what the button says, what data is visible on the screen, and what confirmation text appears. If you genuinely cannot author the wireframe because the spec is silent, record the gap in `diagramModel.openQuestions` AND still emit a placeholder wireframe with the questions visible inside it.
 
 ---
 
@@ -1149,18 +1159,44 @@ 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.
 - [ ] Clicking a UC on the diagram opens the full-screen modal (§8a); Esc / backdrop click closes it. Step actor/UC references are clickable. Actor popup + association popup (§8b) still work for non-UC clicks.
-- [ ] Any `wireframe` HTML passes `wireframeSafe()` (no `<script>`, no `on*=`, no `<iframe>`, no external URLs, no `@import`, no inline `<style>`); all classes are `wf-*` only.
+- [ ] Every UC whose primary actor is human has a wireframe (§WF). System/cron-initiated UCs and pure include-targets may omit.
+- [ ] Any `wireframe` HTML passes `wireframeSafe()` (no `<script>`, no `on*=`, no `<iframe>`, no external URLs, no `@import`, no inline `<style>`); all classes are `wf-*` only; visible text is in Hebrew.
 - [ ] Every actor-UC association has a written §4.1 justification block (role, initiates? one-line "why"); every UC has ≥1 association with `initiates = yes`.
 - [ ] Every association line carries a transparent click-hitbox (stroke-width ≥12, `data-conn-id`) wired to `showDesc(id,'assoc',event)`; `assocDescriptions` entry exists for each id.
 - [ ] `assumptions` and `openQuestions` arrays are present in `diagramModel`; the HTML renders the bottom panel whenever either is non-empty.