airgen-cli 0.15.0 → 0.17.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,5 +1,5 @@
 import { readFileSync, writeFileSync, existsSync } from "node:fs";
-import { UhtClient } from "../uht-client.js";
+import { UhtClient, decodeHexTraits } from "../uht-client.js";
 import { isJsonMode } from "../output.js";
 const TRAIT_CHECKS = [
     // Physical Layer (1-8)
@@ -693,6 +693,7 @@ export function registerLintCommands(program, client) {
         .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")
         .option("--min-severity <level>", "Only show findings at this severity or above: low, medium, high", "low")
+        .option("--substrate-namespace <ns>", "Use existing Substrate entity classifications instead of re-classifying (e.g. SE, SE:naval)")
         .action(async (tenant, project, opts) => {
         const uht = new UhtClient();
         if (!uht.isConfigured) {
@@ -721,26 +722,69 @@ export function registerLintCommands(program, client) {
         const conceptRefs = extractConcepts(requirements);
         const top = topConcepts(conceptRefs, maxConcepts);
         console.error(`  ${conceptRefs.size} unique concepts found, classifying top ${top.length}.`);
-        // Step 3: Classify concepts via UHT (parallelized)
-        console.error("Classifying concepts via UHT...");
-        const classifyResults = await parallelMap(top, async ([name]) => uht.classify(name), 5);
+        // Step 3: Classify concepts — use Substrate namespace if provided, else fresh classify
+        const ns = opts.substrateNamespace;
+        console.error(ns
+            ? `Looking up concepts in Substrate namespace "${ns}"...`
+            : "Classifying concepts via UHT...");
         const concepts = [];
-        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);
-                concepts.push({
-                    name,
-                    hexCode: entry.result.hex_code,
-                    traits: traitNames,
-                    traitSet: new Set(traitNames),
-                    reqs: refs,
-                });
-                console.error(`  ✓ ${name} → ${entry.result.hex_code} (${traitNames.length} traits)`);
+        if (ns) {
+            // Namespace mode: look up pre-classified entities
+            const lookupResults = await parallelMap(top, async ([name]) => uht.lookupEntity(name, ns), 5);
+            for (let i = 0; i < lookupResults.length; i++) {
+                const [name, refs] = top[i];
+                const entity = lookupResults[i].result;
+                if (entity) {
+                    const traitNames = decodeHexTraits(entity.hex_code);
+                    concepts.push({
+                        name: entity.name, // Use canonical name from Substrate
+                        hexCode: entity.hex_code,
+                        traits: traitNames,
+                        traitSet: new Set(traitNames),
+                        reqs: refs,
+                    });
+                    console.error(`  ✓ ${name} → ${entity.name} (${entity.hex_code}, ${traitNames.length} traits)`);
+                }
+                else {
+                    // Fall back to fresh classification
+                    try {
+                        const result = await uht.classify(name);
+                        const traitNames = result.traits.map(t => t.name).filter(Boolean);
+                        concepts.push({
+                            name,
+                            hexCode: result.hex_code,
+                            traits: traitNames,
+                            traitSet: new Set(traitNames),
+                            reqs: refs,
+                        });
+                        console.error(`  ~ ${name} → ${result.hex_code} (${traitNames.length} traits, not in namespace — classified fresh)`);
+                    }
+                    catch (err) {
+                        console.error(`  ✗ ${name}: ${err.message}`);
+                    }
+                }
             }
-            else if (entry.error) {
-                console.error(`  ✗ ${name}: ${entry.error.message}`);
+        }
+        else {
+            // Fresh classification mode (original behavior)
+            const classifyResults = await parallelMap(top, async ([name]) => uht.classify(name), 5);
+            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);
+                    concepts.push({
+                        name,
+                        hexCode: entry.result.hex_code,
+                        traits: traitNames,
+                        traitSet: new Set(traitNames),
+                        reqs: refs,
+                    });
+                    console.error(`  ✓ ${name} → ${entry.result.hex_code} (${traitNames.length} traits)`);
+                }
+                else if (entry.error) {
+                    console.error(`  ✗ ${name}: ${entry.error.message}`);
+                }
             }
         }
         // Step 4: Cross-compare concepts in batches

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/dist/uht-client.d.ts

@@ -4,6 +4,8 @@
  * Talks to the UHT Substrate factory API for entity classification and comparison.
  * Token resolution: UHT_TOKEN env → UHT_API_KEY env → ~/.config/uht-substrate/config.json
  */
+/** Decode an 8-char hex code into trait names by reading the 32-bit field. */
+export declare function decodeHexTraits(hexCode: string): string[];
 export interface UhtClassification {
     entity: string;
     hex_code: string;
@@ -12,6 +14,13 @@ export interface UhtClassification {
         justification: string;
     }>;
 }
+export interface UhtEntityRecord {
+    uuid: string;
+    name: string;
+    hex_code: string;
+    description: string | null;
+    source: string;
+}
 export interface UhtComparison {
     candidate: string;
     hex_code: string;
@@ -42,4 +51,6 @@ export declare class UhtClient {
     private request;
     classify(entity: string): Promise<UhtClassification>;
     batchCompare(entity: string, candidates: string[]): Promise<UhtBatchResult>;
+    /** Look up an entity by name in a Substrate namespace. Returns null if not found. */
+    lookupEntity(name: string, namespace: string): Promise<UhtEntityRecord | null>;
 }

package/dist/uht-client.js

@@ -8,6 +8,30 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 const DEFAULT_UHT_URL = "https://substrate.universalhex.org/api";
+// All 32 UHT v2 canonical trait names, indexed by bit position (1-based)
+const TRAIT_NAMES = {
+    1: "Physical Object", 2: "Synthetic", 3: "Biological/Biomimetic", 4: "Powered",
+    5: "Structural", 6: "Observable", 7: "Physical Medium", 8: "Active",
+    9: "Intentionally Designed", 10: "Outputs Effect", 11: "Processes Signals/Logic", 12: "State-Transforming",
+    13: "Human-Interactive", 14: "System-integrated", 15: "Functionally Autonomous", 16: "System-Essential",
+    17: "Symbolic", 18: "Signalling", 19: "Rule-governed", 20: "Compositional",
+    21: "Normative", 22: "Meta", 23: "Temporal", 24: "Digital/Virtual",
+    25: "Social Construct", 26: "Institutionally Defined", 27: "Identity-Linked", 28: "Regulated",
+    29: "Economically Significant", 30: "Politicised", 31: "Ritualised", 32: "Ethically Significant",
+};
+/** Decode an 8-char hex code into trait names by reading the 32-bit field. */
+export function decodeHexTraits(hexCode) {
+    const binary = parseInt(hexCode, 16).toString(2).padStart(32, "0");
+    const traits = [];
+    for (let i = 0; i < 32; i++) {
+        if (binary[i] === "1") {
+            const name = TRAIT_NAMES[i + 1];
+            if (name)
+                traits.push(name);
+        }
+    }
+    return traits;
+}
 function loadUhtConfigToken() {
     try {
         const configPath = join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "uht-substrate", "config.json");
@@ -52,4 +76,11 @@ export class UhtClient {
     async batchCompare(entity, candidates) {
         return this.request("POST", "/batch-compare", { entity, candidates });
     }
+    /** Look up an entity by name in a Substrate namespace. Returns null if not found. */
+    async lookupEntity(name, namespace) {
+        const data = await this.request("GET", `/entities?namespace=${encodeURIComponent(namespace)}&name=${encodeURIComponent(name)}&limit=10`);
+        // Prefer exact match (case-insensitive), fall back to first result
+        const exact = data.entities.find(e => e.name.toLowerCase() === name.toLowerCase());
+        return exact ?? data.entities[0] ?? null;
+    }
 }

package/package.json

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