@productbrain/cli 0.1.0-beta.18 → 0.1.0-beta.1801

package/dist/__tests__/capture-receipt-domain.test.js

@@ -0,0 +1,29 @@
+/**
+ * TEN-2365: capture receipt echoes the capture-time authority-domain proposal so the operator
+ * sees the entry was filed under a domain (pending ratification), per DEC-1259/1260.
+ */
+import { describe, it, expect } from 'vitest';
+import { formatCaptureReceipt } from '../formatters/capture.js';
+const base = {
+    entryId: 'STD-1',
+    name: 'Data analytics standard',
+    collection: 'standards',
+    status: 'active',
+    classification: null,
+};
+describe('formatCaptureReceipt — authority-domain echo (TEN-2365)', () => {
+    it('renders a pending-proposal domain line when a proposal was filed', () => {
+        const out = formatCaptureReceipt({
+            ...base,
+            authorityDomain: { slug: 'data', status: 'proposal-pending' },
+        });
+        expect(out).toContain('domain: data');
+        expect(out).toMatch(/proposal pending/i);
+        expect(out).toMatch(/ratify/i);
+    });
+    it('omits the domain line when no proposal was filed', () => {
+        const out = formatCaptureReceipt(base);
+        expect(out).not.toMatch(/proposal pending/i);
+    });
+});
+//# sourceMappingURL=capture-receipt-domain.test.js.map

package/dist/__tests__/capture-receipt-domain.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capture-receipt-domain.test.js","sourceRoot":"","sources":["../../src/__tests__/capture-receipt-domain.test.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AAEhE,MAAM,IAAI,GAAG;IACX,OAAO,EAAE,OAAO;IAChB,IAAI,EAAE,yBAAyB;IAC/B,UAAU,EAAE,WAAW;IACvB,MAAM,EAAE,QAAQ;IAChB,cAAc,EAAE,IAAI;CACrB,CAAC;AAEF,QAAQ,CAAC,yDAAyD,EAAE,GAAG,EAAE;IACvE,EAAE,CAAC,kEAAkE,EAAE,GAAG,EAAE;QAC1E,MAAM,GAAG,GAAG,oBAAoB,CAAC;YAC/B,GAAG,IAAI;YACP,eAAe,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,kBAAkB,EAAE;SAC9D,CAAC,CAAC;QACH,MAAM,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,cAAc,CAAC,CAAC;QACtC,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;QACzC,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACjC,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,GAAG,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAC;QACvC,MAAM,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC/C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/capture.test.js

