mjolnir-qa 1.0.8 → 2.0.0

package/dist/cli.d.mts

@@ -179,6 +179,25 @@ interface Finding {
    * Additive within schemaVersion 1.
    */
   fixGroupId?: string;
+  /**
+   * ENGINE-002: disambiguated finding identity (fingerprint + line +
+   * column). Unique per occurrence when the same rule fires multiple
+   * times in one file. Additive within schemaVersion 1.
+   */
+  findingId?: string;
+  /**
+   * ENGINE-002: root-cause identity — initially the same as the
+   * fingerprint (ruleId + file + message). Future rules may coarsen
+   * this to group findings by underlying cause. Additive within
+   * schemaVersion 1.
+   */
+  rootCauseId?: string;
+  /**
+   * ENGINE-002: deduplication group — initially the same as
+   * rootCauseId. Future rules may further coarsen this. Additive
+   * within schemaVersion 1.
+   */
+  deduplicationGroup?: string;
 }
 /**
  * Mutation evidence (master plan P5, plan 1788853205786 — flag 6,
@@ -268,6 +287,15 @@ interface ScanResult {
     name: string;
     rules: number;
   }>;
+  /**
+   * Rules whose suiteInvalidating findings capped the score (e.g.
+   * QA-TEST-001 when `.only` is committed). Additive within
+   * schemaVersion 1; absent when no suite-invalidating rule fired.
+   * Present to explain why the score may be 49 even when all findings
+   * are advisory (E0/quarantine) — the factual state (suite did not
+   * fully execute) prevents a perfect score regardless of severity.
+   */
+  suiteInvalidatedBy?: string[];
   /**
    * Agentic Trust Profile (plan §17): per-scan provenance metadata —
    * share of test files carrying detected generative markers and the
@@ -304,6 +332,13 @@ interface ScanResult {
      */
     rulesCrashed?: number;
   };
+  /**
+   * Scoring model version stamped into the result (ENGINE-001). Allows
+   * consumers to identify which scoring formula produced the score.
+   * Additive within schemaVersion 1; absent when the producer predates
+   * this field.
+   */
+  scoringModelVersion?: string;
   /**
    * Scope Integrity block (product-gap master plan §7, R4c): the
    * claimed-vs-analyzed accounting. `scopeVerdict` is PROVEN only when
@@ -340,6 +375,9 @@ interface ScanResult {
     rulesDigest: string;
     configFingerprint: string;
     engineVersion: string;
+    trustModelVersion?: string;
+    scoringModelVersion?: string;
+    frameworkSupportMatrixVersion?: string;
   };
   /**
    * Evidence Graph (R4c): the chain-law links (VERDICT ← EVIDENCE ←
@@ -385,6 +423,48 @@ interface ScanResult {
    * src/engine/trust-summary.ts — the single definition site.
    */
   trustSummary?: TrustSummary;
