@productbrain/cli 0.1.0-beta.978 → 0.1.0-beta.9791

package/dist/__tests__/capture.test.js

@@ -1,10 +1,13 @@
 /**
  * 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.
+ * WP-319 S3: grounding fires in parallel, fail-open, --strict, PB_GROUNDING_MODE.
  */
-import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import { runCapture } from '../commands/capture.js';
+import { formatCaptureReceipt } from '../formatters/capture.js';
+import { CLIError, ErrorCode } from '../lib/errors.js';
+import { setOutputMode } from '../lib/runner.js';
 const kernelCallWithSessionMock = vi.fn();
 vi.mock('../lib/client.js', () => ({
     kernelCallWithSession: (...args) => kernelCallWithSessionMock(...args),
@@ -22,119 +25,1237 @@ describe('runCapture --link', () => {
         kernelCallWithSessionMock.mockReset();
         mockSession = { sessionId: 'sess-test' };
     });
-    it('creates entry then links to target with default relation type', async () => {
-        // Prefix "TEN:" is extracted → skips classification, routes directly to tensions
+    // WP-688 S4 (TASK-105, element 11): --link with no --link-type no longer defaults to
+    // surfaces_tension_in — it refuses instead. The capture itself still succeeds (createEntry
+    // ran for real); only the relation write is skipped, replaced by a PREVIEW probe used to
+    // list the source entry's legal verbs in the refusal message.
+    it('--link without --link-type refuses (no default), preserving the created entry', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn, args) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-1', entryId: 'TEN-710' });
+            if (fn === 'chain.getEntry') {
+                const entryId = args?.entryId;
+                if (entryId === 'TEN-710')
+                    return Promise.resolve({ entryId: 'TEN-710', name: 'x', status: 'draft', canonicalKey: 'tension' });
+                return Promise.resolve(null);
+            }
+            // bdABL: the type row is resolved by scanning the semantic-types collection and
+            // matching on data.canonical_key — NOT by guessing entryId === `TYPE-<key>`. This
+            // row deliberately uses a non-conventional entryId (`ST-1`) to prove that.
+            if (fn === 'chain.listEntries') {
+                return Promise.resolve([{ entryId: 'ST-1', name: 'tension', status: 'active', data: { canonical_key: 'tension', valid_relation_types: ['related_to', 'depends_on', 'surfaces_tension_in'], description: 'x', cardinality_rule: 'multiple' } }]);
+            }
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runCapture({ text: 'TEN: missing validation', link: 'BET-151' })).rejects.toThrow(CLIError);
+        // The entry was created for real — only the LINK is refused.
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.objectContaining({
+            collectionSlug: 'tensions',
+            name: 'missing validation',
+        }));
+        // Legal verbs are READ by scanning the semantic-types collection (chain.listEntries)
+        // and matching data.canonical_key — the same resolution loadTypeMap itself uses,
+        // never a probe, never a guessed entryId.
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.getEntry', { entryId: 'TEN-710' });
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.listEntries', { collectionSlug: 'semantic-types' });
+        // Never a createEntryRelation call at all — a real write, preview, or probe.
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalledWith('chain.createEntryRelation', expect.anything());
+        writeSpy.mockRestore();
+    });
+    it('--link without --link-type: refusal message lists the source entry\'s declared relation types', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn, args) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-1b', entryId: 'TEN-711' });
+            if (fn === 'chain.getEntry') {
+                const entryId = args?.entryId;
+                if (entryId === 'TEN-711')
+                    return Promise.resolve({ entryId: 'TEN-711', name: 'x', status: 'draft', canonicalKey: 'tension' });
+                // bcRUMR: the target must actually resolve for this test to exercise the
+                // pb-relate-guidance branch rather than the target-missing branch.
+                if (entryId === 'BET-151')
+                    return Promise.resolve({ entryId: 'BET-151', name: 'y', status: 'active', canonicalKey: 'work_package' });
+                return Promise.resolve(null);
+            }
+            if (fn === 'chain.listEntries') {
+                return Promise.resolve([{ entryId: 'TYPE-tension', name: 'tension', status: 'active', data: { canonical_key: 'tension', valid_relation_types: ['related_to', 'depends_on', 'surfaces_tension_in'], description: 'x', cardinality_rule: 'multiple' } }]);
+            }
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        let caught;
+        try {
+            await runCapture({ text: 'TEN: missing validation', link: 'BET-151' });
+        }
+        catch (e) {
+            caught = e;
+        }
+        writeSpy.mockRestore();
+        expect(caught).toBeInstanceOf(CLIError);
+        expect(caught?.code).toBe(ErrorCode.VALIDATION_FAILED);
+        expect(caught?.message).toContain('related_to, depends_on, surfaces_tension_in');
+        expect(caught?.guidance).toContain('TEN-711');
+        expect(caught?.guidance).toContain('pb relate TEN-711');
+    });
+    // WP-688 S4 review round 5 (bcRUML): a whitespace-only --link must not silently no-op —
+    // the entry still gets created, but the link itself must be explicitly refused.
+    it('--link "   " (whitespace-only) refuses instead of silently dropping the link', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-ws', entryId: 'TEN-720' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        let caught;
+        try {
+            await runCapture({ text: 'TEN: whitespace link', link: '   ' });
+        }
+        catch (e) {
+            caught = e;
+        }
+        writeSpy.mockRestore();
+        expect(caught).toBeInstanceOf(CLIError);
+        expect(caught?.message).toContain('--link requires a non-empty entry ID');
+        // Never a relate/probe call — the target never resolved to anything real.
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalledWith('chain.createEntryRelation', expect.anything());
+    });
+    // WP-688 S4 review round 5 (bcRpJQ): --link "" is falsy at the outer `if (options.link)` —
+    // must check `!== undefined` instead, or this whole block (and the bcRUML refusal) never runs.
+    it('--link "" (empty string) refuses instead of silently dropping the link', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-empty', entryId: 'TEN-722' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        let caught;
+        try {
+            await runCapture({ text: 'TEN: empty link', link: '' });
+        }
+        catch (e) {
+            caught = e;
+        }
+        writeSpy.mockRestore();
+        expect(caught).toBeInstanceOf(CLIError);
+        expect(caught?.message).toContain('--link requires a non-empty entry ID');
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalledWith('chain.createEntryRelation', expect.anything());
+    });
+    // WP-688 S4 review round 5 (bcRUMR): the target entry doesn't exist — the recovery
+    // guidance must say so rather than recommending `pb relate <verb> <missing-id>`.
+    it('--link <missing-id> without --link-type reports the target was not found, not a verb-recovery command', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn, args) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-miss', entryId: 'TEN-721' });
+            if (fn === 'chain.getEntry') {
+                const entryId = args?.entryId;
+                if (entryId === 'TEN-721')
+                    return Promise.resolve({ entryId: 'TEN-721', name: 'x', status: 'draft', canonicalKey: 'tension' });
+                return Promise.resolve(null); // GHOST-1 does not exist
+            }
+            if (fn === 'chain.listEntries') {
+                return Promise.resolve([{ entryId: 'TYPE-tension', name: 'tension', status: 'active', data: { canonical_key: 'tension', valid_relation_types: ['informs'], description: 'x', cardinality_rule: 'multiple' } }]);
+            }
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        let caught;
+        try {
+            await runCapture({ text: 'TEN: bad target', link: 'GHOST-1' });
+        }
+        catch (e) {
+            caught = e;
+        }
+        writeSpy.mockRestore();
+        expect(caught?.guidance).toContain('not found');
+        expect(caught?.guidance).toContain('GHOST-1');
+        expect(caught?.guidance).not.toContain('pb relate');
+    });
+    // WP-688 S4 review round 3 (bc4Pj): `replaces`/`do_not_confuse_with` are declared for
+    // scoring but hard-refused at the generic relate door with a DIFFERENT recovery command
+    // (setSupersededBy / addDoNotConfuseWith, guards.ts:308-321) — listing them as usable via
+    // `pb relate` would name a guaranteed-to-fail re-run.
+    it('excludes replaces and do_not_confuse_with from the refusal\'s legal-verb list (both are door-blocked)', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn, args) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-1c', entryId: 'DEC-1' });
+            if (fn === 'chain.getEntry') {
+                const entryId = args?.entryId;
+                if (entryId === 'DEC-1')
+                    return Promise.resolve({ entryId: 'DEC-1', name: 'x', status: 'draft', canonicalKey: 'decision' });
+                return Promise.resolve(null);
+            }
+            if (fn === 'chain.listEntries') {
+                return Promise.resolve([{ entryId: 'TYPE-decision', name: 'decision', status: 'active', data: { canonical_key: 'decision', valid_relation_types: ['informs', 'governs', 'replaces', 'conflicts_with'], description: 'x', cardinality_rule: 'multiple' } }]);
+            }
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        let caught;
+        try {
+            await runCapture({ text: 'DEC: no link-type', link: 'STD-1' });
+        }
+        catch (e) {
+            caught = e;
+        }
+        writeSpy.mockRestore();
+        expect(caught?.message).toContain('informs, governs, conflicts_with');
+        expect(caught?.message).not.toContain('replaces');
+    });
+    // WP-688 S4 review round 5 (bdB5K): a type's declared valid_relation_types may name a verb outside
+    // the kernel ALLOWED_RELATION_TYPES allowlist. guardRelation still refuses it (guards.ts:302-307),
+    // so it must never be listed as a `pb relate`-usable recovery verb.
+    it('excludes a declared verb outside the kernel allowlist from the refusal\'s legal-verb list', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn, args) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-1d', entryId: 'GOAL-1' });
+            if (fn === 'chain.getEntry') {
+                const entryId = args?.entryId;
+                if (entryId === 'GOAL-1')
+                    return Promise.resolve({ entryId: 'GOAL-1', name: 'x', status: 'draft', canonicalKey: 'goal' });
+                return Promise.resolve(null);
+            }
+            if (fn === 'chain.listEntries') {
+                return Promise.resolve([{ entryId: 'TYPE-goal', name: 'goal', status: 'active', data: { canonical_key: 'goal', valid_relation_types: ['informs', 'depends_on', 'custom_hand_added'], description: 'x', cardinality_rule: 'multiple' } }]);
+            }
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        let caught;
+        try {
+            await runCapture({ text: 'GOAL: no link-type', link: 'BET-1' });
+        }
+        catch (e) {
+            caught = e;
+        }
+        writeSpy.mockRestore();
+        expect(caught?.message).toContain('informs, depends_on');
+        expect(caught?.message).not.toContain('custom_hand_added');
+    });
+    // WP-688 S4 review round 5 (cQFZ_): belongs_to/authority_domain toward a domain-tagged
+    // target require ratification metadata (stagingEntryId + source) that `pb relate` cannot
+    // supply (guards.ts:349-363) — never recommend them as recovery verbs for such a target.
+    it('excludes domain-tag verbs from the refusal\'s legal-verb list when the target is a domain', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn, args) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-1e', entryId: 'INS-1' });
+            if (fn === 'chain.getEntry') {
+                const entryId = args?.entryId;
+                if (entryId === 'INS-1')
+                    return Promise.resolve({ entryId: 'INS-1', name: 'x', status: 'draft', canonicalKey: 'insight' });
+                if (entryId === 'DOM-1')
+                    return Promise.resolve({ entryId: 'DOM-1', name: 'product-design', status: 'active', canonicalKey: 'domain' });
+                return Promise.resolve(null);
+            }
+            if (fn === 'chain.listEntries') {
+                return Promise.resolve([{ entryId: 'TYPE-insight', name: 'insight', status: 'active', data: { canonical_key: 'insight', valid_relation_types: ['informs', 'belongs_to', 'authority_domain'], description: 'x', cardinality_rule: 'multiple' } }]);
+            }
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        let caught;
+        try {
+            await runCapture({ text: 'INS: no link-type', link: 'DOM-1' });
+        }
+        catch (e) {
+            caught = e;
+        }
+        writeSpy.mockRestore();
+        expect(caught?.message).toContain('Legal relation types for this entry: informs.');
+        expect(caught?.message).not.toContain('belongs_to');
+        expect(caught?.message).not.toContain('authority_domain');
+    });
+    it('uses the supplied relation type when --link-type provided (no probe, real write)', async () => {
+        // Prefix "INS:" is extracted → skips classification, routes directly to insights
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-2', entryId: 'INS-50' });
+            if (fn === 'chain.createEntryRelation')
+                return Promise.resolve({ relationId: 'rel-1' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runCapture({ text: 'INS: discovered X', link: 'DEC-264', linkType: 'informed_by' });
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalledWith('chain.resolveCollection', expect.anything());
+        // A REAL (non-preview) write — the exact verb supplied, echoed verbatim, no probe call.
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntryRelation', {
+            fromEntryId: 'INS-50',
+            toEntryId: 'DEC-264',
+            type: 'informed_by',
+        });
+        const previewCalls = kernelCallWithSessionMock.mock.calls.filter(([fn, args]) => fn === 'chain.createEntryRelation' && args?.preview);
+        expect(previewCalls).toHaveLength(0);
+        writeSpy.mockRestore();
+    });
+    // WP-745 review (Codex P1): a relate-door refusal (e.g. REL-LEGAL-2) at the --link-type
+    // branch must not escape as an unhandled rejection — the entry above was ALREADY persisted,
+    // so the capture reports it, naming only the link as refused (same shape as the
+    // --link-without---link-type branch above).
+    it('a relate-door refusal during --link is deferred, naming the persisted entry — never an unhandled rejection', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-wp', entryId: 'WP-6' });
+            if (fn === 'chain.createEntryRelation') {
+                return Promise.reject(Object.assign(new Error('A work package is never part_of another work package — capture the smaller piece as a task and relate it part_of this work package.'), { name: 'McpError' }));
+            }
+            return Promise.resolve({});
+        });
+        let caught;
+        try {
+            await runCapture({ text: 'WP: child work package', link: 'WP-5', linkType: 'part_of' });
+        }
+        catch (e) {
+            caught = e;
+        }
+        expect(caught).toBeInstanceOf(CLIError);
+        expect(caught?.message).toContain('A work package is never part_of another work package');
+        expect(caught?.guidance).toContain('WP-6 was captured');
+        expect(caught?.guidance).toContain('only the link was refused');
+    });
+    // WP-745 round 3 (PR #896 review, PRRT_kwDORS4ils6h0CCc): a NON-REL-LEGAL-2 relate-door
+    // failure (auth denial, rate limit) must keep its OWN code/category — the earlier fix
+    // unconditionally relabeled every deferred link failure VALIDATION_FAILED, discarding the
+    // real error's identity.
+    it('a non-validation relate-door failure during --link preserves its own code/category, not a relabeled VALIDATION_FAILED', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-wp7', entryId: 'WP-7' });
+            if (fn === 'chain.createEntryRelation') {
+                return Promise.reject(new CLIError('Rate limit exceeded', { code: ErrorCode.RATE_LIMITED, category: 'network', guidance: 'Wait and retry.' }));
+            }
+            if (fn === 'quality.evaluateHeuristicAndSchedule')
+                return Promise.resolve(undefined);
+            return Promise.resolve({});
+        });
+        let caught;
+        try {
+            await runCapture({ text: 'WP: child work package', link: 'WP-5', linkType: 'part_of' });
+        }
+        catch (e) {
+            caught = e;
+        }
+        expect(caught).toBeInstanceOf(CLIError);
+        expect(caught?.code).toBe(ErrorCode.RATE_LIMITED);
+        expect(caught?.category).toBe('network');
+        expect(caught?.message).toBe('Rate limit exceeded');
+        expect(caught?.guidance).toContain('WP-7 was captured');
+    });
+    // WP-745 round 3 (PR #896 review, PRRT_kwDORS4ils6h0VPP): a NETWORK_TIMEOUT relate failure is
+    // outcome-UNKNOWN (the write may have landed server-side) — the guidance must say so, never
+    // the "was refused, re-run" template, which would prompt a blind duplicate-risking retry.
+    it('a NETWORK_TIMEOUT relate-door failure during --link says outcome-unknown, never "was refused"', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-wp9', entryId: 'WP-9' });
+            if (fn === 'chain.createEntryRelation') {
+                return Promise.reject(new CLIError('"chain.createEntryRelation" exceeded its budget.', { code: ErrorCode.NETWORK_TIMEOUT, category: 'network', guidance: 'Check before retrying.' }));
+            }
+            if (fn === 'quality.evaluateHeuristicAndSchedule')
+                return Promise.resolve(undefined);
+            return Promise.resolve({});
+        });
+        let caught;
+        try {
+            await runCapture({ text: 'WP: child work package', link: 'WP-5', linkType: 'part_of' });
+        }
+        catch (e) {
+            caught = e;
+        }
+        expect(caught).toBeInstanceOf(CLIError);
+        expect(caught?.code).toBe(ErrorCode.NETWORK_TIMEOUT);
+        expect(caught?.guidance).toContain('outcome is UNKNOWN');
+        expect(caught?.guidance).not.toContain('was refused');
+    });
+    // WP-745 round 3 (PR #896 review, PRRT_kwDORS4ils6h0CCc): the quality re-eval must still run
+    // (un-defers deferLLMSchedule) even when the relate call itself throws — previously the
+    // re-eval sat INSIDE the same try as the relate call, so a thrown refusal skipped it
+    // entirely, leaving the entry stuck at llmStatus:'skipped' with no background judgment ever
+    // scheduled.
+    it('the quality re-eval still runs after a relate-door refusal — the entry is not left permanently deferred', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-wp8', entryId: 'WP-8' });
+            if (fn === 'chain.createEntryRelation') {
+                return Promise.reject(Object.assign(new Error('refused'), { name: 'McpError' }));
+            }
+            if (fn === 'quality.evaluateHeuristicAndSchedule')
+                return Promise.resolve({ verdict: 'pass' });
+            return Promise.resolve({});
+        });
+        try {
+            await runCapture({ text: 'WP: child work package', link: 'WP-5', linkType: 'part_of' });
+        }
+        catch {
+            // The refusal itself is expected — asserted by the sibling test above; this test only
+            // cares that the re-eval call happened before/regardless of it.
+        }
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('quality.evaluateHeuristicAndSchedule', {
+            entryId: 'WP-8',
+            context: 'capture',
+        });
+    });
+    // WP-688 S4 (element 11): the human receipt prints the REAL verb — no `?? 'surfaces_tension_in'`
+    // fallback (formatters/capture.ts:105).
+    it('the human-readable receipt prints the real relation type, never the dead surfaces_tension_in fallback', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-2b', entryId: 'INS-51' });
+            if (fn === 'chain.createEntryRelation')
+                return Promise.resolve({ relationId: 'rel-1' });
+            return Promise.resolve({});
+        });
+        let stdoutOutput = '';
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
+            stdoutOutput += String(chunk);
+            return true;
+        });
+        setOutputMode('pretty'); // force the human receipt path (test harness's stdout is non-TTY)
+        try {
+            await runCapture({ text: 'INS: discovered Y', link: 'DEC-265', linkType: 'validates' });
+        }
+        finally {
+            setOutputMode('auto');
+            writeSpy.mockRestore();
+        }
+        expect(stdoutOutput).toContain('Linked: → DEC-265 (validates)');
+        expect(stdoutOutput).not.toContain('surfaces_tension_in');
+    });
+    // WP-688 S4 review round 2 (bc04z): a diverted relation call (the DEC-1399 auto-link gate
+    // routing an edge to a pending suggestion instead of writing it — WP-776 S2a, DEC-1771
+    // deletes the OTHER diversion this once named, the governs-consent proposal) returns
+    // WITHOUT a relationId — only a real, persisted write may claim `linkedTo`/`relationType`.
+    it('an auto-link-gate diversion (no relationId) is never reported as a persisted link', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-3', entryId: 'WPKG-1' });
+            if (fn === 'chain.createEntryRelation') {
+                return Promise.resolve({ ok: false, status: 'advised', advised: true });
+            }
+            return Promise.resolve({});
+        });
+        let stdoutOutput = '';
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
+            stdoutOutput += String(chunk);
+            return true;
+        });
+        await runCapture({ text: 'WPKG: governance test', link: 'STD-1', linkType: 'governs', json: true });
+        writeSpy.mockRestore();
+        const output = JSON.parse(stdoutOutput.split('\n').find((line) => {
+            try {
+                JSON.parse(line);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }));
+        expect(output.relationType).toBeUndefined();
+        // WP-688 S4 review fix (bc7cr): the re-eval call STILL fires — it's the only thing that
+        // un-defers the LLM schedule deferLLMSchedule set (a relate WAS attempted) — but its
+        // verdict is discarded: no relation landed, so relation-dependent criteria stay unscored.
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('quality.evaluateHeuristicAndSchedule', {
+            entryId: 'WPKG-1',
+            context: 'capture',
+        });
+        expect(output.coaching).toBeUndefined();
+    });
+    // WP-688 S4 review round 2 (bc045): --link without --link-type must not defer the LLM
+    // schedule — the refusal branch never runs the re-eval that would un-defer it, so a
+    // deferred-then-never-run schedule would leave the entry permanently stuck.
+    it('--link without --link-type does NOT defer the LLM schedule (nothing will ever un-defer it)', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-4', entryId: 'TEN-20' });
+            if (fn === 'chain.createEntryRelation')
+                return Promise.resolve({ preview: true, advisories: [] });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runCapture({ text: 'TEN: refused link, no defer', link: 'BET-1' })).rejects.toThrow(CLIError);
+        writeSpy.mockRestore();
+        const createCall = kernelCallWithSessionMock.mock.calls.find(([fn]) => fn === 'chain.createEntry');
+        expect(createCall?.[1]).not.toHaveProperty('deferLLMSchedule');
+    });
+    // WP-688 S4 review round 2 (bc049): a dropped field and a --link-type refusal can both be true
+    // on the SAME capture — the entry was created either way, so both must reach the operator.
+    // TASK-584 (WP-802, TEN-4312): the dropped field is a warning on the landed reply, the link
+    // refusal is the only error.
+    it('prints the dropped-field warning AND throws the link-type refusal when they co-occur', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry') {
+                return Promise.resolve({
+                    docId: 'doc-5', entryId: 'TEN-21',
+                    normalization: { remapped: {}, rejected: ['badField'], accepted: [] },
+                });
+            }
+            if (fn === 'chain.createEntryRelation')
+                return Promise.resolve({ preview: true, advisories: [] });
+            return Promise.resolve({});
+        });
+        const out = [];
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => { out.push(String(chunk)); return true; });
+        let caught;
+        try {
+            await runCapture({ text: 'TEN: both failures at once', link: 'BET-1', json: true });
+        }
+        catch (e) {
+            caught = e;
+        }
+        writeSpy.mockRestore();
+        expect(caught).toBeInstanceOf(CLIError);
+        expect(JSON.parse(out.join(''))).toMatchObject({ id: 'TEN-21', droppedFields: ['badField'] });
+        expect(caught?.message).not.toContain('Fields rejected');
+        expect(caught?.message).toContain('--link requires --link-type');
+        expect(caught?.guidance).toContain('TEN-21');
+    });
+    // WP-745 round 3 (PR #896 review, PRRT_kwDORS4ils6h0e82): the link-refused error beside a
+    // dropped field must preserve the link failure's OWN code/category (e.g. NETWORK_TIMEOUT)
+    // rather than always relabeling the aggregate VALIDATION_FAILED — automation branching on the
+    // error code must still see the timeout, not a generic validation failure.
+    it('the link-refused error beside a dropped field keeps the link failure\'s own code (NETWORK_TIMEOUT), not VALIDATION_FAILED', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry') {
+                return Promise.resolve({
+                    docId: 'doc-10', entryId: 'TEN-22',
+                    normalization: { remapped: {}, rejected: ['badField'], accepted: [] },
+                });
+            }
+            if (fn === 'chain.createEntryRelation') {
+                return Promise.reject(new CLIError('"chain.createEntryRelation" exceeded its budget.', { code: ErrorCode.NETWORK_TIMEOUT, category: 'network', guidance: 'Check before retrying.' }));
+            }
+            if (fn === 'quality.evaluateHeuristicAndSchedule')
+                return Promise.resolve(undefined);
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        let caught;
+        try {
+            await runCapture({ text: 'TEN: both failures, timeout link', link: 'BET-1', linkType: 'part_of' });
+        }
+        catch (e) {
+            caught = e;
+        }
+        writeSpy.mockRestore();
+        expect(caught).toBeInstanceOf(CLIError);
+        expect(caught?.code).toBe(ErrorCode.NETWORK_TIMEOUT);
+        expect(caught?.message).not.toContain('Fields rejected');
+    });
+});
+// WP-684 TASK-77 (E1.3): one-step typed create — --entry-type forwards to chain.createEntry's
+// existing `canonicalKey` arg. Named --entry-type since -t/--type is the --link relation type.
+describe('runCapture --entry-type', () => {
+    beforeEach(() => {
+        kernelCallWithSessionMock.mockReset();
+        mockSession = { sessionId: 'sess-test' };
+    });
+    it('forwards --entry-type as canonicalKey on the chain.createEntry payload', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-3', entryId: 'OBJ-1' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runCapture({ text: 'the objective', collection: 'key-results', entryType: 'objective' });
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.objectContaining({
+            collectionSlug: 'key-results',
+            canonicalKey: 'objective',
+        }));
+        writeSpy.mockRestore();
+    });
+    it('omits canonicalKey entirely when --entry-type is absent (byte-identical default path)', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-4', entryId: 'OBJ-1' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runCapture({ text: 'a key result', collection: 'key-results' });
+        const call = kernelCallWithSessionMock.mock.calls.find(([fn]) => fn === 'chain.createEntry');
+        expect(call?.[1]).not.toHaveProperty('canonicalKey');
+        writeSpy.mockRestore();
+    });
+    // Review round 2 (bcI42): --entry-type's help text promises it "bypasses classification",
+    // but without an ALSO-explicit --collection, the resolution chain fell through to
+    // chain.resolveCollection anyway — objective/key_result text could classify into the wrong
+    // collection (e.g. strategy) and then fail the placement guard. --entry-type alone must route
+    // straight to the shared Objectives drawer with no classification call at all.
+    it('--entry-type objective alone (no --collection) skips classification and routes to the Objectives drawer (bcI42)', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-5', entryId: 'OBJ-2' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runCapture({ text: 'another objective', entryType: 'objective' });
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalledWith('chain.resolveCollection', expect.anything());
+        // PR #713 post-merge review (PRRT_kwDORS4ils6cQP_I, P1): 'key-results' is the RETIRED slug —
+        // the fix derives the drawer's current slug from the live registry (OBJ idPrefix), which is
+        // 'objectives' post-WP-686.
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.objectContaining({
+            collectionSlug: 'objectives',
+            canonicalKey: 'objective',
+        }));
+        writeSpy.mockRestore();
+    });
+    // WP-707 S1 round 2 (DEC-1622, Codex PRRT_kwDORS4ils6dUxaz): key_result now files into its
+    // OWN 1:1 drawer (key-results, idPrefix KR) — it no longer shares the Objectives drawer.
+    it('--entry-type key_result alone (no --collection) routes to the Key Results drawer (DEC-1622)', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-6', entryId: 'KR-2' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runCapture({ text: 'another key result', entryType: 'key_result' });
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalledWith('chain.resolveCollection', expect.anything());
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.objectContaining({
+            collectionSlug: 'key-results',
+            canonicalKey: 'key_result',
+        }));
+        writeSpy.mockRestore();
+    });
+    // Review round 3 (bclZ9): --entry-type Objective (mixed case) or " objective " (whitespace)
+    // must route to the drawer too -- the server normalizes explicit keys with
+    // toLowerCase().trim() downstream, so client-side routing must match or it falls through to
+    // classification (often landing in 'strategy') and the placement guard then rejects it.
+    it('--entry-type with mixed case/whitespace still routes to the Objectives drawer, no classification call (bclZ9)', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-7', entryId: 'OBJ-3' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runCapture({ text: 'a padded objective', entryType: ' Objective ' });
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalledWith('chain.resolveCollection', expect.anything());
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.objectContaining({
+            collectionSlug: 'objectives',
+        }));
+        writeSpy.mockRestore();
+    });
+    // WP-707 S1 round 3 (operator ruling #13): the fast path is now a GENERAL derivation off the
+    // registry's defaultCanonicalKey (getCanonicalKeyToCollection), not two hardcoded
+    // objective/key_result branches — this proves a THIRD kind that was never one of those two
+    // branches (strategy) still skips classification and routes to its own drawer.
+    it('--entry-type strategy alone (no --collection) skips classification and routes to the Strategy drawer — proves the derivation is general, not a hardcoded pair', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-8', entryId: 'STR-1' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runCapture({ text: 'our approach to winning', entryType: 'strategy' });
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalledWith('chain.resolveCollection', expect.anything());
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.objectContaining({
+            collectionSlug: 'strategy',
+            canonicalKey: 'strategy',
+        }));
+        writeSpy.mockRestore();
+    });
+    // WP-707 S1 round 3.1 (Codex post-round-3 P2): vision/purpose are brand-new drawers this same
+    // PR adds — the offline SEED fallback (collectionRegistry.ts) must carry them too, or the
+    // --entry-type derivation silently can't resolve them during a chain.listCollections outage.
+    it('--entry-type vision alone (no --collection) skips classification and routes to the Vision drawer, even offline', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-9', entryId: 'VIS-1' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runCapture({ text: 'a world where knowledge compounds', entryType: 'vision' });
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalledWith('chain.resolveCollection', expect.anything());
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.objectContaining({
+            collectionSlug: 'vision',
+            canonicalKey: 'vision',
+        }));
+        writeSpy.mockRestore();
+    });
+});
+describe('runCapture --json', () => {
+    beforeEach(() => {
+        kernelCallWithSessionMock.mockReset();
+        mockSession = { sessionId: 'sess-test' };
+    });
+    it('outputs valid JSON with id field and no other stdout', async () => {
+        // Prefix "TEN:" is extracted → skips classification
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            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);
+            return true;
+        });
+        await runCapture({ text: 'TEN: test', json: true });
+        writeSpy.mockRestore();
+        // Find JSON lines in stdout
+        const jsonLines = stdoutOutput.split('\n').filter(line => {
+            try {
+                JSON.parse(line);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        expect(jsonLines).toHaveLength(1);
+        const output = JSON.parse(jsonLines[0]);
+        expect(output).toHaveProperty('id', 'TEN-711');
+        expect(output).toHaveProperty('collection', 'tensions');
+        expect(output).toHaveProperty('confidence');
+    });
+});
+describe('runCapture coaching passthrough (WP-475 E1)', () => {
+    beforeEach(() => {
+        kernelCallWithSessionMock.mockReset();
+        mockSession = { sessionId: 'sess-test' };
+    });
+    const coaching = {
+        source: 'heuristic',
+        verdict: {
+            entryId: 'DEC-77',
+            canonicalKey: 'decision',
+            tier: 'assertive',
+            context: 'capture',
+            passed: false,
+            criteria: [
+                { id: 'specificity', passed: false, weight: 2, hint: 'Be specific.', questionTemplate: 'What exactly?' },
+            ],
+            weakest: { criterion: 'specificity', hint: 'Be specific.', questionTemplate: 'What exactly?' },
+            overridden: false,
+        },
+    };
+    it('--json output includes the raw coaching object from the write response', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-c1', entryId: 'DEC-77', coaching });
+            return Promise.resolve({});
+        });
+        let stdoutOutput = '';
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
+            stdoutOutput += String(chunk);
+            return true;
+        });
+        await runCapture({ text: 'DEC: chose something', json: true });
+        writeSpy.mockRestore();
+        const jsonLines = stdoutOutput.split('\n').filter((line) => {
+            try {
+                JSON.parse(line);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        expect(jsonLines).toHaveLength(1);
+        const output = JSON.parse(jsonLines[0]);
+        expect(output.coaching).toEqual(coaching);
+    });
+    it('--json output omits coaching when the write response has none (backward compat)', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-c2', entryId: 'DEC-78' });
+            return Promise.resolve({});
+        });
+        let stdoutOutput = '';
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
+            stdoutOutput += String(chunk);
+            return true;
+        });
+        await runCapture({ text: 'DEC: chose another thing', json: true });
+        writeSpy.mockRestore();
+        const jsonLines = stdoutOutput.split('\n').filter((line) => {
+            try {
+                JSON.parse(line);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        expect(jsonLines).toHaveLength(1);
+        expect(JSON.parse(jsonLines[0])).not.toHaveProperty('coaching');
+    });
+    // ── WP-475 E1 fix: relation-aware receipt on --link ────────────────────────
+    // The create-response verdict is computed BEFORE the --link relation exists,
+    // so relation-dependent criteria (wired-in checks) read falsely failed. When
+    // the capture created a relation, the CLI re-evaluates AFTER it lands and
+    // renders THAT verdict.
+    const reEvalCoaching = {
+        source: 'heuristic',
+        verdict: {
+            ...coaching.verdict,
+            passed: true,
+            criteria: [{ id: 'specificity', passed: true, weight: 2, hint: 'Be specific.', questionTemplate: 'What exactly?' }],
+            weakest: null,
+        },
+    };
+    it('--link: re-evaluates after the relation lands and renders the post-relation verdict', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-c3', entryId: 'DEC-79', coaching });
+            if (fn === 'chain.createEntryRelation')
+                return Promise.resolve({ relationId: 'rel-1' });
+            if (fn === 'quality.evaluateHeuristicAndSchedule')
+                return Promise.resolve(reEvalCoaching);
+            return Promise.resolve({});
+        });
+        let stdoutOutput = '';
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
+            stdoutOutput += String(chunk);
+            return true;
+        });
+        await runCapture({ text: 'DEC: chose with a link', link: 'TEN-1', linkType: 'informs', json: true });
+        writeSpy.mockRestore();
+        // Deterministic --link fix: the CREATE call defers the LLM schedule (the
+        // post-relation re-eval owns the single LLM run)…
+        const createCall = kernelCallWithSessionMock.mock.calls.find(([fn]) => fn === 'chain.createEntry');
+        expect(createCall?.[1]).toMatchObject({ deferLLMSchedule: true });
+        // …and the re-eval fires with the created entry, AFTER the relation write,
+        // WITHOUT the defer flag (it schedules the LLM run as normal).
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('quality.evaluateHeuristicAndSchedule', {
+            entryId: 'DEC-79',
+            context: 'capture',
+        });
+        const callOrder = kernelCallWithSessionMock.mock.calls.map(([fn]) => fn);
+        expect(callOrder.indexOf('chain.createEntryRelation')).toBeLessThan(callOrder.indexOf('quality.evaluateHeuristicAndSchedule'));
+        // The receipt carries the POST-relation verdict, not the create-response one.
+        const jsonLines = stdoutOutput.split('\n').filter((line) => {
+            try {
+                JSON.parse(line);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        expect(jsonLines).toHaveLength(1);
+        expect(JSON.parse(jsonLines[0]).coaching).toEqual(reEvalCoaching);
+    });
+    it('--link: keeps the create-response verdict when the re-eval fails (fail-open, BR-144)', async () => {
         kernelCallWithSessionMock.mockImplementation((fn) => {
-            if (fn === 'chain.suggestLinksForCapture')
-                return Promise.resolve([]);
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
             if (fn === 'chain.createEntry')
-                return Promise.resolve({ docId: 'doc-1', entryId: 'TEN-710' });
+                return Promise.resolve({ docId: 'doc-c4', entryId: 'DEC-80', coaching });
             if (fn === 'chain.createEntryRelation')
-                return Promise.resolve({});
+                return Promise.resolve({ relationId: 'rel-1' });
+            if (fn === 'quality.evaluateHeuristicAndSchedule')
+                return Promise.reject(new Error('network'));
+            return Promise.resolve({});
+        });
+        let stdoutOutput = '';
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
+            stdoutOutput += String(chunk);
+            return true;
+        });
+        await runCapture({ text: 'DEC: chose with a broken re-eval', link: 'TEN-2', linkType: 'informs', json: true });
+        writeSpy.mockRestore();
+        const jsonLines = stdoutOutput.split('\n').filter((line) => {
+            try {
+                JSON.parse(line);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        });
+        expect(jsonLines).toHaveLength(1);
+        expect(JSON.parse(jsonLines[0]).coaching).toEqual(coaching);
+    });
+    it('no --link: does NOT call the re-evaluation and does NOT defer the LLM schedule (plain capture unchanged)', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-c5', entryId: 'DEC-81', coaching });
             return Promise.resolve({});
         });
         const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
