@productbrain/cli 0.1.0-beta.11174 → 0.1.0-beta.11180

package/dist/__tests__/capture.test.js

@@ -1,6 +1,6 @@
 /**
  * pb capture extensions — --link, --json flags, WP-319 grounding.
- * TEN-341 test contract: capture --link calls createEntryRelation, capture --json outputs JSON.
+ * TASK-897 (DEC-2113): capture --link rides in the one chain.createEntry request as links[]; the reply's outcomes print.
  * TASK-894 (DEC-2113): one chain.createEntry per capture; the kernel's verdict rides the reply.
  */
 import { beforeEach, describe, expect, it, vi } from 'vitest';
@@ -20,521 +20,96 @@ vi.mock('../lib/session.js', () => ({
     readSession: () => mockSession,
     addCapturedEntry: vi.fn(),
 }));
-describe('runCapture --link', () => {
+// TASK-897 (DEC-2113): a linked capture is ONE request. The --link/--link-type pairs ride in chain.createEntry as
+// links[]; the kernel judges each in the transaction that lands the entry and answers per link, in its own words
+// (`line`, RULE-664). A refused link never fails the capture (exit 0, the entry landed); a pair the kernel could never
+// judge (no type, an empty id) is refused before anything is sent, so nothing is half-done.
+describe('runCapture --link (TASK-897)', () => {
     beforeEach(() => {
         kernelCallWithSessionMock.mockReset();
         mockSession = { sessionId: 'sess-test' };
     });
-    // 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.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. TASK-894: the text goes as typed; the kernel routes the prefix.
-        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.createEntry', expect.objectContaining({
-            name: 'TEN: 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.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.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.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.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.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.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.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 () => {
-        kernelCallWithSessionMock.mockImplementation((fn) => {
-            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' });
-        // 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.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.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.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.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.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)
+    const LINKS = [
+        { toEntryId: 'DEC-29', type: 'related_to', outcome: 'written', line: 'linked related_to DEC-29' },
+        { toEntryId: 'WP-29', type: 'part_of', outcome: 'refused', reason: 'A work package is never part_of another work package.', line: 'link refused: A work package is never part_of another work package.' },
+    ];
+    async function captureWithTwoLinks(json) {
+        kernelCallWithSessionMock.mockImplementation((fn) => (fn === 'chain.createEntry' ? Promise.resolve({ docId: 'doc-1', entryId: 'TEN-710', collection: 'tensions', links: LINKS }) : Promise.resolve({})));
+        let out = '';
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => { out += String(chunk); return true; });
+        const errSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        setOutputMode(json ? 'json' : 'pretty');
         try {
-            await runCapture({ text: 'INS: discovered Y', link: 'DEC-265', linkType: 'validates' });
+            await runCapture({ text: 'TEN: missing validation', link: ['DEC-29', 'WP-29'], linkType: ['related_to', 'part_of'], json });
         }
         finally {
             setOutputMode('auto');
             writeSpy.mockRestore();
+            errSpy.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.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.createEntry')
-                return Promise.resolve({ docId: 'doc-4', entryId: 'TEN-20' });
-            if (fn === 'chain.createEntryRelation')
-                return Promise.resolve({ preview: true, advisories: [] });
-            return Promise.resolve({});
-        });
+        return out;
+    }
+    it('two --link pairs send ONE request carrying links[], and the receipt prints the kernel line per link; a refused link exits 0', async () => {
+        const out = await captureWithTwoLinks(false);
+        expect(kernelCallWithSessionMock.mock.calls.map(([fn]) => fn)).toEqual(['chain.createEntry']);
+        expect(kernelCallWithSessionMock.mock.calls[0][1]).toMatchObject({
+            name: 'TEN: missing validation', links: [{ toEntryId: 'DEC-29', type: 'related_to' }, { toEntryId: 'WP-29', type: 'part_of' }],
+        });
+        expect(kernelCallWithSessionMock.mock.calls[0][1]).not.toHaveProperty('deferLLMSchedule');
+        expect(out).toContain('→ TEN-710 captured');
+        expect(out).toContain('  linked related_to DEC-29');
+        expect(out).toContain('  link refused: A work package is never part_of another work package.');
+    });
+    it('--json carries the links as the kernel answered them', async () => {
+        const out = await captureWithTwoLinks(true);
+        const output = JSON.parse(out.trim().split('\n').pop());
+        expect(output).toMatchObject({ id: 'TEN-710', collection: 'tensions', links: LINKS });
+        expect(output).not.toHaveProperty('relationType');
+    });
+    it('no --link: the request carries no links field and no defer flag', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => (fn === 'chain.createEntry' ? Promise.resolve({ docId: 'doc-2', entryId: 'TEN-711' }) : 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);
+        await runCapture({ text: 'TEN: plain', json: true });
         writeSpy.mockRestore();
-        const createCall = kernelCallWithSessionMock.mock.calls.find(([fn]) => fn === 'chain.createEntry');
-        expect(createCall?.[1]).not.toHaveProperty('deferLLMSchedule');
+        const args = kernelCallWithSessionMock.mock.calls[0][1];
+        expect(args).not.toHaveProperty('links');
+        expect(args).not.toHaveProperty('deferLLMSchedule');
+        expect(kernelCallWithSessionMock.mock.calls.map(([fn]) => fn)).toEqual(['chain.createEntry']);
     });
-    // 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.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; });
+    // WP-688 S4 (element 11): no default verb, ever. TASK-897: the refusal comes before the request, so nothing is captured.
+    it('--link without --link-type is refused before anything is sent', async () => {
         let caught;
         try {
-            await runCapture({ text: 'TEN: both failures at once', link: 'BET-1', json: true });
+            await runCapture({ text: 'TEN: missing validation', link: ['BET-151'] });
         }
         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.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;
-        }
+        expect(caught?.code).toBe(ErrorCode.VALIDATION_FAILED);
+        expect(caught?.message).toContain('--link BET-151 requires --link-type');
+        expect(caught?.guidance).toContain('Nothing was captured');
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled();
+    });
+    it('a second --link without its own --link-type is refused before anything is sent', async () => {
+        await expect(runCapture({ text: 'TEN: two links one type', link: ['DEC-29', 'WP-29'], linkType: ['related_to'] })).rejects.toThrow('--link WP-29 requires --link-type');
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled();
+    });
+    // WP-688 S4 review round 5 (bcRUML, bcRpJQ): an empty or whitespace-only --link never silently no-ops.
+    it.each(['', '   '])('--link %j is refused before anything is sent', async (link) => {
+        await expect(runCapture({ text: 'TEN: empty link', link: [link], linkType: ['related_to'] })).rejects.toThrow('--link requires a non-empty entry ID');
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled();
+    });
+    // TASK-584 (WP-802, TEN-4312): a dropped field is a warning on the landed reply; with a refused link both reach the operator and the command exits 0.
+    it('prints the dropped-field warning AND the refused link on one landed capture, exit 0', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => (fn === 'chain.createEntry'
+            ? Promise.resolve({ docId: 'doc-5', entryId: 'TEN-21', normalization: { remapped: {}, rejected: ['badField'], accepted: [] }, links: [LINKS[1]] })
+            : Promise.resolve({})));
+        let out = '';
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => { out += String(chunk); return true; });
+        await runCapture({ text: 'TEN: both at once', link: ['WP-29'], linkType: ['part_of'], json: true });
         writeSpy.mockRestore();
-        expect(caught).toBeInstanceOf(CLIError);
-        expect(caught?.code).toBe(ErrorCode.NETWORK_TIMEOUT);
-        expect(caught?.message).not.toContain('Fields rejected');
+        expect(JSON.parse(out.trim())).toMatchObject({ id: 'TEN-21', droppedFields: ['badField'], links: [{ outcome: 'refused' }] });
     });
 });
 // WP-684 TASK-77 (E1.3): one-step typed create — --entry-type forwards to chain.createEntry's
