airgen-cli 0.12.0 → 0.13.0

package/dist/commands/lint.js

@@ -4,6 +4,15 @@ import { isJsonMode } from "../output.js";
 // ── Constants ────────────────────────────────────────────────
 const PAGE_SIZE = 100;
 const MAX_PAGES = 50;
+// Well-known acronyms to skip in the undocumented acronym check
+const WELL_KNOWN_ACRONYMS = new Set([
+    "ISO", "IEEE", "HTTP", "HTTPS", "TCP", "UDP", "IP", "USB", "RAM", "ROM",
+    "CPU", "GPU", "API", "URL", "XML", "JSON", "HTML", "CSS", "SQL", "PDF",
+    "NATO", "MIL", "STD", "DOD", "FAA", "NIST", "ANSI", "IEC", "ASME",
+    "REQ", "ID", "OK", "NA", "TBD", "TBC", "NB", "HW", "SW", "FW",
+    "AC", "DC", "RF", "IR", "UV", "IO", "OS", "UI", "UX", "DB",
+    "EARS", "UHT", "MTBF", "MTTF", "MTTR", "SIL", "ASIL", "DAL",
+]);
 // ── Helpers ──────────────────────────────────────────────────
 async function fetchAllRequirements(client, tenant, project) {
     const all = [];
@@ -18,21 +27,74 @@ async function fetchAllRequirements(client, tenant, project) {
     }
     return all.filter(r => !r.deleted && !r.deletedAt);
 }