-        await runCapture({ text: 'TEN: missing validation', link: 'BET-151' });
-        // 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
+        await runCapture({ text: 'DEC: chose without a link', json: true });
+        writeSpy.mockRestore();
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalledWith('quality.evaluateHeuristicAndSchedule', expect.anything());
+        const createCall = kernelCallWithSessionMock.mock.calls.find(([fn]) => fn === 'chain.createEntry');
+        expect(createCall?.[1]).not.toHaveProperty('deferLLMSchedule');
+    });
+});
+// WP-690 S7 (TASK-120): the 'runCapture description field routing' describe block (TEN-1258's
+// ASM:-shortcode -> 'assumptions' collectionSlug routing test) is DELETED here — `assumption` is
+// one of the 15 genuinely-retired canonicalKeys (collectionRegistry.ts no longer carries an
+// 'assumptions'/ASM entry at all), so the scenario this test asserted can no longer occur: an
+// 'ASM:' capture now falls through to auto-classification (collectionSlug: undefined) instead of
+// the old explicit-shortcode routing. Found via the CI Quality Gate on this PR (new failure caused
+// by the S7 registry purge, fixed at root per the standing "fix new failures at root" contract —
+// not deferred, not papered over).
+describe('runCapture --field passthrough', () => {
+    beforeEach(() => {
+        kernelCallWithSessionMock.mockReset();
+        mockSession = { sessionId: 'sess-test' };
+    });
+    it('merges --field pairs into data', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            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({
-            collectionSlug: 'tensions',
-            name: 'missing validation',
+            data: expect.objectContaining({
+                description: 'touched-code stewardship',
+                rationale: 'signed specs define scope but agents need permission',
+            }),
         }));
-        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntryRelation', {
-            fromEntryId: 'TEN-710',
-            toEntryId: 'BET-151',
-            type: 'surfaces_tension_in',
-        });
         writeSpy.mockRestore();
     });