+  /**
+   * Cross-Rule Evidence Correlation Engine (INTEL-005) conclusions.
+   * Produced by `correlateFindings()` after scoring; purely additive —
+   * findings are never modified. Present on every completed scan with
+   * ≥ 1 finding. Additive within schemaVersion 1.
+   */
+  correlationConclusions?: Array<{
+    conclusionType: "CONVERGENT" | "CORROBORATED" | "CONTRADICTED" | "AMPLIFIED" | "INDEPENDENT";
+    certainty: "NONE" | "SUPPORTING" | "STRONG";
+    corroboration: string;
+    sourceCount: number;
+    findingIds: string[];
+  }>;
+  /**
+   * Dependency graph metadata (ECO-005). Present when a dependency
+   * manifest (package.json, pyproject.toml, pom.xml) was found.
+   * Additive within schemaVersion 1.
+   */
+  dependencyGraph?: {
+    /** Number of nodes in the dependency graph. */
+    nodes: number;
+    /** Number of edges (total dependency references). */
+    edges: number;
+  };
+  /**
+   * Monorepo analysis results (ECO-003). Present when --monorepo was
+   * requested and multiple packages were found. Additive within
+   * schemaVersion 1.
+   */
+  monorepoAnalysis?: {
+    packages: Array<{
+      packageName: string;
+      path: string;
+      findings: number;
+      score: number | null;
+      verdict: "pass" | "warn" | "fail";
+    }>;
+    overallScore: number | null;
+    overallVerdict: "pass" | "warn" | "fail";
+    strategy: "worst-package" | "average" | "configurable";
+    blockerPackage?: string;
+  };
 }
 /** Trust summary metric block (plan §6 — measurement, not contract). */
 interface TrustSummary {
@@ -425,6 +505,106 @@ interface OverlapMeta {
   order?: number;
 }
 //#endregion
+//#region src/forensics/classify.d.ts
+declare const FORENSIC_VERDICTS: readonly ["likely-real-defect", "environmental-failure", "infrastructure-failure", "flaky", "retry-dependent", "unstable-construction", "inconclusive"];
+type ForensicVerdict = (typeof FORENSIC_VERDICTS)[number];
+declare const EVIDENCE_STATES: readonly ["exists", "absent", "unsupported", "contradictory", "insufficient"];
+type ForensicEvidenceState = (typeof EVIDENCE_STATES)[number];
+interface ForensicClassification {
+  verdict: ForensicVerdict;
+  evidenceState: ForensicEvidenceState;
+  /** Which signal family won (audit trail for the classification). */
+  signals: {
+    environmental: number;
+    infrastructure: number;
+    construction: number;
+  };
+}
+//#endregion
+//#region src/forensics/types.d.ts
+type RunStatus = "passed" | "failed" | "timedOut" | "skipped" | "interrupted";
+/** Derived per-test reliability facts. */
+interface TestVerdict {
+  file: string;
+  title: string;
+  attempts: number;
+  finalStatus: RunStatus;
+  totalDurationMs: number;
+  /**
+   * TRUE-FLAKE: passed only on attempt >= 2 — not a passing test,
+   * a lucky test.
+   */
+  passedOnRetry: boolean;
+  /** Failed at least once across attempts. */
+  everFailed: boolean;
+  skipped: boolean;
+  /**
+   * 1-based spec declaration line when known (plan §16). Enables
+   * test-level runtime corroboration: a finding between this line and
+   * the next declared test's line in the same file belongs to this
+   * test. Undefined when the report format omits locations (JUnit).
+   */
+  line?: number;
+  /**
+   * WI-18 (growth roadmap §6): the forensic verdict classification —
+   * deterministic minimum-signal table over machine-visible facts
+   * (see forensics/classify.ts). Additive within schemaVersion.
+   */
+  forensic?: ForensicClassification;
+}
+interface ForensicsReport {
+  forensicsSchemaVersion: number;
+  /**
+   * Which report family the records came from. P4 (plan 1788853205786)
+   * widens the union additively: `jest-json` and `vitest-json` ingest
+   * with ONE attempt per record (their reports carry no per-attempt
+   * history), so TRUE-FLAKE can never fire from these sources — honest
+   * degradation, see the parsers' module docs. R5 (WI-17) adds
+   * `playwright-trace`: one record per trace artifact (the per-test
+   * trace convention), action-level facts only.
+   */
+  source: "playwright-json" | "junit-xml" | "jest-json" | "vitest-json" | "playwright-trace";
+  totalTests: number;
+  failed: number;
+  skipped: number;
+  retriedTests: number;
+  flakyTests: number;
+  totalDurationMs: number;
+  verdicts: TestVerdict[];
+  /**
+   * Whether all discovered report files were successfully ingested.
+   * FALSE when any files were skipped due to size limits, parse failures,
+   * or cumulative size cap.
+   */
+  analysisComplete: boolean;
+  /** Number of report files skipped (size limit, corrupt, unsupported). */
+  skippedReports: number;
+  /** Named reasons for incompleteness (e.g. "size-limit", "cumulative-size-limit", "parse-failure"). */
+  incompleteReasons: string[];
+}
+//#endregion
+//#region src/engine/dependency-graph.d.ts
+/**
+ * Dependency Graph (ECO-005).
+ *
+ * Parses package manifests (package.json, pyproject.toml, pom.xml) to
+ * build a dependency graph. Supports transitive dependency resolution,
+ * dependent lookup, and reachable-file computation from test files.
+ */
+interface DependencyNode {
+  path: string;
+  dependencies: string[];
+}
+declare class DependencyGraph {
+  private readonly nodes;
+  addNode(node: DependencyNode): void;
+  getDependencies(path: string): string[];
+  getTransitiveDependencies(path: string): string[];
+  getDependents(path: string): string[];
+  get allPaths(): string[];
+  get size(): number;
+}
+//#endregion
 //#region src/discovery/workspace.d.ts
 /**
  * Repository discovery (Sprint-Plan W1-03).
@@ -440,6 +620,15 @@ interface Workspace {
   workspaceGlobs: string[];
 }
 //#endregion
+//#region src/discovery/frameworks.d.ts
+type TestFramework = "jest" | "vitest" | "playwright";
+interface FrameworkInfo$1 {
+  frameworks: TestFramework[];
+  /** True when no config evidence was found at all. */
+  unknown: boolean;
+}
+declare function detectFrameworks(ws: Workspace): FrameworkInfo$1;
+//#endregion
 //#region src/rules/rule.d.ts
 /**
  * How the rule's primary detection decision is made (Verification Trust
@@ -669,6 +858,12 @@ interface QADoctorRule extends RuleMeta {
   run: RuleFn;
 }
 //#endregion
+//#region src/discovery/ignores.d.ts
+/** An immutable, per-root resolved ignore matcher (audit R-8). */
+interface IgnoreMatcher {
+  isIgnored(relPath: string): boolean;
+}
+//#endregion
 //#region src/engine/adapter.d.ts
 /** Semantic operations a parsed file exposes to rules. */
 interface ParsedFile {
@@ -693,6 +888,87 @@ interface ParsedFile {
    */
   frameworkTags?: readonly string[];
 }
+interface FrameworkInfo {
+  frameworks: string[];
+  unknown: boolean;
+}
+/**
+ * The result of the async parse stage (Verification Trust Evolution Plan
+ * Phase 0.5, §10): an AST plus its explicit disposal path. The scan
+ * pipeline calls `dispose()` exactly once per file, in a
+ * finally-equivalent position that runs whether or not rules completed —
+ * normal completion, rule crash, per-file budget expiry, or scan abort.
+ */
+interface ParsedAst {
+  /** Consumed synchronously by rules via `ParsedFile.ast`. */
+  ast: unknown;
+  /** Release WASM/AST resources (`tree.delete()` for tree-sitter). */
+  dispose(): void;
+}
+interface ScanContext {
+  workspace: Workspace;
+  /** Absolute paths of discovered test files. */
+  testFiles: string[];
+  deadline: number;
+  /** Resolved per-scan ignore matcher (audit R-8) — no module globals. */
+  ignoreMatcher: IgnoreMatcher;
+  /** Called once per file that could not be read/analyzed. */
+  onSkippedFile: (reason: string) => void;
+  /**
+   * Called when discovery stops early (audit H-8): deadline expiry or
+   * the per-adapter file cap. The reason is named in analysisStatus.
+   */
+  onDiscoveryTruncated: (reason: string) => void;
+  /** Per-adapter discovery budget (audit H-8). One language can no
+   * longer consume the whole list and starve the others. */
+  maxFiles: number;
+  /** R4c Scope Integrity: counted matcher exclusions (optional — adapters
+   * whose discovery walks sharedWalk pass this through to the counters). */
+  onIgnored?: () => void;
+  /** R4c Scope Integrity: counted files no adapter claims (optional). */
+  onUnrecognized?: () => void;
+  /**
+   * Called when a rule throws on a file (audit R-9): crash isolation
+   * stays silent by default, but the scan counts it and `--debug`
+   * surfaces it.
+   */
+  onRuleCrash?: (ruleId: string, file: string, error: unknown) => void;
+}
+interface LanguageAdapter {
+  readonly id: string;
+  readonly extensions: readonly string[];
+  /** Human-readable patterns this adapter searches for (empty-state UX). */
+  readonly testFileGlobs: readonly string[];
+  /** Dependency/output directory names this adapter never enters. */
+  readonly dirSkips: readonly string[];
+  /** Canonical test-file check per ecosystem conventions. */
+  isTestFile(path: string): boolean;
+  detectFrameworks(root: string): FrameworkInfo;
+  discoverTestFiles(ctx: ScanContext): void;
+  /**
+   * Async parse stage (Verification Trust Evolution Plan Phase 0.5, §10):
+   * awaited by the scan pipeline between discovery and rule execution.
+   * `runRules` and every rule stay synchronous and consume the produced
+   * tree via `ParsedFile.ast` — the engine is NOT async end-to-end, only
+   * this one seam is (WASM grammar load is inherently async).
+   *
+   * Contract: resolve to a ParsedAst on success, `undefined` when this
+   * adapter has no AST layer (or parsing failed — rules fall back to the
+   * regex path either way). Never throws.
+   */
+  parseAst?(file: ParsedFile): Promise<ParsedAst | undefined>;
+  /**
+   * Run all rules this adapter hosts against one file. `onCrash` is
+   * invoked when a rule throws (audit R-9) — the crash is still
+   * isolated, but never invisible. `budget` (audit P-1) stops rule
+   * execution mid-file when a single file is too expensive to analyze
+   * in full; the caller reports the skip honestly.
+   */
+  runRules(rules: readonly UniversalRule[], file: ParsedFile, emit: (f: Omit<Finding, "ruleId" | "category">, ruleId: string, category: string) => void, onCrash?: (ruleId: string, error: unknown) => void, budget?: {
+    deadline: number;
+    onExceeded: () => void;
+  }): void;
+}
 /**
  * A rule that declares which adapters it supports. Backward compatible:
  * legacy 'test-files' maps to ['typescript'], 'ci-workflows' to
@@ -733,7 +1009,62 @@ interface UniversalRule {
   run(file: ParsedFile): Array<Omit<Finding, "ruleId" | "category">>;
 }
 //#endregion
-//#region src/engine/scan-pipeline.d.ts
+//#region src/engine/provenance.d.ts
+type FileProvenance = "unmarked" | "generated-marked" | "codegen-like";
+/** Classify one file's provenance. Pure. */
+declare function classifyProvenance(file: {
+  text: string;
+  codeText?: string;
+}): FileProvenance;
+//#endregion
+//#region src/engine/scan-cache.d.ts
+interface CacheStats {
+  hits: number;
+  misses: number;
+  /** Where the cache lives — reported so `--json` consumers can audit it. */
+  file: string;
+}
+interface ScanCache {
+  readonly stats: CacheStats;
+  lookup(key: string): Finding[] | undefined;
+  store(key: string, findings: Finding[], fileBudgetExceeded: boolean): void;
+  persist(): void;
+}
+//#endregion
+//#region src/config/config.d.ts
+interface IgnoreEntry {
+  ruleId: string;
+  files?: string[];
+  reason: string;
+  /** ISO date; defaults to 90 days from creation (S11). */
+  expires?: string;
+}
+interface QADoctorConfig {
+  gate?: "advisory" | "error" | "warning";
+  /** Path globs to skip during discovery (see DEFAULT_IGNORES dialect). */
+  exclude?: string[];
+  severityOverrides?: Record<string, Severity>;
+  ignore?: IgnoreEntry[];
+}
+declare function loadConfig(root: string, options?: {
+  knownRuleIds?: ReadonlySet<string>;
+}): {
+  config: QADoctorConfig;
+  path: string | null;
+  /** Non-fatal notes (e.g. unknown rule IDs in severityOverrides). */
+  warnings: string[];
+};
+declare namespace scan_pipeline_d_exports {
+  export { AssembleScanResultInput, CliArgs, DiscoveryResult, EVIDENCE_OVERRIDES$1 as EVIDENCE_OVERRIDES, FileAnalysisResult, KNOWN_RULE_IDS$1 as KNOWN_RULE_IDS, OVERLAP_META_BY_RULE_ID$1 as OVERLAP_META_BY_RULE_ID, PostScanResult, SUITE_INVALIDATING_RULE_IDS$1 as SUITE_INVALIDATING_RULE_IDS, ScanHooks, applyPostScanProcessing, assembleScanResult, buildUniversalRules$1 as buildUniversalRules, discoverAndParseRuntimeReport$1 as discoverAndParseRuntimeReport, discoverTestFilesPhase, fallbackWorkspace$1 as fallbackWorkspace, isValidFindingRecord$1 as isValidFindingRecord, pathMatchesGlob$1 as pathMatchesGlob, runFileAnalysisPhase, runScan$1 as runScan, selectAdapter };
+}
+/** Registered rule IDs — used to warn on unknown severityOverrides keys (M4). */
+declare const KNOWN_RULE_IDS$1: ReadonlySet<string>;
+/**
+ * R6 (Bug Map M-02): per-rule overlap metadata, built from RULES the
+ * same way tierByRuleId is — `asUniversal` drops `overlapWith`, so the
+ * dedup map must come from the registry directly.
+ */
+declare const OVERLAP_META_BY_RULE_ID$1: ReadonlyMap<string, OverlapMeta>;
 declare function buildUniversalRules$1(root: string, strict?: boolean, opts?: {
   /** CLI trust-gate flag (`--enable-plugins`) for this scan. */
   enablePlugins?: boolean;
@@ -749,6 +1080,13 @@ declare function buildUniversalRules$1(root: string, strict?: boolean, opts?: {
   }>;
   externalRules: QADoctorRule[];
 }>;
+/** Rule-declared evidence-level overrides (Honesty Core). */
+declare const EVIDENCE_OVERRIDES$1: ReadonlyMap<string, string>;
+/**
+ * Rules whose findings void the suite's pass claim (RuleMeta.suiteInvalidating).
+ * Built from the registry so the scorer never has to import it.
+ */
+declare const SUITE_INVALIDATING_RULE_IDS$1: ReadonlySet<string>;
 interface CliArgs {
   target: string;
   json: boolean;
@@ -824,6 +1162,13 @@ interface CliArgs {
    * Report is the hero output.
    */
   classic?: boolean;
+  /**
+   * --monorepo: per-package trust analysis (ECO-003). When enabled, the
+   * scan discovers packages and computes per-package scores with
+   * configurable aggregation. Additive flag; absent means "single-project
+   * mode" (no monorepo analysis).
+   */
+  monorepo?: boolean;
 }
 interface ScanHooks {
   /** Invoked when a rule throws on a file (audit R-9). */
@@ -877,11 +1222,14 @@ declare function pathMatchesGlob$1(path: string, glob: string): boolean;
  * accepts. Zero-config search over conventional artifact names at
  * depth ≤ 2 (src/discovery/evidence-discovery.ts); the FIRST parsable
  * candidate wins (priority: mjolnir-report > playwright-json >
- * test-results-dir > junit-file). Returns the path for `runForensics`,
- * or undefined when no convention is present ("no runtime evidence" —
- * never guessed; the CLI surfaces the missing-evidence message).
+ * test-results-dir > junit-file). Validates each candidate by attempting
+ * to parse it and checking that it produces at least one test. Returns
+ * the parsed report alongside the path to avoid double-parsing.
  */
-declare function discoverRuntimeReport$1(scanRoot: string): string | undefined;
+declare function discoverAndParseRuntimeReport$1(scanRoot: string): {
+  path: string;
+  report: ForensicsReport;
+} | undefined;
 /**
  * Audit W10 — runtime shape validation at the rule→Finding boundary.
  * A finding record coming out of a rule (plugin/JSON-manifest rules are
@@ -892,6 +1240,84 @@ declare function discoverRuntimeReport$1(scanRoot: string): string | undefined;
  * caller) — never silently scored.
  */
 declare function isValidFindingRecord$1(f: unknown): f is Omit<Finding, "ruleId" | "category">;
+/**
+ * Replace 7-way nested ternary with a linear probe.
+ * Returns the adapter whose `isTestFile` matches the path, falling
+ * back to the TypeScript adapter (the default language).
+ */
+declare function selectAdapter(path: string): LanguageAdapter;
+interface DiscoveryResult {
+  testFiles: string[];
+  stagedSurface: boolean;
+}
+declare function discoverTestFilesPhase(workspace: Workspace, args: CliArgs, hooks: ScanHooks, scanRoot: Workspace, ctx: ScanContext): DiscoveryResult;
+interface FileAnalysisResult {
+  skippedFiles: number;
+  testFileCount: number;
+  testDeclarationCount: number;
+  rulesPartial: boolean;
+  parseFailed: number;
+  scanned: number;
+}
+declare function runFileAnalysisPhase(findings: Finding[], testFiles: string[], workspace: Workspace, activeRules: UniversalRule[], hooks: ScanHooks, cache: ScanCache, rulesDigest: string, deadline: number, truncationReasons: Set<string>, declarationsByFile: Map<string, number>, fileProvenance: Array<{
+  path: string;
+  provenance: ReturnType<typeof classifyProvenance>;
+}>, onRuleCrash: (ruleId: string, file: string, error: unknown) => void): Promise<FileAnalysisResult>;
+interface PostScanResult {
+  testDeclarationCount: number;
+  scopeInfo: {
+    scope: "all" | "changed";
+    degraded?: string | undefined;
+  };
+  suppressionCount: number;
+  frameworks: ReturnType<typeof detectFrameworks>;
+  runtimeReportPath: string | undefined;
+  config: ReturnType<typeof loadConfig>["config"];
+}
+declare function applyPostScanProcessing(findings: Finding[], workspace: Workspace, args: CliArgs, hooks: ScanHooks, scanRoot: Workspace, declarationsByFile: Map<string, number>, testDeclarationCount: number, tierByRuleId: Map<string, Tier>, REVISION_BY_RULE_ID: Map<string, number>): PostScanResult;
+interface AssembleScanResultInput {
+  findings: Finding[];
+  testFileCount: number;
+  testDeclarationCount: number;
+  declarationsByFile: Map<string, number>;
+  skippedFiles: number;
+  rulesCrashed: number;
+  truncationReasons: Set<string>;
+  discoveryTruncated: boolean;
+  rulesPartial: boolean;
+  scopeIgnored: number;
+  scopeUnrecognized: number;
+  parseFailed: number;
+  scanned: number;
+  testFiles: string[];
+  workspace: Workspace;
+  scanRoot: Workspace;
+  args: CliArgs;
+  hooks: ScanHooks;
+  cache: ScanCache;
+  REVISION_BY_RULE_ID: Map<string, number>;
+  pluginsLoaded: Array<{
+    name: string;
+    rules: number;
+  }>;
+  scopeInfo: {
+    scope: "all" | "changed";
+    degraded?: string | undefined;
+  };
+  suppressionCount: number;
+  frameworks: ReturnType<typeof detectFrameworks>;
+  runtimeReportPath: string | undefined;
+  config: ReturnType<typeof loadConfig>["config"];
+  fileProvenance: Array<{
+    path: string;
+    provenance: ReturnType<typeof classifyProvenance>;
+  }>;
+  started: number;
+  stagedSurface: boolean;
+  /** ECO-005: dependency graph built from project manifests. */
+  dependencyGraph?: DependencyGraph;
+}
+declare function assembleScanResult(o: AssembleScanResultInput): ScanResult;
 /**
  * Testable default scan path core. `hooks` lets callers observe
  * normally-invisible events (swallowed rule crashes) without changing
@@ -913,7 +1339,7 @@ declare function runScan$1(args: CliArgs, hooks?: ScanHooks): Promise<ScanResult
  * scripts/sync-sarif-version.cjs and guarded by the version-consistency
  * spec. cli.ts re-exports this as CLI_VERSION.
  */
-declare const ENGINE_VERSION = "1.0.8";
+declare const ENGINE_VERSION = "2.0.0";
 //#endregion
 //#region src/cli-io.d.ts
 /**
@@ -925,172 +1351,225 @@ declare const ENGINE_VERSION = "1.0.8";
  */
 /** The variadic IO signature shared by all command handlers. */
 type Output = (...parts: unknown[]) => void;
-declare const out: Output;
-declare const err: Output;
-declare function internalErrorMessage(err: unknown, emit: (s: string) => void, debug: boolean): void;
-//#endregion
-//#region src/commands/doctor-run.d.ts
-declare function runDoctorCommand(argv: string[], io?: {
-  out: Output;
-  err: Output;
-}): number;
+export declare const out: Output;
+export declare const err: Output;
+export declare function internalErrorMessage(err: unknown, emit: (s: string) => void, debug: boolean): void;
 //#endregion
-//#region src/cli.d.ts
-declare const runScan: typeof runScan$1, buildUniversalRules: typeof buildUniversalRules$1, fallbackWorkspace: typeof fallbackWorkspace$1, pathMatchesGlob: typeof pathMatchesGlob$1, isValidFindingRecord: typeof isValidFindingRecord$1, discoverRuntimeReport: typeof discoverRuntimeReport$1, KNOWN_RULE_IDS: ReadonlySet<string>, OVERLAP_META_BY_RULE_ID: ReadonlyMap<string, OverlapMeta>, EVIDENCE_OVERRIDES: ReadonlyMap<string, string>, SUITE_INVALIDATING_RULE_IDS: ReadonlySet<string>;
-/** A usage-error detail: the offending token, when one exists. */
-interface UsageErrorDetail {
-  /** The unknown flag or rejected value (e.g. `--nope`, `loud`). */
-  token?: string | undefined;
-  /** The flag whose value was rejected (`--tone` for `--tone loud`). */
-  flag?: string | undefined;
-}
-declare function parseArgs(argv: string[], onError?: (detail: UsageErrorDetail) => void): CliArgs | null;
-/** Hand-rolled Levenshtein distance (plan M2: no new dependencies). */
-declare function levenshtein(a: string, b: string): number;
-/** Nearest known flags within distance ≤ 2, nearest first. */
-declare function nearestFlags(flag: string, max?: number): string[];
+//#region src/cli-handlers.d.ts
 /**
- * Friendly usage error (plan M2, exit 10 preserved): nearest-flag
- * suggestion, the valid neighbors, and the exact help command. Printed
- * to stderr; findings/usage stay on their documented streams.
+ * Render scan output in the requested format.
+ *
+ * Extracted from runScanCommand (Task 6) to reduce cyclomatic complexity.
+ * Handles sarif, mermaid, codequality, json, and terminal (trust-report)
+ * rendering. The caller handles first-run hint + milestones separately.
  */
-declare function usageErrorMessage(detail: UsageErrorDetail): string;
-/** Testable `ci install` handler. Returns the process exit code. */
-declare function runCiInstall(argv: string[], io?: {
+export declare function renderScanOutput(result: Awaited<ReturnType<typeof runScan$1>>, args: CliArgs, target: string, io: {
   out: Output;
   err: Output;
-}): number;
-/** Testable `suppressions` handler. */
-declare function runSuppressions(io?: {
+}): void;
+export declare function runScanCommand(argv: string[], io?: {
   out: Output;
-  err?: Output;
-}): number;
-/** Testable `forensics` handler. */
-declare function runForensicsCommand(argv: string[], io?: {
+  err: Output;
+}): Promise<number>;
+export declare function runTriageCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): number;
-/** Testable `doctor:playwright` handler. */
-declare function runDoctorPlaywright(argv: string[], io?: {
+export declare function runMutationCommand(argv: string[], io?: {
   out: Output;
-  err?: Output;
+  err: Output;
 }): Promise<number>;
-/** Testable `rules` handler — rule catalog with Trust Metadata. */
-declare function runRulesCommand(argv: string[], io?: {
+export declare function runBadgeCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): Promise<number>;
-/**
- * Testable `explain <RULE-ID>` handler (Plan.md Sprint 1.3,
- * Master-Stabilization-Plan Sprint 5 Task 19). Metadata always renders
- * offline from the registry; the concrete example is real detector
- * output from the rule's own must-fire fixture when one is findable
- * (this repo checkout, or --fixtures-root), and honestly omitted
- * otherwise — never a fabricated example.
- */
-declare function runExplainCommand(argv: string[], io?: {
+export declare function runDebtCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): Promise<number>;
-declare function runScanCommand(argv: string[], io?: {
+export declare function runFixCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): Promise<number>;
-/**
- * Exit-code decision for a finished scan under the given gate level
- * (audit H-7): the previously-dead config.gate field now selects which
- * severities block. Advisory (E0) findings never gate at any level.
- */
-declare function exitForFindings(findings: readonly Finding[], gate: "advisory" | "error" | "warning"): number;
-/** Testable `triage` handler (Tier 5 #22). */
-declare function runTriageCommand(argv: string[], io?: {
+export declare function runCreateRuleCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): number;
-/** Testable `mutation` handler (master plan P5, plan 1788853205786).
- * Reads a mutation report (Stryker JSON / mutmut junitxml), renders the
- * survived-mutant leaderboard, and — with `--scan <path>` — re-scans the
- * target, stamps matching findings with `mutationEvidence` (E1→E2 by
- * derivation) and renders the stamped findings. NEVER spawns mutation
- * tools: it reads reports the user already produced. Exit 2 when
- * nothing in the report is recognized — honest no-evidence, not an
- * error. Exit 0 in every other case: the reader is report-only, never a
- * gate. */
-declare function runMutationCommand(argv: string[], io?: {
+export declare function runImpactCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): Promise<number>;
-/** Testable `badge` handler (Tier 1 #5). */
-declare function runBadgeCommand(argv: string[], io?: {
+export declare function runBaselineCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): Promise<number>;
-/** Testable `debt` handler (Tier 5 #27). */
-declare function runDebtCommand(argv: string[], io?: {
+export declare function runVerifyCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): Promise<number>;
-/** Testable `fix` handler (Tier 1 #3) — safe auto-fix with proof. */
-declare function runFixCommand(argv: string[], io?: {
+export declare function runDiffCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): Promise<number>;
-/** Testable `create-rule` handler (Tier 6 #34). */
-declare function runCreateRuleCommand(argv: string[], io?: {
+export declare function runPrCommentCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): Promise<number>;
+export declare function runStatsCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): number;
-/** Testable `impact` handler (Sprint 6 Task 23). */
-declare function runImpactCommand(argv: string[], io?: {
+export declare function runHandoverCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): Promise<number>;
-/** Testable `baseline` handler (Sprint 6 Task 24). */
-declare function runBaselineCommand(argv: string[], io?: {
+export declare function runInitCommand(argv: string[], io?: {
   out: Output;
   err: Output;
-}): Promise<number>;
-/** Testable `diff` handler (Sprint 6 Task 24) — new/worsened debt only. */
-/** Testable `verify` handler — the agent-loop verb (master plan P7,
- * plan 1788853205786). Scans the target and diffs against the committed
- * baseline, rendering the before/after digest the agent loop consumes
- * (resolved per §15 · new · unchanged by ruleId+location · score delta).
- * Exit semantics are the frozen contract: 0 clean · 1 new error
- * findings · 2 partial scan or no baseline · 20 internal. */
-declare function runVerifyCommand(argv: string[], io?: {
+}): number;
+export declare function runPwReportCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+export declare function runForensicsCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+export declare function runRulesCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): Promise<number>;
-declare function runDiffCommand(argv: string[], io?: {
+export declare function runExplainCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): Promise<number>;
-/** Testable `pr-comment` handler (Sprint 6 Task 25). */
-declare function runPrCommentCommand(argv: string[], io?: {
+export declare function runDoctorPlaywright(argv: string[], io?: {
+  out: Output;
+  err?: Output;
+}): Promise<number>;
+//#endregion
+//#region src/commands/doctor-run.d.ts
+export declare function runDoctorCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+//#endregion
+//#region src/commands/summary.d.ts
+/**
+ * Testable summary command core. Returns the process exit code.
+ * Streams: annotations → stdout (always; GitHub greps them), summary →
+ * step-summary file when set unless --stdout. Unknown flags are a
+ * usage error (exit 10) — a typo'd --stdout must not silently route
+ * the summary to $GITHUB_STEP_SUMMARY.
+ */
+export declare function runSummaryCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}): number;
+//#endregion
+//#region src/commands/why.d.ts
+/**
+ * Testable why command core. Returns the process exit code.
+ * Live mode awaits the real scan; saved-report mode is synchronous.
+ */
+export declare function runWhyCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): Promise<number>;
-/** Testable `stats` handler (Sprint 6 Task 26). */
-declare function runStatsCommand(argv: string[], io?: {
+//#endregion
+//#region src/commands/handoff.d.ts
+/**
+ * Testable handoff command core. Returns the process exit code.
+ * `mjolnir handoff [mjolnir.json] [--category <cat>]... [--rules <ids>]`
+ */
+export declare function runHandoffCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): number;
-/** Testable `handover` handler (Tier 5 #28). */
-declare function runHandoverCommand(argv: string[], io?: {
+//#endregion
+//#region src/commands/install-agents.d.ts
+/**
+ * Testable install command core. Returns the process exit code.
+ * `mjolnir install [--dry-run] [--force]` — probes the given cwd
+ * (production default: process.cwd()).
+ */
+export declare function runInstallCommand(argv: string[], io?: {
+  out: Output;
+  err: Output;
+}, cwd?: string): number;
+//#endregion
+//#region src/commands/trust-report.d.ts
+export declare function runTrustReportCommand(argv: string[], io: {
   out: Output;
   err: Output;
 }): Promise<number>;
-/** Testable `init` handler (Tier 2 #10). */
-declare function runInitCommand(argv: string[], io?: {
+//#endregion
+//#region src/commands/release-trust.d.ts
+/**
+ * CLI verb: `mjolnir release-trust [--json] [repo-root]`.
+ * Exit contract (frozen set): 0 verdict PASS · 1 verdict non-PASS ·
+ * 2 no fixtures root (not an mjolnir checkout — BLOCKED context) ·
+ * 10 usage error · 20 internal error.
+ */
+export declare function runReleaseTrustCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): number;
-/** Testable `pw-report` handler (Tier 2 #9 wedge). */
-declare function runPwReportCommand(argv: string[], io?: {
+//#endregion
+//#region src/cli.d.ts
+export declare const runScan: typeof runScan$1, buildUniversalRules: typeof buildUniversalRules$1, fallbackWorkspace: typeof fallbackWorkspace$1, pathMatchesGlob: typeof pathMatchesGlob$1, isValidFindingRecord: typeof isValidFindingRecord$1, discoverAndParseRuntimeReport: typeof discoverAndParseRuntimeReport$1, KNOWN_RULE_IDS: ReadonlySet<string>, OVERLAP_META_BY_RULE_ID: ReadonlyMap<string, OverlapMeta>, EVIDENCE_OVERRIDES: ReadonlyMap<string, string>, SUITE_INVALIDATING_RULE_IDS: ReadonlySet<string>;
+/** A usage-error detail: the offending token, when one exists. */
+export interface UsageErrorDetail {
+  /** The unknown flag or rejected value (e.g. `--nope`, `loud`). */
+  token?: string | undefined;
+  /** The flag whose value was rejected (`--tone` for `--tone loud`). */
+  flag?: string | undefined;
+}
+export declare function parseArgs(argv: string[], onError?: (detail: UsageErrorDetail) => void): CliArgs | null;
+/** Hand-rolled Levenshtein distance (plan M2: no new dependencies). */
+export declare function levenshtein(a: string, b: string): number;
+/** Nearest known flags within distance ≤ 2, nearest first. */
+export declare function nearestFlags(flag: string, max?: number): string[];
+/**
+ * Friendly usage error (plan M2, exit 10 preserved): nearest-flag
+ * suggestion, the valid neighbors, and the exact help command. Printed
+ * to stderr; findings/usage stay on their documented streams.
+ */
+export declare function usageErrorMessage(detail: UsageErrorDetail): string;
+/**
+ * Shared parse-or-report path for scan-backed subcommands: friendly
+ * usage errors on stderr (exit 10), the full overview only for an
+ * explicit help flag. Returns null when the caller must exit 10.
+ */
+export declare function parseArgsOrUsage(argv: string[], io: {
+  out: Output;
+  err: Output;
+}): CliArgs | null;
+/**
+ * Audit H-4 (extended to every scanning subcommand): a nonexistent or
+ * non-directory target is a usage error — a typo'd CI path must be a
+ * loud red, never a silent green. Returns the exit code (10) or null
+ * when the target is valid.
+ */
+export declare function validateScanTarget(target: string, err: Output): number | null;
+/**
+ * Exit-code decision for a finished scan under the given gate level
+ * (audit H-7): the previously-dead config.gate field now selects which
+ * severities block. Advisory (E0) findings never gate at any level.
+ */
+export declare function exitForFindings(findings: readonly Finding[], gate: "advisory" | "error" | "warning"): number;
+/** Testable `ci install` handler. Returns the process exit code. */
+export declare function runCiInstall(argv: string[], io?: {
   out: Output;
   err: Output;
 }): number;
-declare function main(argv?: string[], io?: {
+/** Testable `suppressions` handler. */
+export declare function runSuppressions(io?: {
+  out: Output;
+  err?: Output;
+}): number;
+export declare function printUsage(print: (s: string) => void): void;
+export declare function main(argv?: string[], io?: {
   out: Output;
   err: Output;
 }): Promise<number>;
@@ -1100,10 +1579,10 @@ declare function main(argv?: string[], io?: {
  * Two-word verbs (`ci install`) are resolved first via the join of the
  * leading non-flag tokens, then the single-word form.
  */
-declare function runHelpCommand(argv: string[], io?: {
+export declare function runHelpCommand(argv: string[], io?: {
   out: Output;
   err: Output;
 }): number;
-declare function isEntryPoint(): boolean;
+export declare function isEntryPoint(): boolean;
 //#endregion
-export { ENGINE_VERSION as CLI_VERSION, type CliArgs, EVIDENCE_OVERRIDES, KNOWN_RULE_IDS, OVERLAP_META_BY_RULE_ID, type Output, SUITE_INVALIDATING_RULE_IDS, type ScanHooks, UsageErrorDetail, buildUniversalRules, discoverRuntimeReport, err, exitForFindings, fallbackWorkspace, internalErrorMessage, isEntryPoint, isValidFindingRecord, levenshtein, main, nearestFlags, out, parseArgs, pathMatchesGlob, runBadgeCommand, runBaselineCommand, runCiInstall, runCreateRuleCommand, runDebtCommand, runDiffCommand, runDoctorCommand, runDoctorPlaywright, runExplainCommand, runFixCommand, runForensicsCommand, runHandoverCommand, runHelpCommand, runImpactCommand, runInitCommand, runMutationCommand, runPrCommentCommand, runPwReportCommand, runRulesCommand, runScan, runScanCommand, runStatsCommand, runSuppressions, runTriageCommand, runVerifyCommand, usageErrorMessage };
+export { ENGINE_VERSION as CLI_VERSION, type CliArgs, type Output, type ScanHooks };