-/**
- * Extract domain concepts from requirement text.
- * Looks for:
- *  - Subjects: "The <concept> shall..."
- *  - References: "using the <concept>", "via the <concept>", "from the <concept>"
- *  - Named systems: multi-word capitalized terms, known patterns
- */
+async function fetchTraceLinks(client, tenant, project) {
+    try {
+        const data = await client.get(`/trace-links/${tenant}/${project}`);
+        return data.traceLinks ?? [];
+    }
+    catch {
+        return []; // Graceful fallback — trace-aware checks simply produce no findings
+    }
+}
+async function fetchDocumentTiers(client, tenant, project) {
+    try {
+        const data = await client.get(`/documents/${tenant}/${project}`);
+        const map = new Map();
+        for (const doc of data.documents ?? []) {
+            if (doc.shortCode)
+                map.set(doc.slug, doc.shortCode.toUpperCase());
+        }
+        return map;
+    }
+    catch {
+        return new Map();
+    }
+}
+function buildReqTierMap(requirements, docTierMap) {
+    const map = new Map();
+    for (const req of requirements) {
+        if (!req.ref)
+            continue;
+        if (req.documentSlug) {
+            const tier = docTierMap.get(req.documentSlug);
+            if (tier) {
+                map.set(req.ref, tier);
+                continue;
+            }
+        }
+        // Fallback: infer from ref prefix
+        const prefix = req.ref.split("-")[0]?.toUpperCase();
+        if (["STK", "SYS", "SUB", "IFC", "VER", "HAZ", "ARC"].includes(prefix)) {
+            map.set(req.ref, prefix);
+        }
+    }
+    return map;
+}
+async function parallelMap(items, fn, concurrency) {
+    const results = [];
+    let index = 0;
+    async function worker() {
+        while (index < items.length) {
+            const i = index++;
+            try {
+                results[i] = { item: items[i], result: await fn(items[i]) };
+            }
+            catch (err) {
+                results[i] = { item: items[i], error: err };
+            }
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, items.length) }, () => worker()));
+    return results;
+}
+// ── Concept Extraction ──────────────────────────────────────
 function extractConcepts(requirements) {
     const conceptRefs = new Map();
+    const skip = new Set(["system", "the system", "it", "this", "all", "each", "any", "user", "operator"]);
     function addConcept(concept, ref) {
         const normalized = concept.toLowerCase().trim();
         if (normalized.length < 3 || normalized.length > 60)
             return;
-        // Skip generic words
-        const skip = new Set(["system", "the system", "it", "this", "all", "each", "any"]);
         if (skip.has(normalized))
             return;
         const refs = conceptRefs.get(normalized) ?? [];
@@ -44,23 +106,39 @@ function extractConcepts(requirements) {
         if (!req.text || !req.ref)
             continue;
         const text = req.text;
-        // "The <concept> shall"
+        // Subject: "The <concept> shall"
         const subjectMatch = text.match(/^(?:the|a|an)\s+(.+?)\s+shall\b/i);
         if (subjectMatch)
             addConcept(subjectMatch[1], req.ref);
-        // "If the <concept> detects/is/has..."
+        // Conditional: "If the <concept> detects/is/has..."
         const ifMatch = text.match(/^if\s+the\s+(.+?)\s+(?:detects?|is|has|does|fails?|receives?)\b/i);
         if (ifMatch)
             addConcept(ifMatch[1], req.ref);
-        // "While the <concept> is..."
+        // Temporal: "While the <concept> is..."
         const whileMatch = text.match(/^while\s+(?:the\s+)?(.+?)\s+is\b/i);
         if (whileMatch)
             addConcept(whileMatch[1], req.ref);
-        // "When the <concept> designates/detects..."
-        const whenMatch = text.match(/^when\s+the\s+(.+?)\s+(?:designates?|detects?|receives?|completes?)\b/i);
+        // Temporal: "When the <concept> designates/detects..."
+        const whenMatch = text.match(/^when\s+the\s+(.+?)\s+(?:designates?|detects?|receives?|completes?|initiates?|enters?)\b/i);
         if (whenMatch)
             addConcept(whenMatch[1], req.ref);
-        // References: "using the X", "via X", "from the X", "to the X"
+        // Passive voice: "shall be provided/controlled/managed by X"
+        const passiveMatch = text.match(/shall\s+be\s+\w+(?:ed|en)\s+by\s+(?:the\s+)?(.+?)(?:\s+(?:for|to|at|in|with|when|if|unless)\b|[.,;]|$)/i);
+        if (passiveMatch)
+            addConcept(passiveMatch[1], req.ref);
+        // Object references: "shall transmit/receive X"
+        const objPatterns = [
+            /shall\s+(?:transmit|send|deliver|forward|relay|provide|output)\s+(?:the\s+)?(.+?)\s+to\s+(?:the\s+)?(.+?)(?:\s+(?:for|at|in|with)\b|[.,;]|$)/gi,
+            /shall\s+(?:receive|accept|collect|acquire|read)\s+(?:the\s+)?(.+?)\s+from\s+(?:the\s+)?(.+?)(?:\s+(?:for|at|in|with)\b|[.,;]|$)/gi,
+        ];
+        for (const pat of objPatterns) {
+            let m;
+            while ((m = pat.exec(text)) !== null) {
+                addConcept(m[1], req.ref);
+                addConcept(m[2], req.ref);
+            }
+        }
+        // Reference patterns: "using the X", "via X", "from the X", "to the X"
         const refPatterns = [
             /using\s+(?:the\s+)?(.+?)(?:\s+(?:for|to|at|in|with)\b|[.,;]|$)/gi,
             /via\s+(?:the\s+)?(.+?)(?:\s+(?:for|to|at|in|with)\b|[.,;]|$)/gi,
@@ -74,22 +152,36 @@ function extractConcepts(requirements) {
                 addConcept(m[1], req.ref);
             }
         }
+        // Compound nouns: multi-word capitalized terms (skip sentence starts)
+        const compoundPattern = /\b([A-Z][a-z]+(?:\s+[A-Z][a-z]+){1,4})\b/g;
+        let cm;
+        while ((cm = compoundPattern.exec(text)) !== null) {
+            const before = text.slice(0, cm.index);
+            if (before.length === 0 || /[.!?]\s*$/.test(before))
+                continue;
+            addConcept(cm[1], req.ref);
+        }
+        // Suffix references: "the X interface/module/subsystem"
+        const suffixPattern = /the\s+(.+?)\s+(interface|module|subsystem|component|unit|assembly|sensor|actuator|controller|processor|display|panel|bus|network|link)\b/gi;
+        let sm;
+        while ((sm = suffixPattern.exec(text)) !== null) {
+            addConcept(`${sm[1]} ${sm[2]}`, req.ref);
+        }
     }
     return conceptRefs;
 }
-/**
- * Rank concepts by frequency and pick top N.
- */
 function topConcepts(conceptRefs, maxCount) {
     return [...conceptRefs.entries()]
         .sort((a, b) => b[1].length - a[1].length)
         .slice(0, maxCount);
 }
 // ── Analysis ─────────────────────────────────────────────────
-function analyzeFindings(concepts, comparisons, requirements) {
+function analyzeFindings(concepts, comparisons, requirements, traceLinks, reqTierMap, conceptRefs, options) {
     const findings = [];
     const conceptMap = new Map(concepts.map(c => [c.name, c]));
-    // 1. Physical mismatch: non-physical concepts with environmental/physical requirements
+    // Helper: get requirement texts for a concept
+    const reqTextsFor = (c) => c.reqs.map(ref => requirements.find(r => r.ref === ref)?.text ?? "").join(" ");
+    // ── 1a. Physical mismatch (existing) ──────────────────────
     const envKeywords = /temperature|shock|vibrat|humidity|nbc|contamina|electromagnetic|emc|climatic/i;
     for (const c of concepts) {
         if (c.isPhysical)
@@ -103,18 +195,120 @@ function analyzeFindings(concepts, comparisons, requirements) {
                 severity: "high",
                 category: "Ontological Mismatch",
                 title: `"${c.name}" lacks Physical Object trait but has physical constraints`,
-                description: `UHT classifies "${c.name}" (${c.hexCode}) without the Physical Object trait, but ${envReqs.length} requirement(s) impose physical/environmental constraints on it.`,
+                description: `UHT classifies "${c.name}" (${c.hexCode}) without Physical Object, but ${envReqs.length} requirement(s) impose environmental constraints.`,
                 affectedReqs: envReqs,
-                recommendation: `Add a requirement defining the physical embodiment of "${c.name}" (e.g., housing, LRU, equipment rack).`,
+                recommendation: `Add a requirement defining the physical embodiment of "${c.name}" (housing, LRU, equipment rack).`,
+            });
+        }
+    }
+    // ── 1b. Powered without power budget ──────────────────────
+    const powerKeywords = /power|voltage|current|battery|watt|energy|consumption|supply|mains|generator/i;
+    for (const c of concepts) {
+        if (!c.isPowered)
+            continue;
+        const allText = reqTextsFor(c);
+        if (!powerKeywords.test(allText)) {
+            findings.push({
+                severity: "high",
+                category: "Ontological Mismatch",
+                title: `"${c.name}" is Powered but no requirements specify power source or budget`,
+                description: `UHT classifies "${c.name}" (${c.hexCode}) with Powered trait, but no requirements mention power supply, voltage, current, or energy budget.`,
+                affectedReqs: c.reqs,
+                recommendation: `Add power source, voltage range, and consumption requirements for "${c.name}".`,
+            });
+        }
+    }
+    // ── 1c. Autonomous without safety constraints ─────────────
+    const safetyKeywords = /safety|watchdog|override|kill.?switch|emergency.?stop|fail.?safe|interlock|manual.?override|human.?in.?the.?loop/i;
+    for (const c of concepts) {
+        if (!c.isAutonomous)
+            continue;
+        const allText = reqTextsFor(c);
+        if (!safetyKeywords.test(allText)) {
+            findings.push({
+                severity: "high",
+                category: "Ontological Mismatch",
+                title: `"${c.name}" is Functionally Autonomous but has no safety constraints`,
+                description: `UHT classifies "${c.name}" (${c.hexCode}) as autonomous, but no requirements specify safety constraints, watchdog, override, or emergency stop.`,
+                affectedReqs: c.reqs,
+                recommendation: `Add safety requirements: override mechanism, watchdog timer, fail-safe state, or human-in-the-loop constraints for "${c.name}".`,
+            });
+        }
+    }
+    // ── 1d. Human-Interactive without usability ────────────────
+    const usabilityKeywords = /hmi|display|ergonomic|response.?time|feedback|indicator|user.?interface|touch|screen|readab|legib|contrast|font|icon/i;
+    for (const c of concepts) {
+        if (!c.isHumanInteractive)
+            continue;
+        const allText = reqTextsFor(c);
+        if (!usabilityKeywords.test(allText)) {
+            findings.push({
+                severity: "medium",
+                category: "Ontological Mismatch",
+                title: `"${c.name}" is Human-Interactive but has no usability requirements`,
+                description: `UHT classifies "${c.name}" (${c.hexCode}) as human-interactive, but no requirements address HMI, display, ergonomics, or user feedback.`,
+                affectedReqs: c.reqs,
+                recommendation: `Add usability requirements: display format, response time, ergonomic constraints, or feedback indicators for "${c.name}".`,
+            });
+        }
+    }
+    // ── 1e. Digital/Virtual without cybersecurity ──────────────
+    const cyberKeywords = /security|authenticat|encrypt|access.?control|authoriz|cyber|firewall|certificate|tls|ssl|password|credential|privilege/i;
+    for (const c of concepts) {
+        if (!c.isDigitalVirtual)
+            continue;
+        const allText = reqTextsFor(c);
+        if (!cyberKeywords.test(allText)) {
+            findings.push({
+                severity: "medium",
+                category: "Ontological Mismatch",
+                title: `"${c.name}" is Digital/Virtual but has no cybersecurity requirements`,
+                description: `UHT classifies "${c.name}" (${c.hexCode}) as digital/virtual, but no requirements address security, authentication, encryption, or access control.`,
+                affectedReqs: c.reqs,
+                recommendation: `Add cybersecurity requirements: authentication, encryption, access control, or data protection for "${c.name}".`,
+            });
+        }
+    }
+    // ── 1f. Regulated without compliance ──────────────────────
+    const complianceKeywords = /standard|compliance|certif|approv|regulat|accredit|qualif|homologat|type.?approv|conformance|audit/i;
+    for (const c of concepts) {
+        if (!c.isRegulated)
+            continue;
+        const allText = reqTextsFor(c);
+        if (!complianceKeywords.test(allText)) {
+            findings.push({
+                severity: "medium",
+                category: "Ontological Mismatch",
+                title: `"${c.name}" is Regulated but has no compliance requirements`,
+                description: `UHT classifies "${c.name}" (${c.hexCode}) as regulated, but no requirements reference standards, certification, or compliance.`,
+                affectedReqs: c.reqs,
+                recommendation: `Add compliance requirements: applicable standards, certification authority, or qualification criteria for "${c.name}".`,
+            });
+        }
+    }
+    // ── 1g. System-Essential without redundancy ────────────────
+    const redundancyKeywords = /redundan|failover|backup|graceful.?degrad|hot.?standby|cold.?standby|replicate|fault.?toleran|availability|\d+\s*%.*uptime|single.?point.?of.?failure/i;
+    for (const c of concepts) {
+        if (!c.isSystemEssential)
+            continue;
+        const allText = reqTextsFor(c);
+        if (!redundancyKeywords.test(allText)) {
+            findings.push({
+                severity: "medium",
+                category: "Ontological Mismatch",
+                title: `"${c.name}" is System-Essential but has no redundancy requirements`,
+                description: `UHT classifies "${c.name}" (${c.hexCode}) as system-essential, but no requirements address redundancy, failover, or fault tolerance.`,
+                affectedReqs: c.reqs,
+                recommendation: `Add redundancy or availability requirements: failover mechanism, backup, or graceful degradation for "${c.name}".`,
             });
         }
     }
-    // 2. Abstract metrics without statistical parameters
+    // ── 2. Abstract metrics without statistical parameters ────
     const metricKeywords = /probability|rate|percentage|ratio|mtbf|availability/i;
     const statKeywords = /confidence|sample size|number of|minimum of \d+ |statistical/i;
     for (const c of concepts) {
         if (c.traits.length > 3)
-            continue; // very abstract = few traits
+            continue;
         const metricReqs = c.reqs.filter(ref => {
             const req = requirements.find(r => r.ref === ref);
             return req?.text && metricKeywords.test(req.text);
@@ -130,13 +324,13 @@ function analyzeFindings(concepts, comparisons, requirements) {
                 severity: "medium",
                 category: "Missing Statistical Context",
                 title: `"${c.name}" is an abstract metric without statistical parameters`,
-                description: `"${c.name}" (${c.hexCode}) has only ${c.traits.length} UHT traits (very abstract). Requirements set thresholds but don't specify confidence level, sample size, or test conditions.`,
+                description: `"${c.name}" (${c.hexCode}) has only ${c.traits.length} UHT traits. Requirements set thresholds but don't specify confidence level, sample size, or test conditions.`,
                 affectedReqs: metricReqs,
                 recommendation: `Add statistical parameters (confidence level, sample size, conditions) to requirements referencing "${c.name}".`,
             });
         }
     }
-    // 3. Verification requirements mixed with functional requirements
+    // ── 3. Verification/functional mixing ─────────────────────
     const verificationReqs = requirements.filter(r => r.text && /shall be verified|verification|shall be demonstrated|shall be tested/i.test(r.text));
     const functionalReqs = requirements.filter(r => r.text && /shall\b/i.test(r.text) && !/shall be verified|verification/i.test(r.text));
     if (verificationReqs.length > 0 && functionalReqs.length > 0) {
@@ -146,69 +340,190 @@ function analyzeFindings(concepts, comparisons, requirements) {
                 severity: "medium",
                 category: "Structural Issue",
                 title: "Verification requirements mixed with functional requirements",
-                description: `${verificationReqs.length} verification requirement(s) (${(ratio * 100).toFixed(0)}%) are co-mingled with ${functionalReqs.length} functional requirements. This makes traceability harder.`,
+                description: `${verificationReqs.length} verification requirement(s) (${(ratio * 100).toFixed(0)}%) are co-mingled with ${functionalReqs.length} functional requirements.`,
                 affectedReqs: verificationReqs.map(r => r.ref).filter(Boolean),
-                recommendation: "Move verification requirements to a separate document or tag them with a distinct pattern. Create trace links to parent functional requirements.",
+                recommendation: "Move verification requirements to a separate document or tag them with a distinct pattern.",
             });
         }
     }
