@owasp-aghast/aghast 0.8.3 → 0.9.0-rc.1

package/dist/index.js

@@ -8,11 +8,13 @@ import { resolve, dirname } from 'node:path';
 import { runMultiScanWithCost } from './scan-runner.js';
 import { loadDefaultPricing, mergePricing, formatCostSourceLabel } from './cost-calculator.js';
 import { saveScanRecord, queryScanHistory } from './scan-history.js';
+import { writeIndividualIssueFiles } from './issue-file-writer.js';
 import { createProviderByName, getProviderNames, DEFAULT_PROVIDER_NAME } from './provider-registry.js';
-import { loadCheckRegistry, discoverCheckFolders, resolveChecks, filterChecksForRepository, validateCheck, loadCheckDetails, } from './check-library.js';
+import { loadCheckRegistry, discoverCheckFolders, resolveChecks, filterChecksForRepositoryAsync, sortChecksByPriority, validateCheck, loadCheckDetails, } from './check-library.js';
+import { clearRepoSnapshotCache } from './repo-scan.js';
 import { analyzeRepository } from './repository-analyzer.js';
 import { loadRuntimeConfig } from './runtime-config.js';
-import { logProgress, logDebug, setLogLevel, createTimer, isValidLogLevel, initFileHandler, closeAllHandlers, getAvailableLogTypes } from './logging.js';
+import { logProgress, logDebug, logWarn, setLogLevel, createTimer, isValidLogLevel, initFileHandler, closeAllHandlers, getAvailableLogTypes } from './logging.js';
 import { MOCK_MODEL_NAME, DEFAULT_MODEL } from './types.js';
 import { getFormatter } from './formatters/index.js';
 import { verifySemgrepInstalled } from './semgrep-runner.js';
@@ -21,11 +23,36 @@ import { verifyOpenAntInstalled } from './openant-runner.js';
 import { MockAgentProvider } from './mock-agent-provider.js';
 import { ERROR_CODES, formatError, formatFatalError } from './error-codes.js';
 import { DEFAULT_OUTPUT_FORMAT, DEFAULT_LOG_LEVEL, DEFAULT_LOG_TYPE } from './defaults.js';
+import { docsFooter } from './docs-url.js';
 import { colorStatus } from './colors.js';
 import { getCheckType } from './check-types.js';
 import { getDiscovery, getRegisteredDiscoveries } from './discovery.js';
+import { postPRComments } from './result-handlers/pr-comment-handler.js';
 import { createRequire } from 'node:module';
 const TAG = 'aghast';
+async function createMockJudgeProvider(modelOverride) {
+    // AGHAST_MOCK_JUDGE='true' → default TP response; AGHAST_MOCK_JUDGE=<path> → read from that file
+    const mockJudgeValue = process.env.AGHAST_MOCK_JUDGE;
+    let rawResponse = '{"verdict":"true_positive","confidence":1.0,"rationale":"mock"}';
+    if (mockJudgeValue && mockJudgeValue !== 'true') {
+        try {
+            rawResponse = await readFile(resolve(mockJudgeValue), 'utf-8');
+        }
+        catch (err) {
+            throw new Error(formatError(ERROR_CODES.E8001, `path: ${mockJudgeValue}`), { cause: err });
+        }
+    }
+    // Test hook mirroring AGHAST_MOCK_FAIL_TIMES, but for the judge's own calls.
+    // Kept separate so a test can fail the judge without also failing the scan
+    // (and vice versa) — the two are retried independently.
+    const failTimesRaw = process.env.AGHAST_MOCK_JUDGE_FAIL_TIMES;
+    const parsedFailTimes = failTimesRaw ? Number(failTimesRaw) : 0;
+    const failTimes = Number.isInteger(parsedFailTimes) && parsedFailTimes > 0 ? parsedFailTimes : 0;
+    const provider = new MockAgentProvider({ rawResponse, failTimes });
+    await provider.initialize({});
+    provider.setModel?.(modelOverride ?? MOCK_MODEL_NAME);
+    return provider;
+}
 async function createMockProvider() {
     // AGHAST_MOCK_AI='true' → default empty response; AGHAST_MOCK_AI=<path> → read from that file
     const mockAiValue = process.env.AGHAST_MOCK_AI;
@@ -62,7 +89,13 @@ async function createMockProvider() {
             };
         }
     }
