@xenos1996/usa 2.4.0 → 2.5.0

package/README.md

@@ -179,7 +179,7 @@ Override it: `usa audit . --profile production` — the "what would it take to s
 
 **<!-- usa:fact sections -->16<!-- /usa:fact --> sections**, S1–S16, in [`USA.md`](USA.md) — the human/agent-facing document.
 
-**<!-- usa:fact rules-floor -->300+<!-- /usa:fact --> rules** in [`rules/`](rules) — the machine-facing ones:
+**<!-- usa:fact rules-floor -->310+<!-- /usa:fact --> rules** in [`rules/`](rules) — the machine-facing ones:
 
 <!-- usa:begin rules-tree -->
 
@@ -188,7 +188,7 @@ rules/
 ├── index.yaml              pack registry
 ├── detectors.yaml          ~230 detection signals → facts
 ├── profiles/maturity.yaml  the five lifecycle profiles
-├── core/                   14 universal packs
+├── core/                   15 universal packs
 │   ├── repo.yaml           ├── security.yaml      ├── supply-chain.yaml
 │   ├── architecture.yaml   ├── code-quality.yaml  ├── testing.yaml
 │   ├── cicd.yaml           ├── release.yaml       ├── dependencies.yaml

package/dist/agent/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * LLM provider layer (outside the deterministic spine: proposes, never decides).
+ *
+ * IMPLEMENTED: OpenAI-compatible Chat Completions over fetch.
+ * PROPOSED (not implemented): Anthropic/Google-native protocols.
+ */
+export type { ChatMessage, ChatRequest, ChatResult, ChatUsage, ModelInfo, ProviderOverrides, ProviderPreset, ReasoningEffort, ResolvedConfig, } from './types.js';
+export { ERROR_SNIPPET_LEN, PROVIDER_PRESETS, REQUEST_TIMEOUT_MS, complete, listModels, loadProviderConfig, } from './providers.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/agent/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,YAAY,EACV,WAAW,EACX,WAAW,EACX,UAAU,EACV,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,eAAe,EACf,cAAc,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,QAAQ,EACR,UAAU,EACV,kBAAkB,GACnB,MAAM,gBAAgB,CAAC"}

package/dist/agent/index.js

@@ -0,0 +1,2 @@
+export { ERROR_SNIPPET_LEN, PROVIDER_PRESETS, REQUEST_TIMEOUT_MS, complete, listModels, loadProviderConfig, } from './providers.js';
+//# sourceMappingURL=index.js.map

package/dist/agent/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAiBA,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAClB,QAAQ,EACR,UAAU,EACV,kBAAkB,GACnB,MAAM,gBAAgB,CAAC"}

package/dist/agent/providers.d.ts

