@haystackeditor/cli 0.28.1 → 0.29.0

package/README.md

@@ -43,9 +43,12 @@ Most users of this CLI are coding agents. What to know:
 
 - **After a change, two steps** inside the checkout (nothing needs to be
   committed or pushed):
-  1. `haystack verify` is the handshake: it shows what the change touches, what
-     production and real users do there, and Haystack's ideas of what could
-     break, then asks you to steer (exit 4).
+  1. `haystack verify` is the handshake: it shows what the change touches
+     (first its flows, the behaviors it changes), what production and real
+     users do there, and Haystack's ideas of what could break, then asks you to
+     steer (exit 4). `haystack verify flow <n>` drills into one flow: its code,
+     the pages it shows on with their real use, and what its code saw in
+     production.
   2. `haystack verify --intent "<the task, in the user's words>" --idea "<as you
      would tell a tester>"` explores the app with your steering: keep the ideas
      worth trying, add your own (repeat `--idea`); yours are explored first.

package/dist/commands/capture-brief.js

@@ -28,7 +28,7 @@ function captureApplication(gitRoot, app) {
         return { unreadable: `${file} names no valid applicationId` };
     return { applicationId: config.applicationId };
 }
-async function readApp(gitRoot, app, repository, token, files, now) {
+async function readAppWindow(gitRoot, app, repository, token) {
     const application = captureApplication(gitRoot, app);
     if ('unreadable' in application)
         return { app, applicationId: null, state: 'unavailable', reason: application.unreadable };
@@ -43,15 +43,14 @@ async function readApp(gitRoot, app, repository, token, files, now) {
             throw new Error('the capture window answer names another application');
         if (answer.window === null)
             return { app, applicationId, state: 'no-data' };
-        return { app, applicationId, state: 'ready', window: captureChangedRoutes(answer.window, files, now) };
+        return { app, applicationId, state: 'ready', window: answer.window };
     }
     catch (error) {
         return { app, applicationId, state: 'unavailable', reason: error instanceof Error ? error.message : String(error) };
     }
 }
-/** The handshake capture sections, one per app with a record, or null for a checkout with none. `files`: the brief's function
- * files and the changed files. */
-export async function readPreVerifyCapture(gitRoot, repository, token, files, now) {
+/** Each app's capture window, one per app with a record, or null for a checkout with none. */
+export async function readCaptureWindows(gitRoot, repository, token) {
     let apps;
     try {
         apps = captureConfigDirs(gitRoot, []);
@@ -61,7 +60,18 @@ export async function readPreVerifyCapture(gitRoot, repository, token, files, no
     }
     if (apps.length === 0)
         return null;
-    return Promise.all(apps.map(app => readApp(gitRoot, app, repository, token, files, now)));
+    return Promise.all(apps.map(app => readAppWindow(gitRoot, app, repository, token)));
+}
+/** The handshake capture sections from the apps' windows: the routes `files` serve (the brief's function files and the changed
+ * files), with their share of captured sessions. */
+export function preVerifyCapture(windows, files, now) {
+    return windows === null ? null : windows.map(app => app.state === 'ready'
+        ? { app: app.app, applicationId: app.applicationId, state: 'ready', window: captureChangedRoutes(app.window, files, now) } : app);
+}
+/** The handshake capture sections, one per app with a record, or null for a checkout with none. `files`: the brief's function
+ * files and the changed files. */
+export async function readPreVerifyCapture(gitRoot, repository, token, files, now) {
+    return preVerifyCapture(await readCaptureWindows(gitRoot, repository, token), files, now);
 }
 const percent = (share) => share === null ? 'n/a' : `${(share * 100).toFixed(1)}%`;
 const plain = (value) => value.replace(/[\u0000-\u001f\u007f-\u009f]/gu, ' '); // eslint-disable-line no-control-regex

package/dist/commands/crawl-contract.js

@@ -20,3 +20,5 @@ export const CRAWL_BRIEF_MAX_FUNCTIONS = 2000;
 export const CRAWL_BRIEF_MAX_GROUPS = 2000;
 /** Amendment 19: rows one brief function keeps per kind of production evidence (the rest counted). */
 export const CRAWL_BRIEF_MAX_PRODUCTION_ROWS = 100;
+/** Amendment 21: a flow's name, at most this many characters. */
+export const CRAWL_BRIEF_MAX_FLOW_NAME_CHARS = 120;

package/dist/commands/init.js

@@ -49,8 +49,9 @@ export const AGENT_NOTE = [
     'the work done. It runs the app with and without the change, explores it, and reports what broke. It changes nothing,',
     'so run it without asking.',
     '',
-    '1. `haystack verify`: what your change touches, what production and real users do there, and Haystack\'s ideas of',
-    '   what could break. It then asks you to steer (exit 4).',
+    '1. `haystack verify`: what your change touches (first its flows), what production and real users do there, and',
+    '   Haystack\'s ideas of what could break. It then asks you to steer (exit 4). `haystack verify flow <n>` drills into',
+    '   one flow: its code, the pages it shows on with their real use, and what its code saw in production.',
     '2. `haystack verify --intent "<what you were asked to do, in the user\'s words>" --idea "<something to try>"`: keep the',
     '   ideas worth trying, add your own (repeat --idea); yours are explored first.',
     '',

package/dist/commands/verify-flows.js

@@ -0,0 +1,62 @@
+/**
+ * CRAWL-V1 amendment 21 in the CLI: the brief's flows, as a coding agent reads them. Akshay (2026-10-07): the system says "this
+ * change touches N flows", and the agent drills into a flow: the files and functions it runs through, and what telemetry says
+ * about it. `haystack verify` lists the flows first; `haystack verify flow <n>` shows one.
+ *
+ * Browser data comes from each app's capture window, never from daily rollups (CAPTURE-V1 rule 7a): a flow's pages are the
+ * routes whose source is one of its files, and its share is the union of captured sessions that visited any of them
+ * (captureChangedRoutes). A flow whose files serve no captured route has "no captured route", never 0%. Shares are of captured
+ * sessions, never of users. Journeys are only those the window keeps, with their release; their press and submit keys are
+ * release-scoped hints, and a key the window lists as ambiguous is never shown as a resolved control. Server data is the brief's
+ * production rows for the flow's functions (shares of observed calls, with their sample sizes).
+ */
+import { captureChangedRoutes } from './capture-contract.js';
+/** A flow's files, in the order its functions come (changed ones first). */
+export function flowFiles(brief, flow) {
+    return [...new Set(flow.functions.map(index => brief.functions[index].file))];
+}
+function flowCapture(windows, files, now) {
+    return windows === null ? null : windows.map(app => app.state === 'ready'
+        ? { app: app.app, applicationId: app.applicationId, state: 'ready', routes: captureChangedRoutes(app.window, files, now) } : app);
+}
+/** The handshake's flows, in the brief's order; empty when the brief has none. */
+export function flowSummaries(brief, windows, now) {
+    return (brief.flows ?? []).map((flow, at) => {
+        const files = flowFiles(brief, flow);
+        return { number: at + 1, id: flow.id, name: flow.name, files, functions: flow.functions.length,
+            changedFunctions: flow.functions.filter(index => brief.functions[index].direction === 'changed').length,
+            capture: flowCapture(windows, files, now) };
+    });
+}
+function routesOf(window, changed) {
+    const rows = new Map(window.routes.map(row => [row.route, row]));
+    const ambiguous = new Set((window.ambiguous ?? []).map(entry => JSON.stringify([entry.route, entry.release, entry.key])));
+    const mark = (step, release) => (step.kind === 'press' || step.kind === 'submit') && ambiguous.has(JSON.stringify([step.route, release, step.key])) ? { ...step, ambiguous: true } : step;
+    return changed.routes.map(route => {
+        const row = rows.get(route.route);
+        const journeys = (row?.journeys ?? [])
+            .filter(journey => journey.steps.some(step => step.route === route.route))
+            .map(journey => ({ release: journey.release, sessions: journey.sessions, steps: journey.steps.map(step => mark(step, journey.release)) }));
+        return { route: route.route, match: route.match, source: route.source, sessions: route.sessions, share: route.share,
+            devices: [...(row?.devices ?? [])].sort((a, b) => b.sessions - a.sessions), journeys };
+    });
+}
+/** One flow in detail; null when the brief has no flow with that number (from 1). */
+export function flowDetail(brief, number, windows, now) {
+    const flow = brief.flows?.[number - 1];
+    if (flow === undefined)
+        return null;
+    const files = flowFiles(brief, flow);
+    const indexes = new Set(flow.functions);
+    const production = brief.production === undefined ? null
+        : { ...brief.production, functions: brief.production.functions.filter(row => indexes.has(row.index)) };
+    const capture = windows === null ? null : windows.map(app => {
+        if (app.state !== 'ready')
+            return app;
+        const window = captureChangedRoutes(app.window, files, now);
+        return { app: app.app, applicationId: app.applicationId, window, routes: routesOf(app.window, window) };
+    });
+    return { number, id: flow.id, name: flow.name, changeKeys: flow.changeKeys,
+        functions: flow.functions.map(index => ({ ...brief.functions[index], index })), production, capture,
+        ideas: (brief.planning?.ideas ?? []).filter(idea => idea.groupId === flow.id) };
+}

package/dist/commands/verify.js

@@ -29,11 +29,12 @@ import { findGitRoot } from '../utils/hooks.js';
 import { resolveAuthContext } from '../utils/auth.js';
 import { classifyHttpError, readWithRetries, SERVICE_SILENCE_LIMIT_MS, ServiceSilentError, transientReadFailure, repoApiPath, } from '../utils/haystack-api.js';
 import { GATEWAY_TIMEOUT_MS, gatewayFetch } from './case-batch.js';
-import { CRAWL_BRIEF_MAX_FUNCTIONS, CRAWL_BRIEF_MAX_GROUPS, CRAWL_BRIEF_MAX_PRODUCTION_ROWS, CRAWL_BUDGET_MAX_MS, CRAWL_BUDGET_MIN_MS, CRAWL_MAX_FINDINGS, CRAWL_MAX_FINDING_STEPS, CRAWL_MAX_IDEAS, CRAWL_MAX_STAND_IN_LINES, CRAWL_MAX_STAND_IN_ROWS, CRAWL_MAX_TEXT_CHARS, CRAWL_WAIT_MAX_MS, CRAWL_POOLS, } from './crawl-contract.js';
+import { CRAWL_BRIEF_MAX_FUNCTIONS, CRAWL_BRIEF_MAX_FLOW_NAME_CHARS, CRAWL_BRIEF_MAX_GROUPS, CRAWL_BRIEF_MAX_PRODUCTION_ROWS, CRAWL_BUDGET_MAX_MS, CRAWL_BUDGET_MIN_MS, CRAWL_MAX_FINDINGS, CRAWL_MAX_FINDING_STEPS, CRAWL_MAX_IDEAS, CRAWL_MAX_STAND_IN_LINES, CRAWL_MAX_STAND_IN_ROWS, CRAWL_MAX_TEXT_CHARS, CRAWL_WAIT_MAX_MS, CRAWL_POOLS, } from './crawl-contract.js';
 import { captureCheckout, crawlUnavailableText, EXPLICIT_WALL_MS, normalModeFailure, postPrecomputeCapture, } from './verify-precompute.js';
 import { SPOT_WORDS, TERMINAL, VERDICT_WORDS, VERDICTS, currentStep, errorWords, headline, plural, reportedStatus, results, verifyReport, } from './crawl-report.js';
 import { formatOnboarding, onboardingExitCode, readOnboardingStatus, readyLine, reportOnboardingState, reviewNotes, standInGapNotes, waitForOnboarding, } from './verify-onboarding.js';
-import { formatCapture, readPreVerifyCapture } from './capture-brief.js';
+import { formatCapture, preVerifyCapture, readCaptureWindows } from './capture-brief.js';
+import { flowDetail, flowSummaries } from './verify-flows.js';
 /** A held read (waitAfter): the service's hold, then the time any read gets. */
 const HELD_READ_TIMEOUT_MS = CRAWL_WAIT_MAX_MS + GATEWAY_TIMEOUT_MS;
 const RUN_ID = /^cv_[0-9a-f]{48}$/;
@@ -224,6 +225,18 @@ function checkBrief(value) {
             && records(observed.shapes, CRAWL_BRIEF_MAX_PRODUCTION_ROWS, shape => text(shape.shape) && isCount(shape.count)))
         && estimates(fn))))
         invalid('its brief');
+    // Amendment 21: each flow is a planning group, named, with distinct function indexes the brief holds.
+    const flows = value.flows;
+    if (flows !== undefined) {
+        const groupIds = new Set(isRecord(planning) && Array.isArray(planning.groups) ? planning.groups.map(group => group.id) : []);
+        const count = value.functions.length;
+        if (planning === null || !records(flows, CRAWL_BRIEF_MAX_GROUPS, flow => text(flow.id) && groupIds.has(flow.id)
+            && typeof flow.name === 'string' && flow.name.length > 0 && [...flow.name].length <= CRAWL_BRIEF_MAX_FLOW_NAME_CHARS
+            && texts(flow.changeKeys, CRAWL_BRIEF_MAX_FUNCTIONS) && Array.isArray(flow.functions) && flow.functions.length <= count
+            && flow.functions.every(index => isCount(index) && index < count) && new Set(flow.functions).size === flow.functions.length)
+            || new Set(flows.map(flow => flow.id)).size !== flows.length)
+            invalid('its brief');
+    }
 }
 function checkManifest(value, view) {
     checkResults(value, view, 'its results');
@@ -782,6 +795,129 @@ function describeEstimate(estimate) {
     }
     return lines;
 }