-    const provider = new MockAgentProvider({ rawResponse, tokenUsage });
+    // Test hook: AGHAST_MOCK_FAIL_TIMES=<n> makes the mock fail its first n calls
+    // with a retryable (503) error before succeeding, so retry behaviour can be
+    // exercised end-to-end through the real CLI.
+    const failTimesRaw = process.env.AGHAST_MOCK_FAIL_TIMES;
+    const parsedFailTimes = failTimesRaw ? Number(failTimesRaw) : 0;
+    const failTimes = Number.isInteger(parsedFailTimes) && parsedFailTimes > 0 ? parsedFailTimes : 0;
+    const provider = new MockAgentProvider({ rawResponse, tokenUsage, failTimes });
     await provider.initialize({});
     return provider;
 }
@@ -74,12 +107,13 @@ Arguments:
   <repo-path>                Path to the repository to scan
 
 General options:
+  -h, --help                 Show this help message
   --config-dir <path>        Config directory containing checks-config.json,
                              checks/ folder, and optionally runtime-config.json.
                              Required unless AGHAST_CONFIG_DIR is set.
   --output <path>            Output file path for results
                              (default: <repo-path>/security_checks_results.<ext>)
-  --output-format json|sarif Output format (default: json)
+  --output-format <fmt>      Output format: json, sarif, csv, html, markdown (default: json)
   --fail-on-check-failure    Exit with code 1 if any check FAILs or ERRORs
   --debug                    Shorthand for --log-level debug
   --log-level <level>        Console log level: error, warn, info, debug, trace
@@ -91,6 +125,7 @@ General options:
   --model <model>            AI model override (e.g. claude-sonnet-4-20250514)
   --agent-provider <name>    Agent provider name (default: claude-code)
   --generic-prompt <file>    Generic prompt template filename in prompts/ dir
+  --runtime-config <path>    Path to runtime config file
   --diff-ref <ref>           Git ref to diff against (e.g. HEAD~1, main, SHA).
                              Auto-activates diff filtering on every check whose
                              discovery supports it, unless the check opts out
@@ -102,6 +137,24 @@ General options:
   --budget-limit-tokens <n>  Abort the scan when accumulated tokens exceed n.
                              Warns at 80%, aborts at 100%
 
+PR comment options (post findings as inline GitHub PR review comments):
+  --pr <number>              Pull request number to post comments on
+  --repo <owner/repo>        GitHub repository in owner/repo form
+                             (default: $GITHUB_REPOSITORY)
+  --base-sha <sha>           Base commit SHA (default: $GITHUB_BASE_SHA)
+  --head-sha <sha>           Head commit SHA
+                             (default: $GITHUB_HEAD_SHA / $GITHUB_SHA)
+Judge stage options (enables a post-scan LLM re-evaluation of findings):
+  --judge-model <model>      Enable the judge stage using this model. Required
+                             to activate the stage (no separate --judge flag).
+  --judge-provider <name>    Agent provider for the judge (default: scan provider)
+  --judge-concurrency <n>    Max concurrent judge calls (default: 5)
+  --judge-drop-false-positives  Remove issues judged as false positives from output
+  --judge-min-confidence <f> Demote true_positive verdicts with confidence < this
+                             value to uncertain (0.0–1.0)
+  --retry-max-attempts <n>   Retry transient provider failures up to n attempts
+                             per AI call (default: 1, i.e. no retry)
+
 Environment variables:
   ANTHROPIC_API_KEY           API key for Claude. If unset, AI-based checks fall
                               back to a logged-in local Claude session
@@ -112,16 +165,34 @@ Environment variables:
   AGHAST_LOG_LEVEL            Console log level (CLI --log-level takes precedence)
   AGHAST_LOG_FILE             Log file path (CLI --log-file takes precedence)
   AGHAST_LOG_TYPE             Log file handler type (CLI --log-type takes precedence)
