specky-sdd 3.5.0 → 3.6.0

package/dist/services/diagram-generator.js

@@ -1,7 +1,19 @@
 /**
  * DiagramGenerator — Deterministic Mermaid diagram generation from spec artifacts.
  * All generation is pure string manipulation — no AI calls.
+ *
+ * Invariants:
+ * - Every identifier position (node ids, entity names, class names, state ids,
+ *   participants) contains only [A-Za-z0-9_]; human text lives in quoted labels.
+ * - No generator emits constant filler: output is derived from the artifact's
+ *   requirements, sections, bullets, or (as a last resort) its title/words, so
+ *   different inputs never produce byte-identical diagrams.
+ * - Numeric values (pie slices, gantt tasks) are real counts from the source,
+ *   never fabricated percentages.
  */
+import { currentDateString } from "../utils/runtime-context.js";
+/** Document-plumbing headings that must never become components/entities/states. */
+const STRUCTURAL_HEADING_REGEX = /^(table of contents|contents|toc|overview|introduction|revision history|document (?:control|history)|references|appendix(?:\s+\w+)?|glossary|summary|executive summary|purpose|scope|background|assumptions|out of scope|non-goals|approvals?|sign[- ]?offs?|change ?log|metadata|version history|status)$/i;
 export class DiagramGenerator {
     fileManager;
     constructor(fileManager) {
@@ -70,7 +82,9 @@ export class DiagramGenerator {
         return { type, title, source: "spec", mermaid_code };
     }
     /**
-     * Generate ALL diagram types for a feature from its artifacts.
+     * Generate ALL diagram types for a feature from its artifacts and write the
+     * full set to DIAGRAMS.md in the feature directory (grouped by source),
+     * replacing any scaffold left by earlier pipeline steps.
      */
     async generateAllDiagrams(specDir, featureDir) {
         const diagrams = [];
@@ -85,8 +99,10 @@ export class DiagramGenerator {
         if (specContent) {
             diagrams.push({ ...this.generateDiagram(specContent, "flowchart", "Requirements Flow"), source: "spec" });
             diagrams.push({ ...this.generateDiagram(specContent, "pie", "Requirements Coverage"), source: "spec" });
+            diagrams.push({ ...this.generateDiagram(specContent, "state", "Requirement Lifecycle"), source: "spec" });
         }
         if (designContent) {
+            diagrams.push({ ...this.generateDiagram(designContent, "c4_context", "System Context"), source: "design" });
             diagrams.push({ ...this.generateDiagram(designContent, "c4_container", "Architecture"), source: "design" });
             diagrams.push({ ...this.generateDiagram(designContent, "sequence", "API Flow"), source: "design" });
             diagrams.push({ ...this.generateDiagram(designContent, "er", "Data Model"), source: "design" });
@@ -108,7 +124,16 @@ export class DiagramGenerator {
             diagrams.push({ ...this.generateDiagram(specContent, "activity", "Workflow Activities"), source: "spec" });
         }
         const featureNumber = featureDir.match(/(\d{3})/)?.[1] || "000";
-        return { feature_number: featureNumber, diagrams, total_generated: diagrams.length };
+        let diagramsFile = null;
+        if (diagrams.length > 0) {
+            try {
+                diagramsFile = await this.fileManager.writeSpecFile(featureDir, "DIAGRAMS.md", this.buildDiagramsMarkdown(featureNumber, diagrams), true);
+            }
+            catch {
+                diagramsFile = null;
+            }
+        }
+        return { feature_number: featureNumber, diagrams, total_generated: diagrams.length, diagrams_file: diagramsFile };
     }
     /**
      * Generate user story flow diagram.
@@ -129,7 +154,7 @@ export class DiagramGenerator {
     generateFlowchart(content, title) {
         const items = this.extractListItems(content);
         if (items.length === 0)
-            return `flowchart TD\n  A[${this.sanitize(title)}]`;
+            return `flowchart TD\n  A["${this.sanitize(title)}"]`;
         const nodes = items.slice(0, 12).map((item, i) => {
             const id = `N${i}`;
             const nextId = i < Math.min(items.length, 12) - 1 ? `N${i + 1}` : null;
@@ -139,65 +164,118 @@ export class DiagramGenerator {
         });
         return `flowchart TD\n${nodes.join("\n")}`;
     }
-    generateSequence(content, _title) {
-        const actors = this.extractActors(content);
-        if (actors.length < 2)
-            return `sequenceDiagram\n  participant User\n  participant System\n  User->>System: Request\n  System-->>User: Response`;
-        const lines = [`sequenceDiagram`];
-        for (const actor of actors.slice(0, 6)) {
-            lines.push(`  participant ${this.sanitize(actor)}`);
+    generateSequence(content, title) {
+        const lines = [`sequenceDiagram`, `  participant Client`, `  participant System`];
+        // Preferred: derive one request/response exchange per EARS requirement
+        // (trigger clause -> Client request, shall clause -> System response).
+        const exchanges = this.extractRequirementExchanges(content);
+        if (exchanges.length > 0) {
+            for (const exchange of exchanges.slice(0, 8)) {
+                lines.push(`  Client->>System: ${this.messageText(exchange.trigger)}`);
+                lines.push(`  System-->>Client: ${this.messageText(exchange.response)}`);
+            }
+            return lines.join("\n");
         }
-        // Generate interactions from content patterns
-        const interactions = this.extractInteractions(content);
-        for (const interaction of interactions.slice(0, 10)) {
-            lines.push(`  ${this.sanitize(interaction.from)}->>${this.sanitize(interaction.to)}: ${this.sanitize(interaction.action.substring(0, 40))}`);
+        // Fallback: chart the artifact's own steps as alternating messages.
+        const items = this.extractListItems(content).slice(0, 6);
+        if (items.length > 0) {
+            items.forEach((item, i) => {
+                const arrow = i % 2 === 0 ? "Client->>System" : "System-->>Client";
+                lines.push(`  ${arrow}: ${this.messageText(item)}`);
+            });
+            return lines.join("\n");
         }
+        lines.push(`  Client->>System: ${this.messageText(`Request ${title}`)}`);
+        lines.push(`  System-->>Client: Response`);
         return lines.join("\n");
     }
-    generateERD(content, _title) {
+    generateERD(content, title) {
         const entities = this.extractEntities(content);
-        if (entities.length === 0)
-            return `erDiagram\n  ENTITY {\n    string id PK\n    string name\n  }`;
         const lines = [`erDiagram`];
+        if (entities.length === 0) {
+            const name = this.safeId(this.toPascalCase(title), "Entity").toUpperCase();
+            lines.push(`  ${name} {`, `    string id PK`, `    string name`, `  }`);
+            return lines.join("\n");
+        }
+        const used = new Set();
+        const ids = [];
         for (const entity of entities.slice(0, 8)) {
-            lines.push(`  ${entity.name.toUpperCase().replace(/\s+/g, "_")} {`);
+            const id = this.uniqueId(this.safeId(entity.name, "ENTITY").toUpperCase(), used);
+            ids.push(id);
+            lines.push(`  ${id} {`);
             lines.push(`    string id PK`);
+            const attrUsed = new Set(["id"]);
             for (const attr of entity.attributes.slice(0, 6)) {
-                lines.push(`    string ${attr.replace(/\s+/g, "_").toLowerCase()}`);
+                const attrId = this.uniqueId(this.safeId(attr, "attr").toLowerCase(), attrUsed);
+                lines.push(`    string ${attrId}`);
             }
             lines.push(`  }`);
         }
         // Add relationships
-        for (let i = 0; i < entities.length - 1 && i < 7; i++) {
-            const from = entities[i].name.toUpperCase().replace(/\s+/g, "_");
-            const to = entities[i + 1].name.toUpperCase().replace(/\s+/g, "_");
-            lines.push(`  ${from} ||--o{ ${to} : "has"`);
+        for (let i = 0; i < ids.length - 1 && i < 7; i++) {
+            lines.push(`  ${ids[i]} ||--o{ ${ids[i + 1]} : "has"`);
         }
         return lines.join("\n");
     }
-    generateClassDiagram(content, _title) {
-        const interfaces = this.extractInterfaces(content);
-        if (interfaces.length === 0)
-            return `classDiagram\n  class Service {\n    +execute()\n  }`;
+    generateClassDiagram(content, title) {
+        const classes = this.extractClassCandidates(content);
         const lines = [`classDiagram`];
-        for (const iface of interfaces.slice(0, 8)) {
-            lines.push(`  class ${this.sanitize(iface.name)} {`);
-            for (const method of iface.methods.slice(0, 5)) {
-                lines.push(`    +${this.sanitize(method)}()`);
+        if (classes.length === 0) {
+            lines.push(`  class ${this.safeId(this.toPascalCase(title), "Feature")}`);
+            return lines.join("\n");
+        }
+        const used = new Set();
+        const ids = [];
+        for (const cls of classes.slice(0, 8)) {
+            const id = this.uniqueId(this.safeId(cls.name, "Class"), used);
+            ids.push(id);
+            if (cls.methods.length === 0) {
+                lines.push(`  class ${id}`);
+            }
+            else {
+                lines.push(`  class ${id} {`);
+                for (const method of cls.methods.slice(0, 5)) {
+                    lines.push(`    +${this.safeId(method, "method")}()`);
+                }
+                lines.push(`  }`);
             }
-            lines.push(`  }`);
+        }
+        for (let i = 0; i < ids.length - 1 && i < 7; i++) {
+            lines.push(`  ${ids[i]} ..> ${ids[i + 1]}`);
         }
         return lines.join("\n");
     }
-    generateStateDiagram(content, _title) {
+    generateStateDiagram(content, title) {
+        const lines = [`stateDiagram-v2`];
+        // Preferred: real lifecycle words found in the artifact.
         const states = this.extractStates(content);
-        if (states.length === 0)
-            return `stateDiagram-v2\n  [*] --> Active\n  Active --> Completed\n  Completed --> [*]`;
-        const lines = [`stateDiagram-v2`, `  [*] --> ${this.sanitize(states[0])}`];
-        for (let i = 0; i < states.length - 1; i++) {
-            lines.push(`  ${this.sanitize(states[i])} --> ${this.sanitize(states[i + 1])}`);
+        if (states.length >= 2) {
+            const used = new Set();
+            const ids = states.slice(0, 8).map((s) => this.uniqueId(this.safeId(s, "state"), used));
+            lines.push(`  [*] --> ${ids[0]}`);
+            for (let i = 0; i < ids.length - 1; i++) {
+                lines.push(`  ${ids[i]} --> ${ids[i + 1]}`);
+            }
+            lines.push(`  ${ids[ids.length - 1]} --> [*]`);
+            return lines.join("\n");
+        }
+        // Fallback: the artifact's own section names become sequential stages.
+        const sections = this.extractSections(content).slice(0, 8);
+        if (sections.length > 0) {
+            const ids = sections.map((_, i) => `s${i}`);
+            sections.forEach((section, i) => {
+                lines.push(`  state "${this.plainText(section.heading)}" as ${ids[i]}`);
+            });
+            lines.push(`  [*] --> ${ids[0]}`);
+            for (let i = 0; i < ids.length - 1; i++) {
+                lines.push(`  ${ids[i]} --> ${ids[i + 1]}`);
+            }
+            lines.push(`  ${ids[ids.length - 1]} --> [*]`);
+            return lines.join("\n");
         }
-        lines.push(`  ${this.sanitize(states[states.length - 1])} --> [*]`);
+        // Last resort: a single state derived from the found word or the title.
+        const only = this.safeId(states[0] ?? this.toPascalCase(title), "Active");
+        lines.push(`  [*] --> ${only}`, `  ${only} --> [*]`);
         return lines.join("\n");
     }
     generateC4Context(content, title) {
@@ -212,11 +290,12 @@ export class DiagramGenerator {
             lines.push(`  Rel(user, system, "Uses")`);
         }
         else {
-            for (const sys of systems.slice(0, 6)) {
-                const id = sys.replace(/\s+/g, "_").toLowerCase();
-                lines.push(`  System(${id}, "${this.sanitize(sys)}", "${this.sanitize(sys)}")`);
-            }
-            lines.push(`  Rel(user, ${systems[0].replace(/\s+/g, "_").toLowerCase()}, "Uses")`);
+            const used = new Set(["user"]);
+            const ids = systems.slice(0, 6).map((sys) => this.uniqueId(this.safeId(sys, "system").toLowerCase(), used));
+            systems.slice(0, 6).forEach((sys, i) => {
+                lines.push(`  System(${ids[i]}, "${this.sanitize(sys)}", "${this.sanitize(sys)}")`);
+            });
+            lines.push(`  Rel(user, ${ids[0]}, "Uses")`);
         }
         return lines.join("\n");
     }
@@ -228,54 +307,102 @@ export class DiagramGenerator {
             `  Person(user, "User", "End user")`,
             `  System_Boundary(system, "${this.sanitize(title)}") {`,
         ];
+        const used = new Set(["user", "system"]);
+        let ids;
         if (components.length === 0) {
+            ids = ["api"];
             lines.push(`    Container(api, "API", "REST API")`);
             lines.push(`    ContainerDb(db, "Database", "Data storage")`);
         }
         else {
-            for (const comp of components.slice(0, 8)) {
-                const id = comp.replace(/\s+/g, "_").toLowerCase();
-                lines.push(`    Container(${id}, "${this.sanitize(comp)}", "${this.sanitize(comp)}")`);
-            }
+            ids = components.slice(0, 8).map((comp) => this.uniqueId(this.safeId(comp, "container").toLowerCase(), used));
+            components.slice(0, 8).forEach((comp, i) => {
+                lines.push(`    Container(${ids[i]}, "${this.sanitize(comp)}", "${this.sanitize(comp)}")`);
+            });
         }
         lines.push(`  }`);
-        lines.push(`  Rel(user, ${(components[0] || "api").replace(/\s+/g, "_").toLowerCase()}, "Uses")`);
+        lines.push(`  Rel(user, ${ids[0]}, "Uses")`);
         return lines.join("\n");
     }
     generateGantt(content, title) {
-        const tasks = this.extractTasks(content);
         const lines = [
             `gantt`,
-            `  title ${this.sanitize(title)}`,
+            `  title ${this.plainText(title)}`,
             `  dateFormat YYYY-MM-DD`,
         ];
-        let currentSection = "Setup";
         let taskCount = 0;
-        for (const task of tasks.slice(0, 15)) {
-            if (task.section && task.section !== currentSection) {
-                currentSection = task.section;
-                lines.push(`  section ${this.sanitize(currentSection)}`);
+        const pushTask = (name, duration) => {
+            const id = `t${taskCount}`;
+            // Mermaid gantt metadata order is `id, start, duration`: the first task
+            // is anchored to the (deterministic) generation date, the rest chain
+            // with `after`.
+            const start = taskCount === 0 ? currentDateString() : `after t${taskCount - 1}`;
+            const label = this.plainText(name).substring(0, 40) || `Task ${taskCount + 1}`;
+            lines.push(`  ${label} :${id}, ${start}, ${duration}`);
+            taskCount++;
+        };
+        // TASKS.md path: real checkbox tasks with their sections.
+        const tasks = this.extractTasks(content);
+        if (tasks.length > 0) {
+            let currentSection;
+            for (const task of tasks.slice(0, 15)) {
+                if (task.section && task.section !== currentSection) {
+                    currentSection = task.section;
+                    lines.push(`  section ${this.plainText(currentSection).substring(0, 40)}`);
+                }
+                pushTask(task.name, task.parallel ? "1d" : "2d");
             }
-            const id = `t${taskCount++}`;
-            const duration = task.parallel ? "1d" : "2d";
-            const dep = taskCount > 1 ? `, after t${taskCount - 2}` : "";
-            lines.push(`  ${this.sanitize(task.name.substring(0, 40))} :${id}, ${duration}${dep}`);
+            return lines.join("\n");
         }
+        // Spec/design/constitution path: chart the artifact's own sections so the
+        // gantt is never header-only.
+        const sections = this.extractSections(content).slice(0, 6);
+        if (sections.length > 0) {
+            for (const section of sections) {
+                lines.push(`  section ${this.plainText(section.heading).substring(0, 40)}`);
+                const bullets = section.bullets.slice(0, 3);
+                if (bullets.length === 0) {
+                    pushTask(section.heading, "2d");
+                }
+                else {
+                    for (const bullet of bullets) {
+                        pushTask(bullet, "1d");
+                    }
+                }
+            }
+            return lines.join("\n");
+        }
+        lines.push(`  section ${this.plainText(title).substring(0, 40) || "Plan"}`);
+        pushTask(`Draft ${title}`, "2d");
+        pushTask(`Review ${title}`, "1d");
         return lines.join("\n");
     }
     generatePie(content, title) {
-        // Extract categories and counts from content
         const categories = this.extractCategories(content);
         const lines = [`pie title ${this.sanitize(title)}`];
-        if (categories.length === 0) {
-            lines.push(`  "Functional" : 60`);
-            lines.push(`  "Non-Functional" : 25`);
-            lines.push(`  "Constraints" : 15`);
-        }
-        else {
+        if (categories.length > 0) {
             for (const cat of categories.slice(0, 8)) {
                 lines.push(`  "${this.sanitize(cat.name)}" : ${cat.count}`);
             }
+            return lines.join("\n");
+        }
+        // No categorizable content: chart REAL structural counts of the artifact —
+        // never fabricated percentages.
+        const sectionCount = (content.match(/^#{1,4}\s+.+$/gm) || []).length;
+        const bulletCount = (content.match(/^\s*[-*]\s+.+$/gm) || []).length;
+        const paragraphCount = content.split(/\n{2,}/).filter((p) => p.trim().length > 0).length;
+        const counts = [
+            { name: "Sections", count: sectionCount },
+            { name: "List Items", count: bulletCount },
+            { name: "Paragraphs", count: paragraphCount },
+        ].filter((c) => c.count > 0);
+        if (counts.length === 0) {
+            lines.push(`  "Empty" : 1`);
+        }
+        else {
+            for (const c of counts) {
+                lines.push(`  "${c.name}" : ${c.count}`);
+            }
         }
         return lines.join("\n");
     }
@@ -297,59 +424,66 @@ export class DiagramGenerator {
             `  title ${this.sanitize(title)}`,
             `  Container_Boundary(main, "Main System") {`,
         ];
+        const used = new Set(["main"]);
+        let ids;
         if (components.length === 0) {
+            ids = ["comp1", "comp2", "comp3"];
             lines.push(`    Component(comp1, "Core Module", "Handles main logic")`);
             lines.push(`    Component(comp2, "Data Access", "Database operations")`);
             lines.push(`    Component(comp3, "API Layer", "External interface")`);
         }
         else {
-            for (const comp of components.slice(0, 10)) {
-                const id = comp.replace(/\s+/g, "_").toLowerCase().replace(/[^a-z0-9_]/g, "");
-                lines.push(`    Component(${id}, "${this.sanitize(comp)}", "${this.sanitize(comp)}")`);
-            }
+            ids = components.slice(0, 10).map((comp) => this.uniqueId(this.safeId(comp, "comp").toLowerCase(), used));
+            components.slice(0, 10).forEach((comp, i) => {
+                lines.push(`    Component(${ids[i]}, "${this.sanitize(comp)}", "${this.sanitize(comp)}")`);
+            });
         }
         lines.push(`  }`);
         // Add relationships between adjacent components
-        const ids = components.length > 0
-            ? components.slice(0, 10).map(c => c.replace(/\s+/g, "_").toLowerCase().replace(/[^a-z0-9_]/g, ""))
-            : ["comp1", "comp2", "comp3"];
         for (let i = 0; i < ids.length - 1; i++) {
             lines.push(`  Rel(${ids[i]}, ${ids[i + 1]}, "Uses")`);
         }
         return lines.join("\n");
     }
-    generateC4Code(content, _title) {
-        const interfaces = this.extractInterfaces(content);
-        if (interfaces.length === 0) {
-            return `classDiagram\n  class IService {\n    <<interface>>\n    +execute()\n    +validate()\n  }\n  class ServiceImpl {\n    +execute()\n    +validate()\n  }\n  IService <|.. ServiceImpl`;
-        }
+    generateC4Code(content, title) {
+        const classes = this.extractClassCandidates(content);
         const lines = [`classDiagram`];
-        for (const iface of interfaces.slice(0, 10)) {
-            lines.push(`  class ${this.sanitize(iface.name)} {`);
-            lines.push(`    <<interface>>`);
-            for (const method of iface.methods.slice(0, 6)) {
-                lines.push(`    +${this.sanitize(method)}()`);
+        if (classes.length === 0) {
+            lines.push(`  class ${this.safeId(this.toPascalCase(title), "Feature")} {`, `    <<component>>`, `  }`);
+            return lines.join("\n");
+        }
+        const used = new Set();
+        const entries = [];
+        for (const cls of classes.slice(0, 10)) {
+            const id = this.uniqueId(this.safeId(cls.name, "Class"), used);
+            entries.push({ id, kind: cls.kind });
+            lines.push(`  class ${id} {`);
+            lines.push(`    <<${cls.kind === "interface" ? "interface" : "component"}>>`);
+            for (const method of cls.methods.slice(0, 6)) {
+                lines.push(`    +${this.safeId(method, "method")}()`);
             }
             lines.push(`  }`);
         }
-        // Add implementation relationships
-        for (let i = 1; i < interfaces.length && i < 10; i++) {
-            lines.push(`  ${this.sanitize(interfaces[0].name)} <|.. ${this.sanitize(interfaces[i].name)}`);
+        for (let i = 1; i < entries.length && i < 10; i++) {
+            const edge = entries[0].kind === "interface" ? "<|.." : "-->";
+            lines.push(`  ${entries[0].id} ${edge} ${entries[i].id}`);
         }
         return lines.join("\n");
     }
     generateActivity(content, title) {
-        const items = this.extractListItems(content);
-        if (items.length === 0)
-            return `flowchart TD\n  Start([Start]) --> Action1[Process]\n  Action1 --> End([End])`;
-        const lines = [`flowchart TD`, `  Start([${this.sanitize(title)} - Start])`];
+        const listItems = this.extractListItems(content);
+        const items = listItems.length > 0 ? listItems : this.extractSections(content).map((s) => s.heading);
+        if (items.length === 0) {
+            return `flowchart TD\n  Start(["${this.sanitize(title)} - Start"]) --> End([End])`;
+        }
+        const lines = [`flowchart TD`, `  Start(["${this.sanitize(title)} - Start"])`];
         let prevId = "Start";
         for (let i = 0; i < Math.min(items.length, 12); i++) {
             const item = items[i];
             const id = `A${i}`;
             // Detect decision points
             if (item.toLowerCase().includes("if ") || item.toLowerCase().includes("check") || item.toLowerCase().includes("validate")) {
-                lines.push(`  ${id}{${this.sanitize(item.substring(0, 50))}}`);
+                lines.push(`  ${id}{"${this.sanitize(item.substring(0, 50))}"}`);
                 lines.push(`  ${prevId} --> ${id}`);
                 if (i < items.length - 1) {
                     lines.push(`  ${id} -->|Yes| A${i + 1}`);
@@ -357,7 +491,7 @@ export class DiagramGenerator {
                 }
             }
             else {
-                lines.push(`  ${id}[${this.sanitize(item.substring(0, 50))}]`);
+                lines.push(`  ${id}["${this.sanitize(item.substring(0, 50))}"]`);
                 lines.push(`  ${prevId} --> ${id}`);
             }
             prevId = id;
@@ -367,24 +501,27 @@ export class DiagramGenerator {
     }
     generateUseCase(content, title) {
         const actors = this.extractActors(content);
-        const items = this.extractListItems(content);
         const lines = [`flowchart LR`];
         // Create actor nodes
         const actorList = actors.length > 0 ? actors.slice(0, 4) : ["User"];
-        for (const actor of actorList) {
-            lines.push(`  ${actor.replace(/\s+/g, "")}((${this.sanitize(actor)}))`);
-        }
-        // Create use case boundary
+        const used = new Set();
+        const actorIds = actorList.map((actor) => this.uniqueId(this.safeId(actor, "Actor"), used));
+        actorList.forEach((actor, i) => {
+            lines.push(`  ${actorIds[i]}(("${this.sanitize(actor)}"))`);
+        });
+        // Create use case boundary — cases come from the artifact's list items,
+        // then its real section names; never from an invented canned list.
         lines.push(`  subgraph "${this.sanitize(title)}"`);
-        const useCases = items.length > 0 ? items.slice(0, 8) : ["Login", "View Dashboard", "Export Data"];
+        const items = this.extractListItems(content);
+        const derived = items.length > 0 ? items : this.extractSections(content).map((s) => s.heading);
+        const useCases = derived.length > 0 ? derived.slice(0, 8) : [title];
         for (let i = 0; i < useCases.length; i++) {
-            lines.push(`    UC${i}([${this.sanitize(useCases[i].substring(0, 40))}])`);
+            lines.push(`    UC${i}(["${this.sanitize(useCases[i].substring(0, 40))}"])`);
         }
         lines.push(`  end`);
         // Connect actors to use cases
-        const primaryActor = actorList[0].replace(/\s+/g, "");
         for (let i = 0; i < Math.min(useCases.length, 8); i++) {
-            lines.push(`  ${primaryActor} --> UC${i}`);
+            lines.push(`  ${actorIds[0]} --> UC${i}`);
         }
         return lines.join("\n");
     }
@@ -392,32 +529,32 @@ export class DiagramGenerator {
         const entities = this.extractEntities(content);
         const components = this.extractComponents(content);
         const lines = [`flowchart LR`];
+        const used = new Set(["DS1", "DS2"]);
         // External entities
-        const externals = entities.length > 0 ? entities.slice(0, 3) : [{ name: "User", attributes: [] }];
-        for (const ext of externals) {
-            const id = ext.name.replace(/\s+/g, "_").toLowerCase();
-            lines.push(`  ${id}[/"${this.sanitize(ext.name)}"/]`);
-        }
+        const externals = entities.length > 0 ? entities.slice(0, 3).map((e) => e.name) : ["User"];
+        const extIds = externals.map((name) => this.uniqueId(this.safeId(name, "ext").toLowerCase(), used));
+        externals.forEach((name, i) => {
+            lines.push(`  ${extIds[i]}[/"${this.sanitize(name)}"/]`);
+        });
         // Processes
         const processes = components.length > 0 ? components.slice(0, 4) : ["Process Data"];
         for (let i = 0; i < processes.length; i++) {
-            lines.push(`  P${i}((${this.sanitize(processes[i].substring(0, 30))}))`);
+            lines.push(`  P${i}(("${this.sanitize(processes[i].substring(0, 30))}"))`);
         }
         // Data stores
-        lines.push(`  DS1[(Database)]`);
-        lines.push(`  DS2[(Cache)]`);
+        lines.push(`  DS1[("Database")]`);
+        lines.push(`  DS2[("Cache")]`);
         // Connect: external -> process -> store
-        const extId = externals[0].name.replace(/\s+/g, "_").toLowerCase();
         if (processes.length > 0) {
-            lines.push(`  ${extId} -->|Input| P0`);
+            lines.push(`  ${extIds[0]} -->|Input| P0`);
             lines.push(`  P0 -->|Store| DS1`);
             if (processes.length > 1) {
                 lines.push(`  P0 -->|Forward| P1`);
                 lines.push(`  P1 -->|Cache| DS2`);
-                lines.push(`  P1 -->|Response| ${extId}`);
+                lines.push(`  P1 -->|Response| ${extIds[0]}`);
             }
             else {
-                lines.push(`  P0 -->|Response| ${extId}`);
+                lines.push(`  P0 -->|Response| ${extIds[0]}`);
             }
         }
         return lines.join("\n");
@@ -431,13 +568,16 @@ export class DiagramGenerator {
         lines.push(`  Internet --> LB`);
         // Application layer
         lines.push(`  subgraph "Application Layer"`);
+        const used = new Set(["Internet", "LB", "DB", "Cache"]);
+        let appIds;
         if (components.length > 0) {
-            for (const comp of components.slice(0, 4)) {
-                const id = comp.replace(/\s+/g, "_").toLowerCase().replace(/[^a-z0-9_]/g, "");
-                lines.push(`    ${id}["${this.sanitize(comp)}"]`);
-            }
+            appIds = components.slice(0, 4).map((comp) => this.uniqueId(this.safeId(comp, "app").toLowerCase(), used));
+            components.slice(0, 4).forEach((comp, i) => {
+                lines.push(`    ${appIds[i]}["${this.sanitize(comp)}"]`);
+            });
         }
         else {
+            appIds = ["API", "Worker"];
             lines.push(`    API["API Server"]`);
             lines.push(`    Worker["Background Worker"]`);
         }
@@ -448,9 +588,6 @@ export class DiagramGenerator {
         lines.push(`    Cache[(Redis Cache)]`);
         lines.push(`  end`);
         // Connections
-        const appIds = components.length > 0
-            ? components.slice(0, 4).map(c => c.replace(/\s+/g, "_").toLowerCase().replace(/[^a-z0-9_]/g, ""))
-            : ["API", "Worker"];
         lines.push(`  LB --> ${appIds[0]}`);
         for (const id of appIds) {
             lines.push(`  ${id} --> DB`);
@@ -473,13 +610,16 @@ export class DiagramGenerator {
         // Private zone
         lines.push(`  subgraph "Private Zone"`);
         const components = this.extractComponents(content);
+        const used = new Set(["CDN", "WAF", "LB", "Gateway", "DB", "MQ"]);
+        let privateIds;
         if (components.length > 0) {
-            for (const comp of components.slice(0, 4)) {
-                const id = comp.replace(/\s+/g, "_").toLowerCase().replace(/[^a-z0-9_]/g, "");
-                lines.push(`    ${id}["${this.sanitize(comp)}"]`);
-            }
+            privateIds = components.slice(0, 4).map((comp) => this.uniqueId(this.safeId(comp, "node").toLowerCase(), used));
+            components.slice(0, 4).forEach((comp, i) => {
+                lines.push(`    ${privateIds[i]}["${this.sanitize(comp)}"]`);
+            });
         }
         else {
+            privateIds = ["AppServer", "WorkerNode"];
             lines.push(`    AppServer["Application Server"]`);
             lines.push(`    WorkerNode["Worker Node"]`);
         }
@@ -493,9 +633,6 @@ export class DiagramGenerator {
         lines.push(`  CDN --> WAF`);
         lines.push(`  WAF --> LB`);
         lines.push(`  LB --> Gateway`);
-        const privateIds = components.length > 0
-            ? components.slice(0, 4).map(c => c.replace(/\s+/g, "_").toLowerCase().replace(/[^a-z0-9_]/g, ""))
-            : ["AppServer", "WorkerNode"];
         lines.push(`  Gateway --> ${privateIds[0]}`);
         for (const id of privateIds) {
             lines.push(`  ${id} --> DB`);
@@ -509,67 +646,133 @@ export class DiagramGenerator {
         const regex = /^[-*]\s+(.+)$/gm;
         let match;
         while ((match = regex.exec(content)) !== null) {
-            items.push(match[1].trim());
+            const raw = match[1].trim();
+            // Skip pure-link bullets (tables of contents) and unwrap inline links.
+            if (/^\[[^\]]*\]\([^)]*\)$/.test(raw))
+                continue;
+            const item = raw.replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").trim();
+            if (item)
+                items.push(item);
         }
         return items;
     }
     extractActors(content) {
-        const actors = new Set();
+        const actors = [];
+        const seen = new Set();
         // Look for common actor patterns: "User", "System", "Admin", service names
         const patterns = /\b(User|System|Admin|Client|Server|API|Database|Service|Gateway|Queue|Cache)\b/gi;
         let match;
         while ((match = patterns.exec(content)) !== null) {
-            actors.add(match[1]);
+            const key = match[1].toLowerCase();
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            // Normalize casing so "service"/"Service" never become two actors
+            actors.push(match[1].charAt(0).toUpperCase() + match[1].slice(1));
         }
-        return Array.from(actors);
+        return actors;
     }
-    extractInteractions(content) {
-        const interactions = [];
-        // Look for "X sends/calls/returns to Y" patterns
-        const regex = /(\w+)\s+(?:sends?|calls?|requests?|returns?|responds?)\s+(?:to\s+)?(\w+)/gi;
-        let match;
-        while ((match = regex.exec(content)) !== null) {
-            interactions.push({ from: match[1], to: match[2], action: match[0] });
-        }
-        if (interactions.length === 0) {
-            interactions.push({ from: "User", to: "System", action: "Request" });
-            interactions.push({ from: "System", to: "User", action: "Response" });
+    /**
+     * Derive request/response exchanges from EARS requirement sentences.
+     * "When X, the system shall Y" -> Client request "X", System response "Y".
+     */
+    extractRequirementExchanges(content) {
+        const exchanges = [];
+        const sentences = content.split(/(?<=[.!?])\s+|\n+/);
+        for (const sentence of sentences) {
+            if (!/\bshall\b/i.test(sentence))
+                continue;
+            const conditional = sentence.match(/\b(?:when|while|where|if)\s+(.{3,80}?),?\s*(?:then\s+)?the\s+[\w -]{1,40}?\s+shall\s+(.{3,120})/i);
+            if (conditional) {
+                exchanges.push({
+                    trigger: conditional[1].trim(),
+                    response: conditional[2].replace(/[.\s]+$/, "").trim(),
+                });
+                continue;
+            }
+            const ubiquitous = sentence.match(/\bthe\s+[\w -]{1,40}?\s+shall\s+(.{3,120})/i);
+            if (ubiquitous) {
+                const action = ubiquitous[1].replace(/[.\s]+$/, "").trim();
+                exchanges.push({
+                    trigger: `Request to ${action.split(/\s+/).slice(0, 5).join(" ")}`,
+                    response: action,
+                });
+            }
         }
-        return interactions;
+        return exchanges;
     }
     extractEntities(content) {
         const entities = [];
-        // Look for entity-like headings followed by attribute lists
-        const sections = content.split(/^#{2,3}\s+/m);
-        for (const section of sections) {
-            const lines = section.split("\n");
-            const heading = lines[0]?.trim();
-            if (!heading)
-                continue;
-            const attrs = [];
-            for (const line of lines.slice(1)) {
-                const attrMatch = line.match(/^[-*]\s+\*?\*?(\w[\w\s]*)\*?\*?/);
-                if (attrMatch)
-                    attrs.push(attrMatch[1].trim());
-            }
+        for (const section of this.extractSections(content)) {
+            const attrs = section.bullets
+                .map((bullet) => bullet.replace(/\*\*/g, "").split(/[:—–-]/)[0]?.trim() ?? "")
+                .filter((attr) => /^[A-Za-z]/.test(attr));
             if (attrs.length > 0) {
-                entities.push({ name: heading, attributes: attrs });
+                entities.push({ name: section.heading, attributes: attrs });
             }
         }
         return entities;
     }
-    extractInterfaces(content) {
-        const interfaces = [];
-        const regex = /(?:interface|class|service|module)\s+(\w+)/gi;
+    /**
+     * Class/interface candidates for class and c4_code diagrams.
+     * 1. Explicit `interface X { ... }` / `class X { ... }` declarations (methods
+     *    read from the real body — never invented).
+     * 2. Real section names with methods derived from their bullet items.
+     * 3. Last resort: one class built from the artifact's opening words, so
+     *    different artifacts never collapse to an identical stub.
+     */
+    extractClassCandidates(content) {
+        const classes = [];
+        const seen = new Set();
+        const declRegex = /\b(interface|class)\s+([A-Za-z_]\w*)(?:\s*\{([^}]*)\})?/g;
         let match;
-        while ((match = regex.exec(content)) !== null) {
-            interfaces.push({ name: match[1], methods: ["execute", "validate", "process"] });
+        while ((match = declRegex.exec(content)) !== null) {
+            const kind = match[1].toLowerCase() === "interface" ? "interface" : "class";
+            const name = match[2];
+            const key = name.toLowerCase();
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            const methods = [];
+            if (match[3]) {
+                const methodRegex = /([A-Za-z_]\w*)\s*\(/g;
+                let methodMatch;
+                while ((methodMatch = methodRegex.exec(match[3])) !== null) {
+                    if (!methods.includes(methodMatch[1]))
+                        methods.push(methodMatch[1]);
+                }
+            }
+            classes.push({ name, methods, kind });
+        }
+        if (classes.length > 0)
+            return classes;
+        for (const section of this.extractSections(content)) {
+            const name = this.toPascalCase(section.heading);
+            const key = name.toLowerCase();
+            if (!name || seen.has(key))
+                continue;
+            seen.add(key);
+            const methods = section.bullets
+                .map((bullet) => this.toCamelCase((bullet.split(/[.:—–]/)[0] ?? bullet).substring(0, 40)))
+                .filter((method) => method.length > 1)
+                .slice(0, 5);
+            classes.push({ name, methods, kind: "class" });
+        }
+        if (classes.length > 0)
+            return classes;
+        const words = content
+            .replace(/[^A-Za-z0-9\s]/g, " ")
+            .trim()
+            .split(/\s+/)
+            .filter((word) => word.length > 2);
+        if (words.length > 0) {
+            classes.push({ name: this.toPascalCase(words.slice(0, 3).join(" ")), methods: [], kind: "class" });
         }
-        return interfaces;
+        return classes;
     }
     extractStates(content) {
         const states = [];
-        const regex = /\b(pending|active|processing|completed|failed|cancelled|approved|rejected|draft|published|archived)\b/gi;
+        const regex = /\b(pending|active|processing|completed|failed|cancelled|approved|rejected|draft|published|archived|created|submitted|shipped|delivered|expired|suspended)\b/gi;
         const seen = new Set();
         let match;
         while ((match = regex.exec(content)) !== null) {
@@ -579,7 +782,7 @@ export class DiagramGenerator {
                 states.push(state);
             }
         }
-        return states.length > 0 ? states : ["Pending", "Active", "Completed"];
+        return states;
     }
     extractSystems(content) {
         const systems = [];
@@ -592,16 +795,27 @@ export class DiagramGenerator {
     }
     extractComponents(content) {
         const components = [];
-        const regex = /^#{2,3}\s+(.+(?:Service|API|Gateway|Database|Cache|Queue|Worker|Engine|Manager|Controller))/gm;
+        const seen = new Set();
+        const push = (raw) => {
+            const name = this.cleanHeading(raw);
+            if (!name || this.isStructuralHeading(name))
+                return;
+            const key = name.toLowerCase();
+            if (seen.has(key))
+                return;
+            seen.add(key);
+            components.push(name);
+        };
+        const regex = /^#{2,3}\s+(.+(?:Service|API|Gateway|Database|Cache|Queue|Worker|Engine|Manager|Controller))\s*$/gm;
         let match;
         while ((match = regex.exec(content)) !== null) {
-            components.push(match[1].trim());
+            push(match[1]);
         }
         if (components.length === 0) {
-            // Fallback: extract from headings
+            // Fallback: extract from real (non-structural) headings
             const headingRegex = /^#{2,3}\s+(.+)/gm;
             while ((match = headingRegex.exec(content)) !== null) {
-                components.push(match[1].trim());
+                push(match[1]);
             }
         }
         return components;
@@ -624,23 +838,77 @@ export class DiagramGenerator {
         }
         return tasks;
     }
+    /**
+     * Real category counts for pie charts, tried in order:
+     * 1. Explicit EARS pattern tags, e.g. "(EVENT_DRIVEN)".
+     * 2. Classification of "shall" requirement sentences by EARS keyword.
+     * 3. REQ-ID prefixes (### REQ-XXX-NNN).
+     * 4. Section names weighted by their real bullet counts.
+     */
     extractCategories(content) {
-        const categories = new Map();
-        const regex = /### (REQ-([A-Z]+)-\d{3})/g;
+        const tagNames = {
+            UBIQUITOUS: "Ubiquitous",
+            EVENT_DRIVEN: "Event-Driven",
+            STATE_DRIVEN: "State-Driven",
+            OPTIONAL: "Optional",
+            UNWANTED: "Unwanted Behavior",
+            UNWANTED_BEHAVIOR: "Unwanted Behavior",
+            COMPLEX: "Complex",
+        };
+        const tagCounts = new Map();
+        const tagRegex = /\b(UBIQUITOUS|EVENT[_ ]DRIVEN|STATE[_ ]DRIVEN|OPTIONAL|UNWANTED(?:[_ ]BEHAVIOR)?|COMPLEX)\b/g;
         let match;
-        while ((match = regex.exec(content)) !== null) {
+        while ((match = tagRegex.exec(content)) !== null) {
+            const name = tagNames[match[1].replace(/\s+/g, "_")] ?? match[1];
+            tagCounts.set(name, (tagCounts.get(name) || 0) + 1);
+        }
+        if (tagCounts.size > 0) {
+            return Array.from(tagCounts.entries()).map(([name, count]) => ({ name, count }));
+        }
+        const earsCounts = new Map();
+        const sentences = content.split(/(?<=[.!?])\s+|\n+/);
+        for (const sentence of sentences) {
+            if (!/\bshall\b/i.test(sentence))
+                continue;
+            const trimmed = sentence.trim().toLowerCase();
+            let pattern = "Ubiquitous";
+            if (/^while\b/.test(trimmed))
+                pattern = "State-Driven";
+            else if (/^when\b/.test(trimmed))
+                pattern = "Event-Driven";
+            else if (/^where\b/.test(trimmed))
+                pattern = "Optional";
+            else if (/^if\b/.test(trimmed))
+                pattern = "Unwanted Behavior";
+            earsCounts.set(pattern, (earsCounts.get(pattern) || 0) + 1);
+        }
+        if (earsCounts.size > 0) {
+            return Array.from(earsCounts.entries()).map(([name, count]) => ({ name, count }));
+        }
+        const prefixCounts = new Map();
+        const reqRegex = /### (REQ-([A-Z]+)-\d{3})/g;
+        while ((match = reqRegex.exec(content)) !== null) {
             const cat = match[2];
-            categories.set(cat, (categories.get(cat) || 0) + 1);
+            prefixCounts.set(cat, (prefixCounts.get(cat) || 0) + 1);
         }
-        return Array.from(categories.entries()).map(([name, count]) => ({ name, count }));
+        if (prefixCounts.size > 0) {
+            return Array.from(prefixCounts.entries()).map(([name, count]) => ({ name, count }));
+        }
+        return this.extractSections(content)
+            .slice(0, 8)
+            .map((section) => ({ name: section.heading, count: Math.max(section.bullets.length, 1) }));
     }
     extractTopics(content) {
         const topics = [];
         const sections = content.split(/^##\s+/m).filter(Boolean);
         for (const section of sections) {
             const lines = section.split("\n");
-            const name = lines[0]?.trim();
-            if (!name)
+            const firstLine = lines[0]?.trim() ?? "";
+            // Skip the pre-heading chunk (document title/frontmatter before the first ##)
+            if (firstLine.startsWith("#"))
+                continue;
+            const name = this.cleanHeading(firstLine);
+            if (!name || this.isStructuralHeading(name))
                 continue;
             const subtopics = [];
             for (const line of lines.slice(1)) {
@@ -652,9 +920,128 @@ export class DiagramGenerator {
         }
         return topics;
     }
+    /**
+     * Real (non-structural) sections with their bullet items — the shared
+     * source-derived skeleton used by fallback paths.
+     */
+    extractSections(content) {
+        const sections = [];
+        let current = null;
+        for (const line of content.split("\n")) {
+            const headingMatch = line.match(/^#{2,4}\s+(.+)/);
+            if (headingMatch) {
+                const heading = this.cleanHeading(headingMatch[1]);
+                if (heading && !this.isStructuralHeading(heading)) {
+                    current = { heading, bullets: [] };
+                    sections.push(current);
+                }
+                else {
+                    current = null;
+                }
+                continue;
+            }
+            const bulletMatch = line.match(/^\s*[-*]\s+(.+)/);
+            if (bulletMatch && current) {
+                current.bullets.push(bulletMatch[1].trim());
+            }
+        }
+        return sections;
+    }
     // ─── Utility ───
     sanitize(text) {
-        return text.replace(/["\[\]{}()<>|]/g, "").replace(/\n/g, " ").trim().substring(0, 80);
+        return text.replace(/["'`\[\]{}()<>|*]/g, "").replace(/\n/g, " ").trim().substring(0, 80);
+    }
+    /** Text safe outside quotes (gantt names/sections, message-free positions). */
+    plainText(text) {
+        return this.sanitize(text).replace(/[:;,#]/g, " ").replace(/\s{2,}/g, " ").trim();
+    }
+    /** Sequence message text — keeps it on one line and free of ':' markers. */
+    messageText(text) {
+        const cleaned = this.sanitize(text).replace(/[:;]/g, " ").replace(/\s{2,}/g, " ").trim().substring(0, 60);
+        return cleaned || "Message";
+    }
+    /** Identifier containing only [A-Za-z0-9_], never starting with a digit. */
+    safeId(text, fallback) {
+        const cleaned = text
+            .replace(/[^A-Za-z0-9_]+/g, "_")
+            .replace(/_{2,}/g, "_")
+            .replace(/^_+|_+$/g, "")
+            .substring(0, 40)
+            .replace(/_+$/g, "");
+        if (!cleaned)
+            return fallback;
+        return /^[0-9]/.test(cleaned) ? `N${cleaned}` : cleaned;
+    }
+    uniqueId(base, used) {
+        let id = base;
+        let suffix = 2;
+        while (used.has(id)) {
+            id = `${base}_${suffix}`;
+            suffix++;
+        }
+        used.add(id);
+        return id;
+    }
+    cleanHeading(raw) {
+        return raw
+            .replace(/^\d+(?:\.\d+)*[.)]?\s+/, "")
+            .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1")
+            .replace(/[*_`]/g, "")
+            .trim();
+    }
+    toPascalCase(text) {
+        return text
+            .replace(/[^A-Za-z0-9]+/g, " ")
+            .trim()
+            .split(/\s+/)
+            .filter(Boolean)
+            .slice(0, 4)
+            .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+            .join("")
+            .substring(0, 40);
+    }
+    toCamelCase(text) {
+        const pascal = this.toPascalCase(text);
+        return pascal ? pascal.charAt(0).toLowerCase() + pascal.slice(1) : "";
+    }
+    isStructuralHeading(heading) {
+        return STRUCTURAL_HEADING_REGEX.test(heading.trim());
+    }
+    buildDiagramsMarkdown(featureNumber, diagrams) {
+        const sourceLabels = {
+            constitution: "CONSTITUTION.md",
+            spec: "SPECIFICATION.md",
+            design: "DESIGN.md",
+            tasks: "TASKS.md",
+        };
+        const grouped = new Map();
+        for (const diagram of diagrams) {
+            const group = grouped.get(diagram.source);
+            if (group) {
+                group.push(diagram);
+            }
+            else {
+                grouped.set(diagram.source, [diagram]);
+            }
+        }
+        const canonicalOrder = ["constitution", "spec", "design", "tasks"];
+        const sources = [
+            ...canonicalOrder.filter((source) => grouped.has(source)),
+            ...Array.from(grouped.keys()).filter((source) => !canonicalOrder.includes(source)),
+        ];
+        const lines = [
+            `# Diagrams — Feature ${featureNumber}`,
+            "",
+            `> Generated by \`sdd_generate_all_diagrams\` — ${diagrams.length} diagrams, grouped by source artifact.`,
+            "",
+        ];
+        for (const source of sources) {
+            lines.push(`## Source: ${sourceLabels[source] ?? source}`, "");
+            for (const diagram of grouped.get(source) ?? []) {
+                lines.push(`### ${diagram.title} (${diagram.type})`, "", "```mermaid", diagram.mermaid_code, "```", "");
+            }
+        }
+        return lines.join("\n");
     }
     async safeRead(_specDir, featureDir, fileName) {
         try {