@@ -0,0 +1,56 @@
+/**
+ * LLM provider layer — one transport: OpenAI-compatible Chat Completions
+ * over `fetch`.
+ *
+ * Covers OpenAI, DeepSeek, Groq, Mistral, Together, OpenRouter, Ollama,
+ * LM Studio, vLLM, and custom endpoints — all of which speak
+ * `POST {baseURL}/chat/completions` and (hosted ones plus most local ones)
+ * `GET {baseURL}/models`.
+ *
+ * IMPLEMENTED: OpenAI-compatible Chat Completions (`complete`) and model
+ * listing (`listModels`) as described above.
+ * PROPOSED (not implemented — do not assume they work):
+ *   - Anthropic-native Messages API transport (distinct auth headers,
+ *     `anthropic-version`, prompt-caching blocks, thinking blocks).
+ *   - Google Gemini-native `generateContent` transport (distinct URL shape,
+ *     `x-goog-api-key`, distinct response envelope and safety metadata).
+ * Honesty discipline: only the OpenAI-compatible transport exists. Any
+ * caller asking for `anthropic` / `google-native` must fail loudly with
+ * "not implemented", never silently emulate.
+ *
+ * Security rules enforced here:
+ *   - API keys come ONLY from environment variables. Never from files,
+ *     CLI args, or defaults. A missing key throws naming the variable
+ *     (fail-closed); the caller disables LLM features on that error.
+ *   - Key material is NEVER logged. Tests assert the `Authorization`
+ *     header shape with a fake key, never a real one.
+ */
+import type { ChatRequest, ChatResult, ModelInfo, ProviderOverrides, ProviderPreset, ResolvedConfig } from './types.js';
+/** Request timeout: 60s per attempt, enforced via `AbortSignal.timeout`. */
+export declare const REQUEST_TIMEOUT_MS = 60000;
+/** Max characters of an error body included in thrown HTTP errors. */
+export declare const ERROR_SNIPPET_LEN = 200;
+export declare const PROVIDER_PRESETS: Record<string, ProviderPreset>;
+/**
+ * Resolve a provider id to a concrete config, reading the API key from
+ * the environment. Fail-closed: a missing key throws naming the variable;
+ * the caller disables LLM features on that error. Never logs key material.
+ */
+export declare function loadProviderConfig(providerId: string, overrides?: ProviderOverrides): ResolvedConfig;
+/**
+ * Run one OpenAI-compatible Chat Completions request. Optional fields
+ * (`temperature`, `max_tokens`, `reasoning_effort`) are sent ONLY when set,
+ * so provider defaults apply otherwise. Non-2xx responses throw an `Error`
+ * carrying the HTTP status plus a body snippet (never key material).
+ */
+export declare function complete(req: ChatRequest): Promise<ChatResult>;
+/**
+ * List models via `GET {baseURL}/models` (OpenAI shape `{data:[{id}]}` or
+ * tolerant variants). Degraded-never-empty: any fetch/HTTP/parse failure
+ * falls back to the preset's static default model. If the preset has no
+ * static default (custom without a caller-supplied model... which is
+ * rejected earlier) and the fetch fails, the error is rethrown loudly —
+ * never an empty guess.
+ */
+export declare function listModels(providerId: string, overrides?: ProviderOverrides): Promise<ModelInfo[]>;
+//# sourceMappingURL=providers.d.ts.map

package/dist/agent/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","sourceRoot":"","sources":["../../src/agent/providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,SAAS,EACT,iBAAiB,EACjB,cAAc,EACd,cAAc,EACf,MAAM,YAAY,CAAC;AAEpB,4EAA4E;AAC5E,eAAO,MAAM,kBAAkB,QAAS,CAAC;AAEzC,sEAAsE;AACtE,eAAO,MAAM,iBAAiB,MAAM,CAAC;AAErC,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAkF3D,CAAC;AAuBF;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,iBAAiB,GAC5B,cAAc,CAmBhB;AAgED;;;;;GAKG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAUpE;AAoFD;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,UAAU,EAAE,MAAM,EAClB,SAAS,CAAC,EAAE,iBAAiB,GAC5B,OAAO,CAAC,SAAS,EAAE,CAAC,CAsBtB"}

package/dist/agent/providers.js