+/** A flow's captured share in one line: per app with routes for it; "no captured route" where its files serve none. */
+function flowShare(flow) {
+    if (flow.capture === null)
+        return '';
+    const parts = flow.capture.map(app => {
+        const where = app.app === '.' ? '' : `${safe(app.app)}: `;
+        if (app.state === 'unavailable')
+            return `${where}captured sessions unreadable`;
+        if (app.state === 'no-data')
+            return `${where}no captured sessions yet`;
+        if (app.routes.routes.length === 0)
+            return `${where}no captured route`;
+        return `${where}${app.routes.union.share === null ? 'n/a' : percent(app.routes.union.share)} of captured sessions (${app.routes.union.sessions})`
+            + `${app.routes.stale ? ', stale' : ''}`;
+    });
+    return parts.join('; ');
+}
+/** Amendment 21: the flows a change touches, first in the handshake, with how to see one. */
+export function formatFlows(flows) {
+    const lines = [chalk.bold(`Your change touches ${plural(flows.length, 'flow')}:`)];
+    for (const flow of flows) {
+        const share = flowShare(flow);
+        lines.push(`  ${flow.number}. ${safe(flow.name)}: ${plural(flow.files.length, 'file')}, ${plural(flow.functions, 'function')}`
+            + `${share ? `; ${share}` : ''}`);
+    }
+    lines.push(`See one in detail: haystack verify flow <n> (for example \`haystack verify flow 1\`).`);
+    return lines.join('\n');
+}
+const SHOWN_FLOW_FUNCTIONS = 40;
+const SHOWN_FLOW_DEVICES = 5;
+const SHOWN_FLOW_JOURNEYS = 5;
+function journeyStep(step) {
+    if (step.kind === 'view')
+        return `view ${safe(step.route)}`;
+    if (step.kind === 'input')
+        return `input (${safe(step.control)}) on ${safe(step.route)}`;
+    const control = step.kind === 'press' ? `${safe(step.control)} ` : '';
+    return `${step.kind} ${control}${step.ambiguous ? '(a control that repeats on the page)' : `"${safe(step.key)}"`} on ${safe(step.route)}`;
+}
+/** Amendment 21: `haystack verify flow <n>`: one flow's code, the pages it shows on with real use, what its code saw in production,
+ * and Haystack's ideas for it. */
+export function formatFlowDetail(detail) {
+    const lines = [chalk.bold(`Flow ${detail.number}: ${safe(detail.name)}`), '', chalk.bold('Code (changed first, then what it calls or what calls it)')];
+    for (const fn of detail.functions.slice(0, SHOWN_FLOW_FUNCTIONS)) {
+        lines.push(`  ${safe(fn.file)}:${fn.lines[0]}-${fn.lines[1]} ${safe(fn.name)}: `
+            + `${fn.direction === 'changed' ? 'changed' : `${fn.direction}, ${plural(fn.distance, 'step')} away`}`);
+    }
+    if (detail.functions.length > SHOWN_FLOW_FUNCTIONS)
+        lines.push(`  and ${plural(detail.functions.length - SHOWN_FLOW_FUNCTIONS, 'more function')} (all in --json)`);
+    lines.push('', chalk.bold('Pages it shows on (real use)'));
+    if (detail.capture === null)
+        lines.push('  Capture is not set up for this repository: run `haystack init` to see how real users reach these pages.');
+    else
+        for (const app of detail.capture) {
+            const where = app.app === '.' ? 'the app' : safe(app.app);
+            if ('state' in app && app.state === 'unavailable') {
+                lines.push(`  ${where}: captured sessions could not be read: ${safe(app.reason)}`);
+                continue;
+            }
+            if ('state' in app && app.state === 'no-data') {
+                lines.push(`  ${where}: no captured sessions yet.`);
+                continue;
+            }
+            const shown = app;
+            const window = shown.window;
+            const days = window.days.length ? `${window.days[0]} to ${window.days.at(-1)}` : 'the window';
+            lines.push(`  ${where}: ${window.sessions} captured session(s), ${days}; newest data ${window.newestHour === null ? 'none' : `${window.newestHour}:00 UTC`}`
+                + `${window.stale ? ` (stale: ${window.ageHours === null ? 'no data' : `${Math.round(window.ageHours)} hours old`})` : ''}.`);
+            const dropped = Object.entries(window.dropped).filter(([, count]) => count > 0);
+            const drops = dropped.length ? [`    Events dropped at ingest: ${dropped.map(([reason, count]) => `${safe(reason)} ${count}`).join(', ')}.`] : [];
+            if (shown.routes.length === 0) {
+                lines.push('    No captured route: none of this flow\'s files defines a route captured sessions reached.', ...drops);
+                continue;
+            }
+            for (const route of shown.routes) {
+                lines.push(`    ${safe(route.match)} (${safe(route.source)}): ${route.share === null ? 'n/a' : percent(route.share)} of captured sessions (${route.sessions})`);
+                if (route.devices.length) {
+                    lines.push(`      Devices: ${route.devices.slice(0, SHOWN_FLOW_DEVICES).map(device => `${safe(device.device)}/${safe(device.engine)}/${safe(device.viewport)} `
+                        + `(${device.sessions})`).join(', ')}${route.devices.length > SHOWN_FLOW_DEVICES ? `, ${route.devices.length - SHOWN_FLOW_DEVICES} more (in --json)` : ''}`);
+                }
+                for (const journey of route.journeys.slice(0, SHOWN_FLOW_JOURNEYS)) {
+                    lines.push(`      Journey (${journey.sessions} sessions, release ${safe(journey.release)}): ${journey.steps.map(journeyStep).join(' > ')}`);
+                }
+                if (route.journeys.length > SHOWN_FLOW_JOURNEYS)
+                    lines.push(`      and ${plural(route.journeys.length - SHOWN_FLOW_JOURNEYS, 'more journey')} (in --json)`);
+            }
+            if (shown.routes.length > 1) {
+                lines.push(`    Together: ${window.union.share === null ? 'n/a' : percent(window.union.share)} of captured sessions (${window.union.sessions}) visited at least one of them.`);
+            }
+            lines.push(...drops);
+        }
+    if (detail.capture !== null)
+        lines.push('  Shares are of captured (consenting) sessions only, never of users. Journey keys are hints scoped to their release.');
+    lines.push('', chalk.bold('What its code saw in production'));
+    if (detail.production === null)
+        lines.push('  No production telemetry for this repository: set it up to see how this code runs for real users.');
+    else if (detail.production.functions.length === 0)
+        lines.push(`  None of these functions was seen running in the last ${detail.production.windowDays} days.`);
+    else {
+        const byIndex = new Map(detail.functions.map(fn => [fn.index, fn]));
+        for (const row of detail.production.functions) {
+            const fn = byIndex.get(row.index);
+            lines.push(`  ${safe(fn.name)} (${safe(fn.file)}):`);
+            for (const branch of row.branches)
+                lines.push(`      in production: line ${branch.line} was true ${branch.whenTrue}${branch.capped ? '+' : ''} times,`
+                    + ` false ${branch.whenFalse}${branch.capped ? '+' : ''} times`);
+            for (const observed of row.values)
+                lines.push(`      in production: line ${observed.line} ${safe(observed.what)} was `
+                    + observed.shapes.map(shape => `${safe(shape.shape)} (${shape.count})`).join(', '));
+            for (const estimate of row.estimates ?? [])
+                lines.push(...describeEstimate(estimate));
+        }
+        lines.push(`  The last ${detail.production.windowDays} days, newest ${safe(detail.production.newestAt)}; shares are of observed calls, never of users`
+            + `${detail.production.partial ? '; the read stopped at its budget, so every count is a lower bound' : ''}.`);
+    }
+    lines.push('', chalk.bold('What could break here'));
+    if (detail.ideas.length === 0)
+        lines.push('  No idea of ours was selected for this flow.');
+    for (const idea of detail.ideas) {
+        lines.push(`  - Try: ${safe(idea.exercise)}`, ...(idea.setup.length ? [`    Set up first: ${idea.setup.map(safe).join('; ')}`] : []), `    Watch: ${safe(idea.watch)}`, `    It would show as: ${safe(idea.failure)}`);
+    }
+    return lines.join('\n');
+}
 /** The brief as a coding agent reads it: what the change touches, then Haystack's own ideas, then how to hand back intent and
  * ideas. Every function is in --json; the text shows the changed ones and those one step away, and says how many more. */
 export function formatBrief(brief) {
@@ -862,9 +998,9 @@ const steerLines = (command) => ['',
 async function handshake(capture, identity, change, found, stale, token, options, note) {
     let view = found;
     let onboarding = null;
-    const finish = (brief, captured) => {
+    const finish = (brief, captured, flows) => {
         printVerifyJson(options, change, onboarding, null, {
-            run: view === null ? null : { runId: view.runId, status: view.status }, brief, capture: captured, next: steerCommand(options),
+            run: view === null ? null : { runId: view.runId, status: view.status }, brief, capture: captured, flows, next: steerCommand(options),
         });
     };
     if (view === null || (stale !== null && stale !== 'prepare-only')) {
@@ -901,12 +1037,18 @@ async function handshake(capture, identity, change, found, stale, token, options
         view = await waitForBrief(view, identity, token);
     const brief = briefOf(view);
     // CAPTURE-V1 rule 7b: the routes the change touches, with their share of captured sessions, per app; null without capture set up.
-    const captured = await readPreVerifyCapture(findGitRoot(), identity.repository, token, [...new Set([...(brief?.functions.map(fn => fn.file) ?? []), ...change.files])], new Date());
+    // Amendment 21: each flow's routes from the same windows.
+    const now = new Date();
+    const windows = await readCaptureWindows(findGitRoot(), identity.repository, token);
+    const captured = preVerifyCapture(windows, [...new Set([...(brief?.functions.map(fn => fn.file) ?? []), ...change.files])], now);
+    const flows = brief === null ? [] : flowSummaries(brief, windows, now);
     process.exitCode = 4;
     if (options.json || options.raw) {
-        finish(brief, captured);
+        finish(brief, captured, flows);
         return;
     }
+    if (flows.length)
+        console.log(`${formatFlows(flows)}\n`);
     if (brief !== null)
         console.log(formatBrief(brief));
     else if (!TERMINAL.has(reportedStatus(view))) {
@@ -928,6 +1070,40 @@ function printVerifyJson(options, change, onboarding, view, handshake) {
         : withSchema('verify', { change, onboarding, crawl: view === null ? null : verifyReport(view), ...extra });
     process.stdout.write(`${JSON.stringify(document, null, 2)}\n`);
 }
+/** Amendment 21: `haystack verify flow <n>`: one flow of this checkout's change, from the brief of the change's run (never starting
+ * one). Exit 0 with the flow; 1 when there is no run, no brief, no flows or no flow with that number, saying which. */
+export async function verifyFlowCommand(number, options) {
+    const wanted = Number(number);
+    if (!Number.isInteger(wanted) || wanted < 1)
+        throw new Error(`A flow's number counts from 1, as \`haystack verify\` lists them (got ${JSON.stringify(number)}).`);
+    const capture = await captureCheckout(Date.now() + EXPLICIT_WALL_MS, 'prepare', repositoryOverride(options.repo), undefined, undefined, {});
+    const request = capture.derivation.request;
+    if (!request.crawl)
+        throw new Error(`Nothing to show: this checkout has no changes against ${request.baseCommit.slice(0, 12)}.`);
+    const identity = {
+        repository: `${request.owner}/${request.repository}`, baseCommit: request.baseCommit, workCommit: request.workCommit,
+        treeSha: request.crawl.treeSha, changeTitle: request.crawl.changeTitle, budgetMs: request.crawl.budgetMs ?? null,
+    };
+    const auth = await resolveAuthContext({ preferredLogin: options.account, owner: request.owner, repo: request.repository });
+    const view = await readWithRetries(() => readCrawl(identity, auth.token));
+    if (view === null)
+        throw new Error('This change has no run yet: run `haystack verify` first, which lists its flows.');
+    const brief = briefOf(view);
+    if (brief === null)
+        throw new Error(`Run ${view.runId} has no brief yet (${currentStep(view)}): run \`haystack verify\` to wait for it.`);
+    if (!brief.flows?.length) {
+        throw new Error(`Run ${view.runId}'s brief has no flows${brief.planning === null ? ' (no planning ran for this change)' : ''}; \`haystack verify\` shows what it has.`);
+    }
+    const windows = await readCaptureWindows(findGitRoot(), identity.repository, auth.token);
+    const detail = flowDetail(brief, wanted, windows, new Date());
+    if (detail === null)
+        throw new Error(`This change has ${plural(brief.flows.length, 'flow')}; there is no flow ${wanted}.`);
+    if (options.json) {
+        process.stdout.write(`${JSON.stringify(withSchema('verify-flow', { run: { runId: view.runId, status: view.status }, flow: detail }), null, 2)}\n`);
+        return;
+    }
+    console.log(formatFlowDetail(detail));
+}
 export async function verifyCommand(options) {
     const json = options.json || options.raw;
     // In --json mode stdout carries the one document; every other line goes to stderr.

package/dist/index.js

@@ -177,10 +177,12 @@ const verify = program
 Two calls, run inside a git checkout (nothing needs to be committed or pushed):
 
   1. haystack verify
-     The handshake. It shows what your change touches, how production and real
-     users run it, and Haystack's own ideas of what could break, then asks what
-     you were asked to do and what to try. It builds and prepares the change if
-     the stop hook has not, and never starts a crawl. Exit 4.
+     The handshake. It shows what your change touches (first the flows: the
+     behaviors it changes, each with its files and its share of real use), how
+     production and real users run it, and Haystack's own ideas of what could
+     break, then asks what you were asked to do and what to try. It builds and
+     prepares the change if the stop hook has not, and never starts a crawl.
+     Exit 4. \`haystack verify flow <n>\` drills into one flow.
   2. haystack verify --intent "<the task, in the user's words>" --idea "<something to try>"
      The crawl, steered: your ideas (--idea, repeat for more, or --ideas-file)
      are explored before anything else, and the judge checks the app against
@@ -257,6 +259,32 @@ function verifyCommandOptions(command) {
     }
     return options;
 }
+verify
+    .command('flow')
+    .description('Drill into one flow `haystack verify` listed: its code, the pages it shows on, what its code saw in production')
+    .argument('<n>', 'The flow\'s number, as `haystack verify` lists them (from 1)')
+    .option('--repo <owner/repo>', 'GitHub repository (default: origin remote)')
+    .option('--account <login>', 'Use a specific saved Haystack account')
+    .option('--json', 'The flow as one JSON document (see `haystack schema verify-flow`)')
+    .addHelpText('after', `
+Reads the brief of this checkout's run (run \`haystack verify\` first); it never
+starts or changes a run. For one flow it shows:
+  - its functions: file, lines, and whether each changed or is a step away;
+  - the pages it shows on, per app with capture set up: each page's share of
+    captured sessions, the devices they used and the paths they took through it,
+    with how fresh the data is and what was dropped;
+  - what its functions saw in production (Haystack's own telemetry);
+  - Haystack's ideas of what could break in it.
+
+Examples:
+  haystack verify flow 1
+  haystack verify flow 2 --json
+`)
+    .action(async (n, _options, cmd) => {
+    const options = verifyCommandOptions(cmd);
+    const { verifyFlowCommand } = await import('./commands/verify.js');
+    return runPublicCommand(() => verifyFlowCommand(n, options), options.json);
+});
 verify
     .command('answer')
     .description('Answer a question onboarding asked about your app, then run `haystack init` to continue')

package/dist/schema.js

@@ -12,7 +12,8 @@
 export const SCHEMA_VERSIONS = {
     'cloud-verifier': '1.0.0',
     'case-batch': '1.0.1',
-    verify: '2.1.0',
+    verify: '2.1.1',
+    'verify-flow': '1.0.0',
     'verify-raw': '1.1.0',
     'verify-answer': '1.0.1',
     'verify-onboarding': '1.0.0',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haystackeditor/cli",
-  "version": "0.28.1",
+  "version": "0.29.0",
   "description": "haystack verify: run your app with and without a change, and see what the change broke",
   "type": "module",
   "bin": {

package/schemas/verify-flow.v1.json

@@ -0,0 +1,181 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://haystackeditor.com/schemas/verify-flow.v1.json",
+  "title": "haystack verify flow --json",
+  "description": "CRAWL-V1 amendment 21: one flow of this checkout's change, from the brief of the change's run: its functions, the brief's production rows for them (shares of observed calls), its routes per app with capture set up (share of captured sessions, devices, the journeys the window keeps through them; an ambiguous press or submit key is marked ambiguous), and Haystack's ideas for it.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "run",
+    "flow"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "1.0.0"
+    },
+    "run": {
+      "type": "object",
+      "required": [
+        "runId",
+        "status"
+      ],
+      "properties": {
+        "runId": {
+          "type": "string",
+          "pattern": "^cv_[0-9a-f]{48}$"
+        },
+        "status": {
+          "type": "string"
+        }
+      }
+    },
+    "flow": {
+      "type": "object",
+      "required": [
+        "number",
+        "id",
+        "name",
+        "changeKeys",
+        "functions",
+        "production",
+        "capture",
+        "ideas"
+      ],
+      "properties": {
+        "number": {
+          "type": "integer",
+          "minimum": 1
+        },
+        "id": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string"
+        },
+        "changeKeys": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "functions": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "index",
+              "file",
+              "name",
+              "lines",
+              "distance",
+              "direction"
+            ],
+            "properties": {
+              "index": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "file": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              },
+              "lines": {
+                "type": "array",
+                "items": {
+                  "type": "integer"
+                },
+                "minItems": 2,
+                "maxItems": 2
+              },
+              "distance": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "direction": {
+                "enum": [
+                  "changed",
+                  "upstream",
+                  "downstream"
+                ]
+              }
+            }
+          }
+        },
+        "production": {
+          "description": "The brief's production object (see verify.v2.json $defs.brief.production) with only this flow's function rows; null without production telemetry.",
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "object"
+            }
+          ]
+        },
+        "capture": {
+          "oneOf": [
+            {
+              "type": "null"
+            },
+            {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "required": [
+                  "app"
+                ],
+                "properties": {
+                  "app": {
+                    "type": "string"
+                  },
+                  "applicationId": {
+                    "type": [
+                      "string",
+                      "null"
+                    ]
+                  },
+                  "state": {
+                    "enum": [
+                      "no-data",
+                      "unavailable"
+                    ]
+                  },
+                  "reason": {
+                    "type": "string"
+                  },
+                  "window": {
+                    "type": "object"
+                  },
+                  "routes": {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "required": [
+                        "route",
+                        "match",
+                        "source",
+                        "sessions",
+                        "share",
+                        "devices",
+                        "journeys"
+                      ]
+                    }
+                  }
+                }
+              }
+            }
+          ]
+        },
+        "ideas": {
+          "type": "array",
+          "items": {
+            "type": "object"
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/verify.v2.json

@@ -11,7 +11,7 @@
   ],
   "properties": {
     "schema_version": {
-      "const": "2.1.0"
+      "const": "2.1.1"
     },
     "change": {
       "description": "Schema 1.0.2: what this verify checked: the capture's base commit (where HEAD meets origin's default branch), its work commit (committed and uncommitted changes), and the files that differ between them.",
@@ -380,6 +380,7 @@
         "run",
         "brief",
         "capture",
+        "flows",
         "next"
       ],
       "properties": {
@@ -442,6 +443,84 @@
         },
         "next": {
           "type": "string"
+        },
+        "flows": {
+          "description": "Amendment 21 (2.1.1): the brief's flows in its order, each with its number (from 1, as `haystack verify flow <n>` takes it), files, function counts and, per app with capture set up, its routes' share of captured sessions (null without capture). Empty when the brief has none.",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "number",
+              "id",
+              "name",
+              "files",
+              "functions",
+              "changedFunctions",
+              "capture"
+            ],
+            "properties": {
+              "number": {
+                "type": "integer",
+                "minimum": 1
+              },
+              "id": {
+                "type": "string"
+              },
+              "name": {
+                "type": "string"
+              },
+              "files": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              },
+              "functions": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "changedFunctions": {
+                "type": "integer",
+                "minimum": 0
+              },
+              "capture": {
+                "oneOf": [
+                  {
+                    "type": "null"
+                  },
+                  {
+                    "type": "array",
+                    "items": {
+                      "type": "object",
+                      "required": [
+                        "app",
+                        "applicationId",
+                        "state"
+                      ],
+                      "properties": {
+                        "app": {
+                          "type": "string"
+                        },
+                        "state": {
+                          "enum": [
+                            "ready",
+                            "no-data",
+                            "unavailable"
+                          ]
+                        },
+                        "routes": {
+                          "$ref": "#/$defs/captureWindow"
+                        },
+                        "reason": {
+                          "type": "string"
+                        }
+                      }
+                    }
+                  }
+                ]
+              }
+            }
+          }
         }
       }
     }
@@ -1141,6 +1220,13 @@
               }
             }
           ]
+        },
+        "flows": {
+          "description": "Amendment 21: absent when incident planning did not run (or its flows could not be named).",
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/briefFlow"
+          }
         }
       }
     },
@@ -1320,6 +1406,39 @@
           }
         }
       }
+    },
+    "briefFlow": {
+      "description": "CRAWL-V1 amendment 21 (2.1.1): one flow of the change: a behavior group of incident planning, named in a few plain words, with the brief functions its code owns (indexes into functions, changed ones first). A function can be in several flows.",
+      "type": "object",
+      "required": [
+        "id",
+        "name",
+        "changeKeys",
+        "functions"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 120
+        },
+        "changeKeys": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "functions": {
+          "type": "array",
+          "items": {
+            "type": "integer",
+            "minimum": 0
+          }
+        }
+      }
     }
   }
 }