-    it('uses custom relation type when --type provided', async () => {
-        // Prefix "INS:" is extracted → skips classification, routes directly to insights
+    it('--field description=X overrides the derived description', async () => {
         kernelCallWithSessionMock.mockImplementation((fn) => {
-            if (fn === 'chain.suggestLinksForCapture')
-                return Promise.resolve([]);
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
             if (fn === 'chain.createEntry')
-                return Promise.resolve({ docId: 'doc-2', entryId: 'INS-50' });
-            if (fn === 'chain.createEntryRelation')
-                return Promise.resolve({});
+                return Promise.resolve({ docId: 'doc-7', entryId: 'TEN-1' });
             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(kernelCallWithSessionMock).not.toHaveBeenCalledWith('chain.resolveCollection', expect.anything());
-        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntryRelation', {
-            fromEntryId: 'INS-50',
-            toEntryId: 'DEC-264',
-            type: 'informed_by',
+        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 --json', () => {
+// TASK-584 (WP-802, TEN-4312): the CLI sends only the fields the caller sent. The default
+// description (the capture text) exists to be remapped into the collection's primary field;
+// when -f already set that field and no -d was passed, it is left out.
+describe('runCapture sends only caller fields (TASK-584)', () => {
     beforeEach(() => {
         kernelCallWithSessionMock.mockReset();
         mockSession = { sessionId: 'sess-test' };
     });
-    it('outputs valid JSON with id field and no other stdout', async () => {
-        // Prefix "TEN:" is extracted → skips classification
+    const bodyContract = { governed: false, whyField: null, minChars: 0, descriptionFieldKey: 'body' };
+    const createData = () => kernelCallWithSessionMock.mock.calls.find(([fn]) => fn === 'chain.createEntry')?.[1]?.data;
+    it('omits description when -f sets the primary field and no -d is given', async () => {
         kernelCallWithSessionMock.mockImplementation((fn) => {
-            if (fn === 'chain.suggestLinksForCapture')
-                return Promise.resolve([]);
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.getCollectionFields')
+                return Promise.resolve(bodyContract);
             if (fn === 'chain.createEntry')
-                return Promise.resolve({ docId: 'doc-1', entryId: 'TEN-711' });
+                return Promise.resolve({ docId: 'd', entryId: 'INS-1', status: 'draft' });
             return Promise.resolve({});
         });
-        let stdoutOutput = '';
-        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
-            stdoutOutput += String(chunk);
-            return true;
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runCapture({ text: 'an insight', collection: 'insights', field: ['body=the full body'] });
+        writeSpy.mockRestore();
+        expect(createData()).toEqual({ body: 'the full body' });
+    });
+    it('keeps description when -d is given, even with -f body', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.getCollectionFields')
+                return Promise.resolve(bodyContract);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'd', entryId: 'INS-2', status: 'draft' });
+            return Promise.resolve({});
         });
-        await runCapture({ text: 'TEN: test', json: true });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runCapture({ text: 'an insight', description: 'explicit', collection: 'insights', field: ['body=b'] });
         writeSpy.mockRestore();
-        // Find JSON lines in stdout
-        const jsonLines = stdoutOutput.split('\n').filter(line => {
-            try {
-                JSON.parse(line);
-                return true;
-            }
-            catch {
-                return false;
+        expect(createData()).toEqual({ description: 'explicit', body: 'b' });
+    });
+    it('keeps description on a bare capture so the server can remap it into body', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.getCollectionFields')
+                return Promise.resolve(bodyContract);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'd', entryId: 'INS-3', status: 'draft' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runCapture({ text: 'an insight', collection: 'insights' });
+        writeSpy.mockRestore();
+        expect(createData()).toEqual({ description: 'an insight' });
+    });
+    it('sends description as before when the contract fetch fails', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.getCollectionFields')
+                return Promise.reject(new Error('network'));
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'd', entryId: 'INS-4', status: 'draft' });
+            return Promise.resolve({});
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runCapture({ text: 'an insight', collection: 'insights', field: ['body=b'] });
+        writeSpy.mockRestore();
+        expect(createData()).toEqual({ description: 'an insight', body: 'b' });
+    });
+    it('a landed create with a dropped field resolves (exit 0) and names only that field as dropped', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.getCollectionFields')
+                return Promise.resolve(bodyContract);
+            if (fn === 'chain.createEntry') {
+                return Promise.resolve({
+                    docId: 'd', entryId: 'INS-5', status: 'draft', warnings: ['Unknown fields dropped: nosuchfield. Expected: body (text, required).'],
+                    normalization: { remapped: {}, rejected: ['nosuchfield'], accepted: ['body'] },
+                });
             }
+            return Promise.resolve({});
         });
-        expect(jsonLines).toHaveLength(1);
-        const output = JSON.parse(jsonLines[0]);
-        expect(output).toHaveProperty('id', 'TEN-711');
-        expect(output).toHaveProperty('collection', 'tensions');
-        expect(output).toHaveProperty('confidence');
+        const out = [];
+        const errOut = [];
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => { out.push(String(chunk)); return true; });
+        const errSpy = vi.spyOn(process.stderr, 'write').mockImplementation((chunk) => { errOut.push(String(chunk)); return true; });
+        await expect(runCapture({ text: 'an insight', collection: 'insights', field: ['nosuchfield=x'], json: true })).resolves.toBeUndefined();
+        writeSpy.mockRestore();
+        errSpy.mockRestore();
+        expect(JSON.parse(out.join(''))).toMatchObject({ id: 'INS-5', droppedFields: ['nosuchfield'] });
+        expect(errOut.join('')).not.toContain('Fields rejected');
+    });
+    it('the human receipt names the dropped field as a warning, with pb fields for the collection', () => {
+        const out = formatCaptureReceipt({
+            entryId: 'INS-5', name: 'an insight', collection: 'insights', status: 'draft', classification: null,
+            warnings: ['Unknown fields dropped: nosuchfield. Expected: body (text, required).'],
+            normalization: { remapped: {}, rejected: ['nosuchfield'], accepted: [] },
+        });
+        expect(out).toContain('Warning: Unknown fields dropped: nosuchfield.');
+        expect(out).toContain('pb fields insights');
+        expect(out).not.toContain('Rejected fields');
     });
 });
