@productbrain/cli 0.1.0-beta.95 → 0.1.0-beta.958

package/dist/lib/upgrade-runner.js

@@ -0,0 +1,109 @@
+import { spawn } from 'node:child_process';
+import { basename, dirname } from 'node:path';
+import { CLIError, ErrorCode } from './errors.js';
+import { UPGRADE_COMMAND } from './constants.js';
+import { trackEvent } from './telemetry.js';
+import { writeUpgradePendingSentinel } from './update-check.js';
+function pathSegments(path) {
+    const segments = [];
+    let current = path;
+    while (current && current !== dirname(current)) {
+        segments.push(basename(current).toLowerCase());
+        current = dirname(current);
+    }
+    return segments;
+}
+export function detectInstallChannel(execPath = process.execPath, env = process.env) {
+    const ua = env.npm_config_user_agent?.toLowerCase() ?? '';
+    if (ua.startsWith('pnpm'))
+        return 'pnpm';
+    if (ua.startsWith('yarn'))
+        return 'yarn';
+    if (ua.startsWith('bun'))
+        return 'bun';
+    if (ua.startsWith('npm'))
+        return 'npm';
+    const segments = pathSegments(execPath);
+    if (segments.some((s) => s.includes('pnpm')))
+        return 'pnpm';
+    if (segments.some((s) => s.includes('yarn')))
+        return 'yarn';
+    if (segments.some((s) => s.includes('bun')))
+        return 'bun';
+    if (segments.some((s) => s.includes('homebrew') || s === 'brew' || s === 'cellar'))
+        return 'brew';
+    if (segments.some((s) => s.includes('npm') || s === 'node_modules'))
+        return 'npm';
+    return 'unknown';
+}
+export function buildUpgradeCommand(channel) {
+    switch (channel) {
+        case 'pnpm':
+            return { channel, command: 'pnpm', args: ['add', '-g', '@productbrain/cli@beta'], display: 'pnpm add -g @productbrain/cli@beta' };
+        case 'yarn':
+            return { channel, command: 'yarn', args: ['global', 'add', '@productbrain/cli@beta'], display: 'yarn global add @productbrain/cli@beta' };
+        case 'bun':
+            return { channel, command: 'bun', args: ['add', '-g', '@productbrain/cli@beta'], display: 'bun add -g @productbrain/cli@beta' };
+        case 'brew':
+            return { channel, command: 'brew', args: ['upgrade', 'productbrain'], display: 'brew upgrade productbrain' };
+        case 'npm':
+        case 'unknown':
+            return { channel, command: 'npm', args: ['install', '-g', '@productbrain/cli@beta'], display: UPGRADE_COMMAND };
+    }
+}
+function failureGuidance(message) {
+    const lower = message.toLowerCase();
+    if (lower.includes('eacces') || lower.includes('permission denied')) {
+        return 'Permission denied during global install. Use a Node version manager, fix the global npm prefix, or rerun the install command with the permissions your system requires.';
+    }
+    if (process.platform === 'win32' && (lower.includes('eperm') || lower.includes('busy') || lower.includes('locked'))) {
+        return 'Windows could not replace the active pb executable. Close terminals running pb, then rerun the upgrade command.';
+    }
+    return 'Run the displayed upgrade command manually, then retry pb doctor.';
+}
+export function spawnUpgrade(channel = detectInstallChannel(), options = {}) {
+    const spec = buildUpgradeCommand(channel);
+    const output = [];
+    trackEvent('cli.upgrade.initiated', { channel: spec.channel });
+    return new Promise((resolve, reject) => {
+        const child = spawn(spec.command, spec.args, {
+            env: options.env ?? process.env,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        const emit = (chunk) => {
+            const text = chunk.toString();
+            for (const line of text.split(/\r?\n/).filter(Boolean)) {
+                output.push(line);
+                options.onOutput?.(line);
+            }
+        };
+        child.stdout?.on('data', emit);
+        child.stderr?.on('data', emit);
+        child.on('error', (err) => {
+            const message = err.message || `Failed to spawn ${spec.display}`;
+            trackEvent('cli.upgrade.failed', { channel: spec.channel, reason: err.code ?? 'spawn_error' });
+            reject(new CLIError(`Upgrade failed: ${message}`, {
+                code: ErrorCode.UPGRADE_FAILED,
+                category: 'internal',
+                guidance: failureGuidance(message),
+            }));
+        });
+        child.on('close', (code) => {
+            const exitCode = code ?? 1;
+            if (exitCode !== 0) {
+                const message = output.slice(-4).join('\n') || `${spec.display} exited with code ${exitCode}`;
+                trackEvent('cli.upgrade.failed', { channel: spec.channel, exitCode });
+                reject(new CLIError(`Upgrade failed: ${message}`, {
+                    code: ErrorCode.UPGRADE_FAILED,
+                    category: 'internal',
+                    guidance: failureGuidance(message),
+                }));
+                return;
+            }
+            writeUpgradePendingSentinel();
+            trackEvent('cli.upgrade.succeeded', { channel: spec.channel });
+            resolve({ channel: spec.channel, command: spec.display, exitCode, output });
+        });
+    });
+}
+//# sourceMappingURL=upgrade-runner.js.map

package/dist/lib/upgrade-runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade-runner.js","sourceRoot":"","sources":["../../src/lib/upgrade-runner.ts"],"names":[],"mappings":"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"}

package/dist/lib/workspaceVocabCache.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 5-minute TTL cache for workspace vocabulary context (WP-436 S2).
+ *
+ * Purpose (R2 mitigation): the CLI resolves vocabulary labels on every invocation.
+ * Without a cache, each `pb orient` / `pb get` / `pb capture` would call
+ * `chain.getVocabulary` — adding a Convex round-trip overhead and risking
+ * handshake-time staleness. A 5-min TTL short-circuits repeat calls within
+ * a typical session while staying fresh enough that label changes land quickly.
+ *
+ * PAT-230: the cache holds WorkspaceVocabCtx (pure data, no Convex imports here).
+ * DEC-1021: only Axis 2 (collectionLabels) lives here; Axis 1 (displayNames) is untouched.
+ *
+ * S4 note: when Cortex UI builds its `vocabularyStore`, it should mirror this
+ * contract — a keyed map by workspaceId with an expiresAt field (Cortex has
+ * direct access to workspaceId; the CLI uses apiKey as a 1:1 surrogate, since
+ * the HTTP gateway server-side injects workspaceId from authResult per
+ * convex/http.ts:675).
+ */
+import type { WorkspaceVocabCtx } from './canonicalRefs.js';
+/**
+ * Get a cached WorkspaceVocabCtx by cacheKey, or null if expired/missing.
+ * Prints a staleness warning when the entry is older than STALE_WARN_MS.
+ */
+export declare function getCachedVocabCtx(cacheKey: string): WorkspaceVocabCtx | null;
+/**
+ * Store a WorkspaceVocabCtx under cacheKey with a 5-min TTL.
+ */
+export declare function setCachedVocabCtx(cacheKey: string, ctx: WorkspaceVocabCtx): void;
+/**
+ * Explicitly invalidate a cached vocab context by cacheKey.
+ * Call this when `updateCollectionLabels` mutation succeeds (e.g. after `pb handshake`).
+ */
+export declare function invalidateVocabCtx(cacheKey: string): void;
+/**
+ * Clear all cached entries (useful for testing or `pb handshake --refresh`).
+ */
+export declare function clearVocabCache(): void;
+/**
+ * Get the cached vocab context, or fetch it via the provided async fetcher on cache miss.
+ *
+ * Usage pattern at CLI command sites:
+ * ```ts
+ * const vocabCtx = await getOrFetchVocabCtx(config.apiKey, async () => {
+ *   type VocabResult = { collectionLabels?: Record<string, unknown> };
+ *   const vocab = await kernelCall<VocabResult>('chain.getVocabulary', {});
+ *   return vocab?.collectionLabels
+ *     ? { collectionLabels: vocab.collectionLabels as WorkspaceVocabCtx['collectionLabels'] }
+ *     : null;
+ * });
+ * ```
+ *
+ * - `cacheKey`: use the API key as a surrogate for cacheKey (1:1 mapping at CLI layer).
+ * - `fetcher`: async function that resolves the vocab ctx; returns null on failure to signal
+ *   "don't cache, fall back to resolver literal". Fetcher errors are swallowed — vocabulary
+ *   labels are advisory (PAT-230 / fail-open principle).
+ *
+ * Returns WorkspaceVocabCtx on cache hit or successful fetch; undefined on error/null fetcher result.
+ */
+export declare function getOrFetchVocabCtx(cacheKey: string, fetcher: () => Promise<WorkspaceVocabCtx | null>): Promise<WorkspaceVocabCtx | undefined>;
+//# sourceMappingURL=workspaceVocabCache.d.ts.map

package/dist/lib/workspaceVocabCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceVocabCache.d.ts","sourceRoot":"","sources":["../../src/lib/workspaceVocabCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAc5D;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,GAAG,iBAAiB,GAAG,IAAI,CAe5E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,iBAAiB,GAAG,IAAI,CAEhF;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAEzD;AAED;;GAEG;AACH,wBAAgB,eAAe,IAAI,IAAI,CAEtC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,GAC/C,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC,CAcxC"}

package/dist/lib/workspaceVocabCache.js

@@ -0,0 +1,98 @@
+/**
+ * 5-minute TTL cache for workspace vocabulary context (WP-436 S2).
+ *
+ * Purpose (R2 mitigation): the CLI resolves vocabulary labels on every invocation.
+ * Without a cache, each `pb orient` / `pb get` / `pb capture` would call
+ * `chain.getVocabulary` — adding a Convex round-trip overhead and risking
+ * handshake-time staleness. A 5-min TTL short-circuits repeat calls within
+ * a typical session while staying fresh enough that label changes land quickly.
+ *
+ * PAT-230: the cache holds WorkspaceVocabCtx (pure data, no Convex imports here).
+ * DEC-1021: only Axis 2 (collectionLabels) lives here; Axis 1 (displayNames) is untouched.
+ *
+ * S4 note: when Cortex UI builds its `vocabularyStore`, it should mirror this
+ * contract — a keyed map by workspaceId with an expiresAt field (Cortex has
+ * direct access to workspaceId; the CLI uses apiKey as a 1:1 surrogate, since
+ * the HTTP gateway server-side injects workspaceId from authResult per
+ * convex/http.ts:675).
+ */
+const TTL_MS = 5 * 60 * 1000; // 5 minutes
+const STALE_WARN_MS = 4 * 60 * 1000; // warn after 4 minutes (1 minute before expiry)
+/** In-memory cache: cacheKey (CLI: apiKey; Cortex would use workspaceId) → CacheEntry. */
+const cache = new Map();
+/**
+ * Get a cached WorkspaceVocabCtx by cacheKey, or null if expired/missing.
+ * Prints a staleness warning when the entry is older than STALE_WARN_MS.
+ */
+export function getCachedVocabCtx(cacheKey) {
+    const entry = cache.get(cacheKey);
+    if (!entry)
+        return null;
+    const now = Date.now();
+    if (now >= entry.expiresAt) {
+        cache.delete(cacheKey);
+        return null;
+    }
+    if (now - (entry.expiresAt - TTL_MS) >= STALE_WARN_MS) {
+        // Staleness hint: labels were fetched > 4 min ago, will refresh within 1 min.
+        process.stderr.write(`[pb] Workspace vocabulary context is almost stale — will refresh on next invocation.\n`);
+    }
+    return entry.ctx;
+}
+/**
+ * Store a WorkspaceVocabCtx under cacheKey with a 5-min TTL.
+ */
+export function setCachedVocabCtx(cacheKey, ctx) {
+    cache.set(cacheKey, { ctx, expiresAt: Date.now() + TTL_MS });
+}
+/**
+ * Explicitly invalidate a cached vocab context by cacheKey.
+ * Call this when `updateCollectionLabels` mutation succeeds (e.g. after `pb handshake`).
+ */
+export function invalidateVocabCtx(cacheKey) {
+    cache.delete(cacheKey);
+}
+/**
+ * Clear all cached entries (useful for testing or `pb handshake --refresh`).
+ */
+export function clearVocabCache() {
+    cache.clear();
+}
+/**
+ * Get the cached vocab context, or fetch it via the provided async fetcher on cache miss.
+ *
+ * Usage pattern at CLI command sites:
+ * ```ts
+ * const vocabCtx = await getOrFetchVocabCtx(config.apiKey, async () => {
+ *   type VocabResult = { collectionLabels?: Record<string, unknown> };
+ *   const vocab = await kernelCall<VocabResult>('chain.getVocabulary', {});
+ *   return vocab?.collectionLabels
+ *     ? { collectionLabels: vocab.collectionLabels as WorkspaceVocabCtx['collectionLabels'] }
+ *     : null;
+ * });
+ * ```
+ *
+ * - `cacheKey`: use the API key as a surrogate for cacheKey (1:1 mapping at CLI layer).
+ * - `fetcher`: async function that resolves the vocab ctx; returns null on failure to signal
+ *   "don't cache, fall back to resolver literal". Fetcher errors are swallowed — vocabulary
+ *   labels are advisory (PAT-230 / fail-open principle).
+ *
+ * Returns WorkspaceVocabCtx on cache hit or successful fetch; undefined on error/null fetcher result.
+ */
+export async function getOrFetchVocabCtx(cacheKey, fetcher) {
+    const cached = getCachedVocabCtx(cacheKey);
+    if (cached)
+        return cached;
+    try {
+        const ctx = await fetcher();
+        if (ctx) {
+            setCachedVocabCtx(cacheKey, ctx);
+            return ctx;
+        }
+    }
+    catch {
+        // fail-open — vocabulary labels are advisory, never block the command
+    }
+    return undefined;
+}
+//# sourceMappingURL=workspaceVocabCache.js.map

package/dist/lib/workspaceVocabCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaceVocabCache.js","sourceRoot":"","sources":["../../src/lib/workspaceVocabCache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAUH,MAAM,MAAM,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,YAAY;AAC1C,MAAM,aAAa,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,gDAAgD;AAErF,0FAA0F;AAC1F,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;AAE5C;;;GAGG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB;IAChD,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAClC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACvB,IAAI,GAAG,IAAI,KAAK,CAAC,SAAS,EAAE,CAAC;QAC3B,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QACvB,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,SAAS,GAAG,MAAM,CAAC,IAAI,aAAa,EAAE,CAAC;QACtD,8EAA8E;QAC9E,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,wFAAwF,CACzF,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC;AACnB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,GAAsB;IACxE,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;AAC/D,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,KAAK,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AACzB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe;IAC7B,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,QAAgB,EAChB,OAAgD;IAEhD,MAAM,MAAM,GAAG,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC3C,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAE1B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,MAAM,OAAO,EAAE,CAAC;QAC5B,IAAI,GAAG,EAAE,CAAC;YACR,iBAAiB,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;YACjC,OAAO,GAAG,CAAC;QACb,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,sEAAsE;IACxE,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/setup/__tests__/coach-traces.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=coach-traces.test.d.ts.map

package/dist/setup/__tests__/coach-traces.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coach-traces.test.d.ts","sourceRoot":"","sources":["../../../src/setup/__tests__/coach-traces.test.ts"],"names":[],"mappings":""}

package/dist/setup/__tests__/coach-traces.test.js

@@ -0,0 +1,189 @@
+/**
+ * Cross-model coach validation harness — WP-431 S4 (doneWhen #16).
+ *
+ * Mock harness chosen for cross-model validation per TEN-1962 — deterministic,
+ * runs in CI without API keys. Live trace via dev-only Cursor Desktop documented
+ * separately if needed. The harness does NOT call any model; it simulates the
+ * criteria-progression loop encoded in `.productbrain/skills/pb-setup.md`
+ * Phase 3 and asserts convergence within 3 turns OR correct fallback to the
+ * FLO-72 Path C wizard (DEC-991).
+ *
+ * The fixture set covers cross-model behaviour by encoding three response
+ * shapes that any reasonable instruction-following model produces — the user's
+ * answer is the variable, the agent's response loop is the constant. The
+ * skill body is the universal SSOT (DEC-997); this harness exercises it.
+ */
+import { describe, expect, it } from 'vitest';
+/**
+ * Criteria check (verbatim from `.productbrain/skills/pb-setup.md` Phase 3):
+ *   "answer mentions a verb + a thing they do regularly".
+ *
+ * The criteria predicate keeps the test honest: it deterministically maps a
+ * user utterance to met/not-met. The tokeniser is intentionally simple — the
+ * skill text says "verb + thing", and that's what we look for.
+ */
+const VERB_HINTS = [
+    'ship',
+    'shipping',
+    'fix',
+    'fixing',
+    'write',
+    'writing',
+    'review',
+    'reviewing',
+    'build',
+    'building',
+    'integrate',
+    'integrating',
+    'design',
+    'designing',
+    'debug',
+    'debugging',
+    'refactor',
+    'refactoring',
+    'document',
+    'documenting',
+];
+const THING_HINTS = [
+    'feature',
+    'features',
+    'bug',
+    'bugs',
+    'copy',
+    'integration',
+    'integrations',
+    'review',
+    'reviews',
+    'issue',
+    'issues',
+    'doc',
+    'docs',
+    'api',
+    'apis',
+    'endpoint',
+    'endpoints',
+    'workflow',
+    'workflows',
+    'page',
+    'pages',
+    'rule',
+    'rules',
+];
+function meetsCriteria(answer) {
+    const lower = answer.toLowerCase();
+    const hasVerb = VERB_HINTS.some((v) => new RegExp(`\\b${v}\\b`).test(lower));
+    const hasThing = THING_HINTS.some((t) => new RegExp(`\\b${t}\\b`).test(lower));
+    return hasVerb && hasThing;
+}
+/**
+ * Run the coach loop encoded in pb-setup.md against a scripted user.
+ *
+ * Loop (verbatim from the skill):
+ *   1. Ask the open question.
+ *   2. If answer meets criteria -> progress.
+ *   3. If vague, ask one follow-up.
+ *   4. If 2 follow-ups don't yield, fall back to wizard (DEC-991).
+ *
+ * Convergence target (doneWhen #16): within 3 turns. Three turns means: the
+ * open question + at most two follow-ups. After the third turn without
+ * criteria-met, the agent MUST fall back to the wizard.
+ */
+function runCoachLoop(turns) {
+    const trace = [];
+    let followUps = 0;
+    for (let i = 0; i < turns.length; i++) {
+        const turn = turns[i];
+        const met = meetsCriteria(turn.user);
+        trace.push({ turn: i + 1, user: turn.user, met });
+        if (met) {
+            return {
+                state: 'criteria-met',
+                turnsUsed: i + 1,
+                finalAnswer: turn.user,
+                trace,
+            };
+        }
+        followUps += 1;
+        if (followUps >= 2) {
+            // Skill behaviour: "if 2 follow-ups don't yield, suggest a default
+            // catalog and let them pick (DEC-991 fallback path)".
+            return {
+                state: 'wizard-fallback',
+                turnsUsed: i + 1,
+                finalAnswer: turn.user,
+                trace,
+            };
+        }
+    }
+    // Out of scripted turns without convergence — treat as wizard-fallback so
+    // the test surfaces a faulty fixture rather than silently passing.
+    return {
+        state: 'wizard-fallback',
+        turnsUsed: turns.length,
+        finalAnswer: turns[turns.length - 1]?.user ?? '',
+        trace,
+    };
+}
+describe('Phase 3 coach loop — cross-model trace harness (TEN-1962)', () => {
+    it('Scenario A — happy path (specific answer, 1 turn)', () => {
+        const turns = [
+            { user: 'Mostly shipping new features for our SvelteKit app.' },
+        ];
+        const outcome = runCoachLoop(turns);
+        expect(outcome.state).toBe('criteria-met');
+        expect(outcome.turnsUsed).toBe(1);
+        expect(outcome.turnsUsed).toBeLessThanOrEqual(3);
+    });
+    it('Scenario B — vague then specific (follow-up, 2 turns)', () => {
+        const turns = [
+            { user: 'I dunno, various stuff.' },
+            { user: 'Last week I spent the most time fixing customer bugs.' },
+        ];
+        const outcome = runCoachLoop(turns);
+        expect(outcome.state).toBe('criteria-met');
+        expect(outcome.turnsUsed).toBe(2);
+        expect(outcome.turnsUsed).toBeLessThanOrEqual(3);
+    });
+    it('Scenario C — 2 vague turns triggers wizard fallback (DEC-991 path)', () => {
+        const turns = [
+            { user: 'Just code, you know how it is.' },
+            { user: 'Stuff. Things. The usual.' },
+        ];
+        const outcome = runCoachLoop(turns);
+        expect(outcome.state).toBe('wizard-fallback');
+        expect(outcome.turnsUsed).toBe(2);
+        // Convergence to a deterministic outcome (criteria-met OR wizard) within
+        // the 3-turn budget defends KEY-32 generalisation across surfaces.
+        expect(outcome.turnsUsed).toBeLessThanOrEqual(3);
+    });
+    it('Scenario D — marketing copy answer (non-engineering domain, criteria still met)', () => {
+        const turns = [
+            { user: 'I write marketing copy and review pages from the design team.' },
+        ];
+        const outcome = runCoachLoop(turns);
+        expect(outcome.state).toBe('criteria-met');
+        expect(outcome.turnsUsed).toBe(1);
+    });
+    it('Scenario E — every fixture converges within the 3-turn budget', () => {
+        // Roll-up assertion across all scenarios so a future fixture addition that
+        // exceeds the budget surfaces here as a single named failure.
+        const fixtures = [
+            [{ user: 'Mostly shipping new features for our SvelteKit app.' }],
+            [
+                { user: 'I dunno, various stuff.' },
+                { user: 'Last week I spent the most time fixing customer bugs.' },
+            ],
+            [
+                { user: 'Just code, you know how it is.' },
+                { user: 'Stuff. Things. The usual.' },
+            ],
+            [{ user: 'I write marketing copy and review pages from the design team.' }],
+        ];
+        for (const turns of fixtures) {
+            const outcome = runCoachLoop(turns);
+            expect(outcome.turnsUsed).toBeLessThanOrEqual(3);
+            expect(['criteria-met', 'wizard-fallback']).toContain(outcome.state);
+        }
+    });
+});
+//# sourceMappingURL=coach-traces.test.js.map

package/dist/setup/__tests__/coach-traces.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"coach-traces.test.js","sourceRoot":"","sources":["../../../src/setup/__tests__/coach-traces.test.ts"],"names":[],"mappings":"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"}

package/dist/setup/__tests__/setup-commands.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=setup-commands.test.d.ts.map

package/dist/setup/__tests__/setup-commands.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"setup-commands.test.d.ts","sourceRoot":"","sources":["../../../src/setup/__tests__/setup-commands.test.ts"],"names":[],"mappings":""}