+  AGHAST_MOCK_SARIF           Use a SARIF file instead of running Semgrep or Opengrep
+                              (test/development use only)
+  AGHAST_OPENANT_DATASET      Use a pre-generated OpenAnt dataset JSON file
   AGHAST_DIFF_REF             Git ref to diff against (CLI --diff-ref takes precedence)
+  NO_COLOR                    Set to "1" to disable colored output
+  GITHUB_REPOSITORY           Default for --repo (auto-set in GitHub Actions)
+  GITHUB_BASE_SHA             Default for --base-sha
+  GITHUB_HEAD_SHA             Default for --head-sha
+  GITHUB_SHA                  Fallback for --head-sha (auto-set in GitHub Actions)
+  GH_TOKEN / GITHUB_TOKEN     Auth for the gh CLI when posting PR comments
+  AGHAST_JUDGE_MODEL          Judge model (presence enables the stage; CLI --judge-model takes precedence)
+  AGHAST_JUDGE_PROVIDER       Judge provider (CLI --judge-provider takes precedence)
+  AGHAST_RETRY_MAX_ATTEMPTS   Retry attempts per AI call; >1 enables retry
+                              (CLI --retry-max-attempts takes precedence)
+  AGHAST_MOCK_JUDGE           Enables mock judge provider. Set to "true" for default
+                              {"verdict":"true_positive","confidence":1.0,"rationale":"mock"},
+                              or set to a file path for a custom fixture
 
 Examples:
   aghast scan ./my-repo --config-dir ./my-checks
   aghast scan ./my-repo --config-dir ./my-checks --output results.sarif --output-format sarif
   aghast scan ./my-repo --config-dir ./my-checks --fail-on-check-failure --debug
   aghast scan ./my-repo --config-dir ./my-checks --log-file scan.log --log-level warn