@@ -1,12 +1,14 @@
 /**
- * pb capture extensions — --link, --json flags.
+ * pb capture extensions — --link, --json flags, WP-319 grounding.
  * TEN-341 test contract: capture --link calls createEntryRelation, capture --json outputs JSON.
+ * WP-319 S3: grounding fires in parallel, fail-open, --suggest-only, --strict, PB_GROUNDING_MODE.
  */
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { runCapture } from '../commands/capture.js';
-const mcpCallWithSessionMock = vi.fn();
+import { CLIError, ErrorCode } from '../lib/errors.js';
+const kernelCallWithSessionMock = vi.fn();
 vi.mock('../lib/client.js', () => ({
-    mcpCallWithSession: (...args) => mcpCallWithSessionMock(...args),
+    kernelCallWithSession: (...args) => kernelCallWithSessionMock(...args),
 }));
 vi.mock('../lib/config.js', () => ({
     getConfigOrGuide: vi.fn(() => Promise.resolve({ apiKey: 'pb_sk_test', siteUrl: 'https://test.convex.site' })),
@@ -18,17 +20,30 @@ vi.mock('../lib/session.js', () => ({
 }));
 describe('runCapture --link', () => {
     beforeEach(() => {
-        mcpCallWithSessionMock.mockReset();
+        kernelCallWithSessionMock.mockReset();
         mockSession = { sessionId: 'sess-test' };
     });
     it('creates entry then links to target with default relation type', async () => {
-        mcpCallWithSessionMock
-            .mockResolvedValueOnce({ collection: 'tensions', confidence: 0.9, tier: 'high' })
-            .mockResolvedValueOnce({ docId: 'doc-1', entryId: 'TEN-710' })
-            .mockResolvedValueOnce({});
+        // Prefix "TEN:" is extracted → skips classification, routes directly to tensions
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.resolve([]);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-1', entryId: 'TEN-710' });
+            if (fn === 'chain.createEntryRelation')
+                return Promise.resolve({});
+            return Promise.resolve({});
+        });
         const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
         await runCapture({ text: 'TEN: missing validation', link: 'BET-151' });
-        expect(mcpCallWithSessionMock).toHaveBeenCalledWith('chain.createEntryRelation', {
+        // Verify classification was skipped (no resolveCollection call)
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalledWith('chain.resolveCollection', expect.anything());
+        // Verify prefix was stripped from entry name and routed to correct collection
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.objectContaining({
+            collectionSlug: 'tensions',
+            name: 'missing validation',
+        }));
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntryRelation', {
             fromEntryId: 'TEN-710',
             toEntryId: 'BET-151',
             type: 'surfaces_tension_in',
@@ -36,13 +51,20 @@ describe('runCapture --link', () => {
         writeSpy.mockRestore();
     });
     it('uses custom relation type when --type provided', async () => {
-        mcpCallWithSessionMock
-            .mockResolvedValueOnce({ collection: 'insights', confidence: 0.8, tier: 'high' })
-            .mockResolvedValueOnce({ docId: 'doc-2', entryId: 'INS-50' })
-            .mockResolvedValueOnce({});
+        // Prefix "INS:" is extracted → skips classification, routes directly to insights
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.resolve([]);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-2', entryId: 'INS-50' });
+            if (fn === 'chain.createEntryRelation')
+                return Promise.resolve({});
+            return Promise.resolve({});
+        });
         const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
         await runCapture({ text: 'INS: discovered X', link: 'DEC-264', type: 'informed_by' });
-        expect(mcpCallWithSessionMock).toHaveBeenCalledWith('chain.createEntryRelation', {
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalledWith('chain.resolveCollection', expect.anything());
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntryRelation', {
             fromEntryId: 'INS-50',
             toEntryId: 'DEC-264',
             type: 'informed_by',
@@ -52,13 +74,18 @@ describe('runCapture --link', () => {
 });
 describe('runCapture --json', () => {
     beforeEach(() => {
-        mcpCallWithSessionMock.mockReset();
+        kernelCallWithSessionMock.mockReset();
         mockSession = { sessionId: 'sess-test' };
     });
     it('outputs valid JSON with id field and no other stdout', async () => {
-        mcpCallWithSessionMock
-            .mockResolvedValueOnce({ collection: 'tensions', confidence: 0.9, tier: 'high' })
-            .mockResolvedValueOnce({ docId: 'doc-1', entryId: 'TEN-711' });
+        // Prefix "TEN:" is extracted → skips classification
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.resolve([]);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-1', entryId: 'TEN-711' });
+            return Promise.resolve({});
+        });
         let stdoutOutput = '';
         const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
             stdoutOutput += String(chunk);
@@ -83,37 +110,251 @@ describe('runCapture --json', () => {
         expect(output).toHaveProperty('confidence');
     });
 });
-describe('runCapture classification guard', () => {
+describe('runCapture description field routing', () => {
     beforeEach(() => {
-        mcpCallWithSessionMock.mockReset();
+        kernelCallWithSessionMock.mockReset();
         mockSession = { sessionId: 'sess-test' };
     });
-    it('exits cleanly when classification requires review', async () => {
-        mcpCallWithSessionMock.mockResolvedValueOnce(null);
-        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
-        const exitSpy = vi
-            .spyOn(process, 'exit')
-            .mockImplementation(((code) => {
-            throw new Error(`EXIT:${code ?? ''}`);
+    it('passes description key to createEntry for assumptions (TEN-1258 — remap happens in Convex)', async () => {
+        // The CLI always sends `description` — the Convex write gate remaps it to `belief`
+        // for the assumptions collection (TEN-1258). Verify the CLI routes correctly and
+        // sends the text as description so the Convex remap can fire.
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.resolve([]);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-5', entryId: 'ASM-1' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runCapture({ text: 'ASM: users won\'t pay before seeing value' });
+        const createCall = kernelCallWithSessionMock.mock.calls.find(([fn]) => fn === 'chain.createEntry');
+        expect(createCall?.[1]).toMatchObject({
+            collectionSlug: 'assumptions',
+            name: "users won't pay before seeing value",
+            data: { description: "users won't pay before seeing value" },
+        });
+        writeSpy.mockRestore();
+    });
+});
+describe('runCapture --field passthrough', () => {
+    beforeEach(() => {
+        kernelCallWithSessionMock.mockReset();
+        mockSession = { sessionId: 'sess-test' };
+    });
+    it('merges --field pairs into data', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.resolve([]);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-6', entryId: 'STD-1' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runCapture({
+            text: 'touched-code stewardship',
+            collection: 'standards',
+            field: ['rationale=signed specs define scope but agents need permission'],
+        });
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.objectContaining({
+            data: expect.objectContaining({
+                description: 'touched-code stewardship',
+                rationale: 'signed specs define scope but agents need permission',
+            }),
         }));
-        await expect(runCapture({ text: 'Ambiguous capture' })).rejects.toThrow('EXIT:1');
-        expect(stderrSpy).toHaveBeenCalledWith('Classification needs review before capture can continue. Re-run with `--collection <slug>`.\n');
-        stderrSpy.mockRestore();
-        exitSpy.mockRestore();
+        writeSpy.mockRestore();
+    });
+    it('--field description=X overrides the derived description', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.resolve([]);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-7', entryId: 'TEN-1' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runCapture({
+            text: 'derived',
+            collection: 'tensions',
+            field: ['description=explicit'],
+        });
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.objectContaining({
+            data: expect.objectContaining({ description: 'explicit' }),
+        }));
+        writeSpy.mockRestore();
+    });
+});
+describe('runCapture WHY pre-flight', () => {
+    beforeEach(() => {
+        kernelCallWithSessionMock.mockReset();
+        mockSession = { sessionId: 'sess-test' };
+    });
+    it('blocks with guidance when governed and whyField is missing', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.resolve([]);
+            if (fn === 'chain.getCollectionFields') {
+                return Promise.resolve({ governed: true, whyField: 'rationale', minChars: 12, fields: [] });
+            }
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-8', entryId: 'STD-2' });
+            return Promise.resolve({});
+        });
+        await expect(runCapture({ text: 'x', collection: 'standards' })).rejects.toThrow(/rationale/);
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalledWith('chain.createEntry', expect.anything());
+    });
+    it('does not block when whyField is description', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.resolve([]);
+            if (fn === 'chain.getCollectionFields') {
+                return Promise.resolve({ governed: true, whyField: 'description', minChars: 12, fields: [] });
+            }
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-9', entryId: 'ARCH-1' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runCapture({ text: 'an architecture note body', collection: 'architecture' });
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.anything());
+        writeSpy.mockRestore();
+    });
+    it('does not block when description remaps to the whyField (descriptionFieldKey === whyField)', async () => {
+        // TEN-1258 regression: `decisions` sets descriptionFieldKey='rationale' and the server
+        // remaps data.description → rationale before the WHY gate. A bare `pb capture "DEC: …"`
+        // (description set, no --field rationale) must NOT be false-blocked client-side.
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.resolve([]);
+            if (fn === 'chain.getCollectionFields') {
+                return Promise.resolve({
+                    governed: true,
+                    whyField: 'rationale',
+                    minChars: 12,
+                    descriptionFieldKey: 'rationale',
+                    fields: [],
+                });
+            }
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-12', entryId: 'DEC-5' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runCapture({ text: 'chose X because it is simpler', collection: 'decisions' });
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.anything());
+        writeSpy.mockRestore();
+    });
+    it('still blocks a governed collection whose descriptionFieldKey does NOT map to the whyField', async () => {
+        // proof_governed has whyField='rationale' but no descriptionFieldKey remap, so a bare
+        // capture (no --field rationale) is correctly blocked — the description will not satisfy it.
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.resolve([]);
+            if (fn === 'chain.getCollectionFields') {
+                return Promise.resolve({
+                    governed: true,
+                    whyField: 'rationale',
+                    minChars: 12,
+                    descriptionFieldKey: null,
+                    fields: [],
+                });
+            }
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-13', entryId: 'PGV-9' });
+            return Promise.resolve({});
+        });
+        await expect(runCapture({ text: 'x', collection: 'proof_governed' })).rejects.toThrow(/rationale/);
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalledWith('chain.createEntry', expect.anything());
+    });
+    it('fails open and proceeds when the contract fetch fails', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.resolve([]);
+            if (fn === 'chain.getCollectionFields')
+                return Promise.reject(new Error('network'));
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-10', entryId: 'STD-3' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runCapture({
+            text: 'x',
+            collection: 'standards',
+            field: ['rationale=enough characters here ok'],
+        });
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.anything());
+        writeSpy.mockRestore();
+    });
+    it('fails open when the contract fetch rejects with a CLIError (server 4xx/5xx surfaces as McpError, an instanceof CLIError)', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.resolve([]);
+            if (fn === 'chain.getCollectionFields') {
+                return Promise.reject(new CLIError('Could not reach test.convex.site.', {
+                    code: ErrorCode.NETWORK_UNREACHABLE,
+                    category: 'network',
+                }));
+            }
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-11', entryId: 'STD-4' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runCapture({
+            text: 'x',
+            collection: 'standards',
+            field: ['rationale=enough characters here ok'],
+        });
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.anything());
+        writeSpy.mockRestore();
+    });
+    it('surfaces the server WHY-gate reason on rejection', async () => {
+        const serverReason = 'Governance entries (standard) require an explicit WHY before they can be created. Set "rationale" to at least 12 characters.';
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.resolve([]);
+            if (fn === 'chain.getCollectionFields') {
+                return Promise.resolve({ governed: true, whyField: 'rationale', minChars: 12, fields: [] });
+            }
+            if (fn === 'chain.createEntry')
+                return Promise.reject(new Error(serverReason));
+            return Promise.resolve({});
+        });
+        await expect(runCapture({
+            text: 'x',
+            collection: 'standards',
+            field: ['rationale=short'],
+        })).rejects.toThrow(/at least 12 characters/);
+    });
+});
+describe('runCapture classification guard', () => {
+    beforeEach(() => {
+        kernelCallWithSessionMock.mockReset();
+        mockSession = { sessionId: 'sess-test' };
+    });
+    it('throws CLIError when classification requires review', async () => {
+        kernelCallWithSessionMock.mockResolvedValueOnce(null);
+        await expect(runCapture({ text: 'Ambiguous capture' })).rejects.toThrow('Classification needs review before capture can continue.');
     });
 });
 describe('runCapture date inference', () => {
     beforeEach(() => {
-        mcpCallWithSessionMock.mockReset();
+        kernelCallWithSessionMock.mockReset();
         mockSession = { sessionId: 'sess-test' };
     });
     it('does not default date to today when no source date is present', async () => {
-        mcpCallWithSessionMock
-            .mockResolvedValueOnce({ collection: 'decisions', confidence: 0.9, tier: 'high' })
-            .mockResolvedValueOnce({ docId: 'doc-3', entryId: 'DEC-10' });
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.resolve([]);
+            if (fn === 'chain.resolveCollection')
+                return Promise.resolve({ collection: 'decisions', confidence: 0.9, tier: 'high' });
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-3', entryId: 'DEC-10' });
+            return Promise.resolve({});
+        });
         const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
         await runCapture({ text: 'Decision without explicit source date' });
-        const createCall = mcpCallWithSessionMock.mock.calls.find(([fn]) => fn === 'chain.createEntry');
+        const createCall = kernelCallWithSessionMock.mock.calls.find(([fn]) => fn === 'chain.createEntry');
         expect(createCall?.[1]).toMatchObject({
             collectionSlug: 'decisions',
             data: { description: 'Decision without explicit source date' },
@@ -122,14 +363,206 @@ describe('runCapture date inference', () => {
         writeSpy.mockRestore();
     });
     it('uses inferred source date when the capture text includes one', async () => {
-        mcpCallWithSessionMock
-            .mockResolvedValueOnce({ collection: 'decisions', confidence: 0.9, tier: 'high' })
-            .mockResolvedValueOnce({ docId: 'doc-4', entryId: 'DEC-11' });
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.resolve([]);
+            if (fn === 'chain.resolveCollection')
+                return Promise.resolve({ collection: 'decisions', confidence: 0.9, tier: 'high' });
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-4', entryId: 'DEC-11' });
+            return Promise.resolve({});
+        });
         const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
         await runCapture({ text: 'Decision from April 1, 2026 steering meeting' });
-        const createCall = mcpCallWithSessionMock.mock.calls.find(([fn]) => fn === 'chain.createEntry');
+        const createCall = kernelCallWithSessionMock.mock.calls.find(([fn]) => fn === 'chain.createEntry');
         expect((createCall?.[1]).data.date).toBe('2026-04-01');
         writeSpy.mockRestore();
     });
 });