@@ -692,103 +267,20 @@ describe('runCapture coaching passthrough (WP-475 E1)', () => {
         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.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({});
-        });
+    // TASK-897: the one verdict on the reply already saw the links (the kernel writes them before it judges), so a
+    // linked capture renders the create-response verdict as a plain one does; nothing is re-evaluated.
+    it('--link: renders the create-response verdict and calls no re-evaluation', async () => {
+        kernelCallWithSessionMock.mockImplementation((fn) => (fn === 'chain.createEntry'
+            ? Promise.resolve({ docId: 'doc-c3', entryId: 'DEC-79', coaching, links: [{ toEntryId: 'TEN-1', type: 'informs', outcome: 'written', line: 'linked informs TEN-1' }] })
+            : 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.createEntry')
-                return Promise.resolve({ docId: 'doc-c4', entryId: 'DEC-80', coaching });
-            if (fn === 'chain.createEntryRelation')
-                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.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: 'DEC: chose without a link', json: true });
+        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();
-        expect(kernelCallWithSessionMock).not.toHaveBeenCalledWith('quality.evaluateHeuristicAndSchedule', expect.anything());
-        const createCall = kernelCallWithSessionMock.mock.calls.find(([fn]) => fn === 'chain.createEntry');
-        expect(createCall?.[1]).not.toHaveProperty('deferLLMSchedule');
+        expect(kernelCallWithSessionMock.mock.calls.map(([fn]) => fn)).toEqual(['chain.createEntry']);
+        const output = JSON.parse(stdoutOutput.trim());
+        expect(output.coaching).toEqual(coaching);
+        expect(output.links).toEqual([{ toEntryId: 'TEN-1', type: 'informs', outcome: 'written', line: 'linked informs TEN-1' }]);
     });
 });
 // WP-690 S7 (TASK-120): the 'runCapture description field routing' describe block (TEN-1258's