-describe('runCapture description field routing', () => {
+describe('runCapture WHY pre-flight', () => {
     beforeEach(() => {
         kernelCallWithSessionMock.mockReset();
         mockSession = { sessionId: 'sess-test' };
     });
-    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.
+    it('blocks with guidance when governed and whyField is missing', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            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('blocks with guidance for a why-required, non-governed collection (WP-770 W2a, DEC-1787 ruling A)', async () => {
+        // purpose/vision/strategy/objective are why-required but NOT `governed` (steering-shared
+        // subject) — the gate must fire on `whyField` alone, since getCollectionFields now widens
+        // `whyField` for these four independently of `governed`.
+        kernelCallWithSessionMock.mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.getCollectionFields') {
+                return Promise.resolve({ governed: false, whyField: 'why', minChars: 12, fields: [] });
+            }
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-10', entryId: 'STRAT-2' });
+            return Promise.resolve({});
+        });
+        await expect(runCapture({ text: 'x', collection: 'strategy' })).rejects.toThrow(/why/);
+        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.capture')
+                return Promise.resolve(null);
+            if (fn === 'chain.getCollectionFields') {
+                return Promise.resolve({ governed: true, whyField: 'description', minChars: 12, fields: [] });
+            }
             if (fn === 'chain.createEntry')
-                return Promise.resolve({ docId: 'doc-5', entryId: 'ASM-1' });
+                return Promise.resolve({ docId: 'doc-9', entryId: 'ARCH-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" },
+        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.capture')
+                return Promise.resolve(null);
+            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.capture')
+                return Promise.resolve(null);
+            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.capture')
+                return Promise.resolve(null);
+            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.capture')
+                return Promise.resolve(null);
+            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.capture')
+                return Promise.resolve(null);
+            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(() => {
@@ -146,71 +1267,60 @@ describe('runCapture classification guard', () => {
         await expect(runCapture({ text: 'Ambiguous capture' })).rejects.toThrow('Classification needs review before capture can continue.');
     });
 });
-describe('runCapture date inference', () => {
+describe('runCapture writes no date (TEN-4244, DEC-1787)', () => {
     beforeEach(() => {
         kernelCallWithSessionMock.mockReset();
         mockSession = { sessionId: 'sess-test' };
     });
-    it('does not default date to today when no source date is present', async () => {
+    it.each([
+        ['tasks', 'TASK-10', 'Task due April 1, 2026'],
+        ['decisions', 'DEC-10', 'Decision from April 1, 2026 steering meeting'],
+        ['tasks', 'TASK-11', 'Task without any date'],
+    ])('a %s capture carries no data.date, even when the text names a date', async (collection, entryId, text) => {
         kernelCallWithSessionMock.mockImplementation((fn) => {
-            if (fn === 'chain.suggestLinksForCapture')
-                return Promise.resolve([]);
+            if (fn === 'chain.capture')
+                return Promise.resolve(null);
             if (fn === 'chain.resolveCollection')
-                return Promise.resolve({ collection: 'decisions', confidence: 0.9, tier: 'high' });
+                return Promise.resolve({ collection, confidence: 0.9, tier: 'high' });
             if (fn === 'chain.createEntry')
-                return Promise.resolve({ docId: 'doc-3', entryId: 'DEC-10' });
+                return Promise.resolve({ docId: 'doc-3', entryId });
             return Promise.resolve({});
         });
         const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
-        await runCapture({ text: 'Decision without explicit source date' });
+        await runCapture({ text });
         const createCall = kernelCallWithSessionMock.mock.calls.find(([fn]) => fn === 'chain.createEntry');
-        expect(createCall?.[1]).toMatchObject({
-            collectionSlug: 'decisions',
-            data: { description: 'Decision without explicit source date' },
-        });
+        expect(createCall?.[1]).toMatchObject({ collectionSlug: collection });
         expect((createCall?.[1]).data).not.toHaveProperty('date');
         writeSpy.mockRestore();
     });
-    it('uses inferred source date when the capture text includes one', async () => {
-        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 = 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
+// WP-319 S3 / WP-755 C1a: Pre-write grounding tests (the one capture door)
 // ---------------------------------------------------------------------------
-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,
+describe('runCapture WP-319/WP-755 grounding', () => {
+    const emptyVerdict = { kind: 'create', candidates: [], scanTruncated: false };
+    const askVerdict = {
+        kind: 'ask',
+        candidates: [{ entryId: 'TEN-5', name: 'Similar tension', collectionSlug: 'tensions', score: 0.6 }],
+        scanTruncated: false,
     };
     beforeEach(() => {
         kernelCallWithSessionMock.mockReset();
         mockSession = { sessionId: 'sess-test' };
         delete process.env.PB_GROUNDING_MODE;
+        // Pre-existing gap this fix round's new --strict tests surfaced: runner.ts's outputMode is
+        // module-level `let` state, set permanently by any earlier test in this file that passed
+        // `json: true` (setOutputMode is never test-scoped). Reset it here so a later test's
+        // `!json` branches (the --strict prompt gate) are never silently skipped by an earlier
+        // test's leaked JSON mode.
+        setOutputMode('auto');
     });
-    it('fires chain.suggestLinksForCapture in parallel and still calls createEntry', async () => {
+    it('fires chain.capture 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.capture')
+                return Promise.resolve(emptyVerdict);
             if (fn === 'chain.createEntry')
                 return Promise.resolve({ docId: 'doc-1', entryId: 'TEN-720' });
             return Promise.resolve({});
@@ -218,8 +1328,8 @@ describe('runCapture WP-319 grounding', () => {
         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.capture', expect.objectContaining({
+            name: 'grounding test tension',
         }));
         expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.anything());
         writeSpy.mockRestore();
@@ -228,7 +1338,7 @@ describe('runCapture WP-319 grounding', () => {
     it('does NOT block capture when grounding call fails', async () => {
         kernelCallWithSessionMock
             .mockImplementation((fn) => {
-            if (fn === 'chain.suggestLinksForCapture')
+            if (fn === 'chain.capture')
                 return Promise.reject(new Error('network error'));
             if (fn === 'chain.createEntry')
                 return Promise.resolve({ docId: 'doc-2', entryId: 'TEN-721' });
@@ -242,70 +1352,11 @@ describe('runCapture WP-319 grounding', () => {
         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 () => {
+    it('a create verdict prints no Related line and no how-it-connects list (TASK-608, DEC-1915)', async () => {
         kernelCallWithSessionMock
             .mockImplementation((fn) => {
-            if (fn === 'chain.suggestLinksForCapture')
-                return Promise.resolve([emptyGrounding]);
+            if (fn === 'chain.capture')
+                return Promise.resolve(emptyVerdict);
             if (fn === 'chain.createEntry')
                 return Promise.resolve({ docId: 'doc-3', entryId: 'TEN-722' });
             return Promise.resolve({});
@@ -317,13 +1368,15 @@ describe('runCapture WP-319 grounding', () => {
             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'));
+        // No "Related"/"Possible match" banner in stderr, and no first-capture "how it connects" list.
+        const groundingInStderr = stderrLines.some((l) => l.includes('Related') || l.includes('Possible match'));
         expect(groundingInStderr).toBe(false);
+        const stdoutText = writeSpy.mock.calls.map(([chunk]) => String(chunk)).join('');
+        expect(stdoutText).not.toContain('how it connects');
         writeSpy.mockRestore();
         stderrSpy.mockRestore();
     });
-    it('PB_GROUNDING_MODE=off skips grounding call entirely', async () => {
+    it('PB_GROUNDING_MODE=off skips the door entirely', async () => {
         process.env.PB_GROUNDING_MODE = 'off';
         kernelCallWithSessionMock
             .mockImplementation((fn) => {
@@ -334,7 +1387,7 @@ describe('runCapture WP-319 grounding', () => {
         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).not.toHaveBeenCalledWith('chain.capture', expect.anything());
         expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.anything());
         delete process.env.PB_GROUNDING_MODE;
         writeSpy.mockRestore();
@@ -343,8 +1396,8 @@ describe('runCapture WP-319 grounding', () => {
     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.capture')
+                return Promise.resolve(askVerdict);
             if (fn === 'chain.createEntry')
                 return Promise.resolve({ docId: 'doc-5', entryId: 'TEN-724' });
             return Promise.resolve({});
@@ -369,9 +1422,112 @@ describe('runCapture WP-319 grounding', () => {
         expect(parsed.id).toBe('TEN-724');
         // No grounding content in stdout
         expect(stdoutOutput).not.toContain('Grounding');
-        expect(stdoutOutput).not.toContain('duplicate');
+        expect(stdoutOutput).not.toContain('Possible match');
+        writeSpy.mockRestore();
+        stderrSpy.mockRestore();
+    });
+    // TASK-619: an automated --json caller must learn the close match (id, name, collection, score)
+    // to update it deliberately — still one JSON line on stdout.
+    it('--json on an ask verdict carries possibleMatches in the single JSON line', async () => {
+        kernelCallWithSessionMock
+            .mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(askVerdict);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-6', entryId: 'TEN-725' });
+            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 ask shape', json: true });
+        const lines = stdoutOutput.split('\n').filter((l) => l.trim());
+        expect(lines).toHaveLength(1);
+        const parsed = JSON.parse(lines[0]);
+        expect(parsed.id).toBe('TEN-725');
+        expect(parsed.possibleMatches).toEqual([{ entryId: 'TEN-5', name: 'Similar tension', collection: 'tensions', score: 0.6 }]);
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalledWith('chain.updateEntry', expect.anything());
+        writeSpy.mockRestore();
+        stderrSpy.mockRestore();
+    });
+    it('--json on a create verdict carries no possibleMatches field', async () => {
+        kernelCallWithSessionMock
+            .mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(emptyVerdict);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-7', entryId: 'TEN-726' });
+            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 create shape', json: true });
+        const parsed = JSON.parse(stdoutOutput.split('\n').filter((l) => l.trim())[0]);
+        expect(parsed).not.toHaveProperty('possibleMatches');
         writeSpy.mockRestore();
         stderrSpy.mockRestore();
     });
+    const originalStdinIsTTY = process.stdin.isTTY;
+    function mockInteractiveStdin(answer) {
+        Object.defineProperty(process.stdin, 'isTTY', { value: true, configurable: true });
+        vi.spyOn(process.stdin, 'once').mockImplementation((_event, cb) => {
+            cb(Buffer.from(answer));
+            return process.stdin;
+        });
+    }
+    afterEach(() => {
+        // vitest's own hook, not a manual end-of-test call — runs even when an assertion above threw,
+        // so one failing case in this block can never leak its stdin mock into the next test.
+        Object.defineProperty(process.stdin, 'isTTY', { value: originalStdinIsTTY, configurable: true });
+        vi.restoreAllMocks();
+    });
+    it('--strict prompts on an "ask" verdict too (unchanged from before this fix round)', async () => {
+        kernelCallWithSessionMock
+            .mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(askVerdict);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-12', entryId: 'TEN-728' });
+            return Promise.resolve({});
+        });
+        mockInteractiveStdin('y');
+        vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        const stderrLines = [];
+        vi.spyOn(process.stderr, 'write').mockImplementation((chunk) => {
+            stderrLines.push(String(chunk));
+            return true;
+        });
+        await runCapture({ text: 'TEN: ask strict prompt', strict: true });
+        expect(stderrLines.some((l) => l.includes('Proceed with capture?'))).toBe(true);
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.anything());
+    });
+    // TASK-619 (TEN-4420): a close match never overwrites the matched entry. The CLI names the
+    // match and writes only its own new draft; chain.updateEntry is never called from capture.
+    it('a close same-collection match names the match and never updates it', async () => {
+        const closeMatch = {
+            kind: 'ask',
+            candidates: [{ entryId: 'TEN-9', name: 'Existing near-duplicate tension', collectionSlug: 'tensions', score: 0.95 }],
+            scanTruncated: false,
+        };
+        kernelCallWithSessionMock
+            .mockImplementation((fn) => {
+            if (fn === 'chain.capture')
+                return Promise.resolve(closeMatch);
+            if (fn === 'chain.createEntry')
+                return Promise.resolve({ docId: 'doc-13', entryId: 'TEN-729' });
+            return Promise.resolve({});
+        });
+        vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        const stderrLines = [];
+        vi.spyOn(process.stderr, 'write').mockImplementation((chunk) => {
+            stderrLines.push(String(chunk));
+            return true;
+        });
+        await runCapture({ text: 'TEN: existing near-duplicate tension' });
+        expect(stderrLines.some((l) => l.includes('Possible match') && l.includes('TEN-9'))).toBe(true);
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalledWith('chain.updateEntry', expect.anything());
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.anything());
+    });
 });
 //# sourceMappingURL=capture.test.js.map