@xenos1996/usa 2.0.1 → 2.3.1

package/README.md

@@ -9,7 +9,8 @@
 [![CI](https://github.com/Er-Sajan-PLG/universal-software-auditor/actions/workflows/ci.yml/badge.svg)](https://github.com/Er-Sajan-PLG/universal-software-auditor/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@xenos1996/usa)](https://www.npmjs.com/package/@xenos1996/usa)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
-[![Rules](https://img.shields.io/badge/rules-200%2B-blue)](rules/)
+[![Rules](https://img.shields.io/badge/rules-280%2B-blue)](rules/)
+[![CII Best Practices](https://img.shields.io/badge/CII%20Best%20Practices-in%20progress-yellow)](https://www.bestpractices.dev/en)
 
 </div>
 
@@ -57,31 +58,32 @@ into a PR, or email to a client.
 ```markdown
 ## 📊 Executive Summary
 
-### Overall Health Score: 71.4/100
+### Overall Health Score: **45.2/100**
 
-`█████████████████░░░░░░░`
+`███████████░░░░░░░░░░░░░`
 
-Expected band for Beta / Growing: 60–85 — within the expected band 👍
+Verified automatically: **65.8%** of applicable checks. 27 checks need a human — see the judgement queue.
+
+Expected band for **Prototype / Spike**: 30–65 — **within the expected band** 👍
 
 | Dimension                            | Score  | Confidence |
 | ------------------------------------ | ------ | ---------- |
-| S1 · Repository & Project Structure  | 8.4/10 | 72.7%      |
-| S2 · Security                        | 6.2/10 | 100%       |
-| S3 · Supply Chain & Build Provenance | 5.1/10 | 100%       |
-| S7 · Testing & Quality Assurance     | 7.5/10 | 80%        |
+| S1 · Repository & Project Structure  | 7.2/10 | 83.3%      |
+| S2 · Security                        | 4.9/10 | 92.9%      |
+| S3 · Supply Chain & Build Provenance | 0/10   | 100%       |
+| S5 · Code Quality                    | 3.5/10 | 87.5%      |
+| S7 · Testing & Quality Assurance     | 0/10 † | 33.3%      |
 
 ## 🚨 Immediate Action Required
 
 1. 🔴 **No hardcoded credentials in source** · `SEC-001`
    - **Where:** `src/config.js:3`, `src/config.js:4`
-   - **Why:** 2 occurrence(s): `api_key: 'example_key_not_real_12345',` at src/config.js:3 (+1 more)
-   - **Fix:** Move to environment variables backed by a secret manager…
-
-## 🧠 Judgement Queue (agent / human review)
-
-| Rule                                            | Section | Severity | What to look for | Evidence to record               |
-| ----------------------------------------------- | ------- | -------- | ---------------- | -------------------------------- |
-| `SEC-015` Authorization is enforced per request | S2      | 🟠 HIGH  | …                | file:line of the ownership check |
+   - **Why:** 2 occurrence(s): `api_key: 'example_key_not_real_12345',` at src/config.js:3 (+1 more).
+   - **Fix:** Move to environment variables backed by a secret manager; rotate anything that was ever committed.
+2. 🔴 **SQL is not built by string concatenation** · `SEC-005`
+   - **Where:** `src/db.js:15`
+   - **Why:** 1 instance(s): `'SELECT * FROM orders WHERE id = ' + orderId,` at src/db.js:15.
+   - **Fix:** Use parameterised queries ($1, ?, :name) or the ORM query API.
 ```
 
 That excerpt is real output, generated by running USA against
@@ -100,7 +102,7 @@ See the full report: [`examples/sample-report.md`](examples/sample-report.md).
 
 ## 🔍 How it adapts
 
-**1 · Detect.** ~200 declarative signals in [`rules/detectors.yaml`](rules/detectors.yaml)
+**1 · Detect.** <!-- usa:fact detectors-approx -->~230<!-- /usa:fact --> declarative signals in [`rules/detectors.yaml`](rules/detectors.yaml)
 produce facts about your project — language, framework, package manager, platform,
 database, auth, CI, AI stack, and more.
 
@@ -175,28 +177,32 @@ Override it: `usa audit . --profile production` — the "what would it take to s
 
 ## 📦 What it checks
 
-**16 sections**, S1–S16, in [`USA.md`](USA.md) — the human/agent-facing document.
+**<!-- usa:fact sections -->16<!-- /usa:fact --> sections**, S1–S16, in [`USA.md`](USA.md) — the human/agent-facing document.
 
-**200+ rules** in [`rules/`](rules) — the machine-facing ones:
+**<!-- usa:fact rules-floor -->280+<!-- /usa:fact --> rules** in [`rules/`](rules) — the machine-facing ones:
+
+<!-- usa:begin rules-tree -->
 
 ```
 rules/
 ├── index.yaml              pack registry
-├── detectors.yaml          ~200 detection signals → facts
-├── sections.yaml           section weights (override the defaults)
+├── detectors.yaml          ~230 detection signals → facts
 ├── profiles/maturity.yaml  the five lifecycle profiles
-├── core/                   11 universal packs
+├── core/                   13 universal packs
 │   ├── repo.yaml           ├── security.yaml      ├── supply-chain.yaml
 │   ├── architecture.yaml   ├── code-quality.yaml  ├── testing.yaml
 │   ├── cicd.yaml           ├── release.yaml       ├── dependencies.yaml
 │   ├── documentation.yaml  └── future-readiness.yaml
-└── stacks/                 16 conditional packs
+└── stacks/                 17 conditional packs
     ├── node-typescript     ├── python      ├── go        ├── rust
     ├── jvm                 ├── web-frontend├── mobile    ├── containers
     ├── iac                 ├── solidity    ├── ml-ai      ├── cli
-    ├── data                ├── api-backend ├── compliance └── ai-era
+    ├── data                ├── api-backend ├── compliance ├── ai-era
+    └── swift
 ```
 
+<!-- usa:end rules-tree -->
+
 ### What USA adds beyond a conventional audit checklist
 
 | Addition                                            | Why                                                                                                                                                       |
@@ -238,7 +244,7 @@ Ready-made packs:
 
 ## 🔧 Configuration
 
-`usa init` scaffolds `.usa.yaml`:
+`usa init` scaffolds `.usa.yaml` (all entries commented — uncomment what you need):
 
 ```yaml
 version: 1
@@ -246,14 +252,14 @@ version: 1
 # include: [stacks/solidity]  # force a pack on
 # exclude: [stacks/mobile]    # force a pack off
 rules:
-  DOC-003:
-    severity: LOW
-    reason: 'Docs live in Notion (decision: ADR-014)'
+  # DOC-003:
+  #   severity: LOW
+  #   reason: "Docs live in Notion, not the repo (decision: ADR-014)"
 suppressions:
-  - rule: PERF-005
-    reason: 'Known N+1 in the admin panel; 40 rows max.'
-    until: '2026-12-31'
-ignore: [] # extra globs to exclude from indexing
+  # - rule: PERF-005
+  #   reason: "Known N+1 in the admin panel; 40 rows max. Revisit Q4."
+  #   until: "2026-12-31"
+ignore: []
 facts: [] # assert facts detection missed, e.g. "has:database"
 ```
 
@@ -296,9 +302,14 @@ Add to any workflow ([`action.yml`](action.yml) is a composite action if you pre
 | [`docs/detectors.md`](docs/detectors.md)                 | The fact catalogue and how to add signals                                       |
 | [`docs/maturity-profiles.md`](docs/maturity-profiles.md) | Lifecycle stages and dampening rules                                            |
 | [`docs/agent-integration.md`](docs/agent-integration.md) | Driving USA from Claude/Cursor/Codex/Copilot                                    |
-| [`docs/ci-integration.md`](docs/ci-integration.md)       | GitHub Actions, GitLab CI, quality gates                                        |
+| [`docs/ci-integration.md`](docs/ci-integration.md)       | GitHub Actions, GitLab CI, quality gates, SARIF/JSON output                     |
 | [`docs/standards-mapping.md`](docs/standards-mapping.md) | USA ↔ ASVS 5.0, SSDF, SLSA, Scorecard, ISO 5055, WCAG, CRA                      |
 | [`docs/configuration.md`](docs/configuration.md)         | `.usa.yaml` reference                                                           |
+| [`docs/EVOLUTION.md`](docs/EVOLUTION.md)                 | The deterministic self-extension loop                                           |
+| [`docs/reference/api.md`](docs/reference/api.md)         | Programmatic API: `runAudit`, renderers, scoring, diffing, evolution            |
+
+The full index — including architecture, ADRs, and the CLI reference — is
+[`docs/README.md`](docs/README.md).
 
 ---
 

package/USA.md

@@ -18,13 +18,13 @@ usa audit .                      # 1. deterministic pass → AUDIT.md
 
 ## 0 · How the agent uses this template
 
-| Step | Action                                                    | Output                         |
-| ---- | --------------------------------------------------------- | ------------------------------ |
-| 1    | Run `usa detect <path>` (or read `rules/detectors.yaml`)  | The project's **facts**        |
-| 2    | Match facts against `applies_when` in `rules/`            | The **applicable rule set**    |
-| 3    | Run `usa audit <path>`                                    | Deterministic findings + score |
-| 4    | Work the **Judgement Queue** in the generated report      | Evidence-backed findings       |
-| 5    | Emit the [Section 14 report](#14--report-output-template) | The deliverable                |
+| Step | Action                                                     | Output                         |
+| ---- | ---------------------------------------------------------- | ------------------------------ |
+| 1    | Run `usa detect <path>` (or read `rules/detectors.yaml`)   | The project's **facts**        |
+| 2    | Match facts against `applies_when` in `rules/`             | The **applicable rule set**    |
+| 3    | Run `usa audit <path>`                                     | Deterministic findings + score |
+| 4    | Work the **Judgement Queue** in the generated report       | Evidence-backed findings       |
+| 5    | Emit the [report output template](#report-output-template) | The deliverable                |
 
 **Ten behaviour rules.** They are not stylistic; each one prevents a specific failure mode.
 
@@ -121,7 +121,7 @@ Sections are activated by detection, not by the auditor's attention span. `S15
 | **S15** | Platform-Specific                     | per stack: Node, Python, Go, Rust, JVM, Web, Mobile, Containers, IaC, Solidity, ML, CLI, API | 1.0     |
 | **S16** | Future Readiness                      | always                                                                                       | 0.4     |
 
-The machine-readable version of every section lives in [`rules/core/`](rules/core), [`rules/stacks/`](rules/stacks), and [`rules/sections.yaml`](rules/sections.yaml).
+The machine-readable rules live in [`rules/core/`](rules/core) and [`rules/stacks/`](rules/stacks). Section titles and weights are defined in [`src/engine/sections.ts`](src/engine/sections.ts); override them per-repo with an optional `sections.yaml` in your rules directory (`$rulesDir/sections.yaml`).
 
 ### What USA added to the classic 14-section audit
 
@@ -472,7 +472,7 @@ All 🔵 `FUTURE` — these are plans, not defects, and they never block a relea
 
 ---
 
-## 14 · Report Output Template
+## Report output template
 
 > The `usa` CLI emits exactly this structure. If you are an agent writing it by hand, match it — a report that looks the same every time is a report you can diff.
 

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAmGA,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CA6B3C;AA6nBD,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":";AAgHA,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CA6B3C;AA+zBD,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

@@ -8,14 +8,19 @@ import { loadDetectorFile } from './detect/index.js';
 import { Project } from './util/project.js';
 import { detect } from './detect/index.js';
 import { renderMarkdown, parseTrailer } from './report/markdown.js';
+import { parseDetachedSignature, verifyDetachedSignature, } from './report/signature.js';
+import { renderJson } from './report/json.js';
+import { renderSarif } from './report/sarif.js';
 import { diffReports } from './engine/diff.js';
 import { bootstrapPacks, writeBootstrapPacks } from './bootstrap/index.js';
 import { EXAMPLE_CONFIG, loadConfig } from './config.js';
-import { evaluateGate } from './engine/gate.js';
+import { evaluateGate, evaluateNewCodeGate, parseBaselineTrailer } from './engine/gate.js';
 import { learnFromReport, renderSuggestions } from './learn/index.js';
 import { Store } from './store/index.js';
 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';
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 const DEFAULT_RULES_DIR = path.resolve(HERE, '..', 'rules');
 const VERSION = readVersion();
@@ -72,10 +77,12 @@ const COMMANDS = {
     rules: cmdRules,
     explain: cmdExplain,
     diff: cmdDiff,
+    'verify-report': cmdVerifyReport,
     init: cmdInit,
     bootstrap: cmdBootstrap,
     learn: cmdLearn,
     evolve: cmdEvolve,
+    standards: cmdStandards,
 };
 export function main(argv) {
     const args = parseArgs(argv);
@@ -107,6 +114,18 @@ export function main(argv) {
             return 2;
     }
 }
+const FORMATS = ['md', 'json', 'sarif'];
+/** Resolves the report format from an explicit flag, else the --out suffix. */
+function resolveFormat(flag, out) {
+    if (flag)
+        return flag.toLowerCase();
+    const ext = path.extname(out).toLowerCase();
+    if (ext === '.json')
+        return 'json';
+    if (ext === '.sarif')
+        return 'sarif';
+    return 'md';
+}
 function parseCountFlag(v) {
     if (v === undefined)
         return undefined;
@@ -114,13 +133,16 @@ function parseCountFlag(v) {
     return Number.isFinite(n) ? n : NaN;
 }
 function readAuditOptions(args) {
+    const out = str(args, 'out', 'AUDIT.md') ?? 'AUDIT.md';
     return {
         target: args._[1] ?? '.',
         rulesDir: path.resolve(str(args, 'rules-dir', DEFAULT_RULES_DIR) ?? DEFAULT_RULES_DIR),
         depth: str(args, 'depth', 'standard') ?? 'standard',
         profileArg: str(args, 'profile', 'auto') ?? 'auto',
-        out: str(args, 'out', 'AUDIT.md') ?? 'AUDIT.md',
+        out,
+        format: resolveFormat(str(args, 'format'), out),
         failOn: (str(args, 'fail-on', 'none') ?? 'none').toLowerCase(),
+        baseline: str(args, 'baseline'),
         quiet: bool(args, 'quiet'),
         maxFiles: parseCountFlag(str(args, 'max-files')),
         maxBytes: parseCountFlag(str(args, 'max-bytes')),
@@ -132,6 +154,8 @@ function validateAuditOptions(o) {
     if (o.profileArg !== 'auto' && !MATURITIES.includes(o.profileArg)) {
         return `--profile must be auto or one of ${MATURITIES.join('|')}`;
     }
+    if (!FORMATS.includes(o.format))
+        return `--format must be one of ${FORMATS.join('|')}`;
     if (o.maxFiles !== undefined && !(o.maxFiles > 0))
         return '--max-files must be a positive number';
     if (o.maxBytes !== undefined && !(o.maxBytes > 0))
@@ -174,13 +198,61 @@ function cmdAudit(args) {
     });
     for (const w of warnings)
         console.error(`warning: ${w}`);
-    const markdown = renderMarkdown(report, profile);
-    fs.writeFileSync(o.out, markdown, 'utf8');
+    const rendered = renderReport(report, profile, o.format);
+    fs.writeFileSync(o.out, rendered, 'utf8');
     if (!o.quiet) {
         console.log(summaryLine(report));
         console.log(`  report → ${o.out}`);
     }
-    return evaluateGate(report, o.failOn, o.quiet);
+    // Without --baseline the absolute gate below is byte-identical to before:
+    // same function, same arguments, same exit codes.
+    if (!o.baseline)
+        return evaluateGate(report, o.failOn, o.quiet);
+    return runBaselineGate(report, o.baseline, o.failOn, o.quiet, args);
+}
+/**
+ * New-code gate: fail only on findings this change introduced or regressed,
+ * compared against a previous report's trailer. Every baseline failure mode
+ * exits 2 loudly — a gate that cannot read its baseline must never pass.
+ */
+function runBaselineGate(report, baselinePath, failOn, quiet, args) {
+    let text;
+    try {
+        text = fs.readFileSync(baselinePath, 'utf8');
+    }
+    catch {
+        console.error(`--baseline file not found or unreadable: ${baselinePath}`);
+        return 2;
+    }
+    // Tolerate a raw YAML trailer file, mirroring `usa diff`.
+    const trailerYaml = parseTrailer(text) ?? text;
+    if (!trailerYaml.trim()) {
+        console.error(`--baseline has no report trailer and no YAML content: ${baselinePath}`);
+        return 2;
+    }
+    try {
+        const baseline = parseBaselineTrailer(trailerYaml);
+        // An explicit --fail-on (even none) wins; otherwise the new-code gate
+        // defaults to HIGH so legacy MEDIUM/LOW debt never blocks adoption.
+        const threshold = failOn === 'none' && args['baseline'] !== undefined && args['fail-on'] === undefined
+            ? 'high'
+            : failOn;
+        return evaluateNewCodeGate(report, baseline, threshold, quiet);
+    }
+    catch (err) {
+        console.error(`--baseline is malformed (${baselinePath}): ${err.message}`);
+        return 2;
+    }
+}
+function renderReport(report, profile, format) {
+    switch (format) {
+        case 'json':
+            return renderJson(report);
+        case 'sarif':
+            return renderSarif(report);
+        default:
+            return renderMarkdown(report, profile);
+    }
 }
 function summaryLine(report) {
     const s = report.score.severityCounts;
@@ -262,17 +334,36 @@ function cmdExplain(args) {
     }
     const rulesDir = path.resolve(str(args, 'rules-dir', DEFAULT_RULES_DIR) ?? DEFAULT_RULES_DIR);
     const { packs } = loadRulePacks(rulesDir);
+    const { catalogues } = loadCatalogues(rulesDir);
     for (const pack of packs) {
         const rule = pack.rules.find((r) => r.id.toLowerCase() === id.toLowerCase());
         if (!rule)
             continue;
-        printRuleDetail(pack.id, rule);
+        printRuleDetail(pack.id, rule, catalogues);
         return 0;
     }
     console.error(`Rule not found: ${id}`);
     return 1;
 }
-function printRuleDetail(packId, rule) {
+function cmdStandards(args) {
+    const rulesDir = path.resolve(str(args, 'rules-dir', DEFAULT_RULES_DIR) ?? DEFAULT_RULES_DIR);
+    const { packs } = loadRulePacks(rulesDir);
+    const { catalogues } = loadCatalogues(rulesDir);
+    const rows = catalogueCoverage(packs, catalogues);
+    const fmt = (str(args, 'format') ?? 'md').toLowerCase();
+    if (fmt === 'json') {
+        console.log(JSON.stringify(rows, null, 2));
+        return 0;
+    }
+    // Markdown table: catalogue → rules → how many the engine can fully decide.
+    console.log('| Catalogue | Rules | Fully automated | Assisted | Manual |');
+    console.log('| --------- | ----- | --------------- | -------- | ------ |');
+    for (const row of rows) {
+        console.log(`| ${row.name} (\`${row.catalogue}\`) | ${row.rules} | ${row.automatable.full} | ${row.automatable.assist} | ${row.automatable.manual} |`);
+    }
+    return 0;
+}
+function printRuleDetail(packId, rule, catalogues) {
     console.log(`# ${rule.id} — ${rule.title}`);
     console.log();
     console.log(`pack      : ${packId}`);
@@ -281,6 +372,10 @@ function printRuleDetail(packId, rule) {
     console.log(`class     : ${rule.ruleClass}`);
     console.log(`weight    : ${rule.weight ?? 'default'}`);
     console.log(`depths    : ${rule.depths?.join(', ') ?? 'all'}`);
+    console.log(`automatable: ${ruleAutomatability(rule)}`);
+    const catalogue = catalogueOf(rule, catalogues);
+    if (catalogue)
+        console.log(`catalogue : ${catalogue}`);
     console.log(`check     : ${JSON.stringify(rule.check)}`);
     printRuleOptional(rule);
 }
@@ -321,6 +416,80 @@ function cmdDiff(args) {
         return 2;
     }
 }
+/* -------------------------------------------------------- verify-report -- */
+/** Reads a text input, or reports it loudly and returns null (exit 2). */
+function readTextInput(file, label) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        console.error(`${label} not found or unreadable: ${file}`);
+        return null;
+    }
+}
+function cmdVerifyReport(args) {
+    const reportPath = args._[1];
+    const bundlePath = str(args, 'bundle');
+    if (!reportPath || !bundlePath) {
+        console.error('Usage: usa verify-report <AUDIT.md> --bundle <sidecar.sig.json> [--key <pubkey>] [--cosign-binary <path>] [--quiet]');
+        return 2;
+    }
+    const markdown = readTextInput(reportPath, 'Report file');
+    if (markdown === null)
+        return 2;
+    const sidecarRaw = readTextInput(bundlePath, 'Signature sidecar');
+    if (sidecarRaw === null)
+        return 2;
+    const trailerYaml = parseTrailer(markdown);
+    if (!trailerYaml || !trailerYaml.trim()) {
+        console.error(`Report has no machine-readable trailer: ${reportPath}`);
+        return 2;
+    }
+    let signature;
+    try {
+        signature = parseDetachedSignature(sidecarRaw);
+    }
+    catch (err) {
+        console.error(`Signature sidecar is malformed (${bundlePath}): ${err.message}`);
+        return 2;
+    }
+    // Payload bytes are exactly canonicalReportBytes(report) for the report
+    // that rendered this trailer: the trailer projection plus '\n'. The CLI
+    // only ever sees rendered bytes, so it reconstructs them from the parsed
+    // trailer rather than re-deriving a report object.
+    const payload = Buffer.from(`${trailerYaml}\n`, 'utf8');
+    return runSignatureVerify(args, reportPath, payload, signature);
+}
+/**
+ * Runs the cosign verification and maps the outcome onto the gate
+ * convention: 0 verified, 1 mismatch/failed, 2 environment refusal (an
+ * absent cosign binary throws — a loud error, never a fake pass).
+ */
+function runSignatureVerify(args, reportPath, payload, signature) {
+    const quiet = bool(args, 'quiet');
+    const cosignBinary = str(args, 'cosign-binary');
+    let result;
+    try {
+        result = verifyDetachedSignature(payload, signature, {
+            publicKeyPath: str(args, 'key') ?? '',
+            ...(cosignBinary === undefined ? {} : { cosignBinary }),
+        });
+    }
+    catch (err) {
+        console.error(err.message);
+        return 2;
+    }
+    if (result.ok) {
+        if (!quiet)
+            console.log(`Signature verified: ${reportPath}`);
+        return 0;
+    }
+    // Gate convention: the mismatch detail goes to stderr, suppressed by
+    // --quiet; the exit code alone carries the verdict then.
+    if (!quiet)
+        console.error(`Signature verification failed for ${reportPath}: ${result.detail}`);
+    return 1;
+}
 /* -------------------------------------------------------------- bootstrap -- */
 function cmdBootstrap(args) {
     const target = args._[1] ?? '.';
@@ -619,10 +788,12 @@ usa — Universal Software Auditor
   usa rules [--section S2]      List all loaded rule packs and rules
   usa explain <RULE-ID>         Show everything about one rule
   usa diff <before> <after>     Compare two previously generated reports
+  usa verify-report <AUDIT.md>  Verify a report's detached signature sidecar
   usa init [path]               Scaffold .usa.yaml + a GitHub Actions workflow
   usa bootstrap [path]          Propose rule packs for stacks USA cannot audit yet
   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
 
 evolve options
   --store <dir>        Persist audit runs/results (content-addressed store)
@@ -638,8 +809,13 @@ learn options
   --out <file>        Output YAML file (default learn-suggestions.yaml)
   --min-severity <s>  Minimum severity to consider (CRITICAL|HIGH|MEDIUM|LOW|FUTURE, default MEDIUM)
 
+standards options
+  --format <fmt>      md | json                       (default md)
+  --rules-dir <dir>   Rule pack directory             (default bundled rules/)
+
 audit options
   --out <file>        Report path (default AUDIT.md)
+  --format <fmt>      md | json | sarif        (default: inferred from --out)
   --depth <level>     quick | standard | deep          (default standard)
   --profile <stage>   auto | prototype | mvp | beta | production | legacy
   --rules-dir <dir>   Rule pack directory             (default bundled rules/)
@@ -649,6 +825,9 @@ audit options
   --fact <ns:value>   Assert a fact detection missed, e.g. --fact has:database
   --allow-commands    Run \`command:\` checks (shells out; off by default)
   --fail-on <sev>     Exit 1 on findings >= sev: critical|high|medium|low|none
+  --baseline <file>   New-code gate: only fail on findings new or regressed
+                      vs this previous report (default threshold high;
+                      explicit --fail-on overrides it)
   --quiet             Only errors
   --max-files <n>     Index at most n files (overrides config; default 60000)
   --max-bytes <n>     Skip files larger than n bytes (overrides config; default 2 MiB)
@@ -656,12 +835,20 @@ audit options
 bootstrap options
   --out <file|dir>    Write pack files instead of printing (default: print)
 
+verify-report options
+  --bundle <file>       Signature sidecar (required, e.g. AUDIT.md.sig.json)
+  --key <file>          PEM public key the bundle is verified against
+  --cosign-binary <bin> Override the cosign binary (default cosign)
+  --quiet               Only errors
+
 examples
   usa audit . --depth deep
   usa bootstrap ~/code/legacy-php-app --out /tmp/packs
   usa audit ../api --profile production --fail-on high
+  usa audit . --baseline reports/2026-08.md --fail-on high
   usa audit . --out reports/audit-$(date +%F).md
   usa learn AUDIT.md --out swift-suggestions.yaml
+  usa verify-report AUDIT.md --bundle AUDIT.md.sig.json --key cosign.pub
 `.trim();
 const WORKFLOW_TEMPLATE = `# USA — Universal Software Auditor
 # Runs on every PR and pushes a Markdown summary you can read in the Actions UI.