-    // 4. Degraded mode gaps: requirements mentioning "manual", "reversion", "fallback" without performance criteria
+    // ── 4. Degraded mode gaps ─────────────────────────────────
     const degradedReqs = requirements.filter(r => r.text && /manual\s+(?:reversion|mode|override|backup)|fallback|degraded/i.test(r.text));
-    // Numeric performance patterns: "10 Hz", "3.6m", "250 ms", "95%", "< 5 seconds", ">= 99.9%",
-    // "within 100ms", "at least 10", units with numbers, ranges like "5-10"
     const perfPattern = /\d+\.?\d*\s*(?:%|Hz|kHz|MHz|s\b|ms\b|sec|second|minute|min\b|hour|hr|m\b|km|cm|mm|m\/s|km\/h|mph|kph|dB|dBm|°C|°F|K\b|V\b|A\b|W\b|kW|MW|N\b|kN|Pa|kPa|MPa|bar|psi|kg|g\b|lb|fps|bps|Mbps|Gbps)|(?:within|under|below|above|at least|no (?:more|less) than|maximum|minimum)\s+\d|\d+\s*(?:to|-)\s*\d/i;
     for (const req of degradedReqs) {
-        const hasPerf = perfPattern.test(req.text ?? "");
-        if (!hasPerf) {
+        if (!perfPattern.test(req.text ?? "")) {
             findings.push({
                 severity: "medium",
                 category: "Coverage Gap",
                 title: `Degraded mode without performance criteria: ${req.ref}`,
-                description: `${req.ref} specifies a degraded/manual mode but provides no measurable acceptance criteria for performance in that mode.`,
+                description: `${req.ref} specifies a degraded/manual mode but provides no measurable acceptance criteria.`,
                 affectedReqs: [req.ref],
-                recommendation: "Add measurable performance criteria for degraded operation (e.g., acceptable accuracy, response time, available subsystems).",
+                recommendation: "Add measurable performance criteria for degraded operation.",
             });
         }
     }
-    // 5. Cross-comparison: high similarity between concepts in different categories
+    // ── 5. Cross-concept ambiguity ────────────────────────────
     for (const batch of comparisons) {
         for (const comp of batch.comparisons) {
             const a = conceptMap.get(batch.entity);
             const b = conceptMap.get(comp.candidate);
             if (!a || !b)
                 continue;
-            // Different physical classification but high similarity = potential confusion
-            if (comp.jaccard_similarity > 0.6 && a.isPhysical !== b.isPhysical) {
+            if (comp.jaccard_similarity > options.jaccardThreshold && a.isPhysical !== b.isPhysical) {
                 findings.push({
                     severity: "low",
                     category: "Ontological Ambiguity",
-                    title: `"${a.name}" and "${b.name}" are similar (${(comp.jaccard_similarity * 100).toFixed(0)}%) but differ in physical classification`,
-                    description: `"${a.name}" is ${a.isPhysical ? "" : "not "}a Physical Object; "${b.name}" is ${b.isPhysical ? "" : "not "}. High Jaccard similarity (${comp.jaccard_similarity.toFixed(3)}) suggests they should be treated consistently.`,
+                    title: `"${a.name}" and "${b.name}" similar (${(comp.jaccard_similarity * 100).toFixed(0)}%) but differ in physical classification`,
+                    description: `"${a.name}" is ${a.isPhysical ? "" : "not "}Physical Object; "${b.name}" is ${b.isPhysical ? "" : "not "}. High Jaccard similarity suggests they should be treated consistently.`,
                     affectedReqs: [...a.reqs, ...b.reqs],
-                    recommendation: `Review whether both concepts should have consistent physical classification. Consider adding clarifying requirements.`,
+                    recommendation: "Review whether both concepts should have consistent physical classification.",
                 });
             }
         }
     }
-    // 6. Requirements without "shall" (weak language)
+    // ── 6. Weak language (no "shall") ─────────────────────────
     const weakReqs = requirements.filter(r => r.text && !/\bshall\b/i.test(r.text) && !/shall be verified/i.test(r.text));
     if (weakReqs.length > 0) {
         findings.push({
             severity: "low",
             category: "Language Quality",
             title: `${weakReqs.length} requirement(s) lack "shall" keyword`,
-            description: `Requirements without "shall" may be informational text rather than testable requirements.`,
+            description: "Requirements without \"shall\" may be informational text rather than testable requirements.",
             affectedReqs: weakReqs.map(r => r.ref).filter(Boolean),
-            recommendation: 'Rephrase using "shall" for testable requirements, or move informational text to notes/rationale.',
+            recommendation: "Rephrase using \"shall\" for testable requirements, or move informational text to notes/rationale.",
         });
     }
+    // ── 7. Spray pattern: mass links without rationale ────────
+    if (traceLinks.length > 0) {
+        const outgoing = new Map();
+        for (const link of traceLinks) {
+            const src = link.sourceRef ?? link.sourceRequirementId ?? "";
+            if (!outgoing.has(src))
+                outgoing.set(src, []);
+            outgoing.get(src).push(link);
+        }
+        for (const [reqRef, links] of outgoing) {
+            if (links.length > options.sprayThreshold) {
+                const hasAnyRationale = links.some(l => l.rationale && l.rationale.trim().length > 0);
+                if (!hasAnyRationale) {
+                    findings.push({
+                        severity: "high",
+                        category: "Trace Quality",
+                        title: `Spray pattern: ${reqRef} has ${links.length} outgoing links with no rationale`,
+                        description: `${reqRef} has ${links.length} outgoing trace links, none with engineering rationale. This suggests mechanical linking.`,
+                        affectedReqs: [reqRef],
+                        recommendation: `Review trace links from ${reqRef}. Add rationale to justified links and remove spurious ones.`,
+                    });
+                }
+            }
+        }
+    }
+    // ── 8. Concept coverage gaps across document tiers ────────
+    if (reqTierMap.size > 0 && conceptRefs.size > 0) {
+        const tiersPresent = new Set(reqTierMap.values());
+        for (const [concept, refs] of conceptRefs) {
+            const tiers = new Set();
+            for (const ref of refs) {
+                const tier = reqTierMap.get(ref);
+                if (tier)
+                    tiers.add(tier);
+            }
+            if (tiers.has("STK") && !tiers.has("SYS") && !tiers.has("SUB") && tiersPresent.has("SYS")) {
+                findings.push({
+                    severity: "medium",
+                    category: "Coverage Gap",
+                    title: `Concept "${concept}" in STK but not in SYS or SUB`,
+                    description: `"${concept}" is referenced in stakeholder requirements but has no corresponding system or subsystem requirements.`,
+                    affectedReqs: refs.filter(r => reqTierMap.get(r) === "STK"),
+                    recommendation: `Create system-level requirements addressing "${concept}" to ensure stakeholder intent flows down.`,
+                });
+            }
+            if (tiers.has("SYS") && !tiers.has("SUB") && tiers.size === 1 && tiersPresent.has("SUB")) {
+                findings.push({
+                    severity: "medium",
+                    category: "Coverage Gap",
+                    title: `Concept "${concept}" in SYS but not in SUB`,
+                    description: `"${concept}" is referenced in system requirements but has no corresponding subsystem requirements.`,
+                    affectedReqs: refs.filter(r => reqTierMap.get(r) === "SYS"),
+                    recommendation: `Create subsystem requirements decomposing "${concept}" for implementation traceability.`,
+                });
+            }
+        }
+    }
+    // ── 9. Contradictory requirements on same concept ─────────
+    const numericExtract = /(?:shall\s+(?:not\s+)?(?:exceed|be (?:less|greater|more|fewer) than|be (?:at least|at most|no more than|no less than)))\s+(\d+(?:\.\d+)?)/i;
+    const negPattern = /shall\s+not\b/i;
+    for (const c of concepts) {
+        if (c.reqs.length < 2)
+            continue;
+        const withNums = [];
+        for (const ref of c.reqs) {
+            const req = requirements.find(r => r.ref === ref);
+            if (!req?.text)
+                continue;
+            const nm = req.text.match(numericExtract);
+            if (nm)
+                withNums.push({ ref, value: parseFloat(nm[1]), negated: negPattern.test(req.text) });
+        }
+        for (let i = 0; i < withNums.length; i++) {
+            for (let j = i + 1; j < withNums.length; j++) {
+                const a = withNums[i], b = withNums[j];
+                if (a.negated !== b.negated) {
+                    const pos = a.negated ? b : a;
+                    const neg = a.negated ? a : b;
+                    if (neg.value < pos.value) {
+                        findings.push({
+                            severity: "medium",
+                            category: "Contradiction",
+                            title: `Contradictory thresholds on "${c.name}": ${pos.ref} vs ${neg.ref}`,
+                            description: `${pos.ref} requires exceeding ${pos.value} but ${neg.ref} caps at ${neg.value} (lower).`,
+                            affectedReqs: [pos.ref, neg.ref],
+                            recommendation: `Reconcile conflicting thresholds for "${c.name}".`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    // ── 10. Undocumented acronyms ─────────────────────────────
+    const acronymPattern = /\b([A-Z]{2,})\b/g;
+    const allText = requirements.map(r => `${r.text ?? ""} ${r.rationale ?? ""}`).join(" ");
+    const allAcronyms = new Map();
+    for (const req of requirements) {
+        if (!req.text || !req.ref)
+            continue;
+        let m;
+        while ((m = acronymPattern.exec(req.text)) !== null) {
+            const acr = m[1];
+            if (WELL_KNOWN_ACRONYMS.has(acr))
+                continue;
+            if (!allAcronyms.has(acr))
+                allAcronyms.set(acr, []);
+            const refs = allAcronyms.get(acr);
+            if (!refs.includes(req.ref))
+                refs.push(req.ref);
+        }
+    }
+    for (const [acr, refs] of allAcronyms) {
+        // Check for expansion: "Full Name (ACR)" or "ACR (Full Name)"
+        const defPat = new RegExp(`[A-Za-z][a-z]+(?:\\s+[A-Za-z][a-z]+)*\\s*\\(${acr}\\)|${acr}\\s*\\([A-Za-z][a-z]+(?:\\s+[A-Za-z][a-z]+)*\\)`, "i");
+        if (!defPat.test(allText)) {
+            findings.push({
+                severity: "low",
+                category: "Documentation Quality",
+                title: `Acronym "${acr}" used but never defined`,
+                description: `"${acr}" appears in ${refs.length} requirement(s) but no expansion was found.`,
+                affectedReqs: refs.slice(0, 10),
+                recommendation: `Define "${acr}" on first use or in a glossary document.`,
+            });
+        }
+    }
     return findings.sort((a, b) => {
         const sev = { high: 0, medium: 1, low: 2 };
         return sev[a.severity] - sev[b.severity];
     });
 }
 // ── Report formatting ────────────────────────────────────────
-function formatReport(tenant, project, requirements, concepts, comparisons, findings) {
+function formatReport(tenant, project, requirements, traceLinks, concepts, comparisons, findings) {
     const lines = [];
     const high = findings.filter(f => f.severity === "high").length;
     const med = findings.filter(f => f.severity === "medium").length;
@@ -216,17 +531,16 @@ function formatReport(tenant, project, requirements, concepts, comparisons, find
     lines.push("  Semantic Lint Report");
     lines.push("  ════════════════════");
     lines.push(`  Project: ${project} (${tenant})`);
-    lines.push(`  Requirements: ${requirements.length} | Concepts classified: ${concepts.length}`);
+    lines.push(`  Requirements: ${requirements.length} | Trace links: ${traceLinks.length} | Concepts: ${concepts.length}`);
     lines.push(`  Findings: ${findings.length} (${high} high, ${med} medium, ${low} low)`);
     lines.push("");
-    // Concept classifications table
+    // Concept classifications
     lines.push("  ┄┄ Concept Classifications ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄");
     lines.push("");
     const nameW = Math.max(...concepts.map(c => c.name.length), 10);
     for (const c of concepts) {
-        const phys = c.isPhysical ? "Physical" : "Abstract";
         const pad = " ".repeat(Math.max(0, nameW - c.name.length));
-        lines.push(`    ${c.name}${pad}  ${c.hexCode}  ${phys.padEnd(8)}  ${c.traits.slice(0, 4).join(", ")}${c.traits.length > 4 ? "..." : ""}`);
+        lines.push(`    ${c.name}${pad}  ${c.hexCode}  ${c.traits.slice(0, 5).join(", ")}${c.traits.length > 5 ? "..." : ""}`);
     }
     lines.push("");
     // Cross-comparison highlights
@@ -236,8 +550,7 @@ function formatReport(tenant, project, requirements, concepts, comparisons, find
         for (const batch of comparisons) {
             for (const comp of batch.comparisons) {
                 if (comp.jaccard_similarity >= 0.4) {
-                    const pct = (comp.jaccard_similarity * 100).toFixed(0);
-                    lines.push(`    ${batch.entity} ↔ ${comp.candidate}: ${pct}% Jaccard`);
+                    lines.push(`    ${batch.entity} ↔ ${comp.candidate}: ${(comp.jaccard_similarity * 100).toFixed(0)}% Jaccard`);
                 }
             }
         }
@@ -262,25 +575,23 @@ function formatReport(tenant, project, requirements, concepts, comparisons, find
     }
     return lines.join("\n");
 }
-function formatMarkdown(tenant, project, requirements, concepts, comparisons, findings) {
+function formatMarkdown(tenant, project, requirements, traceLinks, concepts, comparisons, findings) {
     const lines = [];
     const high = findings.filter(f => f.severity === "high").length;
     const med = findings.filter(f => f.severity === "medium").length;
     const low = findings.filter(f => f.severity === "low").length;
     lines.push("## Semantic Lint Report");
     lines.push(`**Project:** ${project} (\`${tenant}\`)  `);
-    lines.push(`**Requirements:** ${requirements.length} | **Concepts classified:** ${concepts.length}  `);
+    lines.push(`**Requirements:** ${requirements.length} | **Trace links:** ${traceLinks.length} | **Concepts:** ${concepts.length}  `);
     lines.push(`**Findings:** ${findings.length} (${high} high, ${med} medium, ${low} low)`);
     lines.push("");
-    // Concept table
     lines.push("### Concept Classifications");
-    lines.push("| Concept | UHT Code | Physical? | Key Traits |");
-    lines.push("|---|---|---|---|");
+    lines.push("| Concept | UHT Code | Key Traits |");
+    lines.push("|---|---|---|");
     for (const c of concepts) {
-        lines.push(`| ${c.name} | \`${c.hexCode}\` | ${c.isPhysical ? "Yes" : "No"} | ${c.traits.slice(0, 4).join(", ")} |`);
+        lines.push(`| ${c.name} | \`${c.hexCode}\` | ${c.traits.slice(0, 5).join(", ")} |`);
     }
     lines.push("");
-    // Similarities
     if (comparisons.length > 0) {
         lines.push("### Key Similarities");
         lines.push("| Pair | Jaccard |");
@@ -294,7 +605,6 @@ function formatMarkdown(tenant, project, requirements, concepts, comparisons, fi
         }
         lines.push("");
     }
-    // Findings
     lines.push("### Findings");
     lines.push("| # | Severity | Title | Affected |");
     lines.push("|---|---|---|---|");
@@ -317,7 +627,7 @@ function formatMarkdown(tenant, project, requirements, concepts, comparisons, fi
 export function registerLintCommands(program, client) {
     program
         .command("lint")
-        .description("Semantic requirements lint — classifies domain concepts via UHT and flags ontological issues")
+        .description("Semantic requirements lint — classifies concepts via UHT, checks trait consistency, analyzes trace quality")
         .argument("<tenant>", "Tenant slug")
         .argument("<project>", "Project slug")
         .option("--concepts <n>", "Max concepts to classify", "15")
@@ -326,6 +636,8 @@ export function registerLintCommands(program, client) {
         .option("--suppress <titles...>", "Suppress findings by title substring (repeatable)")
         .option("--baseline <file>", "Suppress findings listed in a baseline file (one title per line)")
         .option("--save-baseline <file>", "Write current finding titles to a baseline file for future suppression")
+        .option("--threshold <n>", "Jaccard similarity threshold (0.0-1.0)", "0.6")
+        .option("--spray-threshold <n>", "Outgoing trace link count for spray pattern detection", "8")
         .action(async (tenant, project, opts) => {
         const uht = new UhtClient();
         if (!uht.isConfigured) {
@@ -334,44 +646,59 @@ export function registerLintCommands(program, client) {
             process.exit(1);
         }
         const maxConcepts = parseInt(opts.concepts, 10) || 15;
-        // Step 1: Fetch all requirements
-        console.error("Fetching requirements...");
-        const requirements = await fetchAllRequirements(client, tenant, project);
+        const jaccardThreshold = parseFloat(opts.threshold) || 0.6;
+        const sprayThreshold = parseInt(opts.sprayThreshold, 10) || 8;
+        // Step 1: Fetch requirements, trace links, and documents in parallel
+        console.error("Fetching project data...");
+        const [requirements, traceLinks, docTierMap] = await Promise.all([
+            fetchAllRequirements(client, tenant, project),
+            fetchTraceLinks(client, tenant, project),
+            fetchDocumentTiers(client, tenant, project),
+        ]);
         if (requirements.length === 0) {
             console.error("No requirements found.");
             process.exit(1);
         }
-        console.error(`  ${requirements.length} requirements loaded.`);
+        const reqTierMap = buildReqTierMap(requirements, docTierMap);
+        console.error(`  ${requirements.length} requirements, ${traceLinks.length} trace links, ${docTierMap.size} documents loaded.`);
         // Step 2: Extract domain concepts
         console.error("Extracting domain concepts...");
         const conceptRefs = extractConcepts(requirements);
         const top = topConcepts(conceptRefs, maxConcepts);
         console.error(`  ${conceptRefs.size} unique concepts found, classifying top ${top.length}.`);
-        // Step 3: Classify each concept via UHT
+        // Step 3: Classify concepts via UHT (parallelized)
         console.error("Classifying concepts via UHT...");
+        const classifyResults = await parallelMap(top, async ([name]) => uht.classify(name), 5);
         const concepts = [];
-        for (const [name, refs] of top) {
-            try {
-                const result = await uht.classify(name);
-                const traitNames = result.traits.map(t => t.name).filter(Boolean);
+        for (let i = 0; i < classifyResults.length; i++) {
+            const entry = classifyResults[i];
+            const [name, refs] = top[i];
+            if (entry.result) {
+                const traitNames = entry.result.traits.map(t => t.name).filter(Boolean);
+                const has = (t) => traitNames.includes(t);
                 concepts.push({
                     name,
-                    hexCode: result.hex_code,
-                    isPhysical: traitNames.includes("Physical Object"),
+                    hexCode: entry.result.hex_code,
                     traits: traitNames,
+                    isPhysical: has("Physical Object"),
+                    isPowered: has("Powered"),
+                    isHumanInteractive: has("Human-Interactive"),
+                    isAutonomous: has("Functionally Autonomous"),
+                    isSystemEssential: has("System-Essential"),
+                    isDigitalVirtual: has("Digital/Virtual"),
+                    isRegulated: has("Regulated"),
                     reqs: refs,
                 });
-                console.error(`  ✓ ${name} → ${result.hex_code} (${traitNames.length} traits)`);
+                console.error(`  ✓ ${name} → ${entry.result.hex_code} (${traitNames.length} traits)`);
             }
-            catch (err) {
-                console.error(`  ✗ ${name}: ${err.message}`);
+            else if (entry.error) {
+                console.error(`  ✗ ${name}: ${entry.error.message}`);
             }
         }
         // Step 4: Cross-compare concepts in batches
         console.error("Cross-comparing concepts...");
         const comparisons = [];
         if (concepts.length >= 2) {
-            // Compare top concept against others, then second against rest
             const names = concepts.map(c => c.name);
             const batchSize = Math.min(names.length - 1, 15);
             try {
@@ -397,8 +724,8 @@ export function registerLintCommands(program, client) {
         }
         // Step 5: Analyze findings
         console.error("Analyzing...");
-        let findings = analyzeFindings(concepts, comparisons, requirements);
-        // Step 5b: Save baseline if requested (before suppression)
+        let findings = analyzeFindings(concepts, comparisons, requirements, traceLinks, reqTierMap, conceptRefs, { sprayThreshold, jaccardThreshold });
+        // Step 5b: Save baseline (before suppression)
         if (opts.saveBaseline) {
             const titles = findings.map(f => f.title);
             writeFileSync(opts.saveBaseline, titles.join("\n") + "\n", "utf-8");
@@ -408,28 +735,30 @@ export function registerLintCommands(program, client) {
         const suppressions = [...(opts.suppress ?? [])];
         if (opts.baseline && existsSync(opts.baseline)) {
             const baselineContent = readFileSync(opts.baseline, "utf-8");
-            const baselineLines = baselineContent.split("\n").map(l => l.trim()).filter(Boolean);
-            suppressions.push(...baselineLines);
+            suppressions.push(...baselineContent.split("\n").map(l => l.trim()).filter(Boolean));
         }
         if (suppressions.length > 0) {
             const before = findings.length;
             findings = findings.filter(f => !suppressions.some(s => f.title.includes(s)));
             const suppressed = before - findings.length;
-            if (suppressed > 0) {
+            if (suppressed > 0)
                 console.error(`Suppressed ${suppressed} known finding(s).`);
-            }
         }
         // Step 6: Output report
         let report;
         if (opts.format === "json" || isJsonMode()) {
-            const data = { tenant, project, requirements: requirements.length, concepts, comparisons, findings };
-            report = JSON.stringify(data, null, 2);
+            report = JSON.stringify({
+                tenant, project,
+                requirements: requirements.length,
+                traceLinks: traceLinks.length,
+                concepts, comparisons, findings,
+            }, null, 2);
         }
         else if (opts.format === "markdown") {
-            report = formatMarkdown(tenant, project, requirements, concepts, comparisons, findings);
+            report = formatMarkdown(tenant, project, requirements, traceLinks, concepts, comparisons, findings);
         }
         else {
-            report = formatReport(tenant, project, requirements, concepts, comparisons, findings);
+            report = formatReport(tenant, project, requirements, traceLinks, concepts, comparisons, findings);
         }
         if (opts.output) {
             writeFileSync(opts.output, report + "\n", "utf-8");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "airgen-cli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "AIRGen CLI — requirements engineering from the command line",
   "type": "module",
   "main": "dist/index.js",