@haystackeditor/cli 0.15.19 → 0.15.21

package/dist/commands/verify.js

@@ -0,0 +1,97 @@
+import { readFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+import chalk from 'chalk';
+import { setVerifyToken, verifyAuthHeaders } from './verify-core.js';
+const DEFAULT_CONTROL_PLANE = 'http://127.0.0.1:3000';
+const SPECIMENS = new Set(['all', 'posthog-js-478', 'analytics-js-255']);
+function openResults(url) {
+    const platform = process.platform;
+    const command = platform === 'darwin' ? 'open' : platform === 'win32' ? 'cmd' : 'xdg-open';
+    const args = platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    const child = spawn(command, args, { detached: true, stdio: 'ignore' });
+    child.unref();
+}
+async function readIntentTranscript(path) {
+    if (!path)
+        return undefined;
+    const absolutePath = resolve(path);
+    try {
+        return await readFile(absolutePath, 'utf8');
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not read intent transcript at ${absolutePath}: ${message}`);
+    }
+}
+export async function verifyCommand(specimenArg, options) {
+    const specimen = specimenArg || 'all';
+    if (!SPECIMENS.has(specimen)) {
+        throw new Error(`Unknown or unreproduced specimen "${specimen}". Choose all, posthog-js-478, or analytics-js-255.`);
+    }
+    setVerifyToken(options.token);
+    const server = (options.server || process.env.HAYSTACK_VERIFY_SERVER || DEFAULT_CONTROL_PLANE)
+        .replace(/\/+$/, '');
+    const intentTranscript = await readIntentTranscript(options.intentTranscript);
+    if (!options.json) {
+        console.error(chalk.dim('Preparing the cloud verification run…'));
+    }
+    let response;
+    try {
+        response = await fetch(`${server}/api/cloud-verifier/runs`, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', ...verifyAuthHeaders() },
+            body: JSON.stringify({
+                specimen,
+                repoPath: options.repo ? resolve(options.repo) : undefined,
+                baseRef: options.base,
+                headRef: options.head,
+                intentTranscript,
+            }),
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Could not reach the Haystack verifier at ${server}. Start the demo control plane with \`pnpm dev\` and retry. ${message}`);
+    }
+    const raw = await response.text();
+    if (response.status === 401) {
+        throw new Error(`Control plane at ${server} requires a token (HTTP 401). Pass --token or set HAYSTACK_VERIFY_TOKEN.`);
+    }
+    if (!response.ok) {
+        let reason = raw;
+        try {
+            reason = JSON.parse(raw).error || raw;
+        }
+        catch {
+            // Preserve the response body when it is not JSON.
+        }
+        throw new Error(`Verifier rejected the run (${response.status}): ${reason}`);
+    }
+    let started;
+    try {
+        started = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('Verifier returned an invalid response.');
+    }
+    if (!started.runId || !started.resultsUrl) {
+        throw new Error('Verifier response is missing runId or resultsUrl.');
+    }
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify({
+            schema_version: '1.0.0',
+            run_id: started.runId,
+            status: started.status,
+            results_url: started.resultsUrl,
+        }, null, 2)}\n`);
+    }
+    else {
+        console.log('');
+        console.log(`${chalk.green('✓')} Verification started: ${chalk.bold(started.runId)}`);
+        console.log(`  ${chalk.dim('Results:')} ${chalk.cyan(started.resultsUrl)}`);
+    }
+    if (options.open !== false) {
+        openResults(started.resultsUrl);
+    }
+}

package/dist/index.js

@@ -25,6 +25,7 @@ import { dirname, join } from 'node:path';
 import chalk from 'chalk';
 import { Command, Option } from 'commander';
 import { statusCommand } from './commands/status.js';
+import { withSchema } from './schema.js';
 import { initCommand } from './commands/init.js';
 import { authListCommand, authUseCommand, loginCommand, logoutCommand, whoamiCommand, } from './commands/login.js';
 import { handleAgenticTool, handleAutoMerge, handleAutoFix, handleWaitForReviewers, isAutoMergeEnabled, isAutoFixEnabled } from './commands/config.js';
@@ -46,6 +47,8 @@ import { setupCommand } from './commands/setup.js';
 import { schemaCommand, listSchemas } from './commands/schema-cmd.js';
 import { registerWebhook, listWebhooks, rotateWebhookSecret, setWebhookEnabled, listDeliveries, replayDelivery, } from './commands/webhooks.js';
 import { editRulesCommand, validateRulesCommand } from './commands/rules.js';
+import { systemMapValidateCommand } from './commands/system-map.js';
+import { verifyCommand } from './commands/verify.js';
 import { headlessLoginCommand, headlessLogoutCommand, listTokensCommand, revokeTokenCommand, } from './commands/tokens.js';
 // `mcp` is imported lazily inside its command action (below), NOT at the top level.
 // It is the only module that pulls in `@modelcontextprotocol/sdk`; keeping it out of
@@ -53,12 +56,19 @@ import { headlessLoginCommand, headlessLogoutCommand, listTokensCommand, revokeT
 // like `triage`/`submit`. (0.15.12 shipped `mcp.js` but published its package.json
 // WITHOUT `@modelcontextprotocol/sdk`, so the eager import here hard-crashed every
 // command at startup with ERR_MODULE_NOT_FOUND.)
-async function runPublicCommand(action) {
+async function runPublicCommand(action, json) {
     try {
         await action();
     }
     catch (err) {
-        console.error(chalk.red(err instanceof Error ? err.message : String(err)));
+        const message = err instanceof Error ? err.message : String(err);
+        // In --json mode stdout must still carry one parseable document — emit the
+        // versioned error envelope (`haystack schema error`) instead of leaving
+        // stdout empty with prose on stderr.
+        if (json) {
+            process.stdout.write(JSON.stringify(withSchema('error', { status: 'error', error: message }), null, 2) + '\n');
+        }
+        console.error(chalk.red(message));
         process.exitCode = 1;
     }
 }
@@ -112,7 +122,7 @@ program
     .description('Onboarding wizard — scan repos for rules/policies and write Haystack config')
     .option('--json', 'Agent mode: emit NDJSON events on stdout, read answers on stdin (no TTY prompts)')
     .option('--repo <repo...>', 'Repo(s) to configure (owner/name); skips the repo picker')
-    .option('-y, --yes', 'Accept defaults non-interactively (keep all discovered items, confirm write)')
+    .option('-y, --yes', 'Accept defaults non-interactively (keep all discovered items, confirm write, ENABLE auto-merge — pass --no-auto-merge to opt out)')
     // Defining --no-auto-merge also accepts --auto-merge; default is "ask" unless
     // one is explicitly passed (detected via getOptionValueSource below).
     .option('--no-auto-merge', 'Set auto-merge in the written config (--auto-merge / --no-auto-merge; omit to be asked)')
@@ -155,6 +165,260 @@ program
     .command('status')
     .description('Check if .haystack.json exists and is valid')
     .action(statusCommand);
+const verify = program
+    .command('verify')
+    .description('Verify a change in matched cloud universes, or bisect a historical regression')
+    .argument('[specimen]', 'Launch specimen to run (default: all)')
+    .option('--repo <path>', 'Repository to analyze (defaults to the selected launch specimen)')
+    .option('--base <ref>', 'Base revision for a repository run')
+    .option('--head <ref>', 'Head revision for a repository run')
+    .option('--intent-transcript <file>', 'Coding-agent transcript used as intent evidence')
+    .option('--server <url>', 'Verifier control-plane URL (default: http://127.0.0.1:3000)')
+    .option('--token <token>', 'Bearer token for a control plane that requires auth (or HAYSTACK_VERIFY_TOKEN)')
+    .option('--no-open', 'Do not open the live results page')
+    .option('--json', 'Machine-readable run id, status, and results URL')
+    .addHelpText('after', `
+Launch specimens:
+  posthog-js-478   Replay PostHog/posthog-js PR #478 in matched browser environments (latent-issue mode)
+  analytics-js-255 Identity routing regression with sandbox bisect
+  all              Run each reproduced specimen as an isolated chapter (default)
+
+The local control plane must be running. From the Haystack repository:
+  pnpm dev
+
+Examples:
+  haystack verify posthog-js-478         # start a run, then:
+  haystack verify watch                  # block until it finishes (exit 1 = tests failed)
+  haystack verify status                 # one-screen verdicts + live environment URLs
+  haystack verify findings               # every problem found, with the readings that moved
+  haystack verify show latest 3          # one test in full: readings, timeline, SDK log
+  haystack verify diff latest 3          # base-vs-head screenshot differ (1/2/3 views)
+  haystack verify open latest 3 --live   # open a failing test's live environment
+  haystack verify cleanup latest 3       # retained-state deletion/reference status
+  haystack verify refork latest 3 attempt:fix-2 # checkpoint a durable child
+  haystack verify shell latest 3         # terminal into that live universe
+  haystack verify artifacts latest       # pull screenshots / DOM / video locally
+  haystack verify sandboxes --kill-stale # reclaim E2B capacity from superseded runs
+  haystack verify reseal <specimen>      # rebuild a sealed bundle + restart control plane
+`)
+    .action((specimen, options) => runPublicCommand(() => verifyCommand(specimen, options), options.json));
+const verifyRunArg = 'Run id, chapter id (newest run of that chapter), or "latest" (default)';
+verify
+    .command('status')
+    .description('One screen for a run: per-test verdicts, counts, live environments and expiry')
+    .argument('[run]', verifyRunArg)
+    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
+    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
+    .option('--json', 'Machine-readable summary')
+    .action(async (run, _options, cmd) => {
+    // optsWithGlobals: the parent `verify` command also declares --json/--server
+    // and commander's default parsing lets it consume those flags even when
+    // they appear after the subcommand; the merged view (self wins) restores them.
+    const options = cmd.optsWithGlobals();
+    const { verifyStatusCommand } = await import('./commands/verify-ops.js');
+    return runPublicCommand(() => verifyStatusCommand(run, options), options.json);
+});
+verify
+    .command('watch')
+    .description('Follow a run until it finishes; exit 0 all passed, 1 tests failed, 2 run/infra broke')
+    .argument('[run]', verifyRunArg)
+    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
+    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
+    .option('--interval <seconds>', 'Poll interval (default 3)')
+    .option('--timeout <minutes>', 'Give up after this long (default: wait forever)')
+    .option('--json', 'Suppress streaming; print the final summary as JSON')
+    .action(async (run, _options, cmd) => {
+    const options = cmd.optsWithGlobals();
+    const { verifyWatchCommand } = await import('./commands/verify-ops.js');
+    return runPublicCommand(() => verifyWatchCommand(run, options), options.json);
+});
+verify
+    .command('list')
+    .description('Runs newest first: chapter, verdict counts, age (control plane, else disk)')
+    .option('--limit <n>', 'Max runs to show (default 20)')
+    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
+    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
+    .option('--json', 'Machine-readable list')
+    .action(async (_options, cmd) => {
+    const options = cmd.optsWithGlobals();
+    const { verifyListCommand } = await import('./commands/verify-ops.js');
+    return runPublicCommand(() => verifyListCommand(options), options.json);
+});
+verify
+    .command('findings')
+    .description('Every problem the run found, in one screen: what failed, which readings moved, live links')
+    .argument('[run]', verifyRunArg)
+    .option('--full', 'Print the judge\'s full explanation for each finding')
+    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
+    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
+    .option('--json', 'Machine-readable findings')
+    .action(async (run, _options, cmd) => {
+    const options = cmd.optsWithGlobals();
+    const { verifyFindingsCommand } = await import('./commands/verify-ops.js');
+    return runPublicCommand(() => verifyFindingsCommand(run, options), options.json);
+});
+verify
+    .command('open')
+    .description('Open a run artifact (screenshot/video/DOM) or a failing test\'s live environment')
+    .argument('<run>', verifyRunArg)
+    .argument('<target>', 'Test selector (ordinal/title), or an artifact file name (….png/.webm/.html)')
+    .option('--live', 'Open the test\'s live environment URL instead of an artifact')
+    .option('--side <side>', 'base or head (default head)')
+    .option('--step <n>', 'Open the screenshot captured after replay step n')
+    .option('--kind <kind>', 'screenshot | video | dom (default: video, else last screenshot)')
+    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
+    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
+    .action(async (run, target, _options, cmd) => {
+    const options = cmd.optsWithGlobals();
+    const { verifyOpenCommand } = await import('./commands/verify-ops.js');
+    return runPublicCommand(() => verifyOpenCommand(run, target, options));
+});
+verify
+    .command('diff')
+    .description('Open a base-vs-head screenshot differ for one test (1 what changed / 2 before / 3 after)')
+    .argument('<run>', verifyRunArg)
+    .argument('<cell>', 'Test selector: ordinal, cell id, or title substring')
+    .option('--step <n>', 'Compare only the screenshot captured after replay step n')
+    .option('--out <dir>', 'Where to build the diff page (default: a temp directory)')
+    .option('--no-open', 'Build the page but do not open it')
+    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
+    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
+    .option('--json', 'Machine-readable result (implies --no-open)')
+    .action(async (run, cell, _options, cmd) => {
+    const options = { ...cmd.optsWithGlobals(), ...cmd.opts() };
+    const { verifyDiffCommand } = await import('./commands/verify-ops.js');
+    return runPublicCommand(() => verifyDiffCommand(run, cell, options), options.json);
+});
+verify
+    .command('cleanup')
+    .description('Show exact retained-state references, provider deletion, and cleanup-SLO status')
+    .argument('<run>', verifyRunArg)
+    .argument('<cell>', 'Stable test selector: ordinal, riskCellId, or exact planner cellKey')
+    .option('--side <side>', 'base or head (default head)')
+    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
+    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
+    .option('--json', 'Machine-readable cleanup status')
+    .action(async (run, cell, _options, cmd) => {
+    const options = cmd.optsWithGlobals();
+    const { verifyCleanupCommand } = await import('./commands/verify-ops.js');
+    return runPublicCommand(() => verifyCleanupCommand(run, cell, options), options.json);
+});
+verify
+    .command('reopen')
+    .description('Attach fresh E2B compute to retained Archil state from a test or exact fork ID')
+    .argument('<source>', 'Run selector, or an exact archil:…:branch:… fork ID')
+    .argument('[cell]', 'Stable test selector for a run: ordinal, riskCellId, or exact planner cellKey')
+    .option('--side <side>', 'base or head (default head)')
+    .option('--open-browser', 'Open the restarted application in a browser')
+    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
+    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
+    .option('--json', 'Machine-readable attachment details')
+    .action(async (source, cell, _options, cmd) => {
+    const options = cmd.optsWithGlobals();
+    const { verifyReopenCommand } = await import('./commands/verify-ops.js');
+    return runPublicCommand(() => verifyReopenCommand(source, cell, options), options.json);
+});
+verify
+    .command('refork')
+    .description('Checkpoint a reopened Archil universe into a durable child fork')
+    .argument('<source>', 'Run selector, or an exact archil:…:branch:… parent fork ID')
+    .argument('<cell-or-child-key>', 'Stable test selector for a run, or child key for an exact fork ID')
+    .argument('[child-key]', 'Structured stable child key when source is a run')
+    .option('--side <side>', 'base or head (default head; only applies to a run)')
+    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
+    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
+    .option('--json', 'Machine-readable parent, child, checkpoint, and expiry')
+    .action(async (source, cellOrChildKey, childKey, _options, cmd) => {
+    const options = cmd.optsWithGlobals();
+    const { verifyReforkCommand } = await import('./commands/verify-ops.js');
+    return runPublicCommand(() => verifyReforkCommand(source, cellOrChildKey, childKey, options), options.json);
+});
+verify
+    .command('shell')
+    .description('Terminal into a failing test\'s live universe (e2b sandbox connect)')
+    .argument('<run>', verifyRunArg)
+    .argument('<cell>', 'Stable test selector: ordinal, riskCellId, or exact planner cellKey')
+    .option('--side <side>', 'base or head (default head; only failing tests keep a universe alive)')
+    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
+    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
+    .action(async (run, cell, _options, cmd) => {
+    const options = cmd.optsWithGlobals();
+    const { verifyShellCommand } = await import('./commands/verify-ops.js');
+    return runPublicCommand(() => verifyShellCommand(run, cell, options));
+});
+verify
+    .command('show')
+    .description('One test in full: finding, changed readings, request timeline, SDK log lines')
+    .argument('<run>', verifyRunArg)
+    .argument('<cell>', 'Test ordinal, cell id, planner cell key, or title substring')
+    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
+    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
+    .option('--no-timeline', 'Skip the request timeline')
+    .option('--json', 'Machine-readable detail')
+    .action(async (run, cell, _options, cmd) => {
+    const options = cmd.optsWithGlobals();
+    const { verifyShowCommand } = await import('./commands/verify-ops.js');
+    return runPublicCommand(() => verifyShowCommand(run, cell, options), options.json);
+});
+verify
+    .command('artifacts')
+    .description('Pull a run\'s screenshots, DOM snapshots and videos to a local directory')
+    .argument('<run>', verifyRunArg)
+    .option('--out <dir>', 'Destination (default: ./verify-artifacts/<runId>)')
+    .option('--cell <selector>', 'Only artifacts for one test (ordinal, cell id, or title substring)')
+    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
+    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
+    .option('--json', 'Machine-readable result')
+    .action(async (run, _options, cmd) => {
+    const options = cmd.optsWithGlobals();
+    const { verifyArtifactsCommand } = await import('./commands/verify-ops.js');
+    return runPublicCommand(() => verifyArtifactsCommand(run, options), options.json);
+});
+verify
+    .command('sandboxes')
+    .description('E2B sandbox inventory with run attribution; --kill-stale reclaims superseded ones')
+    .option('--kill-stale', 'Kill verifier-attributed sandboxes superseded by newer runs (never unattributed ones)')
+    .option('--kill-run <runId>', 'Kill every sandbox attributed to one run')
+    .option('--server <url>', 'Control-plane URL, preferred over direct E2B access (default: http://127.0.0.1:3000)')
+    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
+    .option('--json', 'Machine-readable inventory')
+    .action(async (_options, cmd) => {
+    const options = cmd.optsWithGlobals();
+    const { verifySandboxesCommand } = await import('./commands/verify-sandboxes.js');
+    return runPublicCommand(() => verifySandboxesCommand(options), options.json);
+});
+verify
+    .command('reseal')
+    .description('Rebuild a sealed specimen bundle (guarded) and restart the control plane onto it')
+    .argument('<specimen>', 'Specimen id, e.g. posthog-js-478')
+    .option('--source <dir>', 'Specimen source directory holding reseal.sh')
+    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
+    .option('--repo-root <path>', 'Repository holding demo/cloud-verifier (default: walk up from cwd)')
+    .option('--no-restart', 'Only rebuild the bundle; leave the running server on the old checkout')
+    .action(async (specimen, _options, cmd) => {
+    const options = cmd.optsWithGlobals();
+    const { verifyResealCommand } = await import('./commands/verify-reseal.js');
+    return runPublicCommand(() => verifyResealCommand(specimen, options));
+});
+verify
+    .command('mcp')
+    .description('Run a stdio MCP server exposing the verifier to agents (verify_start/verify_wait/…)')
+    .option('--server <url>', 'Control-plane URL (default: http://127.0.0.1:3000)')
+    .option('--token <token>', 'Bearer token for a control plane that requires auth (or HAYSTACK_VERIFY_TOKEN)')
+    .option('--repo-root <path>', 'Repository holding .haystack/verify (default: walk up from cwd)')
+    .action(async (_options, cmd) => {
+    const options = cmd.optsWithGlobals();
+    try {
+        // Lazy import, same reasoning as the top-level `mcp` command: only this
+        // path needs @modelcontextprotocol/sdk.
+        const { runVerifyMcpServer } = await import('./commands/verify-mcp.js');
+        await runVerifyMcpServer(options);
+    }
+    catch (err) {
+        console.error(chalk.red('verify mcp server failed:'), err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
 program
     .command('login')
     .description('Add or refresh a saved GitHub account (use --headless for CI tokens)')
@@ -247,7 +511,9 @@ program
     .option('--force', 'Skip pre-PR triage checks')
     .addOption(new Option('--auto-fix', 'Alpha auto-fix for entitled repositories').hideHelp())
     .option('--auto-merge', 'Apply auto-merge label (default: from .haystack.json, --no-auto-merge to disable)')
+    .option('--no-auto-merge', 'Do not apply the auto-merge label')
     .option('--no-wait', 'Skip waiting for analysis results')
+    .option('--json', 'Machine-readable: one JSON document on stdout (see `haystack schema submit`), progress on stderr')
     .option('--max-turns <n>', 'Max agentic turns per triage checker (overrides .haystack.json triage.maxTurns)', (v) => parseInt(v, 10))
     .option('--triage-timeout <seconds>', 'Wall-clock timeout per triage checker in seconds (overrides .haystack.json triage.timeoutMs)', (v) => parseInt(v, 10))
     .addHelpText('after', `