@@ -1038,63 +530,43 @@ describe('runCapture renders the kernel verdict', () => {
         expect(JSON.parse(out.trim())).not.toHaveProperty('possibleMatches');
     });
 });
-// TASK-898 (DEC-2113): a re-sent capture the kernel replayed. The first send may have timed out before its link,
-// so the link is resent if-missing; nothing model-driven (the re-eval) or bookkeeping (the grounding outcome) runs
-// again, and the reply names the collection the first send landed in, not the retry's own resolution.
+// TASK-898 (DEC-2113): a re-sent capture the kernel replayed. TASK-897: the kernel answers the retry's links from the rows
+// (written by the first send, or refused then); the CLI prints them as on a first send and sends nothing more.
 describe('runCapture on a replayed reply (TASK-898)', () => {
-    const REPLAY = { entryId: 'INS-60', docId: 'doc-60', status: 'draft', collection: 'decisions', replayed: true };
-    function mockReplay(relate) {
+    const REPLAY_LINKS = [
+        { toEntryId: 'DEC-266', type: 'informed_by', outcome: 'written', line: 'linked informed_by DEC-266' },
+        { toEntryId: 'WP-29', type: 'part_of', outcome: 'refused', reason: 'Not written when INS-60 first landed; this reply is a replay. Relate it again to read the reason.', line: 'link refused: Not written when INS-60 first landed; this reply is a replay. Relate it again to read the reason.' },
+    ];
+    const REPLAY = { entryId: 'INS-60', docId: 'doc-60', status: 'draft', collection: 'decisions', replayed: true, links: REPLAY_LINKS };
+    async function run(json) {
         kernelCallWithSessionMock.mockReset();
         mockSession = { sessionId: 'sess-test' };
-        kernelCallWithSessionMock.mockImplementation((fn) => {
-            if (fn === 'chain.createEntry')
-                return Promise.resolve(REPLAY);
-            if (fn === 'chain.createEntryRelation')
-                return relate();
-            return Promise.resolve({});
-        });
-    }
-    async function run() {
+        kernelCallWithSessionMock.mockImplementation((fn) => (fn === 'chain.createEntry' ? Promise.resolve(REPLAY) : Promise.resolve({})));
         let out = '';
         const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => { out += String(chunk); return true; });
+        const errSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
+        setOutputMode(json ? 'json' : 'pretty');
         try {
-            await runCapture({ text: 'INS: discovered Z', link: 'DEC-266', linkType: 'informed_by', json: true });
+            await runCapture({ text: 'INS: discovered Z', link: ['DEC-266', 'WP-29'], linkType: ['informed_by', 'part_of'], json });
         }
         finally {
+            setOutputMode('auto');
             writeSpy.mockRestore();
+            errSpy.mockRestore();
         }
         return out;
     }
-    const calledFns = () => kernelCallWithSessionMock.mock.calls.map(([fn]) => fn);
-    it('an already-existing link is success: exit 0, "existing", no re-eval, no outcome row, the kernel collection', async () => {
-        mockReplay(() => Promise.reject(new CLIError('Duplicate relation: a "informed_by" relation from this entry to the target already exists.', { code: ErrorCode.VALIDATION_FAILED, category: 'validation' })));
-        const output = JSON.parse((await run()).trim().split('\n').pop());
-        expect(output).toMatchObject({ id: 'INS-60', collection: 'decisions', replayed: true, relationType: 'informed_by', linkOutcome: 'existing' });
-        expect(calledFns()).not.toContain('quality.evaluateHeuristicAndSchedule');
-        expect(calledFns()).not.toContain('chain.recordGroundingOutcome');
-    });
-    it('a link the first send never reached is written now, still with no re-eval', async () => {
-        mockReplay(() => Promise.resolve({ relationId: 'rel-60' }));
-        const output = JSON.parse((await run()).trim().split('\n').pop());
-        expect(output).toMatchObject({ id: 'INS-60', collection: 'decisions', replayed: true, linkOutcome: 'written' });
-        expect(calledFns().filter((fn) => fn === 'chain.createEntryRelation')).toHaveLength(1);
-        expect(calledFns()).not.toContain('quality.evaluateHeuristicAndSchedule');
+    it('the replay is one request too: exit 0, the kernel collection, the links as the kernel reports them', async () => {
+        const output = JSON.parse((await run(true)).trim().split('\n').pop());
+        expect(output).toMatchObject({ id: 'INS-60', collection: 'decisions', replayed: true, links: REPLAY_LINKS });
+        expect(kernelCallWithSessionMock.mock.calls.map(([fn]) => fn)).toEqual(['chain.createEntry']);
     });
-    it('the receipt names the first send\'s collection and says the link is already there', async () => {
-        mockReplay(() => Promise.reject(new CLIError('Duplicate relation: already exists.', { code: ErrorCode.VALIDATION_FAILED, category: 'validation' })));
-        let out = '';
-        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => { out += String(chunk); return true; });
-        setOutputMode('pretty');
-        try {
-            await runCapture({ text: 'INS: discovered Z', link: 'DEC-266', linkType: 'informed_by' });
-        }
-        finally {
-            setOutputMode('auto');
-            writeSpy.mockRestore();
-        }
+    it('the receipt names the first send\'s collection, says nothing was written twice, and prints the link lines', async () => {
+        const out = await run(false);
         expect(out).toContain('decisions');
         expect(out).toContain('Already captured as INS-60');
-        expect(out).toContain('Link informed_by DEC-266: already there.');
+        expect(out).toContain('  linked informed_by DEC-266');
+        expect(out).toContain('  link refused: Not written when INS-60 first landed');
     });
 });
 // TASK-889 (TEN-4610, RULE-664): the capture receipt names the new row in the kernel's word, the one the Rail shows.