airgen-cli 0.14.0 → 0.16.0

package/dist/commands/diagrams.js

@@ -225,9 +225,13 @@ export function registerDiagramCommands(program, client) {
         .description("List all diagrams in a project")
         .argument("<tenant>", "Tenant slug")
         .argument("<project>", "Project slug")
-        .action(async (tenant, project) => {
+        .option("--name <name>", "Filter by exact name match")
+        .action(async (tenant, project, opts) => {
         const data = await client.get(`/architecture/diagrams/${tenant}/${project}`);
-        const diagrams = data.diagrams ?? [];
+        let diagrams = data.diagrams ?? [];
+        if (opts.name) {
+            diagrams = diagrams.filter(d => d.name === opts.name);
+        }
         if (isJsonMode()) {
             output(diagrams);
         }
@@ -283,7 +287,11 @@ export function registerDiagramCommands(program, client) {
         if (opts.format === "mermaid") {
             rendered = renderMermaid(blocks, connectors, opts.direction);
             if (opts.clean) {
-                rendered = rendered.split("\n").filter(l => !l.trim().startsWith("classDef ") && !l.trim().startsWith("class ") && !l.trim().startsWith("style ")).join("\n");
+                rendered = rendered
+                    .split("\n")
+                    .filter(l => !l.trim().startsWith("classDef ") && !l.trim().startsWith("class ") && !l.trim().startsWith("style "))
+                    .map(l => l.replace(/<<[^>]+>><br\/>/g, "")) // Strip <<stereotype>><br/> from node labels
+                    .join("\n");
             }
             if (isJsonMode()) {
                 output({ mermaid: rendered, blocks: blocks.length, connectors: connectors.length });

package/dist/commands/lint.js

@@ -1,6 +1,140 @@
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
 import { UhtClient } from "../uht-client.js";
 import { isJsonMode } from "../output.js";
+const TRAIT_CHECKS = [
+    // Physical Layer (1-8)
+    { trait: "Physical Object", bit: 1, severity: "high", inverted: true,
+        missingWhat: "physical embodiment",
+        keywords: /temperature|shock|vibrat|humidity|nbc|contamina|electromagnetic|emc|climatic/i,
+        recommendation: "Add a requirement defining the physical embodiment (housing, LRU, equipment rack)." },
+    { trait: "Synthetic", bit: 2, severity: "medium",
+        missingWhat: "manufacturing/material requirements",
+        keywords: /manufactur|assembl|tolerance|material|fabricat|finish|coating|process|mach[iu]n/i,
+        recommendation: "Add manufacturing, material, or assembly requirements." },
+    { trait: "Biological/Biomimetic", bit: 3, severity: "high",
+        missingWhat: "biocompatibility/sterilization requirements",
+        keywords: /biocompat|steril|cytotox|implant|tissue|ISO.?10993|clean.?room|contaminat|biolog/i,
+        recommendation: "Add biocompatibility, sterilization, or biological safety requirements." },
+    { trait: "Powered", bit: 4, severity: "high",
+        missingWhat: "power source/budget requirements",
+        keywords: /power|voltage|current|battery|watt|energy|consumption|supply|mains|generator/i,
+        recommendation: "Add power source, voltage range, and consumption requirements." },
+    { trait: "Structural", bit: 5, severity: "medium",
+        missingWhat: "structural integrity requirements",
+        keywords: /load|stress|fatigue|deform|yield|strength|FEA|resonan|torque|buckling|stiffness/i,
+        recommendation: "Add load-bearing, stress, or fatigue requirements." },
+    { trait: "Observable", bit: 6, severity: "low",
+        missingWhat: "monitoring/diagnostics requirements",
+        keywords: /monitor|diagnos|instrument|telemetry|log|alert|BIT|health|status|indicator/i,
+        recommendation: "Add monitoring, diagnostics, or built-in-test requirements." },
+    { trait: "Physical Medium", bit: 7, severity: "medium",
+        missingWhat: "material property requirements",
+        keywords: /material|density|viscosity|thermal.?conduct|corrosion|wear|hardness|porosity/i,
+        recommendation: "Add material property, corrosion, or wear requirements." },
+    { trait: "Active", bit: 8, severity: "medium",
+        missingWhat: "stimulus-response/timing requirements",
+        keywords: /response.?time|latency|react|trigger|within.*(?:ms|second)|timeout|watchdog|stimul/i,
+        recommendation: "Add response time, latency, or stimulus-response requirements." },
+    // Functional Layer (9-16)
+    { trait: "Intentionally Designed", bit: 9, severity: "low",
+        missingWhat: "verification/validation method",
+        keywords: /verif|validat|test|inspect|review|acceptance|qualif|demonstrat/i,
+        recommendation: "Specify a verification or validation method." },
+    { trait: "Outputs Effect", bit: 10, severity: "medium",
+        missingWhat: "output specification",
+        keywords: /output|emit|produce|generate|signal|transmit|radiat|illuminate|actuate/i,
+        recommendation: "Add output specification requirements (signal type, range, accuracy)." },
+    { trait: "Processes Signals/Logic", bit: 11, severity: "medium",
+        missingWhat: "I/O format/protocol requirements",
+        keywords: /protocol|format|interface|data|message|bus|bandwidth|encoding|API|input.*output/i,
+        recommendation: "Add data format, protocol, or interface requirements." },
+    { trait: "State-Transforming", bit: 12, severity: "medium",
+        missingWhat: "state machine/mode transition requirements",
+        keywords: /state|mode|transition|startup|shutdown|initializ|reset|idle|standby|operat.*mode/i,
+        recommendation: "Add state machine, mode transition, or initialization requirements." },
+    { trait: "Human-Interactive", bit: 13, severity: "medium",
+        missingWhat: "usability/HMI requirements",
+        keywords: /HMI|display|ergonomic|response.?time|feedback|indicator|touch|screen|readab|legib/i,
+        recommendation: "Add usability, HMI, or human factors requirements." },
+    { trait: "System-integrated", bit: 14, severity: "medium",
+        missingWhat: "interface/integration requirements",
+        keywords: /interface|integrat|compatible|interoperab|plug|connector|harness|mount|install/i,
+        recommendation: "Add interface, integration, or interoperability requirements." },
+    { trait: "Functionally Autonomous", bit: 15, severity: "high",
+        missingWhat: "safety/override constraints",
+        keywords: /safety|watchdog|override|kill.?switch|emergency.?stop|fail.?safe|interlock|manual.?override|human.?in.?the.?loop/i,
+        recommendation: "Add safety constraints: override mechanism, watchdog, fail-safe state, or human-in-the-loop." },
+    { trait: "System-Essential", bit: 16, severity: "medium",
+        missingWhat: "redundancy/failover requirements",
+        keywords: /redundan|failover|backup|graceful.?degrad|fault.?toleran|availability|single.?point.?of.?failure|hot.?standby/i,
+        recommendation: "Add redundancy, failover, or fault tolerance requirements." },
+    // Abstract Layer (17-24)
+    { trait: "Symbolic", bit: 17, severity: "low",
+        missingWhat: "representation fidelity requirements",
+        keywords: /accuracy|fidelity|resolution|precision|representation|model|symbol|semantic/i,
+        recommendation: "Add representation accuracy, fidelity, or resolution requirements." },
+    { trait: "Signalling", bit: 18, severity: "medium",
+        missingWhat: "signal integrity/protocol requirements",
+        keywords: /protocol|bandwidth|latency|throughput|packet|frame|bit.?rate|SNR|jitter|signal/i,
+        recommendation: "Add signal protocol, bandwidth, or integrity requirements." },
+    { trait: "Rule-governed", bit: 19, severity: "low",
+        missingWhat: "algorithm/logic validation requirements",
+        keywords: /algorithm|logic|rule|protocol|compliance|valid|verify|formal|deterministic/i,
+        recommendation: "Add algorithm validation or formal verification requirements." },
+    { trait: "Compositional", bit: 20, severity: "low",
+        missingWhat: "modularity/interface requirements",
+        keywords: /module|layer|component|partition|encapsulat|abstraction|API|decompos|architect/i,
+        recommendation: "Add modularity, decomposition, or internal interface requirements." },
+    { trait: "Normative", bit: 21, severity: "medium",
+        missingWhat: "constraint validation requirements",
+        keywords: /constraint|rule|limit|bound|threshold|policy|enforce|comply|govern/i,
+        recommendation: "Add constraint enforcement or policy compliance requirements." },
+    { trait: "Meta", bit: 22, severity: "low",
+        missingWhat: "configuration/metadata requirements",
+        keywords: /config|metadata|schema|version|self.?test|self.?diagnos|introspect|calibrat/i,
+        recommendation: "Add configuration management, versioning, or self-test requirements." },
+    { trait: "Temporal", bit: 23, severity: "medium",
+        missingWhat: "timing/scheduling requirements",
+        keywords: /timing|sequence|schedul|deadline|period|interval|cycle|synchron|clock|real.?time/i,
+        recommendation: "Add timing, scheduling, or real-time requirements." },
+    { trait: "Digital/Virtual", bit: 24, severity: "medium",
+        missingWhat: "cybersecurity requirements",
+        keywords: /security|authenticat|encrypt|access.?control|authoriz|cyber|firewall|TLS|SSL|certificate/i,
+        recommendation: "Add cybersecurity, authentication, or encryption requirements." },
+    // Social Layer (25-32)
+    { trait: "Social Construct", bit: 25, severity: "low",
+        missingWhat: "stakeholder/user requirements",
+        keywords: /stakeholder|user|role|persona|scenario|use.?case|workflow|actor/i,
+        recommendation: "Add stakeholder, user role, or use case requirements." },
+    { trait: "Institutionally Defined", bit: 26, severity: "medium",
+        missingWhat: "standard/specification references",
+        keywords: /standard|specification|definition|classif|categor|nomenclature|taxonomy|MIL.?STD|DEF.?STAN/i,
+        recommendation: "Add references to applicable standards or specifications." },
+    { trait: "Identity-Linked", bit: 27, severity: "low",
+        missingWhat: "access control/identity requirements",
+        keywords: /role|identity|credential|permission|access|privilege|authenticat|authoriz/i,
+        recommendation: "Add access control, role-based, or identity management requirements." },
+    { trait: "Regulated", bit: 28, severity: "medium",
+        missingWhat: "compliance/certification requirements",
+        keywords: /standard|compliance|certif|approv|regulat|accredit|qualif|homologat|type.?approv/i,
+        recommendation: "Add compliance, certification, or regulatory approval requirements." },
+    { trait: "Economically Significant", bit: 29, severity: "low",
+        missingWhat: "cost/lifecycle requirements",
+        keywords: /cost|budget|price|procurement|COTS|lifecycle|maintenance|obsolescence|sustainab/i,
+        recommendation: "Add cost, lifecycle, or obsolescence management requirements." },
+    { trait: "Politicised", bit: 30, severity: "low",
+        missingWhat: "export control/classification requirements",
+        keywords: /export.?control|ITAR|EAR|classification|restricted|controlled|clearance|secret|classified/i,
+        recommendation: "Add export control, security classification, or handling requirements." },
+    { trait: "Ritualised", bit: 31, severity: "low",
+        missingWhat: "procedure/protocol requirements",
+        keywords: /procedure|protocol|ceremony|ritual|formal|checklist|handover|commissioning/i,
+        recommendation: "Add procedural, commissioning, or handover requirements." },
+    { trait: "Ethically Significant", bit: 32, severity: "medium",
+        missingWhat: "ethical/safety requirements",
+        keywords: /ethical|moral|harm|consent|privacy|bias|proportional|rules.?of.?engagement|collateral/i,
+        recommendation: "Add ethical, proportionality, or rules-of-engagement requirements." },
+];
 // ── Constants ────────────────────────────────────────────────
 const PAGE_SIZE = 100;
 const MAX_PAGES = 50;
@@ -179,128 +313,46 @@ function topConcepts(conceptRefs, maxCount) {
 function analyzeFindings(concepts, comparisons, requirements, traceLinks, reqTierMap, conceptRefs, options) {
     const findings = [];
     const conceptMap = new Map(concepts.map(c => [c.name, c]));
-    // Helper: get requirement texts for a concept
+    // Helper: get all requirement text for a concept (joined)
     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)
-            continue;
-        const envReqs = c.reqs.filter(ref => {
-            const req = requirements.find(r => r.ref === ref);
-            return req?.text && envKeywords.test(req.text);
-        });
-        if (envReqs.length > 0) {
-            findings.push({
-                severity: "high",
-                category: "Ontological Mismatch",
-                title: `"${c.name}" lacks Physical Object trait but has physical constraints`,
-                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}" (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}".`,
-            });
+    // ── UHT Trait Checks (all 32 traits, data-driven) ─────────
+    for (const check of TRAIT_CHECKS) {
+        for (const c of concepts) {
+            if (check.inverted) {
+                // Inverted check (Physical Object): fires when trait ABSENT but keywords PRESENT
+                if (c.traitSet.has(check.trait))
+                    continue;
+                const matchingReqs = c.reqs.filter(ref => {
+                    const req = requirements.find(r => r.ref === ref);
+                    return req?.text && check.keywords.test(req.text);
+                });
+                if (matchingReqs.length > 0) {
+                    findings.push({
+                        severity: check.severity,
+                        category: "Ontological Mismatch",
+                        title: `"${c.name}" lacks ${check.trait} trait but has ${check.missingWhat}`,
+                        description: `UHT classifies "${c.name}" (${c.hexCode}) without ${check.trait}, but ${matchingReqs.length} requirement(s) impose related constraints.`,
+                        affectedReqs: matchingReqs,
+                        recommendation: check.recommendation,
+                    });
+                }
+            }
+            else {
+                // Standard check: fires when trait PRESENT but keywords ABSENT
+                if (!c.traitSet.has(check.trait))
+                    continue;
+                const allText = reqTextsFor(c);
+                if (!check.keywords.test(allText)) {
+                    findings.push({
+                        severity: check.severity,
+                        category: "Ontological Mismatch",
+                        title: `"${c.name}" is ${check.trait} but has no ${check.missingWhat}`,
+                        description: `UHT classifies "${c.name}" (${c.hexCode}) with ${check.trait} (bit ${check.bit}), but no requirements address this.`,
+                        affectedReqs: c.reqs,
+                        recommendation: check.recommendation,
+                    });
+                }
+            }
         }
     }
     // ── 2. Abstract metrics without statistical parameters ────
@@ -368,12 +420,14 @@ function analyzeFindings(concepts, comparisons, requirements, traceLinks, reqTie
             const b = conceptMap.get(comp.candidate);
             if (!a || !b)
                 continue;
-            if (comp.jaccard_similarity > options.jaccardThreshold && a.isPhysical !== b.isPhysical) {
+            const aPhys = a.traitSet.has("Physical Object");
+            const bPhys = b.traitSet.has("Physical Object");
+            if (comp.jaccard_similarity > options.jaccardThreshold && aPhys !== bPhys) {
                 findings.push({
                     severity: "low",
                     category: "Ontological Ambiguity",
-                    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.`,
+                    title: `"${a.name}" and "${b.name}" similar (${(comp.jaccard_similarity * 100).toFixed(0)}%) but differ in Physical Object trait`,
+                    description: `"${a.name}" is ${aPhys ? "" : "not "}Physical Object; "${b.name}" is ${bPhys ? "" : "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.",
                 });
@@ -676,18 +730,11 @@ export function registerLintCommands(program, client) {
             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: 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"),
+                    traitSet: new Set(traitNames),
                     reqs: refs,
                 });
                 console.error(`  ✓ ${name} → ${entry.result.hex_code} (${traitNames.length} traits)`);

package/dist/commands/requirements.js

@@ -14,7 +14,29 @@ export function registerRequirementCommands(program, client) {
         .option("--order <dir>", "Sort order: asc, desc")
         .option("--tags <tags>", "Comma-separated tags to filter by (server-side)")
         .option("--document <slug>", "Filter by document slug (server-side)")
+        .option("--homeless", "Show only requirements not assigned to any document")
         .action(async (tenant, project, opts) => {
+        // Handle --homeless: fetch all and filter to unassigned
+        if (opts.homeless) {
+            const all = [];
+            for (let page = 1; page <= 50; page++) {
+                const data = await client.get(`/requirements/${tenant}/${project}`, { page: String(page), limit: "500" });
+                all.push(...(data.data ?? []));
+                if (page >= (data.meta?.totalPages ?? 1))
+                    break;
+            }
+            const homeless = all.filter(r => !r.documentSlug);
+            if (isJsonMode()) {
+                output({ data: homeless, meta: { totalItems: homeless.length } });
+            }
+            else {
+                console.log(`Homeless requirements (no document): ${homeless.length}/${all.length}\n`);
+                if (homeless.length > 0) {
+                    printTable(["Ref", "Text", "QA"], homeless.map(r => [r.ref ?? "?", truncate(r.text ?? "", 65), r.qaScore != null ? String(r.qaScore) : "-"]));
+                }
+            }
+            return;
+        }
         // Handle --limit all: fetch all pages
         if (opts.limit.toLowerCase() === "all") {
             const all = [];
@@ -116,6 +138,10 @@ export function registerRequirementCommands(program, client) {
         .option("--tags <tags>", "Comma-separated tags")
         .option("--idempotency-key <key>", "Prevent duplicates on retry — returns existing if key was already used")
         .action(async (tenant, projectKey, opts) => {
+        if (!opts.section && !opts.document) {
+            console.error("Warning: No --section or --document specified. Requirement will be project-level with a generic ref (e.g., REQ-PROJECTNAME-001).");
+            console.error("         Use --section <id> to assign to a document section for proper ref prefixing.");
+        }
         const data = await client.post("/requirements", {
             tenant,
             projectKey,

package/dist/commands/verify.js

@@ -268,31 +268,61 @@ export function registerVerifyCommands(program, client) {
     // ── Engine ─────────────────────────────────────────────
     cmd
         .command("run")
-        .description("Run the verification engine — check for gaps, conflicts, and drift")
+        .description("Run the verification engine — checks both verification activities and 'verifies' trace links")
         .argument("<tenant>", "Tenant slug")
         .argument("<project>", "Project slug")
         .action(async (tenant, project) => {
-        const data = await client.get(`/verification/engine/${tenant}/${project}`);
-        const report = data.report;
+        // Fetch engine report (activities-based) and trace links in parallel
+        const [engineData, linkData, reqData] = await Promise.all([
+            client.get(`/verification/engine/${tenant}/${project}`).catch(() => ({ report: null })),
+            client.get(`/trace-links/${tenant}/${project}`).catch(() => ({ traceLinks: [] })),
+            client.get(`/requirements/${tenant}/${project}`, { page: "1", limit: "1" }).catch(() => ({ meta: { totalItems: 0 } })),
+        ]);
+        const report = engineData.report;
+        const totalReqs = reqData.meta?.totalItems ?? 0;
+        // Compute trace-link-based coverage (requirements targeted by 'verifies' links)
+        const verifiedByLinks = new Set();
+        for (const link of linkData.traceLinks ?? []) {
+            if (link.linkType === "verifies" && link.targetRequirementId) {
+                verifiedByLinks.add(link.targetRequirementId);
+            }
+        }
+        const traceCoverage = totalReqs > 0 ? Math.round((verifiedByLinks.size / totalReqs) * 100) : 0;
         if (isJsonMode()) {
-            output(report);
+            output({
+                activities: report,
+                traceLinkCoverage: {
+                    totalRequirements: totalReqs,
+                    verifiedByTraceLinks: verifiedByLinks.size,
+                    coveragePercent: traceCoverage,
+                },
+            });
             return;
         }
-        const s = report.summary;
-        console.log(`Verification Report\n`);
-        console.log(`Coverage: ${s.coveragePercent}%  (${s.verified}/${s.totalRequirements} verified)`);
-        console.log(`Unverified: ${s.unverified}  |  Incomplete: ${s.incomplete}  |  Drifted: ${s.driftedEvidence}\n`);
-        if (report.findings.length === 0) {
-            console.log("No findings. All clear.");
+        console.log("Verification Report\n");
+        // Trace link coverage (most common approach)
+        console.log(`Trace Link Coverage: ${traceCoverage}%  (${verifiedByLinks.size}/${totalReqs} have 'verifies' links)`);
+        // Activities coverage (formal V&V workflow)
+        if (report) {
+            const s = report.summary;
+            console.log(`Activity Coverage:   ${s.coveragePercent}%  (${s.verified}/${s.totalRequirements} have verification activities)`);
+            console.log(`  Unverified: ${s.unverified}  |  Incomplete: ${s.incomplete}  |  Drifted: ${s.driftedEvidence}`);
+            if (report.findings.length > 0) {
+                console.log(`\nFindings (${report.findings.length}):`);
+                printTable(["Severity", "Type", "Req", "Message"], report.findings.map(f => [
+                    severityIcon(f.severity) + " " + f.severity,
+                    f.type,
+                    f.requirementRef ?? "",
+                    truncate(f.message, 60),
+                ]));
+            }
         }
         else {
-            printTable(["Severity", "Type", "Req", "Message"], report.findings.map(f => [
-                severityIcon(f.severity) + " " + f.severity,
-                f.type,
-                f.requirementRef ?? "",
-                truncate(f.message, 60),
-            ]));
-            console.log(`\n${report.findings.length} finding(s) total.`);
+            console.log("Activity Coverage:   N/A (no verification activities configured)");
+        }
+        if (traceCoverage === 0 && (!report || report.summary.coveragePercent === 0)) {
+            console.log("\nTip: Create 'verifies' trace links from VER requirements to SYS/SUB requirements,");
+            console.log("or set up verification activities via 'airgen verify activities create'.");
         }
     });
     // ── Matrix ─────────────────────────────────────────────

package/package.json

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