+// ---------------------------------------------------------------------------
+// WP-319 S3: Pre-write grounding tests
+// ---------------------------------------------------------------------------
+describe('runCapture WP-319 grounding', () => {
+    const emptyGrounding = { index: 0, related: [], duplicates: [], governance: [], v: 1 };
+    const groundingWithDuplicate = {
+        index: 0,
+        related: [],
+        duplicates: [{ entryId: 'TEN-5', name: 'Similar tension', collectionSlug: 'tensions', matchType: 'possible_duplicate', overlapRatio: 0.9 }],
+        governance: [],
+        v: 1,
+    };
+    beforeEach(() => {
+        kernelCallWithSessionMock.mockReset();
+        mockSession = { sessionId: 'sess-test' };
+        delete process.env.PB_GROUNDING_MODE;
+    });
+    it('fires chain.suggestLinksForCapture in parallel and still calls createEntry', async () => {
+        // Prefix-based route skips classification; grounding fires for TEN prefix
+        kernelCallWithSessionMock
+            .mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.resolve([emptyGrounding]);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-1', entryId: 'TEN-720' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        await runCapture({ text: 'TEN: grounding test tension' });
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.suggestLinksForCapture', expect.objectContaining({
+            entries: expect.arrayContaining([expect.objectContaining({ name: 'grounding test tension' })]),
+        }));
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.anything());
+        writeSpy.mockRestore();
+        stderrSpy.mockRestore();
+    });
+    it('does NOT block capture when grounding call fails', async () => {
+        kernelCallWithSessionMock
+            .mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.reject(new Error('network error'));
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-2', entryId: 'TEN-721' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        // Must not throw — grounding failure is fail-open
+        await expect(runCapture({ text: 'TEN: grounding failure test' })).resolves.toBeUndefined();
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.anything());
+        writeSpy.mockRestore();
+        stderrSpy.mockRestore();
+    });
+    it('--suggest-only does NOT call createEntry and outputs grounding data', async () => {
+        // In test env (non-TTY), isJsonMode() returns true → JSON path is taken.
+        kernelCallWithSessionMock
+            .mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.resolve([groundingWithDuplicate]);
+            return Promise.resolve({});
+        });
+        let stdoutOutput = '';
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
+            stdoutOutput += String(chunk);
+            return true;
+        });
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        await runCapture({ text: 'TEN: duplicate candidate', suggestOnly: true });
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalledWith('chain.createEntry', expect.anything());
+        // JSON output contains suggestOnly flag and grounding report
+        const jsonLines = stdoutOutput.split('\n').filter((l) => { try {
+            JSON.parse(l);
+            return true;
+        }
+        catch {
+            return false;
+        } });
+        expect(jsonLines).toHaveLength(1);
+        const parsed = JSON.parse(jsonLines[0]);
+        expect(parsed.suggestOnly).toBe(true);
+        expect(parsed.groundingReport).toBeDefined();
+        writeSpy.mockRestore();
+        stderrSpy.mockRestore();
+    });
+    it('--suggest-only with --json outputs machine-readable object without calling createEntry', async () => {
+        kernelCallWithSessionMock
+            .mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.resolve([emptyGrounding]);
+            return Promise.resolve({});
+        });
+        let stdoutOutput = '';
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
+            stdoutOutput += String(chunk);
+            return true;
+        });
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        await runCapture({ text: 'TEN: dry run json', json: true, suggestOnly: true });
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalledWith('chain.createEntry', expect.anything());
+        const jsonLines = stdoutOutput.split('\n').filter((l) => { try {
+            JSON.parse(l);
+            return true;
+        }
+        catch {
+            return false;
+        } });
+        expect(jsonLines).toHaveLength(1);
+        const parsed = JSON.parse(jsonLines[0]);
+        expect(parsed.suggestOnly).toBe(true);
+        writeSpy.mockRestore();
+        stderrSpy.mockRestore();
+    });
+    it('banner is suppressed when grounding has no matches (zero-noise floor)', async () => {
+        kernelCallWithSessionMock
+            .mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.resolve([emptyGrounding]);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-3', entryId: 'TEN-722' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        const stderrLines = [];
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation((chunk) => {
+            stderrLines.push(String(chunk));
+            return true;
+        });
+        await runCapture({ text: 'TEN: no matches tension' });
+        // No "Grounding" banner in stderr when zero matches
+        const groundingInStderr = stderrLines.some((l) => l.includes('Grounding'));
+        expect(groundingInStderr).toBe(false);
+        writeSpy.mockRestore();
+        stderrSpy.mockRestore();
+    });
+    it('PB_GROUNDING_MODE=off skips grounding call entirely', async () => {
+        process.env.PB_GROUNDING_MODE = 'off';
+        kernelCallWithSessionMock
+            .mockImplementation((fn) => {
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-4', entryId: 'TEN-723' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        await runCapture({ text: 'TEN: no grounding env off' });
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalledWith('chain.suggestLinksForCapture', expect.anything());
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.anything());
+        delete process.env.PB_GROUNDING_MODE;
+        writeSpy.mockRestore();
+        stderrSpy.mockRestore();
+    });
+    it('--json output stdout is clean (no grounding on stdout)', async () => {
+        kernelCallWithSessionMock
+            .mockImplementation((fn) => {
+            if (fn === 'chain.suggestLinksForCapture')
+                return Promise.resolve([groundingWithDuplicate]);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-5', entryId: 'TEN-724' });
+            return Promise.resolve({});
+        });
+        let stdoutOutput = '';
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
+            stdoutOutput += String(chunk);
+            return true;
+        });
+        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        await runCapture({ text: 'TEN: json clean stdout', json: true });
+        // Stdout must be exactly one valid JSON line (jq .id must work)
+        const jsonLines = stdoutOutput.split('\n').filter((l) => { try {
+            JSON.parse(l);
+            return true;
+        }
+        catch {
+            return false;
+        } });
+        expect(jsonLines).toHaveLength(1);
+        const parsed = JSON.parse(jsonLines[0]);
+        expect(parsed.id).toBe('TEN-724');
+        // No grounding content in stdout
+        expect(stdoutOutput).not.toContain('Grounding');
+        expect(stdoutOutput).not.toContain('duplicate');
+        writeSpy.mockRestore();
+        stderrSpy.mockRestore();
+    });
+});
 //# sourceMappingURL=capture.test.js.map