@@ -296,8 +562,22 @@ Review Routing:
                          needs-assignment queue (a teammate will pick it up)
   • --review <username>  Same label, plus requests review from that GitHub user
 
+Machine-readable output (--json):
+  stdout carries exactly one JSON document (schema: \`haystack schema submit\`);
+  all progress goes to stderr. On success the payload includes the PR ref,
+  the resolved title/body and their sources, auto-merge/auto-fix state with
+  source, and the analysis outcome. On failure it is an error envelope
+  { status: "error", error: "..." }.
+
+Exit codes:
+  0  PR created/updated (including verdict "needs_input" — the PR exists;
+     read the verdict from the JSON or from \`haystack triage\`)
+  1  Hard failure (bad flags, auth, push, PR creation, blocking triage
+     findings, or the analysis status check itself failing)
+
 Examples:
   haystack submit                      # Recommended: triage, create PR, auto-merge queue
+  haystack submit --json               # Agent mode: JSON on stdout, progress on stderr
   haystack submit --force              # Skip triage
   haystack submit --no-wait            # Don't wait for analysis
   haystack submit --title "Fix auth"   # Custom PR title
@@ -312,17 +592,23 @@ Examples:
   haystack submit --max-turns 12       # Raise triage turn cap to 12 per checker
   haystack submit --triage-timeout 300 # Raise triage wall-clock to 5 minutes
 `)