@@ -0,0 +1,334 @@
+/**
+ * LLM provider layer — one transport: OpenAI-compatible Chat Completions
+ * over `fetch`.
+ *
+ * Covers OpenAI, DeepSeek, Groq, Mistral, Together, OpenRouter, Ollama,
+ * LM Studio, vLLM, and custom endpoints — all of which speak
+ * `POST {baseURL}/chat/completions` and (hosted ones plus most local ones)
+ * `GET {baseURL}/models`.
+ *
+ * IMPLEMENTED: OpenAI-compatible Chat Completions (`complete`) and model
+ * listing (`listModels`) as described above.
+ * PROPOSED (not implemented — do not assume they work):
+ *   - Anthropic-native Messages API transport (distinct auth headers,
+ *     `anthropic-version`, prompt-caching blocks, thinking blocks).
+ *   - Google Gemini-native `generateContent` transport (distinct URL shape,
+ *     `x-goog-api-key`, distinct response envelope and safety metadata).
+ * Honesty discipline: only the OpenAI-compatible transport exists. Any
+ * caller asking for `anthropic` / `google-native` must fail loudly with
+ * "not implemented", never silently emulate.
+ *
+ * Security rules enforced here:
+ *   - API keys come ONLY from environment variables. Never from files,
+ *     CLI args, or defaults. A missing key throws naming the variable
+ *     (fail-closed); the caller disables LLM features on that error.
+ *   - Key material is NEVER logged. Tests assert the `Authorization`
+ *     header shape with a fake key, never a real one.
+ */
+/** Request timeout: 60s per attempt, enforced via `AbortSignal.timeout`. */
+export const REQUEST_TIMEOUT_MS = 60_000;
+/** Max characters of an error body included in thrown HTTP errors. */
+export const ERROR_SNIPPET_LEN = 200;
+export const PROVIDER_PRESETS = {
+    openai: {
+        id: 'openai',
+        label: 'OpenAI',
+        baseURL: 'https://api.openai.com/v1',
+        apiKeyEnv: 'OPENAI_API_KEY',
+        defaultModel: 'gpt-4o-mini',
+        fetchModels: true,
+    },
+    deepseek: {
+        id: 'deepseek',
+        label: 'DeepSeek',
+        baseURL: 'https://api.deepseek.com/v1',
+        apiKeyEnv: 'DEEPSEEK_API_KEY',
+        defaultModel: 'deepseek-chat',
+        fetchModels: true,
+    },
+    groq: {
+        id: 'groq',
+        label: 'Groq',
+        baseURL: 'https://api.groq.com/openai/v1',
+        apiKeyEnv: 'GROQ_API_KEY',
+        defaultModel: 'llama-3.3-70b-versatile',
+        freeTier: true,
+        fetchModels: true,
+    },
+    mistral: {
+        id: 'mistral',
+        label: 'Mistral',
+        baseURL: 'https://api.mistral.ai/v1',
+        apiKeyEnv: 'MISTRAL_API_KEY',
+        defaultModel: 'mistral-small-latest',
+        freeTier: true,
+        fetchModels: true,
+    },
+    together: {
+        id: 'together',
+        label: 'Together AI',
+        baseURL: 'https://api.together.xyz/v1',
+        apiKeyEnv: 'TOGETHER_API_KEY',
+        defaultModel: 'meta-llama/Meta-Llama-3.1-8B-Instruct-Turbo',
+        fetchModels: true,
+    },
+    openrouter: {
+        id: 'openrouter',
+        label: 'OpenRouter',
+        baseURL: 'https://openrouter.ai/api/v1',
+        apiKeyEnv: 'OPENROUTER_API_KEY',
+        defaultModel: 'openai/gpt-4o-mini',
+        freeTier: true,
+        fetchModels: true,
+    },
+    ollama: {
+        id: 'ollama',
+        label: 'Ollama (local)',
+        baseURL: 'http://localhost:11434/v1',
+        apiKeyEnv: '',
+        defaultModel: 'llama3.1',
+        freeTier: true,
+        fetchModels: true,
+    },
+    lmstudio: {
+        id: 'lmstudio',
+        label: 'LM Studio (local)',
+        baseURL: 'http://localhost:1234/v1',
+        apiKeyEnv: '',
+        defaultModel: 'local-model',
+        freeTier: true,
+        fetchModels: true,
+    },
+    custom: {
+        id: 'custom',
+        label: 'Custom OpenAI-compatible endpoint',
+        // Empty on purpose: the caller MUST supply baseURL (and usually
+        // apiKeyEnv/model) via overrides. Any vLLM / text-generation-webui /
+        // corporate-gateway endpoint works as long as it speaks the
+        // OpenAI-compatible Chat Completions dialect.
+        baseURL: '',
+        apiKeyEnv: '',
+        defaultModel: '',
+        fetchModels: false,
+    },
+};
+/** Names of explicitly PROPOSED-but-unimplemented native transports. */
+const UNIMPLEMENTED_TRANSPORTS = new Set(['anthropic', 'google', 'gemini', 'vertex', 'bedrock']);
+/** Resolve a provider id to its preset, or throw naming what exists. */
+function findPreset(providerId) {
+    if (UNIMPLEMENTED_TRANSPORTS.has(providerId)) {
+        throw new Error(`LLM provider "${providerId}" is PROPOSED, not implemented: ` +
+            `only OpenAI-compatible Chat Completions transports are available ` +
+            `(${Object.keys(PROVIDER_PRESETS).join(', ')}).`);
+    }
+    const preset = PROVIDER_PRESETS[providerId];
+    if (!preset) {
+        throw new Error(`Unknown LLM provider "${providerId}". Known providers: ${Object.keys(PROVIDER_PRESETS).join(', ')}.`);
+    }
+    return preset;
+}
+/**
+ * Resolve a provider id to a concrete config, reading the API key from
+ * the environment. Fail-closed: a missing key throws naming the variable;
+ * the caller disables LLM features on that error. Never logs key material.
+ */
+export function loadProviderConfig(providerId, overrides) {
+    const preset = findPreset(providerId);
+    const baseURL = overrides?.baseURL ?? preset.baseURL;
+    if (!baseURL) {
+        throw new Error(`LLM provider "${providerId}" has no baseURL: supply one via overrides.baseURL ` +
+            `(custom endpoints must always provide a baseURL).`);
+    }
+    const apiKey = resolveApiKey(providerId, overrides?.apiKeyEnv ?? preset.apiKeyEnv);
+    const model = resolveModel(providerId, overrides?.model ?? preset.defaultModel);
+    const resolved = {
+        providerId: preset.id,
+        label: preset.label,
+        baseURL: stripTrailingSlashes(baseURL),
+        model,
+    };
+    if (apiKey !== undefined)
+        resolved.apiKey = apiKey;
+    return resolved;
+}
+/**
+ * Trailing-slash strip without a regex: the input is caller-controlled
+ * (custom baseURL), and a regex here is a ReDoS surface CodeQL flags.
+ * Linear scan, identical result to `/\/+$/` removal.
+ */
+function stripTrailingSlashes(url) {
+    let end = url.length;
+    while (end > 0 && url[end - 1] === '/')
+        end -= 1;
+    return url.slice(0, end);
+}
+/** Key from the environment, or undefined for keyless local endpoints. */
+function resolveApiKey(providerId, apiKeyEnv) {
+    if (!apiKeyEnv)
+        return undefined;
+    const raw = process.env[apiKeyEnv];
+    if (!raw) {
+        throw new Error(`LLM provider "${providerId}" needs an API key: environment variable ${apiKeyEnv} ` +
+            `is missing or empty. Set it, or disable LLM features.`);
+    }
+    return raw;
+}
+/** Explicit model wins; otherwise the preset default (both may be absent). */
+function resolveModel(providerId, model) {
+    if (model)
+        return model;
+    throw new Error(`LLM provider "${providerId}" has no default model: supply one via overrides.model ` +
+        `or ChatRequest.model.`);
+}
+function authHeaders(apiKey) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (apiKey !== undefined)
+        headers['Authorization'] = `Bearer ${apiKey}`;
+    return headers;
+}
+async function readSnippet(res) {
+    try {
+        return (await res.text()).slice(0, ERROR_SNIPPET_LEN);
+    }
+    catch {
+        return '<unreadable body>';
+    }
+}
+function numOrUndefined(v) {
+    return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+}
+/**
+ * Run one OpenAI-compatible Chat Completions request. Optional fields
+ * (`temperature`, `max_tokens`, `reasoning_effort`) are sent ONLY when set,
+ * so provider defaults apply otherwise. Non-2xx responses throw an `Error`
+ * carrying the HTTP status plus a body snippet (never key material).
+ */
+export async function complete(req) {
+    const cfg = loadProviderConfig(req.provider, { model: req.model });
+    const res = await fetch(`${cfg.baseURL}/chat/completions`, {
+        method: 'POST',
+        headers: authHeaders(cfg.apiKey),
+        body: JSON.stringify(buildChatBody(req, cfg.model)),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+    });
+    await ensureOk(res);
+    return readChatResult(res, cfg.model);
+}
+/** Optional fields ride along ONLY when set — provider defaults win otherwise. */
+function buildChatBody(req, model) {
+    const body = {
+        model,
+        messages: req.messages.map((m) => ({ role: m.role, content: m.content })),
+    };
+    if (req.temperature !== undefined)
+        body['temperature'] = req.temperature;
+    if (req.maxTokens !== undefined)
+        body['max_tokens'] = req.maxTokens;
+    if (req.reasoningEffort !== undefined)
+        body['reasoning_effort'] = req.reasoningEffort;
+    return body;
+}
+/** Non-2xx becomes an Error carrying status plus a body snippet (no keys). */
+async function ensureOk(res) {
+    if (res.ok)
+        return;
+    const snippet = await readSnippet(res);
+    throw new Error(`Chat completions request failed: HTTP ${res.status} ${snippet}`);
+}
+/** Parse the completion envelope; anything shapeless throws loudly. */
+async function readChatResult(res, fallbackModel) {
+    let json;
+    try {
+        json = (await res.json());
+    }
+    catch (err) {
+        throw new Error(`Chat completions request failed: unreadable JSON response (${err.message})`, {
+            cause: err,
+        });
+    }
+    const content = json.choices?.[0]?.message?.content;
+    if (typeof content !== 'string') {
+        throw new Error('Chat completions request failed: response has no choices[0].message.content string');
+    }
+    return {
+        text: content,
+        model: typeof json.model === 'string' && json.model ? json.model : fallbackModel,
+        ...usageOf(json),
+    };
+}
+/** Usage block only when at least one counter parsed (else omitted). */
+function usageOf(json) {
+    const promptTokens = numOrUndefined(json.usage?.prompt_tokens);
+    const completionTokens = numOrUndefined(json.usage?.completion_tokens);
+    const totalTokens = numOrUndefined(json.usage?.total_tokens);
+    if (promptTokens === undefined && completionTokens === undefined && totalTokens === undefined) {
+        return {};
+    }
+    const usage = {};
+    if (promptTokens !== undefined)
+        usage.promptTokens = promptTokens;
+    if (completionTokens !== undefined)
+        usage.completionTokens = completionTokens;
+    if (totalTokens !== undefined)
+        usage.totalTokens = totalTokens;
+    return { usage };
+}
+/** Extract model names tolerantly from a `GET /models` payload. */
+function parseModelList(json) {
+    const names = [];
+    const push = (v) => {
+        if (typeof v === 'string' && v)
+            names.push(v);
+        else if (v && typeof v === 'object') {
+            const o = v;
+            const cand = o['name'] ?? o['id'];
+            if (typeof cand === 'string' && cand)
+                names.push(cand);
+        }
+    };
+    if (Array.isArray(json)) {
+        for (const item of json)
+            push(item);
+    }
+    else if (json && typeof json === 'object') {
+        const data = json['data'];
+        if (Array.isArray(data)) {
+            for (const item of data)
+                push(item);
+        }
+    }
+    return [...new Set(names)];
+}
+/**
+ * List models via `GET {baseURL}/models` (OpenAI shape `{data:[{id}]}` or
+ * tolerant variants). Degraded-never-empty: any fetch/HTTP/parse failure
+ * falls back to the preset's static default model. If the preset has no
+ * static default (custom without a caller-supplied model... which is
+ * rejected earlier) and the fetch fails, the error is rethrown loudly —
+ * never an empty guess.
+ */
+export async function listModels(providerId, overrides) {
+    const cfg = loadProviderConfig(providerId, overrides);
+    try {
+        const res = await fetch(`${cfg.baseURL}/models`, {
+            method: 'GET',
+            headers: authHeaders(cfg.apiKey),
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        const json = await res.json();
+        const names = parseModelList(json);
+        if (names.length === 0)
+            throw new Error('empty model list');
+        return names.map((name) => ({ name }));
+    }
+    catch {
+        if (!cfg.model) {
+            throw new Error(`Could not list models for provider "${providerId}" and no static default exists: ` +
+                `supply overrides.model.`);
+        }
+        return [{ name: cfg.model }];
+    }
+}
+//# sourceMappingURL=providers.js.map

package/dist/agent/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../../src/agent/providers.ts"],"names":[],"mappings":"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"}

package/dist/agent/types.d.ts

@@ -0,0 +1,103 @@
+/**
+ * LLM provider layer — shared request/result types.
+ *
+ * Doctrine: the deterministic offline spine never depends on this layer.
+ * The LLM only *proposes* from outside the spine; the engine verifies.
+ * Every key comes from the environment (fail-closed when missing); key
+ * material is never logged.
+ *
+ * IMPLEMENTED: OpenAI-compatible Chat Completions over `fetch`.
+ * PROPOSED (not implemented — do not assume they work):
+ *   - Anthropic Messages API (`anthropic-*` headers, `anthropic-version`):
+ *     different auth scheme, prompt-caching headers, and message roles.
+ *   - Google Gemini native `generateContent` protocol (`:generateContent`,
+ *     `x-goog-api-key`): different URL shape and response envelope.
+ * Both remain documented follow-ups until a contributor adds a dedicated
+ * transport plus tests. Anything not listed under IMPLEMENTED does not work.
+ */
+/** A single turn in a chat-completions conversation. */
+export interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+}
+/**
+ * Reasoning-effort hint forwarded verbatim as `reasoning_effort`.
+ * Kept as a plain string: the accepted values differ per vendor
+ * (OpenAI `low|medium|high`, others accept `minimal`, `xhigh`, …),
+ * so this layer does not validate — the server decides.
+ */
+export type ReasoningEffort = string;
+/** One LLM completion request against a configured provider preset. */
+export interface ChatRequest {
+    /** Key of {@link PROVIDER_PRESETS} (see providers.ts). */
+    provider: string;
+    /** Model id as advertised by the provider (e.g. `gpt-4o-mini`). */
+    model: string;
+    messages: ChatMessage[];
+    temperature?: number;
+    maxTokens?: number;
+    reasoningEffort?: ReasoningEffort;
+}
+/** Token usage reported by the provider, when it reports any. */
+export interface ChatUsage {
+    promptTokens?: number;
+    completionTokens?: number;
+    totalTokens?: number;
+}
+/** The assistant's reply plus echo of the serving model. */
+export interface ChatResult {
+    text: string;
+    model: string;
+    usage?: ChatUsage;
+}
+/**
+ * Static description of one OpenAI-compatible endpoint.
+ * `baseURL` is the API root WITHOUT a trailing path operation
+ * (this layer appends `/chat/completions` and `/models`).
+ */
+export interface ProviderPreset {
+    /** Stable key used in {@link ChatRequest.provider}. */
+    id: string;
+    /** Human-readable label for status/CLI output. */
+    label: string;
+    /** API root, e.g. `https://api.openai.com/v1`. */
+    baseURL: string;
+    /**
+     * Environment variable holding the API key. Empty string means the
+     * provider needs no key (local runtimes); such presets never throw
+     * for a missing key and send no `Authorization` header.
+     */
+    apiKeyEnv: string;
+    /**
+     * Model used when the caller does not pick one. Empty string means
+     * "no static default" — the caller MUST supply a model and a failed
+     * `/models` fetch throws loudly instead of falling back.
+     */
+    defaultModel: string;
+    /** Whether the vendor offers a free tier (informational only). */
+    freeTier?: boolean;
+    /** Whether the vendor is known to serve `GET {baseURL}/models`. */
+    fetchModels: boolean;
+}
+/** A model id advertised via (or in place of) `GET {baseURL}/models`. */
+export interface ModelInfo {
+    name: string;
+}
+/**
+ * A preset with secrets resolved. `apiKey` is `undefined` exactly when
+ * the preset needs no key; it is never read from files or CLI args.
+ */
+export interface ResolvedConfig {
+    providerId: string;
+    label: string;
+    baseURL: string;
+    apiKey?: string;
+    model: string;
+}
+/** Caller-supplied overrides, used for the `custom` preset. */
+export interface ProviderOverrides {
+    baseURL?: string;
+    apiKeyEnv?: string;
+    model?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/agent/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agent/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,wDAAwD;AACxD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,WAAW,GAAG,MAAM,CAAC;IAC/C,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,CAAC;AAErC,uEAAuE;AACvE,MAAM,WAAW,WAAW;IAC1B,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,WAAW,EAAE,CAAC;IACxB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,CAAC,EAAE,eAAe,CAAC;CACnC;AAED,iEAAiE;AACjE,MAAM,WAAW,SAAS;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,4DAA4D;AAC5D,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,uDAAuD;IACvD,EAAE,EAAE,MAAM,CAAC;IACX,kDAAkD;IAClD,KAAK,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,YAAY,EAAE,MAAM,CAAC;IACrB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,mEAAmE;IACnE,WAAW,EAAE,OAAO,CAAC;CACtB;AAED,yEAAyE;AACzE,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf;AAED,+DAA+D;AAC/D,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB"}

package/dist/agent/types.js

@@ -0,0 +1,19 @@
+/**
+ * LLM provider layer — shared request/result types.
+ *
+ * Doctrine: the deterministic offline spine never depends on this layer.
+ * The LLM only *proposes* from outside the spine; the engine verifies.
+ * Every key comes from the environment (fail-closed when missing); key
+ * material is never logged.
+ *
+ * IMPLEMENTED: OpenAI-compatible Chat Completions over `fetch`.
+ * PROPOSED (not implemented — do not assume they work):
+ *   - Anthropic Messages API (`anthropic-*` headers, `anthropic-version`):
+ *     different auth scheme, prompt-caching headers, and message roles.
+ *   - Google Gemini native `generateContent` protocol (`:generateContent`,
+ *     `x-goog-api-key`): different URL shape and response envelope.
+ * Both remain documented follow-ups until a contributor adds a dedicated
+ * transport plus tests. Anything not listed under IMPLEMENTED does not work.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/agent/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/agent/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG"}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAkHA,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CA6B3C;AAo1BD,iBAAS,YAAY,CACnB,KAAK,GAAE,MAAM,GAAG,SAA2B,EAC3C,OAAO,GAAE,MAAwB,GAChC,OAAO,CAOT;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAoHA,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CA6B3C;AAm3BD,iBAAS,YAAY,CACnB,KAAK,GAAE,MAAM,GAAG,SAA2B,EAC3C,OAAO,GAAE,MAAwB,GAChC,OAAO,CAOT;AAED,OAAO,EAAE,YAAY,EAAE,CAAC"}

package/dist/cli.js

@@ -21,6 +21,7 @@ import { runEvolutionCycle } from './evolution/run.js';
 import { capabilityFromPack } from './evolution/capability.js';
 import { ruleAutomatability } from './engine/automatability.js';
 import { catalogueCoverage, catalogueOf, loadCatalogues } from './engine/catalogues.js';
+import { categoryCoverage, loadCategories } from './engine/categories.js';
 import { runFoundationInit, runFoundationShow } from './foundation/interview.js';
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const DEFAULT_RULES_DIR = path.resolve(HERE, '..', 'rules');
@@ -85,6 +86,7 @@ const COMMANDS = {
     evolve: cmdEvolve,
     standards: cmdStandards,
     foundation: cmdFoundation,
+    categories: cmdCategories,
 };
 export function main(argv) {
     const args = parseArgs(argv);
@@ -365,6 +367,30 @@ function cmdStandards(args) {
     }
     return 0;
 }
+/**
+ * Category coverage is derived, never scored (ADR-0030 taxonomy rule): the
+ * table answers "which future domains already have rules" without touching
+ * scoring, gates, or confidence.
+ */
+function cmdCategories(args) {
+    const rulesDir = path.resolve(str(args, 'rules-dir', DEFAULT_RULES_DIR) ?? DEFAULT_RULES_DIR);
+    const { packs } = loadRulePacks(rulesDir);
+    const { categories, warnings } = loadCategories(rulesDir);
+    for (const w of warnings)
+        console.error(`warning: ${w}`);
+    const rows = categoryCoverage(packs, categories);
+    const fmt = (str(args, 'format') ?? 'md').toLowerCase();
+    if (fmt === 'json') {
+        console.log(JSON.stringify(rows, null, 2));
+        return 0;
+    }
+    console.log('| Category | Rules | Sections |');
+    console.log('| -------- | ----- | -------- |');
+    for (const row of rows) {
+        console.log(`| ${row.name} (\`${row.id}\`) | ${row.ruleCount} | ${row.sections.join(', ') || '—'} |`);
+    }
+    return 0;
+}
 /* ------------------------------------------------------------ foundation -- */
 function cmdFoundation(args) {
     const sub = args._[1];
@@ -809,6 +835,7 @@ usa — Universal Software Auditor
   usa learn <report.md>         Generate suggested rules from audit findings
   usa evolve [path]             Run the audit → gap → candidate → release loop
   usa standards                 Report catalogue coverage and automatability
+  usa categories                Report future-domain category coverage
   usa foundation init [path]    Capture project intent into .usa/foundation.yaml
   usa foundation show [path]    Print the effective intent and asserted facts
 
@@ -830,6 +857,10 @@ standards options
   --format <fmt>      md | json                       (default md)
   --rules-dir <dir>   Rule pack directory             (default bundled rules/)
 
+categories options
+  --format <fmt>      md | json                       (default md)
+  --rules-dir <dir>   Rule pack directory             (default bundled rules/)
+
 foundation options
   --dir <path>        Project directory (default .; a positional path works too)
   --non-interactive   Write the defaults file without prompting (init only)