@slicedearth/whoisleuth-cli 1.32.2 → 1.36.1

package/cli/completion.mjs

@@ -1,8 +1,9 @@
 import { CLI_COMMANDS } from "./arguments.mjs";
+import { INVESTIGATION_PLAN_RECIPES } from "./investigation-plan.mjs";
 const COMMON_OPTIONS = Object.freeze(['--help', '--output', '--force']);
 const OPTIONS_BY_COMMAND = Object.freeze({
-    lookup: ['--json', '--markdown', '--html', '--fast', '--deep', '--summary', '--verbose', '--strict-exit', '--events', '--quiet', '--no-color'],
-    bulk: ['--json', '--jsonl', '--csv', '--domains', '--registered-only', '--inconclusive-only', '--fast', '--deep', '--concurrency', '--checkpoint', '--resume', '--events', '--quiet', '--no-color'],
+    lookup: ['--json', '--markdown', '--html', '--fast', '--deep', '--plan', '--summary', '--verbose', '--strict-exit', '--events', '--quiet', '--no-color'],
+    bulk: ['--json', '--jsonl', '--csv', '--domains', '--queries', '--registered-only', '--inconclusive-only', '--errors-only', '--fast', '--deep', '--concurrency', '--checkpoint', '--resume', '--events', '--quiet', '--no-color'],
     'ct-search': ['--json', '--quiet', '--no-color'],
     discover: ['--tlds', '--preset', '--families', '--keyboard', '--dictionary', '--snapshot', '--json', '--jsonl', '--domains', '--quiet', '--no-color'],
     'discover-scan': ['--tlds', '--preset', '--families', '--keyboard', '--dictionary', '--fast', '--deep', '--scan-limit', '--chunk-size', '--concurrency', '--resolver', '--allowlist', '--checkpoint', '--resume', '--observation-snapshot', '--registered-only', '--inconclusive-only', '--acquisition-only', '--suppressed-only', '--events', '--json', '--jsonl', '--csv', '--domains', '--quiet', '--no-color'],
@@ -19,9 +20,14 @@ const OPTIONS_BY_COMMAND = Object.freeze({
     compare: ['--json', '--quiet', '--no-color'],
     'page-compare': ['--json', '--quiet', '--no-color'],
     'mail-review': ['--json', '--quiet', '--no-color'],
+    'review-evidence': ['--json', '--quiet', '--no-color'],
+    'domain-control': ['--json', '--quiet', '--no-color'],
+    'workflow-plan': ['--json', '--quiet', '--no-color'],
     diff: ['--json', '--quiet', '--no-color'],
+    timeline: ['--json', '--quiet', '--no-color'],
     export: ['--markdown', '--html', '--compact'],
     completion: [],
+    commands: ['--json', '--quiet', '--no-color'],
     doctor: ['--network', '--json', '--quiet', '--no-color'],
     manual: [],
 });
@@ -36,7 +42,7 @@ const COMMAND_DESCRIPTIONS = Object.freeze({
     tls: 'Inspect one TLS connection',
     'registry-support': 'Explain local registry coverage',
     'risk-calibrate': 'Replay reviewed Risk labels offline',
-    'verify-artifact': 'Validate an evidence artifact offline',
+    'verify-artifact': 'Validate saved evidence offline',
     'inspect-archive': 'Inspect an archive locally',
     'sign-artifact': 'Sign a reviewed artifact locally',
     'verify-signature': 'Verify a signed evidence package',
@@ -44,9 +50,14 @@ const COMMAND_DESCRIPTIONS = Object.freeze({
     compare: 'Compare registry publications in one lookup',
     'page-compare': 'Compare saved static page evidence',
     'mail-review': 'Review saved passive mail evidence',
+    'review-evidence': 'Review supplied evidence offline',
+    'domain-control': 'Build or review a domain control manifest',
+    'workflow-plan': 'Plan a fixed investigation recipe',
     diff: 'Compare two saved domain lookups',
+    timeline: 'Build same-domain history from saved lookups',
     export: 'Convert a lookup to an evidence report',
     completion: 'Print shell completion',
+    commands: 'List installed command contracts',
     doctor: 'Check the local CLI runtime',
     manual: 'Print the generated manual page',
 });
@@ -92,7 +103,11 @@ _whoisleuth_completion() {
     return
   fi
   if [[ "\${command}" == "completion" && \${COMP_CWORD} -eq 2 ]]; then
-    COMPREPLY=( $(compgen -W "bash zsh fish" -- "\${current}") )
+    COMPREPLY=( $(compgen -W "bash zsh fish powershell" -- "\${current}") )
+    return
+  fi
+  if [[ "\${command}" == "workflow-plan" && \${COMP_CWORD} -eq 2 ]]; then
+    COMPREPLY=( $(compgen -W "${INVESTIGATION_PLAN_RECIPES.join(' ')}" -- "\${current}") )
     return
   fi
   case "\${previous}" in
@@ -125,7 +140,11 @@ _whoisleuth() {
   command="\${words[2]}"
   previous="\${words[CURRENT-1]}"
   if [[ "\${command}" == "completion" && CURRENT -eq 3 ]]; then
-    compadd -- bash zsh fish
+    compadd -- bash zsh fish powershell
+    return
+  fi
+  if [[ "\${command}" == "workflow-plan" && CURRENT -eq 3 ]]; then
+    compadd -- ${INVESTIGATION_PLAN_RECIPES.join(' ')}
     return
   fi
   case "\${previous}" in
@@ -160,16 +179,60 @@ complete -c whoisleuth -f
 complete -c whoisleuth -n '__fish_use_subcommand' -l help
 complete -c whoisleuth -n '__fish_use_subcommand' -l version
 ${commandLines.join('\n')}
-complete -c whoisleuth -n '__fish_seen_subcommand_from completion' -a 'bash zsh fish'
+complete -c whoisleuth -n '__fish_seen_subcommand_from completion' -a 'bash zsh fish powershell'
+complete -c whoisleuth -n '__fish_seen_subcommand_from workflow-plan' -a '${INVESTIGATION_PLAN_RECIPES.join(' ')}'
 ${optionLines.join('\n')}
 ${valueLines.join('\n')}
 `;
 }
+function powershellCompletion() {
+    const commandOptions = Object.fromEntries(CLI_COMMANDS.map((command) => [
+        command,
+        [...COMMON_OPTIONS, ...(OPTIONS_BY_COMMAND[command] || [])],
+    ]));
+    return `# WHOISleuth PowerShell completion
+Register-ArgumentCompleter -Native -CommandName whoisleuth -ScriptBlock {
+  param($wordToComplete, $commandAst, $cursorPosition)
+  $commands = @(${CLI_COMMANDS.map((command) => `'${command}'`).join(', ')})
+  $options = @{
+${Object.entries(commandOptions).map(([command, options]) => `    '${command}' = @(${options.map((option) => `'${option}'`).join(', ')})`).join('\n')}
+  }
+  $values = @{
+${Object.entries(VALUE_OPTIONS).map(([option, values]) => `    '${option}' = @(${values.map((value) => `'${value}'`).join(', ')})`).join('\n')}
+    'completion' = @('bash', 'zsh', 'fish', 'powershell')
+    'workflow-plan' = @(${INVESTIGATION_PLAN_RECIPES.map((value) => `'${value}'`).join(', ')})
+  }
+  $elements = @($commandAst.CommandElements | ForEach-Object { $_.Extent.Text })
+  $command = if ($elements.Count -gt 1) { $elements[1] } else { '' }
+  $previous = if ($elements.Count -gt 1) { $elements[$elements.Count - 1] } else { '' }
+  $candidates = if ($elements.Count -le 2) {
+    @($commands) + @('--help', '--version')
+  } elseif ($command -eq 'completion' -and $elements.Count -le 3) {
+    $values['completion']
+  } elseif ($command -eq 'workflow-plan' -and $elements.Count -le 3) {
+    $values['workflow-plan']
+  } elseif ($values.ContainsKey($previous)) {
+    $values[$previous]
+  } elseif ($options.ContainsKey($command)) {
+    $options[$command]
+  } else {
+    @('--help')
+  }
+  foreach ($candidate in $candidates) {
+    if ($candidate.StartsWith($wordToComplete, [System.StringComparison]::OrdinalIgnoreCase)) {
+      [System.Management.Automation.CompletionResult]::new($candidate, $candidate, 'ParameterValue', $candidate)
+    }
+  }
+}
+`;
+}
 function buildShellCompletion(shell) {
     if (shell === 'bash')
         return bashCompletion();
     if (shell === 'zsh')
         return zshCompletion();
-    return fishCompletion();
+    if (shell === 'fish')
+        return fishCompletion();
+    return powershellCompletion();
 }
 export { buildShellCompletion, };

package/cli/doctor.mjs

@@ -1,4 +1,4 @@
-import { resolvePublicAddresses } from "../lib/safe-fetch.mjs";
+import { resolvePublicAddresses, safeFetch } from "../lib/safe-fetch.mjs";
 import { withTimeout } from "../lib/abort.mjs";
 import { whoisQuery } from "../lib/whois-transport.mjs";
 const DOCTOR_SCHEMA = 'whoisleuth.cli.doctor';
@@ -6,6 +6,7 @@ const DOCTOR_VERSION = 1;
 const MINIMUM_NODE_MAJOR = 24;
 const NETWORK_HOST = 'whois.iana.org';
 const NETWORK_QUERY = 'example.com';
+const NETWORK_HTTPS_URL = 'https://data.iana.org/rdap/dns.json';
 const NETWORK_TIMEOUT_MS = 6_000;
 const MAX_DOCTOR_DETAIL_LENGTH = 180;
 function boundedDetail(value, fallback) {
@@ -57,58 +58,92 @@ async function buildDoctorReport(options) {
             id: 'network',
             label: 'Network checks',
             state: 'skipped',
-            detail: 'Not requested. Run doctor --network to test bounded public DNS and WHOIS connectivity.',
+            detail: 'Not requested. Run doctor --network to test bounded public DNS, HTTPS, and WHOIS connectivity.',
         }));
     }
     else {
         const resolve = options.resolveAddresses || resolvePublicAddresses;
+        const fetchHttps = options.fetchHttps || safeFetch;
         const query = options.queryWhois || whoisQuery;
         const networkTimeoutMs = Number.isSafeInteger(options.networkTimeoutMs)
             && Number(options.networkTimeoutMs) >= 1
             && Number(options.networkTimeoutMs) <= NETWORK_TIMEOUT_MS
             ? Number(options.networkTimeoutMs)
             : NETWORK_TIMEOUT_MS;
-        try {
-            const addresses = await withTimeout(() => resolve(NETWORK_HOST), networkTimeoutMs, `Public DNS check timed out after ${networkTimeoutMs} ms.`);
-            checks.push(Object.freeze({
-                id: 'public_dns',
-                label: 'Public DNS',
-                state: addresses.length > 0 ? 'pass' : 'partial',
-                detail: addresses.length > 0
-                    ? `${addresses.length} public address${addresses.length === 1 ? '' : 'es'} validated; addresses were not retained.`
-                    : 'The fixed diagnostic host returned no validated public addresses.',
-            }));
-        }
-        catch (error) {
-            checks.push(Object.freeze({
-                id: 'public_dns',
-                label: 'Public DNS',
-                state: 'partial',
-                detail: boundedDetail(error && typeof error === 'object' && 'message' in error ? error.message : error, 'Public DNS check failed.'),
-            }));
-        }
-        try {
-            const response = await query(NETWORK_HOST, NETWORK_QUERY, {
-                timeoutMs: Math.max(1, networkTimeoutMs - 1_000),
-                totalDeadlineMs: networkTimeoutMs,
-            });
-            checks.push(Object.freeze({
-                id: 'whois_transport',
-                label: 'WHOIS transport',
-                state: response.trim() ? 'pass' : 'partial',
-                detail: response.trim()
-                    ? 'A bounded port 43 response was received; response content was not retained.'
-                    : 'The fixed diagnostic query returned an empty response.',
-            }));
-        }
-        catch (error) {
-            checks.push(Object.freeze({
-                id: 'whois_transport',
-                label: 'WHOIS transport',
-                state: 'partial',
-                detail: boundedDetail(error && typeof error === 'object' && 'message' in error ? error.message : error, 'WHOIS transport check failed.'),
-            }));
-        }
+        const networkChecks = await Promise.all([
+            (async () => {
+                try {
+                    const addresses = await withTimeout(() => resolve(NETWORK_HOST), networkTimeoutMs, `Public DNS check timed out after ${networkTimeoutMs} ms.`);
+                    return Object.freeze({
+                        id: 'public_dns',
+                        label: 'Public DNS',
+                        state: addresses.length > 0 ? 'pass' : 'partial',
+                        detail: addresses.length > 0
+                            ? `${addresses.length} public address${addresses.length === 1 ? '' : 'es'} validated; addresses were not retained.`
+                            : 'The fixed diagnostic host returned no validated public addresses.',
+                    });
+                }
+                catch (error) {
+                    return Object.freeze({
+                        id: 'public_dns',
+                        label: 'Public DNS',
+                        state: 'partial',
+                        detail: boundedDetail(error && typeof error === 'object' && 'message' in error ? error.message : error, 'Public DNS check failed.'),
+                    });
+                }
+            })(),
+            (async () => {
+                try {
+                    const response = await withTimeout(() => fetchHttps(NETWORK_HTTPS_URL, {
+                        headers: { accept: 'application/json' },
+                        signal: AbortSignal.timeout(networkTimeoutMs),
+                    }), networkTimeoutMs, `HTTPS check timed out after ${networkTimeoutMs} ms.`);
+                    const status = response.status;
+                    await response.body?.cancel().catch(() => { });
+                    return Object.freeze({
+                        id: 'https_transport',
+                        label: 'HTTPS transport',
+                        state: response.ok ? 'pass' : 'partial',
+                        detail: response.ok
+                            ? `The fixed IANA RDAP bootstrap endpoint returned HTTP ${status}; response content was not retained.`
+                            : `The fixed IANA RDAP bootstrap endpoint returned HTTP ${status}.`,
+                    });
+                }
+                catch (error) {
+                    return Object.freeze({
+                        id: 'https_transport',
+                        label: 'HTTPS transport',
+                        state: 'partial',
+                        detail: boundedDetail(error && typeof error === 'object' && 'message' in error ? error.message : error, 'HTTPS transport check failed.'),
+                    });
+                }
+            })(),
+            (async () => {
+                try {
+                    const response = await withTimeout(() => query(NETWORK_HOST, NETWORK_QUERY, {
+                        timeoutMs: Math.max(1, networkTimeoutMs - 1_000),
+                        totalDeadlineMs: networkTimeoutMs,
+                    }), networkTimeoutMs, `WHOIS check timed out after ${networkTimeoutMs} ms.`);
+                    return Object.freeze({
+                        id: 'whois_transport',
+                        label: 'WHOIS transport',
+                        state: response.trim() ? 'pass' : 'partial',
+                        detail: response.trim()
+                            ? 'A bounded port 43 response was received; response content was not retained.'
+                            : 'The fixed diagnostic query returned an empty response.',
+                    });
+                }
+                catch (error) {
+                    return Object.freeze({
+                        id: 'whois_transport',
+                        label: 'WHOIS transport',
+                        state: 'partial',
+                        detail: boundedDetail(error && typeof error === 'object' && 'message' in error ? error.message : error, 'WHOIS transport check failed.'),
+                    });
+                }
+            })(),
+        ]);
+        checks.push(...networkChecks);
     }
     const state = checks.some((check) => check.state === 'partial') ? 'partial' : 'pass';
     return Object.freeze({

package/cli/export-evidence.mjs

@@ -1,5 +1,8 @@
+import { createRequire } from 'node:module';
 import { projectCliLookupComparisonInput } from "./compare.mjs";
 import { parseSavedLookupDocument } from "./saved-lookup.mjs";
+const require = createRequire(import.meta.url);
+const { version: APPLICATION_VERSION } = require('../package.json');
 function objectOrNull(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
 }
@@ -14,7 +17,11 @@ function buildCliEvidenceExport(text, evidenceModule, generatedAt = new Date().t
         throw new TypeError('Lookup evidence export dependency is required.');
     }
     const buildLookupEvidence = dependency.buildLookupEvidence;
-    const result = objectOrNull(buildLookupEvidence(source, { generatedAt, idnAnalysis: null }));
+    const result = objectOrNull(buildLookupEvidence(source, {
+        generatedAt,
+        idnAnalysis: null,
+        applicationVersion: APPLICATION_VERSION,
+    }));
     if (!result
         || result.schema !== dependency.LOOKUP_EVIDENCE_SCHEMA
         || result.schemaVersion !== dependency.LOOKUP_EVIDENCE_SCHEMA_VERSION) {
@@ -25,4 +32,4 @@ function buildCliEvidenceExport(text, evidenceModule, generatedAt = new Date().t
 function formatCliEvidenceExport(document, compact = false) {
     return `${JSON.stringify(document, null, compact ? 0 : 2)}\n`;
 }
-export { buildCliEvidenceExport, formatCliEvidenceExport };
+export { APPLICATION_VERSION, buildCliEvidenceExport, formatCliEvidenceExport };

package/cli/formatters/html.mjs

@@ -28,7 +28,7 @@ function renderRegistrarComparison(comparison) {
 }
 function formatLookupEvidenceHtml(document) {
     const report = buildLookupEvidenceReport(document);
-    const title = `Lookup evidence report — ${report.title}`;
+    const title = `Lookup evidence report: ${report.title}`;
     return `<!doctype html>
 <html lang="en">
 <head>

package/cli/formatters/terminal.mjs

@@ -271,7 +271,6 @@ function formatTerminalRegistrySupport(document) {
         `WHOIS scope    ${supportLabel(whois.queryScope)}`,
         `WHOIS encoding ${supportLabel(whois.encodingProfile)}`,
         `WHOIS parser   ${supportLabel(whois.parserProfile)}`,
-        `Fallback       ${profile.fallbackProfile ? supportLabel(profile.fallbackProfile) : 'None'}`,
         `Fixture states ${fixtures.length ? fixtures.map((value) => supportLabel(value)).join(', ') : 'None documented'}`,
     ];
     for (const file of files)
@@ -284,12 +283,12 @@ function formatTerminalRegistrySupport(document) {
 function formatTerminalBulk(items, metadata) {
     const lines = items.map((item) => {
         if (!item.ok)
-            return `! ${safeTerminalValue(item.query)} — ${safeTerminalValue(item.error, 'Lookup failed')}`;
+            return `! ${safeTerminalValue(item.query)}: ${safeTerminalValue(item.error, 'Lookup failed')}`;
         const result = terminalRecord(item.result);
         const availability = terminalRecord(result.availability);
         const state = titleCase(availability.state);
         const confidence = titleCase(availability.confidence);
-        return `✓ ${safeTerminalValue(item.query)} — ${state} (${confidence} confidence)`;
+        return `✓ ${safeTerminalValue(item.query)}: ${state} (${confidence} confidence)`;
     });
     const succeeded = items.filter((item) => item.ok).length;
     lines.push('');
@@ -302,6 +301,11 @@ function formatTerminalBulk(items, metadata) {
 }
 function formatTerminalCtSearch(document) {
     const matches = Array.isArray(document.matches) ? document.matches : [];
+    const certificateGroups = Array.isArray(document.certificateGroups) ? document.certificateGroups : [];
+    const crossDomainGroups = certificateGroups.filter((value) => {
+        const group = terminalRecord(value);
+        return Array.isArray(group.domains) && group.domains.length > 1;
+    });
     const visible = matches.slice(0, MAX_CT_TERMINAL_MATCHES);
     const observation = terminalRecord(document.observation);
     const lines = [
@@ -310,7 +314,9 @@ function formatTerminalCtSearch(document) {
         `Certificates   ${safeTerminalValue(document.certCount, '0')}`,
         `Observed hosts ${safeTerminalValue(Array.isArray(document.domains) ? document.domains.length : 0, '0')}`,
         `Matches        ${safeTerminalValue(matches.length, '0')}`,
+        `Issuance groups ${safeTerminalValue(certificateGroups.length, '0')} (${safeTerminalValue(crossDomainGroups.length, '0')} cross-domain)`,
         `Truncated      ${document.truncated ? 'Yes' : 'No'}`,
+        `Group cap      ${document.certificateGroupsTruncated ? 'Reached' : 'Not reached'}`,
         '',
     ];
     if (!visible.length) {
@@ -367,7 +373,7 @@ function formatTerminalDiscover(document, mutationLabels = {}) {
         const unicodeDetail = unicodeDomain && unicodeDomain !== candidateDomain
             ? ` [Unicode: ${safeTerminalValue(unicodeDomain)}]`
             : '';
-        lines.push(`${safeTerminalValue(candidateDomain)}${unicodeDetail} — ${labels.join(', ') || 'Generated variant'}`);
+        lines.push(`${safeTerminalValue(candidateDomain)}${unicodeDetail}: ${labels.join(', ') || 'Generated variant'}`);
     }
     if (!visible.length)
         lines.push('No candidates were generated.');
@@ -396,7 +402,7 @@ function formatTerminalPosture(document) {
     ];
     for (const value of checks) {
         const item = terminalRecord(value);
-        lines.push(`[${safeTerminalValue(item.status, 'info').toUpperCase()}] ${safeTerminalValue(item.label)} — ${safeTerminalValue(item.summary)}`);
+        lines.push(`[${safeTerminalValue(item.status, 'info').toUpperCase()}] ${safeTerminalValue(item.label)}: ${safeTerminalValue(item.summary)}`);
         if (item.detail)
             lines.push(`  Detail  ${safeTerminalValue(item.detail)}`);
         if (item.remediation)
@@ -444,7 +450,7 @@ function formatTerminalHttp(document) {
     for (const value of attempts) {
         const attempt = terminalRecord(value);
         const outcome = attempt.httpStatus ? `HTTP ${attempt.httpStatus}` : attempt.error || attempt.outcome;
-        lines.push(`Attempt        ${safeTerminalValue(attempt.url)} — ${safeTerminalValue(outcome)}`);
+        lines.push(`Attempt        ${safeTerminalValue(attempt.url)}: ${safeTerminalValue(outcome)}`);
     }
     for (const limitation of limitations)
         lines.push(`Limitation     ${safeTerminalValue(limitation)}`);
@@ -535,7 +541,7 @@ function formatTerminalTls(document) {
         lines.push(`Error          ${safeTerminalValue(diagnostics.error)}`);
     for (const value of findings) {
         const finding = terminalRecord(value);
-        lines.push(`Finding        ${safeTerminalValue(finding.label)} — ${safeTerminalValue(finding.detail)}`);
+        lines.push(`Finding        ${safeTerminalValue(finding.label)}: ${safeTerminalValue(finding.detail)}`);
     }
     for (const limitation of limitations)
         lines.push(`Limitation     ${safeTerminalValue(limitation)}`);

package/cli/investigation-plan.mjs

@@ -0,0 +1,112 @@
+import { domainToASCII } from 'node:url';
+export const CLI_INVESTIGATION_PLAN_SCHEMA = 'whoisleuth.cli.investigation-plan';
+export const CLI_INVESTIGATION_PLAN_VERSION = 1;
+export const INVESTIGATION_PLAN_RECIPES = [
+    'domain-triage',
+    'lookalike-review',
+    'owned-domain-review',
+    'historical-comparison',
+];
+const RECIPES = Object.freeze({
+    'domain-triage': Object.freeze({
+        label: 'New domain triage',
+        requiresDomain: true,
+        objective: 'Collect and preserve a source-aware registration, DNS, HTTP, TLS, page, and network-context review.',
+        steps: (domain) => Object.freeze([
+            step('collect', 'Collect a Deep lookup', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'Review source health and limitations before using missing fields.'),
+            step('export', 'Create a portable evidence report', 'export', ['<saved-lookup.json>'], 'offline', 'analyst_selection', 'whoisleuth.lookup-evidence', 'Select the reviewed lookup file; the plan never guesses a path.'),
+            step('verify', 'Verify the exported artifact', 'verify-artifact', ['<evidence.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.offline-artifact-verification', 'Keep verification distinct from a claim that the observations are correct or current.'),
+        ]),
+    }),
+    'lookalike-review': Object.freeze({
+        label: 'Lookalike candidate review',
+        requiresDomain: false,
+        objective: 'Generate a bounded candidate queue, collect only the selected scope, and retain a reviewed candidate lookup.',
+        steps: (subject) => Object.freeze([
+            step('generate', 'Generate candidates offline', 'discover', [subject, '--preset', 'all', '--json'], 'offline', 'none', 'whoisleuth.cli.discover', 'Review mutation families and suppressions before collection.'),
+            step('scan', 'Collect a bounded candidate queue', 'discover-scan', [subject, '--fast', '--scan-limit', '50', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.discovery-scan', 'Fast collection is a triage boundary; partial or inconclusive authority evidence remains explicit.'),
+            step('inspect', 'Deep-review one selected candidate', 'lookup', ['<selected-domain>', '--deep', '--json'], 'network', 'analyst_selection', 'whoisleuth.cli.lookup', 'Select a candidate deliberately; generation does not prove registration, control, intent, or maliciousness.'),
+        ]),
+    }),
+    'owned-domain-review': Object.freeze({
+        label: 'Owned domain posture review',
+        requiresDomain: true,
+        objective: 'Review current passive posture and compare supplied observations with an analyst-authored control manifest.',
+        steps: (domain) => Object.freeze([
+            step('posture', 'Collect bounded DNS posture', 'posture', [domain, '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.posture', 'Review mail profile and delegation evidence before interpreting missing records.'),
+            step('lookup', 'Collect supporting Deep evidence', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'Retain separately attributed registration, DNS, TLS, and page observations.'),
+            step('manifest', 'Review the domain control manifest', 'domain-control', ['<review-input.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.domain-control-review', 'Only complete supplied observations may produce drift.'),
+        ]),
+    }),
+    'historical-comparison': Object.freeze({
+        label: 'Historical observation comparison',
+        requiresDomain: true,
+        objective: 'Collect a current observation and compare it with analyst-selected saved observations without merging source states.',
+        steps: (domain) => Object.freeze([
+            step('current', 'Collect the current lookup', 'lookup', [domain, '--deep', '--json'], 'network', 'network_disclosure', 'whoisleuth.cli.lookup', 'A current request does not refresh or validate older provider-reported history.'),
+            step('diff', 'Compare two selected observations', 'diff', ['<previous.json>', '<current.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.lookup-diff', 'Equal, different, conflicting, and unavailable evidence remain separate.'),
+            step('timeline', 'Build a bounded local timeline', 'timeline', ['<oldest.json>', '<newer.json>', '<current.json>', '--json'], 'offline', 'analyst_selection', 'whoisleuth.cli.lookup-timeline', 'Choose two to twenty same-domain files in chronological scope.'),
+        ]),
+    }),
+});
+function step(id, label, command, args, mode, approval, produces, completion) {
+    return Object.freeze({ id, label, command, arguments: Object.freeze([...args]), mode, approval, produces, completion });
+}
+function boundedSubject(value) {
+    if (typeof value !== 'string' || !value.trim() || value.length > 253 || /[\u0000-\u001f\u007f]/u.test(value)) {
+        throw new TypeError('Investigation-plan subject must be bounded text without control characters.');
+    }
+    return value.replace(/\s+/gu, ' ').trim();
+}
+function normalizedDomain(value) {
+    const candidate = domainToASCII(value.toLowerCase().replace(/\.$/u, ''));
+    if (!candidate || candidate.length > 253 || !candidate.includes('.'))
+        return null;
+    return candidate.split('.').every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/u.test(label))
+        ? candidate
+        : null;
+}
+export function buildInvestigationPlan(recipeId, subjectValue, generatedAtValue = new Date().toISOString()) {
+    const recipe = RECIPES[recipeId];
+    if (!recipe)
+        throw new TypeError('Investigation-plan recipe is unsupported.');
+    const suppliedSubject = boundedSubject(subjectValue);
+    const subject = recipe.requiresDomain ? normalizedDomain(suppliedSubject) : suppliedSubject.toLowerCase();
+    if (!subject)
+        throw new TypeError('This investigation-plan recipe requires one valid domain.');
+    const parsedTime = Date.parse(generatedAtValue);
+    if (!Number.isFinite(parsedTime))
+        throw new TypeError('Investigation-plan generation time is invalid.');
+    const steps = recipe.steps(subject);
+    return Object.freeze({
+        schema: CLI_INVESTIGATION_PLAN_SCHEMA,
+        version: CLI_INVESTIGATION_PLAN_VERSION,
+        generatedAt: new Date(parsedTime).toISOString(),
+        recipe: Object.freeze({ id: recipeId, label: recipe.label, objective: recipe.objective }),
+        subject,
+        execution: 'plan_only',
+        steps,
+        limitations: Object.freeze([
+            'This document is a fixed plan. It does not execute commands, expand placeholders, make requests, read files, change cases, or submit reports.',
+            'Network steps require deliberate execution and disclose the selected target to the sources described by that command.',
+            'Analyst-selection steps require reviewed local artifacts; placeholders are never interpreted as file paths by this planner.',
+        ]),
+    });
+}
+export function formatInvestigationPlan(plan) {
+    return [
+        `Investigation plan: ${plan.recipe.label}`,
+        `Subject  ${plan.subject}`,
+        `Mode     ${plan.execution}`,
+        '',
+        ...plan.steps.flatMap((item, index) => [
+            `${index + 1}. ${item.label}`,
+            `   ${item.command} ${item.arguments.join(' ')}`,
+            `   ${item.mode}; approval: ${item.approval.replaceAll('_', ' ')}`,
+            `   ${item.completion}`,
+        ]),
+        '',
+        ...plan.limitations.map((item) => `Limitation: ${item}`),
+        '',
+    ].join('\n');
+}

package/cli/lookup-command-runner.mjs

@@ -8,6 +8,7 @@ import { formatLookupEvidenceHtml } from "./formatters/html.mjs";
 import { buildCliLookupDocument, formatJsonDocument } from "./formatters/json.mjs";
 import { formatLookupEvidenceMarkdown } from "./formatters/markdown.mjs";
 import { formatTerminalLookup } from "./formatters/terminal.mjs";
+import { buildCliLookupPlan, formatCliLookupPlan } from "./lookup-plan.mjs";
 import { createCliProgressEvents } from "./progress-events.mjs";
 import { lookupStrictExitFindings } from "./strict-exit.mjs";
 async function runLookupCommand(args, dependencies, context) {
@@ -33,6 +34,13 @@ async function runLookupCommand(args, dependencies, context) {
     if ((args.output === 'markdown' || args.output === 'html') && classified.type !== 'domain') {
         throw new CliUsageError('Markdown and HTML reports support domain lookups only.');
     }
+    if (args.plan) {
+        const plan = buildCliLookupPlan(query, classified, args.deep);
+        context.writeStdout(args.output === 'json'
+            ? formatJsonDocument(plan)
+            : context.terminal(formatCliLookupPlan(plan), args.color));
+        return EXIT_CODES.SUCCESS;
+    }
     const indicator = context.beginProgress(args.deep
         ? 'Collecting deep Lookup evidence'
         : 'Collecting registration evidence');

package/cli/lookup-diff.mjs

@@ -119,13 +119,20 @@ function lookupComparisonInput(document) {
         sourceCoverage: sourceCoverage(document, availability),
     };
 }
-function buildCliLookupDiff(leftText, rightText, generatedAt = new Date().toISOString()) {
+function buildCliLookupDiff(leftText, rightText, generatedAt = new Date().toISOString(), options = {}) {
     const left = parseSavedLookupDocument(leftText, { label: 'Left lookup input' });
     const right = parseSavedLookupDocument(rightText, { label: 'Right lookup input' });
-    if (left.registrableDomain === right.registrableDomain) {
+    const domainMode = options.domainMode ?? 'different';
+    if (domainMode === 'different' && left.registrableDomain === right.registrableDomain) {
         throw new CliUsageError('Lookup diff requires documents for two different domains.');
     }
-    const comparison = buildBulkDomainComparison(lookupComparisonInput(left), lookupComparisonInput(right), null);
+    if (domainMode === 'same' && left.registrableDomain !== right.registrableDomain) {
+        throw new CliUsageError('Lookup history requires observations for the same domain.');
+    }
+    const comparison = buildBulkDomainComparison(lookupComparisonInput(left), lookupComparisonInput(right), domainMode === 'same' ? right.generatedAt : null, {
+        allowSameDomain: domainMode === 'same',
+        ...(domainMode === 'same' ? { now: Date.parse(right.generatedAt) } : {}),
+    });
     if (!comparison)
         throw new CliUsageError('Lookup documents could not be compared.');
     return {
@@ -136,9 +143,13 @@ function buildCliLookupDiff(leftText, rightText, generatedAt = new Date().toISOS
         right: { domain: right.registrableDomain, generatedAt: right.generatedAt, mode: right.mode },
         comparison,
         limitations: [
-            'This command compares bounded observations already present in two saved Lookup documents and makes no network request.',
+            domainMode === 'same'
+                ? 'This comparison uses bounded observations already present in two saved Lookup documents for the same domain and makes no network request.'
+                : 'This command compares bounded observations already present in two saved Lookup documents and makes no network request.',
             'A missing value remains distinct from unavailable collection and from an observed difference.',
-            'Shared infrastructure or matching values do not establish common ownership, control, intent, safety, or maliciousness.',
+            domainMode === 'same'
+                ? 'An observed difference can reflect a domain change or changed collection conditions and does not by itself establish current state, intent, safety, or maliciousness.'
+                : 'Shared infrastructure or matching values do not establish common ownership, control, intent, safety, or maliciousness.',
         ],
     };
 }