-    .action(async (options) => {
-    // Resolve --auto-merge default from .haystack.json when not explicitly set
-    if (options.autoMerge === undefined) {
+    .action(async (options, command) => {
+    // Resolve --auto-merge / --auto-fix defaults from .haystack.json when not
+    // explicitly set, and record WHERE each value came from so submit can
+    // announce the source (silent config-driven defaults are invisible to
+    // the caller otherwise).
+    const autoMergeFromCli = command.getOptionValueSource('autoMerge') === 'cli';
+    const autoFixFromCli = command.getOptionValueSource('autoFix') === 'cli';
+    if (!autoMergeFromCli) {
         options.autoMerge = await isAutoMergeEnabled();
     }
-    // Resolve --auto-fix default from .haystack.json (preferences.auto_fix).
     // Auto-fix remains alpha — the explicit --auto-fix flag still surfaces
     // discouragement warnings; opting in via repo config is the supported path.
-    if (options.autoFix === undefined) {
+    if (!autoFixFromCli) {
         options.autoFix = await isAutoFixEnabled();
     }
+    options.autoMergeSource = autoMergeFromCli ? 'flag' : 'config';
+    options.autoFixSource = autoFixFromCli ? 'flag' : 'config';
     return submitCommand(options);
 });
 program
@@ -364,35 +650,36 @@ inbox
     .command('list')
     .description('List PRs in your Haystack inbox')
     .option('--json', 'Output as JSON')
-    .action((options) => runPublicCommand(() => inboxListCommand(options)));
+    .action((options) => runPublicCommand(() => inboxListCommand(options), options.json));
 const prProgram = program.command('pr').description('Inspect one pull request');
 prProgram
     .command('get <ref>')
     .description('Get triage, merge blockers, and trace availability')
     .option('--json', 'Output as JSON')
-    .action((ref, options) => runPublicCommand(() => prReadCommand(ref, options)));
+    .action((ref, options) => runPublicCommand(() => prReadCommand(ref, options), options.json));
 program
     .command('ask <ref> <question>')
     .description('Ask Haystack about a pull request')
     .option('--json', 'Output the answer and every consulted customer-facing source as JSON')
     .option('--session <id>', 'Continue a previous Ask Haystack session')
-    .action((ref, question, options) => runPublicCommand(() => askHaystackCommand(ref, question, options)));
+    .action((ref, question, options) => runPublicCommand(() => askHaystackCommand(ref, question, options), options.json));
 const traces = program.command('traces').description('Inspect customer-owned Entire traces');
 traces
     .command('list <ref>')
     .description('List retained checkpoints for a pull request')
     .option('--json', 'Output as JSON')
-    .action((ref, options) => runPublicCommand(() => tracesListCommand(ref, options)));
+    .action((ref, options) => runPublicCommand(() => tracesListCommand(ref, options), options.json));
 traces
     .command('get <ref> <checkpoint>')
     .description('Get retained transcript chunks for one checkpoint')
     .option('--cursor <cursor>', 'Zero-based chunk cursor')
     .option('--limit <count>', 'Chunks per page', '20')
     .option('--json', 'Output as JSON')
-    .action((ref, checkpoint, options) => runPublicCommand(() => tracesGetCommand(ref, checkpoint, options)));
+    .action((ref, checkpoint, options) => runPublicCommand(() => tracesGetCommand(ref, checkpoint, options), options.json));
 program
     .command('dismiss <pr>')
     .description('Dismiss analysis findings for a PR')
+    .option('--json', 'Machine-readable output (see `haystack schema action`)')
     .addHelpText('after', `
 Dismiss analysis findings for a PR, moving it from "Issues Found" to
 "Good to Merge" in the Haystack feed.
@@ -414,6 +701,7 @@ Examples:
 program
     .command('mark-reviewed <pr>')
     .description('Mark human review as not needed for a PR')
+    .option('--json', 'Machine-readable output (see `haystack schema action`)')
     .addHelpText('after', `
 Mark human review as not needed for a PR, moving it from "Needs Review"
 to "Good to Merge" in the Haystack feed.
@@ -435,6 +723,7 @@ Examples:
 program
     .command('undismiss <pr>')
     .description('Undo a dismiss or mark-reviewed override for a PR')
+    .option('--json', 'Machine-readable output (see `haystack schema action`)')
     .addHelpText('after', `
 Clear all overrides (dismissed findings and/or review-not-needed) for a PR,
 returning it to its original feed bucket.
@@ -452,8 +741,9 @@ Examples:
     .action(undismissCommand);
 program
     .command('review [pr]')
-    .description('Trigger a fresh Haystack analysis for a PR')
+    .description('Trigger a fresh Haystack analysis for a PR (machine analysis — for HUMAN review use request-review)')
     .option('--no-wait', 'Exit after triggering instead of waiting for results')
+    .option('--json', 'Machine-readable output (see `haystack schema action`)')
     .addHelpText('after', `
 Re-run full Haystack analysis on a PR's current head.
 
@@ -481,6 +771,7 @@ Examples:
 program
     .command('request-review <pr> [reviewer]')
     .description('Tag a PR as needing human review')
+    .option('--json', 'Machine-readable output (see `haystack schema action`)')
     .addHelpText('after', `
 Tag any PR with "needs human review", even after it was created.
 Adds the haystack:needs-review label to the PR, moving it from
@@ -551,9 +842,9 @@ config
     .description('Auto-merge safe PRs submitted via haystack submit (on|off|status)')
     .addHelpText('after', `
 Actions:
-  on, enable    Enable auto-merge for safe PRs
-  off, disable  Disable auto-merge
-  status        Show current status (default)
+  on, enable, true     Enable auto-merge for safe PRs
+  off, disable, false  Disable auto-merge
+  status               Show current status (default)
 
 When enabled, PRs submitted via \`haystack submit\` will be
 automatically merged if Haystack analysis finds no issues
@@ -571,9 +862,9 @@ config
     .description('(Alpha) Auto-fix mechanical issues on PRs submitted via haystack submit (on|off|status)')
     .addHelpText('after', `
 Actions:
-  on, enable    Enable auto-fix for mechanical issues
-  off, disable  Disable auto-fix
-  status        Show current status (default)
+  on, enable, true     Enable auto-fix for mechanical issues
+  off, disable, false  Disable auto-fix
+  status               Show current status (default)
 
 ⚠ Auto-fix is alpha. When enabled, PRs submitted via \`haystack submit\`
 are labeled haystack:auto-fix. The Haystack analysis pipeline then
@@ -882,6 +1173,38 @@ rules
         process.exit(1);
     }
 });
+// ─── system-map ──────────────────────────────────────────────────────────────
+const systemMap = program
+    .command('system-map')
+    .description('Manage .haystack/system.yml — runtime facts that help Haystack QA run your system');
+systemMap
+    .command('validate')
+    .description('Check .haystack/system.yml against the rules Haystack QA will apply')
+    .option('--json', 'Machine-readable result')
+    .addHelpText('after', `
+The system map holds VERIFIED facts about how your system works — install/
+build commands, how services boot and signal readiness, seed/reset commands,
+dev-only test logins, external services that must never be touched live, and
+prebuilt CI artifacts. Haystack QA uses these facts to run more of what it
+already wants to test; the file never selects tests.
+
+Author it with the /map-your-system skill (haystack skills install), then run
+this before committing. Checks: valid YAML + version, no test-selection keys,
+no secret values, non-empty boot/login/run commands, artifact declarations.
+
+Examples:
+  haystack system-map validate
+  haystack system-map validate --json
+`)
+    .action(async (opts) => {
+    try {
+        await systemMapValidateCommand(opts);
+    }
+    catch (err) {
+        console.error(chalk.red('validate failed:'), err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+});
 // ─── mcp ─────────────────────────────────────────────────────────────────────
 program
     .command('mcp')

package/dist/schema.d.ts

@@ -13,9 +13,13 @@ export declare const SCHEMA_VERSIONS: {
     readonly triage: "2.0.0";
     readonly setup: "1.0.0";
     readonly pr: "2.0.0";
+    readonly 'pr-status': "1.0.0";
     readonly inbox: "1.0.0";
     readonly ask: "1.0.0";
     readonly traces: "1.0.0";
+    readonly submit: "1.0.0";
+    readonly action: "1.0.0";
+    readonly error: "1.0.0";
 };
 export type SchemaName = keyof typeof SCHEMA_VERSIONS;
 /** Wrap a payload with the `schema_version` envelope. */

package/dist/schema.js

@@ -13,9 +13,13 @@ export const SCHEMA_VERSIONS = {
     triage: '2.0.0',
     setup: '1.0.0',
     pr: '2.0.0',
+    'pr-status': '1.0.0',
     inbox: '1.0.0',
     ask: '1.0.0',
     traces: '1.0.0',
+    submit: '1.0.0',
+    action: '1.0.0',
+    error: '1.0.0',
 };
 /** Wrap a payload with the `schema_version` envelope. */
 export function withSchema(name, payload) {