airgen-cli 0.1.7 → 0.2.0

package/README.md

@@ -0,0 +1,261 @@
+# airgen-cli
+
+Requirements engineering from the command line. Manage requirements, architecture diagrams, traceability, baselines, and more — all from your terminal.
+
+Pairs with [AIRGen Studio](https://airgen.studio) and the AIRGen MCP server.
+
+## Install
+
+```bash
+npm install -g airgen-cli
+```
+
+## Configuration
+
+Set credentials via environment variables or `~/.airgenrc`:
+
+```bash
+# Environment variables
+export AIRGEN_API_URL=https://api.airgen.studio/api
+export AIRGEN_EMAIL=you@example.com
+export AIRGEN_PASSWORD=your-password
+```
+
+Or create `~/.airgenrc`:
+
+```json
+{
+  "apiUrl": "https://api.airgen.studio/api",
+  "email": "you@example.com",
+  "password": "your-password"
+}
+```
+
+For semantic linting, also set a UHT token:
+
+```bash
+export UHT_API_KEY=your-token    # or UHT_TOKEN
+```
+
+## Quick start
+
+```bash
+# List your tenants and projects
+airgen tenants list
+airgen projects list my-tenant
+
+# List requirements
+airgen reqs list my-tenant my-project
+
+# Render a diagram in the terminal
+airgen diag list my-tenant my-project
+airgen diag render my-tenant my-project diagram-123
+
+# Run semantic lint
+airgen lint my-tenant my-project
+
+# Get a compliance report
+airgen report compliance my-tenant my-project
+```
+
+## Global options
+
+| Flag | Description |
+|---|---|
+| `--json` | Output as JSON (works with any command) |
+| `-V, --version` | Print version |
+| `-h, --help` | Show help |
+
+## Commands
+
+### Tenants & Projects
+
+```bash
+airgen tenants list                          # List all tenants
+airgen projects list <tenant>                # List projects in a tenant
+airgen projects create <tenant> --name "X"   # Create a project
+airgen projects delete <tenant> <project>    # Delete a project
+```
+
+### Requirements
+
+```bash
+airgen reqs list <tenant> <project>                    # List (paginated)
+airgen reqs list <tenant> <project> --page 2 --limit 50
+airgen reqs get <tenant> <project> <ref>               # Full detail
+airgen reqs create <tenant> <project> --text "The system shall..."
+airgen reqs update <tenant> <project> <id> --text "..." --tags safety,critical
+airgen reqs delete <tenant> <project> <id>             # Soft-delete
+airgen reqs history <tenant> <project> <id>            # Version history
+airgen reqs search <tenant> <project> --query "thermal" --mode semantic
+airgen reqs filter <tenant> <project> --pattern functional --tag safety
+```
+
+### Architecture Diagrams
+
+```bash
+airgen diag list <tenant> <project>                    # List diagrams
+airgen diag get <tenant> <project> <id>                # Blocks + connectors JSON
+airgen diag render <tenant> <project> <id>             # Terminal display (default)
+airgen diag render <tenant> <project> <id> --format mermaid  # Mermaid syntax
+airgen diag render <tenant> <project> <id> --format mermaid --wrap -o diagram.md
+airgen diag create <tenant> <project> --name "X" --view block
+airgen diag update <tenant> <project> <id> --name "Y"
+airgen diag delete <tenant> <project> <id>
+```
+
+**Blocks:**
+
+```bash
+airgen diag blocks library <tenant> <project>
+airgen diag blocks create <tenant> <project> --diagram <id> --name "X" --kind subsystem
+airgen diag blocks delete <tenant> <project> <block-id>
+```
+
+**Connectors:**
+
+```bash
+airgen diag conn create <tenant> <project> --diagram <id> --source <id> --target <id> --kind flow --label "data"
+airgen diag conn delete <tenant> <project> <conn-id> --diagram <id>
+```
+
+### Traceability
+
+```bash
+airgen trace list <tenant> <project>                   # List trace links
+airgen trace create <tenant> <project> --source <id> --target <id> --type derives
+airgen trace delete <tenant> <project> <link-id>
+airgen trace linksets list <tenant> <project>          # Document linksets
+```
+
+### Baselines
+
+```bash
+airgen bl list <tenant> <project>
+airgen bl create <tenant> <project> --name "v1.0"
+airgen bl compare <tenant> <project> --from <id1> --to <id2>
+```
+
+### Quality & AI
+
+```bash
+airgen qa analyze "The system shall..."               # Analyze single requirement
+airgen qa score start <tenant> <project>               # Background QA scoring
+airgen qa draft "user needs thermal imaging"           # Draft requirements from NL
+
+airgen ai generate <tenant> <project> --prompt "..."   # Generate candidates
+airgen ai candidates <tenant> <project>                # List pending candidates
+airgen ai accept <candidate-id>                        # Promote to requirement
+airgen ai reject <candidate-id>                        # Reject candidate
+```
+
+### Reports
+
+```bash
+airgen report stats <tenant> <project>                 # Overview statistics
+airgen report quality <tenant> <project>               # QA score summary
+airgen report compliance <tenant> <project>            # Compliance + impl status
+airgen report orphans <tenant> <project>               # Untraced requirements
+```
+
+All report commands auto-paginate through the full requirement set (up to 5000).
+
+### Implementation Tracking
+
+```bash
+airgen impl status <tenant> <project> <req> --status implemented --notes "done in v2"
+airgen impl summary <tenant> <project>                 # Coverage breakdown
+airgen impl list <tenant> <project> --status blocked   # Filter by status
+airgen impl bulk-update <tenant> <project> --file updates.json
+
+# Artifact linking
+airgen impl link <tenant> <project> <req> --type file --path src/engine.ts
+airgen impl unlink <tenant> <project> <req> --artifact <id>
+```
+
+**Statuses:** `not_started`, `in_progress`, `implemented`, `verified`, `blocked`
+
+**Bulk update file format:**
+
+```json
+[
+  { "ref": "REQ-001", "status": "implemented", "notes": "shipped" },
+  { "ref": "REQ-002", "status": "in_progress" }
+]
+```
+
+### Import / Export
+
+```bash
+airgen import requirements <tenant> <project> --file reqs.csv
+airgen export requirements <tenant> <project>          # Markdown
+airgen export requirements <tenant> <project> --json   # JSON
+```
+
+### Activity
+
+```bash
+airgen activity list <tenant> <project>                # Recent activity
+airgen activity list <tenant> <project> --limit 50
+```
+
+### Documents
+
+```bash
+airgen docs list <tenant> <project>
+airgen docs get <tenant> <project> <slug>
+airgen docs create <tenant> <project> --title "X" --kind structured
+airgen docs delete <tenant> <project> <slug>
+airgen docs export <tenant> <project> <slug>           # Markdown export
+airgen docs sec list <tenant> <project> <slug>         # List sections
+```
+
+### Semantic Lint
+
+Classifies domain concepts from your requirements using the [Universal Hex Taxonomy](https://universalhex.org) and flags ontological issues, structural problems, and coverage gaps.
+
+```bash
+airgen lint <tenant> <project>                         # Full lint (top 15 concepts)
+airgen lint <tenant> <project> --concepts 20           # Classify more concepts
+airgen lint <tenant> <project> --format markdown -o lint-report.md
+airgen lint <tenant> <project> --format json           # Machine-readable
+```
+
+**What it detects:**
+
+- Ontological mismatches (e.g., non-physical entity with physical constraints)
+- Abstract metrics missing statistical parameters
+- Verification requirements mixed with functional requirements
+- Degraded modes without performance criteria
+- Ontological ambiguity between similar concepts
+- Requirements lacking "shall" keyword
+
+**Requires:** `UHT_TOKEN` or `UHT_API_KEY` environment variable. Get a token at [universalhex.org](https://universalhex.org).
+
+## JSON mode
+
+Append `--json` to any command for machine-readable output:
+
+```bash
+airgen reqs list my-tenant my-project --json | jq '.[].ref'
+airgen report compliance my-tenant my-project --json | jq '.summary'
+```
+
+## Aliases
+
+| Full command | Alias |
+|---|---|
+| `requirements` | `reqs` |
+| `diagrams` | `diag` |
+| `documents` | `docs` |
+| `connectors` | `conn` |
+| `baselines` | `bl` |
+| `traces` | `trace` |
+| `quality` | `qa` |
+| `reports` | `report` |
+| `projects` | `proj` |
+| `sections` | `sec` |
+
+## License
+
+MIT

package/dist/commands/lint.d.ts

@@ -0,0 +1,3 @@
+import { Command } from "commander";
+import type { AirgenClient } from "../client.js";
+export declare function registerLintCommands(program: Command, client: AirgenClient): void;

package/dist/commands/lint.js

@@ -0,0 +1,415 @@
+import { writeFileSync } from "node:fs";
+import { UhtClient } from "../uht-client.js";
+import { isJsonMode } from "../output.js";
+// ── Constants ────────────────────────────────────────────────
+const PAGE_SIZE = 100;
+const MAX_PAGES = 50;
+// ── Helpers ──────────────────────────────────────────────────
+async function fetchAllRequirements(client, tenant, project) {
+    const all = [];
+    for (let page = 1; page <= MAX_PAGES; page++) {
+        const data = await client.get(`/requirements/${tenant}/${project}`, {
+            page: String(page),
+            limit: String(PAGE_SIZE),
+        });
+        all.push(...(data.data ?? []));
+        if (page >= (data.meta?.totalPages ?? 1))
+            break;
+    }
+    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
+ */
+function extractConcepts(requirements) {
+    const conceptRefs = new Map();
+    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) ?? [];
+        if (!refs.includes(ref))
+            refs.push(ref);
+        conceptRefs.set(normalized, refs);
+    }
+    for (const req of requirements) {
+        if (!req.text || !req.ref)
+            continue;
+        const text = req.text;
+        // "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..."
+        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..."
+        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);
+        if (whenMatch)
+            addConcept(whenMatch[1], req.ref);
+        // References: "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,
+            /from\s+the\s+(.+?)(?:\s+(?:for|to|at|in|with)\b|[.,;]|$)/gi,
+            /(?:to|into)\s+the\s+(.+?)(?:\s+(?:for|to|at|in|with)\b|[.,;]|$)/gi,
+            /(?:against|per|in accordance with)\s+(.+?)(?:\s+(?:for|to|at|in|with)\b|[.,;]|$)/gi,
+        ];
+        for (const pat of refPatterns) {
+            let m;
+            while ((m = pat.exec(text)) !== null) {
+                addConcept(m[1], 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) {
+    const findings = [];
+    const conceptMap = new Map(concepts.map(c => [c.name, c]));
+    // 1. Physical mismatch: non-physical concepts with environmental/physical requirements
+    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 the Physical Object trait, but ${envReqs.length} requirement(s) impose physical/environmental constraints on it.`,
+                affectedReqs: envReqs,
+                recommendation: `Add a requirement defining the physical embodiment of "${c.name}" (e.g., housing, LRU, equipment rack).`,
+            });
+        }
+    }
+    // 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
+        const metricReqs = c.reqs.filter(ref => {
+            const req = requirements.find(r => r.ref === ref);
+            return req?.text && metricKeywords.test(req.text);
+        });
+        if (metricReqs.length === 0)
+            continue;
+        const hasStats = metricReqs.some(ref => {
+            const req = requirements.find(r => r.ref === ref);
+            return req?.text && statKeywords.test(req.text);
+        });
+        if (!hasStats) {
+            findings.push({
+                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.`,
+                affectedReqs: metricReqs,
+                recommendation: `Add statistical parameters (confidence level, sample size, conditions) to requirements referencing "${c.name}".`,
+            });
+        }
+    }
+    // 3. Verification requirements mixed with functional requirements
+    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) {
+        const ratio = verificationReqs.length / requirements.length;
+        if (ratio > 0.05 && ratio < 0.95) {
+            findings.push({
+                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.`,
+                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.",
+            });
+        }
+    }
+    // 4. Degraded mode gaps: requirements mentioning "manual", "reversion", "fallback" without performance criteria
+    const degradedReqs = requirements.filter(r => r.text && /manual\s+(?:reversion|mode|override|backup)|fallback|degraded/i.test(r.text));
+    for (const req of degradedReqs) {
+        const hasPerf = /\d+%|\d+\s*(?:second|ms|metre|meter|m\b)/i.test(req.text ?? "");
+        if (!hasPerf) {
+            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 acceptance criteria for performance in that mode.`,
+                affectedReqs: [req.ref],
+                recommendation: "Add measurable performance criteria for degraded operation (e.g., acceptable accuracy, response time, available subsystems).",
+            });
+        }
+    }
+    // 5. Cross-comparison: high similarity between concepts in different categories
+    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) {
+                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.`,
+                    affectedReqs: [...a.reqs, ...b.reqs],
+                    recommendation: `Review whether both concepts should have consistent physical classification. Consider adding clarifying requirements.`,
+                });
+            }
+        }
+    }
+    // 6. Requirements without "shall" (weak language)
+    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.`,
+            affectedReqs: weakReqs.map(r => r.ref).filter(Boolean),
+            recommendation: 'Rephrase using "shall" for testable requirements, or move informational text to notes/rationale.',
+        });
+    }
+    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) {
+    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("  ════════════════════");
+    lines.push(`  Project: ${project} (${tenant})`);
+    lines.push(`  Requirements: ${requirements.length} | Concepts classified: ${concepts.length}`);
+    lines.push(`  Findings: ${findings.length} (${high} high, ${med} medium, ${low} low)`);
+    lines.push("");
+    // Concept classifications table
+    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("");
+    // Cross-comparison highlights
+    if (comparisons.length > 0) {
+        lines.push("  ┄┄ Key Similarities ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄");
+        lines.push("");
+        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("");
+    }
+    // Findings
+    lines.push("  ┄┄ Findings ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄");
+    lines.push("");
+    for (let i = 0; i < findings.length; i++) {
+        const f = findings[i];
+        const sevIcon = f.severity === "high" ? "!!!" : f.severity === "medium" ? " ! " : " . ";
+        lines.push(`  ${i + 1}. [${sevIcon}] ${f.title}`);
+        lines.push(`     Category: ${f.category}`);
+        lines.push(`     ${f.description}`);
+        lines.push(`     Affects: ${f.affectedReqs.join(", ")}`);
+        lines.push(`     Fix: ${f.recommendation}`);
+        lines.push("");
+    }
+    if (findings.length === 0) {
+        lines.push("  No findings — requirements look clean.");
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+function formatMarkdown(tenant, project, requirements, 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(`**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("|---|---|---|---|");
+    for (const c of concepts) {
+        lines.push(`| ${c.name} | \`${c.hexCode}\` | ${c.isPhysical ? "Yes" : "No"} | ${c.traits.slice(0, 4).join(", ")} |`);
+    }
+    lines.push("");
+    // Similarities
+    if (comparisons.length > 0) {
+        lines.push("### Key Similarities");
+        lines.push("| Pair | Jaccard |");
+        lines.push("|---|---|");
+        for (const batch of comparisons) {
+            for (const comp of batch.comparisons) {
+                if (comp.jaccard_similarity >= 0.4) {
+                    lines.push(`| ${batch.entity} / ${comp.candidate} | **${(comp.jaccard_similarity * 100).toFixed(0)}%** |`);
+                }
+            }
+        }
+        lines.push("");
+    }
+    // Findings
+    lines.push("### Findings");
+    lines.push("| # | Severity | Title | Affected |");
+    lines.push("|---|---|---|---|");
+    for (let i = 0; i < findings.length; i++) {
+        const f = findings[i];
+        lines.push(`| ${i + 1} | **${f.severity}** | ${f.title} | ${f.affectedReqs.join(", ")} |`);
+    }
+    lines.push("");
+    for (const f of findings) {
+        lines.push(`#### ${f.title}`);
+        lines.push(`- **Severity:** ${f.severity} | **Category:** ${f.category}`);
+        lines.push(`- ${f.description}`);
+        lines.push(`- **Affects:** ${f.affectedReqs.join(", ")}`);
+        lines.push(`- **Recommendation:** ${f.recommendation}`);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+// ── Command registration ─────────────────────────────────────
+export function registerLintCommands(program, client) {
+    program
+        .command("lint")
+        .description("Semantic requirements lint — classifies domain concepts via UHT and flags ontological issues")
+        .argument("<tenant>", "Tenant slug")
+        .argument("<project>", "Project slug")
+        .option("--concepts <n>", "Max concepts to classify", "15")
+        .option("--format <fmt>", "Output format: text, markdown, json", "text")
+        .option("-o, --output <file>", "Write report to file")
+        .action(async (tenant, project, opts) => {
+        const uht = new UhtClient();
+        if (!uht.isConfigured) {
+            console.error("UHT not configured. Set UHT_TOKEN environment variable.");
+            console.error("Get a token at https://universalhex.org");
+            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);
+        if (requirements.length === 0) {
+            console.error("No requirements found.");
+            process.exit(1);
+        }
+        console.error(`  ${requirements.length} requirements 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
+        console.error("Classifying concepts via UHT...");
+        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);
+                concepts.push({
+                    name,
+                    hexCode: result.hex_code,
+                    isPhysical: traitNames.includes("Physical Object"),
+                    traits: traitNames,
+                    reqs: refs,
+                });
+                console.error(`  ✓ ${name} → ${result.hex_code} (${traitNames.length} traits)`);
+            }
+            catch (err) {
+                console.error(`  ✗ ${name}: ${err.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 {
+                const result = await uht.batchCompare(names[0], names.slice(1, batchSize + 1));
+                comparisons.push(result);
+                console.error(`  ✓ ${names[0]} vs ${batchSize} others`);
+            }
+            catch (err) {
+                console.error(`  ✗ batch compare: ${err.message}`);
+            }
+            if (names.length > 3) {
+                try {
+                    const mid = Math.floor(names.length / 2);
+                    const candidates = [...names.slice(0, mid), ...names.slice(mid + 1)].slice(0, 10);
+                    const result = await uht.batchCompare(names[mid], candidates);
+                    comparisons.push(result);
+                    console.error(`  ✓ ${names[mid]} vs ${candidates.length} others`);
+                }
+                catch (err) {
+                    console.error(`  ✗ batch compare: ${err.message}`);
+                }
+            }
+        }
+        // Step 5: Analyze findings
+        console.error("Analyzing...");
+        const findings = analyzeFindings(concepts, comparisons, requirements);
+        // 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);
+        }
+        else if (opts.format === "markdown") {
+            report = formatMarkdown(tenant, project, requirements, concepts, comparisons, findings);
+        }
+        else {
+            report = formatReport(tenant, project, requirements, concepts, comparisons, findings);
+        }
+        if (opts.output) {
+            writeFileSync(opts.output, report + "\n", "utf-8");
+            console.error(`Report written to ${opts.output}`);
+        }
+        else {
+            console.log(report);
+        }
+    });
+}

package/dist/index.js

@@ -19,6 +19,7 @@ import { registerReportCommands } from "./commands/reports.js";
 import { registerImportExportCommands } from "./commands/import-export.js";
 import { registerActivityCommands } from "./commands/activity.js";
 import { registerImplementationCommands } from "./commands/implementation.js";
+import { registerLintCommands } from "./commands/lint.js";
 const program = new Command();
 // Lazy-init: only create client when a command actually runs
 let client = null;
@@ -67,6 +68,7 @@ registerReportCommands(program, clientProxy);
 registerImportExportCommands(program, clientProxy);
 registerActivityCommands(program, clientProxy);
 registerImplementationCommands(program, clientProxy);
+registerLintCommands(program, clientProxy);
 // Handle async errors from Commander action handlers
 process.on("uncaughtException", (err) => {
     console.error(`Error: ${err.message}`);

package/dist/uht-client.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Minimal UHT (Universal Hex Taxonomy) API client.
+ *
+ * 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
+ */
+export interface UhtClassification {
+    entity: string;
+    hex_code: string;
+    traits: Array<{
+        name: string;
+        justification: string;
+    }>;
+}
+export interface UhtComparison {
+    candidate: string;
+    hex_code: string;
+    jaccard_similarity: number;
+    hamming_distance: number;
+    shared_traits: Array<{
+        name: string;
+    }>;
+    traits_entity_only: Array<{
+        name: string;
+    }>;
+    traits_candidate_only: Array<{
+        name: string;
+    }>;
+}
+export interface UhtBatchResult {
+    entity: string;
+    hex_code: string;
+    comparisons: UhtComparison[];
+    best_match: string;
+    best_jaccard: number;
+}
+export declare class UhtClient {
+    private baseUrl;
+    private token;
+    constructor();
+    get isConfigured(): boolean;
+    private request;
+    classify(entity: string): Promise<UhtClassification>;
+    batchCompare(entity: string, candidates: string[]): Promise<UhtBatchResult>;
+}

package/dist/uht-client.js

@@ -0,0 +1,55 @@
+/**
+ * Minimal UHT (Universal Hex Taxonomy) API client.
+ *
+ * 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
+ */
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const DEFAULT_UHT_URL = "https://substrate.universalhex.org/api";
+function loadUhtConfigToken() {
+    try {
+        const configPath = join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "uht-substrate", "config.json");
+        const config = JSON.parse(readFileSync(configPath, "utf-8"));
+        return config.token ?? "";
+    }
+    catch {
+        return "";
+    }
+}
+export class UhtClient {
+    baseUrl;
+    token;
+    constructor() {
+        this.baseUrl = (process.env.UHT_API_URL ?? DEFAULT_UHT_URL).replace(/\/+$/, "");
+        this.token = process.env.UHT_TOKEN || process.env.UHT_API_KEY || loadUhtConfigToken();
+    }
+    get isConfigured() {
+        return this.token.length > 0;
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {};
+        if (body)
+            headers["Content-Type"] = "application/json";
+        if (this.token)
+            headers["Authorization"] = `Bearer ${this.token}`;
+        const res = await globalThis.fetch(url, {
+            method,
+            headers,
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new Error(`UHT API error (${res.status}): ${text}`);
+        }
+        return (await res.json());
+    }
+    async classify(entity) {
+        return this.request("POST", "/classify", { entity, context: "", use_semantic_priors: false });
+    }
+    async batchCompare(entity, candidates) {
+        return this.request("POST", "/batch-compare", { entity, candidates });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "airgen-cli",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "AIRGen CLI — requirements engineering from the command line",
   "type": "module",
   "main": "dist/index.js",
@@ -9,7 +9,8 @@
   },
   "files": [
     "dist",
-    "package.json"
+    "package.json",
+    "README.md"
   ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
@@ -21,7 +22,12 @@
     "requirements",
     "engineering",
     "cli",
-    "requirements-management"
+    "requirements-management",
+    "systems-engineering",
+    "traceability",
+    "sysml",
+    "mbse",
+    "uht"
   ],
   "license": "MIT",
   "repository": {