-  aghast scan ./my-repo --config-dir ./my-checks --model claude-sonnet-4-20250514`;
+  aghast scan ./my-repo --config-dir ./my-checks --model claude-sonnet-4-20250514
+
+${docsFooter('scanning.md')}`;
 function parseArgs(args) {
-    if (args.length < 1 || args[0] === '--help' || args[0] === '-h') {
+    if (args.length < 1 || args.includes('--help') || args.includes('-h')) {
         console.log(SCAN_HELP);
         process.exit(0);
     }
@@ -145,6 +216,16 @@ function parseArgs(args) {
     let diffFile;
     let budgetLimitCost;
     let budgetLimitTokens;
+    let prNumber;
+    let prRepo;
+    let baseSha;
+    let headSha;
+    let judgeModel;
+    let judgeProvider;
+    let judgeConcurrency;
+    const judgeDropFalsePositives = args.includes('--judge-drop-false-positives');
+    let judgeMinConfidence;
+    let retryMaxAttempts;
     for (let i = startIdx; i < args.length; i++) {
         switch (args[i]) {
             case '--config-dir': {
@@ -290,7 +371,126 @@ function parseArgs(args) {
                 i++;
                 break;
             }
-            // --fail-on-check-failure and --debug are handled above via includes()
+            case '--pr': {
+                const raw = args[i + 1];
+                if (!raw) {
+                    console.error(formatError(ERROR_CODES.E1001, '--pr requires a pull request number'));
+                    process.exit(1);
+                }
+                const parsedNum = Number.parseInt(raw, 10);
+                if (!Number.isInteger(parsedNum) || parsedNum <= 0) {
+                    console.error(formatError(ERROR_CODES.E1001, `--pr requires a positive integer (got "${raw}")`));
+                    process.exit(1);
+                }
+                prNumber = parsedNum;
+                i++;
+                break;
+            }
+            case '--repo': {
+                prRepo = args[i + 1];
+                if (!prRepo) {
+                    console.error(formatError(ERROR_CODES.E1001, '--repo requires an owner/repo argument'));
+                    process.exit(1);
+                }
+                i++;
+                break;
+            }
+            case '--base-sha': {
+                baseSha = args[i + 1];
+                if (!baseSha) {
+                    console.error(formatError(ERROR_CODES.E1001, '--base-sha requires a SHA argument'));
+                    process.exit(1);
+                }
+                i++;
+                break;
+            }
+            case '--head-sha': {
+                headSha = args[i + 1];
+                if (!headSha) {
+                    console.error(formatError(ERROR_CODES.E1001, '--head-sha requires a SHA argument'));
+                    process.exit(1);
+                }
+                i++;
+                break;
+            }
+            case '--judge-model': {
+                judgeModel = args[i + 1];
+                if (!judgeModel) {
+                    console.error(formatError(ERROR_CODES.E1001, '--judge-model requires a model name argument'));
+                    process.exit(1);
+                }
+                i++;
+                break;
+            }
+            case '--judge-provider': {
+                judgeProvider = args[i + 1];
+                if (!judgeProvider) {
+                    console.error(formatError(ERROR_CODES.E1001, '--judge-provider requires a provider name argument'));
+                    process.exit(1);
+                }
+                i++;
+                break;
+            }
+            case '--judge-concurrency': {
+                const raw = args[i + 1];
+                if (!raw) {
+                    console.error(formatError(ERROR_CODES.E1001, '--judge-concurrency requires a number argument'));
+                    process.exit(1);
+                }
+                const n = Number(raw);
+                if (!Number.isFinite(n) || n <= 0 || !Number.isInteger(n)) {
+                    console.error(formatError(ERROR_CODES.E1001, `--judge-concurrency must be a positive integer (got "${raw}")`));
+                    process.exit(1);
+                }
+                judgeConcurrency = n;
+                i++;
+                break;
+            }
+            case '--judge-min-confidence': {
+                const raw = args[i + 1];
+                if (!raw) {
+                    console.error(formatError(ERROR_CODES.E1001, '--judge-min-confidence requires a number argument (0.0–1.0)'));
+                    process.exit(1);
+                }
+                const n = Number(raw);
+                if (!Number.isFinite(n) || n < 0 || n > 1) {
+                    console.error(formatError(ERROR_CODES.E1001, `--judge-min-confidence must be between 0 and 1 (got "${raw}")`));
+                    process.exit(1);
+                }
+                judgeMinConfidence = n;
+                i++;
+                break;
+            }
+            case '--retry-max-attempts': {
+                const raw = args[i + 1];
+                if (!raw) {
+                    console.error(formatError(ERROR_CODES.E1001, '--retry-max-attempts requires a number argument'));
+                    process.exit(1);
+                }
+                const n = Number(raw);
+                if (!Number.isFinite(n) || n < 1 || !Number.isInteger(n)) {
+                    console.error(formatError(ERROR_CODES.E1001, `--retry-max-attempts must be an integer >= 1 (got "${raw}")`));
+                    process.exit(1);
+                }
+                retryMaxAttempts = n;
+                i++;
+                break;
+            }
+            // Boolean flags: their values are read via args.includes() above, but each
+            // still needs a case here — without one it reaches `default` and is
+            // rejected as an unknown option.
+            case '--fail-on-check-failure':
+            case '--debug':
+            case '--judge-drop-false-positives':
+                break;
+            default: {
+                const arg = args[i];
+                if (arg?.startsWith('--')) {
+                    const suggestion = arg === '--provider' ? ' Did you mean --agent-provider?' : '';
+                    console.error(formatError(ERROR_CODES.E1002, `Unknown option: ${arg}.${suggestion}`));
+                    process.exit(1);
+                }
+            }
         }
     }
     return {
@@ -299,8 +499,36 @@ function parseArgs(args) {
         runtimeConfigPath, model, agentProvider, genericPrompt,
         diffRef, diffFile,
         budgetLimitCost, budgetLimitTokens,
+        prNumber, prRepo, baseSha, headSha,
+        judgeModel, judgeProvider, judgeConcurrency,
+        judgeDropFalsePositives: judgeDropFalsePositives || undefined,
+        judgeMinConfidence,
+        retryMaxAttempts,
     };
 }
+/**
+ * Parse "owner/repo" into its parts. Returns undefined when the input is
+ * missing or malformed so callers can produce a CLI-friendly error.
+ *
+ * Validates each half against `^[A-Za-z0-9_.-]+$` — the character set GitHub
+ * actually permits in owner/repo names. This rejects whitespace and shell
+ * metacharacters defensively, even though the parsed value is only ever
+ * interpolated into a `gh api` URL path (no shell).
+ */
+const REPO_SLUG_PART = /^[A-Za-z0-9_.-]+$/;
+export function parseRepoSlug(slug) {
+    if (!slug)
+        return undefined;
+    const parts = slug.split('/');
+    if (parts.length !== 2)
+        return undefined;
+    const [owner, repo] = parts;
+    if (!owner || !repo)
+        return undefined;
+    if (!REPO_SLUG_PART.test(owner) || !REPO_SLUG_PART.test(repo))
+        return undefined;
+    return { owner, repo };
+}
 async function createProvider(useMock, agentProviderName, modelOverride) {
     if (useMock) {
         logProgress(TAG, `Mock provider enabled via AGHAST_MOCK_AI=${process.env.AGHAST_MOCK_AI}`);
@@ -359,6 +587,16 @@ async function validateConfigDir(configDir) {
 export async function runScan(args) {
     const globalTimer = createTimer();
     const parsed = parseArgs(args);
+    // Reset the per-process repo-snapshot cache so back-to-back programmatic
+    // invocations of `runScan` don't reuse a stale filesystem snapshot from a
+    // previous run (e.g. when callers edit the target repo between scans).
+    //
+    // Caveat: the cache is module-scoped, so two `runScan` invocations running
+    // *concurrently* in the same Node process will clobber each other's cached
+    // snapshots — each scan still works correctly, it just won't share the
+    // filesystem walk across invocations. Sequential invocations are the
+    // primary supported pattern.
+    clearRepoSnapshotCache();
     // --config-dir is required (CLI flag > AGHAST_CONFIG_DIR env var)
     const rawConfigDir = parsed.configDir || process.env.AGHAST_CONFIG_DIR;
     if (!rawConfigDir) {
@@ -441,7 +679,9 @@ export async function runScan(args) {
     const effectiveRepoPath = parsed.repositoryPath;
     const repoAnalysis = await analyzeRepository(effectiveRepoPath);
     const repoUrl = repoAnalysis?.repository.remoteUrl ?? effectiveRepoPath;
-    const matchingChecks = filterChecksForRepository(allChecks, repoUrl);
+    const filtered = await filterChecksForRepositoryAsync(allChecks, repoUrl, effectiveRepoPath);
+    // Run lower-priority checks first; checks without a priority sort to the end.
+    const matchingChecks = sortChecksByPriority(filtered);
     logProgress(TAG, `Found ${matchingChecks.length} matching checks (of ${allChecks.length} total)`);
     if (matchingChecks.length === 0) {
         logProgress(TAG, 'No matching checks found for this repository');
@@ -452,6 +692,11 @@ export async function runScan(args) {
         // instructionsFile is already absolute from resolveChecks — validate against ''
         const validation = await validateCheck(check, '');
         if (!validation.valid) {
+            const emptyInstructionsError = validation.errors.find((error) => error.includes('Instructions file') && error.includes('is empty'));
+            if (emptyInstructionsError) {
+                console.error(formatError(ERROR_CODES.E2004, `Invalid check "${check.id}": ${emptyInstructionsError}`));
+                process.exit(1);
+            }
             logProgress(TAG, `Skipping invalid check "${check.id}": ${validation.errors.join(', ')}`);
             continue;
         }
@@ -627,8 +872,67 @@ export async function runScan(args) {
             logDebug(TAG, `Could not load scan history for budget check: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    // ─── Judge stage setup ───
+    // Stage is enabled iff a judge model is resolvable from any config source.
+    // Provider defaults to the scan provider if not explicitly set (decision #8).
+    const resolvedJudgeModel = parsed.judgeModel ?? process.env.AGHAST_JUDGE_MODEL ?? runtimeConfig.judge?.model;
+    const resolvedJudgeProvider = parsed.judgeProvider ?? process.env.AGHAST_JUDGE_PROVIDER ?? runtimeConfig.judge?.provider;
+    const resolvedJudgeConcurrency = parsed.judgeConcurrency ?? runtimeConfig.judge?.concurrency;
+    const resolvedJudgeDropFP = parsed.judgeDropFalsePositives ?? runtimeConfig.judge?.dropFalsePositives;
+    const resolvedJudgeMinConf = parsed.judgeMinConfidence ?? runtimeConfig.judge?.minConfidence;
+    const mockJudgeEnv = process.env.AGHAST_MOCK_JUDGE;
+    const useMockJudge = !!(mockJudgeEnv && mockJudgeEnv !== 'false');
+    let judgeOptions;
+    if (resolvedJudgeModel) {
+        const judgeProviderName = resolvedJudgeProvider ?? agentProviderName;
+        let judgeProvider;
+        if (useMockJudge) {
+            logProgress(TAG, `Mock judge provider enabled via AGHAST_MOCK_JUDGE=${mockJudgeEnv}`);
+            judgeProvider = await createMockJudgeProvider(resolvedJudgeModel);
+        }
+        else if (useMock) {
+            // If scan uses mock, use mock for judge too (tests that set AGHAST_MOCK_AI but not AGHAST_MOCK_JUDGE)
+            logWarn(TAG, 'AGHAST_MOCK_AI is set; judge provider will also use mock (set AGHAST_MOCK_JUDGE to control judge response)');
+            judgeProvider = await createMockJudgeProvider(resolvedJudgeModel);
+        }
+        else {
+            const jp = createProviderByName(judgeProviderName);
+            await jp.initialize({ apiKey: process.env.ANTHROPIC_API_KEY, model: resolvedJudgeModel });
+            judgeProvider = jp;
+        }
+        judgeOptions = {
+            provider: judgeProvider,
+            providerName: useMockJudge || useMock ? 'mock' : judgeProviderName,
+            model: resolvedJudgeModel,
+            concurrency: resolvedJudgeConcurrency,
+            dropFalsePositives: resolvedJudgeDropFP,
+            minConfidence: resolvedJudgeMinConf,
+        };
+        logProgress(TAG, `Judge stage enabled: model=${resolvedJudgeModel}, provider=${judgeOptions.providerName}`);
+    }
+    // Retry is opt-in. Precedence matches every other setting:
+    // CLI --retry-max-attempts > AGHAST_RETRY_MAX_ATTEMPTS > runtime config.
+    // When none is supplied this stays undefined and the scan runner's default
+    // (one attempt, no backoff, no circuit breaker) applies.
+    let resolvedRetry = runtimeConfig.retry;
+    const envRetryAttempts = process.env.AGHAST_RETRY_MAX_ATTEMPTS;
+    let retryAttemptsOverride = parsed.retryMaxAttempts;
+    if (retryAttemptsOverride === undefined && envRetryAttempts !== undefined) {
+        const n = Number(envRetryAttempts);
+        if (!Number.isFinite(n) || n < 1 || !Number.isInteger(n)) {
+            console.error(formatError(ERROR_CODES.E1001, `AGHAST_RETRY_MAX_ATTEMPTS must be an integer >= 1 (got "${envRetryAttempts}")`));
+            process.exit(1);
+        }
+        retryAttemptsOverride = n;
+    }
+    if (retryAttemptsOverride !== undefined) {
+        resolvedRetry = { ...resolvedRetry, maxAttempts: retryAttemptsOverride };
+    }
+    if (resolvedRetry?.maxAttempts !== undefined && resolvedRetry.maxAttempts > 1) {
+        logProgress(TAG, `Retry enabled: up to ${resolvedRetry.maxAttempts} attempts per AI call`);
+    }
     try {
-        const outcome = await runMultiScanWithCost({
+        const scanOptions = {
             repositoryPath: effectiveRepoPath,
             checks: checksWithDetails,
             agentProvider: provider,
@@ -646,7 +950,13 @@ export async function runScan(args) {
             // Prefer the provider's resolved auth mode (covers auto-detected local login);
             // fall back to the env var for providers without the concept (e.g. mock).
             isLocalClaude: provider?.isLocalMode?.() ?? (process.env.AGHAST_LOCAL_CLAUDE === 'true'),
-        });
+            judge: judgeOptions,
+            // Undefined when absent, which leaves the scan runner on its defaults —
+            // and the default is retry OFF, so a scan with no retry configuration
+            // anywhere fails fast exactly as it did before retry existed.
+            retry: resolvedRetry,
+        };
+        const outcome = await runMultiScanWithCost(scanOptions);
         const results = outcome.results;
         // Resolve output path: --output flag > runtime config dir > default
         let resolvedOutputPath;
@@ -662,6 +972,17 @@ export async function runScan(args) {
         }
         await mkdir(dirname(resolvedOutputPath), { recursive: true });
         await writeFile(resolvedOutputPath, formatter.format(results), 'utf-8');
+        // Optional: write one file per issue alongside the main report (Spec E.3.2).
+        let individualIssueDir;
+        let individualIssueCount = 0;
+        if (runtimeConfig.reporting?.includeIndividualIssueFiles && results.issues.length > 0) {
+            const issueFormat = runtimeConfig.reporting.individualIssueFormat ?? 'markdown';
+            const issueOutputDir = dirname(resolvedOutputPath);
+            const written = await writeIndividualIssueFiles(results, issueOutputDir, issueFormat);
+            individualIssueDir = written.rootDir;
+            individualIssueCount = written.files.length;
+            logProgress(TAG, `Wrote ${individualIssueCount} individual issue file(s) to ${individualIssueDir}`);
+        }
         // Summary output
         const statusIcon = results.summary.failedChecks > 0
             ? 'ISSUES DETECTED'
@@ -695,8 +1016,16 @@ export async function runScan(args) {
             const equiv = outcome.costCoveredBySubscription ? ' equivalent' : '';
             console.log(`  Cost:          $${outcome.totalCostUsd.toFixed(4)}${equiv}  ${label}`);
         }
+        if (outcome.judgeSummary) {
+            const js = outcome.judgeSummary;
+            const truePos = js.judgedIssues - js.falsePositives - js.uncertainJudgements;
+            console.log(`  Judged:        ${js.judgedIssues} issues: ${truePos} true / ${js.falsePositives} false / ${js.uncertainJudgements} uncertain (judge: ${outcome.judgeModel})`);
+        }
         console.log(`  Duration:      ${globalTimer.elapsedStr()}`);
         console.log(`  Results:       ${resolvedOutputPath}`);
+        if (individualIssueDir) {
+            console.log(`  Issue files:   ${individualIssueCount} in ${individualIssueDir}`);
+        }
         console.log('='.repeat(60));
         // Persist the scan record to history (best-effort — never blocks exit).
         // We DO save the record even when the scan was aborted by budget: per-period
@@ -741,6 +1070,32 @@ export async function runScan(args) {
             console.error(formatError(ERROR_CODES.E7001, reason));
             logProgress(TAG, `Scan aborted by budget: ${reason}`);
         }
+        // ─── Optional: post findings as PR comments ──────────────────────────────
+        if (parsed.prNumber !== undefined) {
+            const repoSlug = parsed.prRepo ?? process.env.GITHUB_REPOSITORY;
+            const repoParts = parseRepoSlug(repoSlug);
+            if (!repoParts) {
+                console.error(formatError(ERROR_CODES.E1001, '--pr was supplied but --repo (or $GITHUB_REPOSITORY) is missing or not in owner/repo form'));
+                await closeAllHandlers();
+                process.exit(1);
+            }
+            try {
+                const headSha = parsed.headSha ?? process.env.GITHUB_HEAD_SHA ?? process.env.GITHUB_SHA;
+                const baseSha = parsed.baseSha ?? process.env.GITHUB_BASE_SHA;
+                const summary = await postPRComments(results, {
+                    owner: repoParts.owner,
+                    repo: repoParts.repo,
+                    prNumber: parsed.prNumber,
+                    baseSha,
+                    headSha,
+                });
+                console.log(`  PR comments:   posted ${summary.posted}, skipped ${summary.skipped}`);
+            }
+            catch (err) {
+                console.error(formatError(ERROR_CODES.E7201, `Failed to post PR comments: ${err instanceof Error ? err.message : String(err)}`));
+                // Non-fatal: don't override scan exit code, but log a warning.
+            }
+        }
         // Exit code based on --fail-on-check-failure flag or runtime config (spec Section 9.3),
         // OR a budget abort.
         const failOnCheckFailure = parsed.failOnCheckFailure || runtimeConfig.failOnCheckFailure === true;