@productbrain/cli 0.1.0-beta.9 → 0.1.0-beta.9000

package/dist/__tests__/update.test.js

@@ -1,19 +1,47 @@
 /**
- * pb update — verify mcpCallWithSession sequence and args.
+ * pb update — verify kernelCallWithSession sequence and args.
  * TEN-341 test contract: happy path, no session, empty entryId.
  */
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { runUpdate } from '../commands/update.js';
-const mcpCallWithSessionMock = vi.fn();
+import { CLIError, ErrorCode } from '../lib/errors.js';
+import { isJsonMode } from '../lib/runner.js';
+const mockIsJsonMode = vi.mocked(isJsonMode);
+const kernelCallWithSessionMock = vi.fn();
+const kernelCallMock = vi.fn();
 vi.mock('../lib/client.js', () => ({
-    mcpCallWithSession: (...args) => mcpCallWithSessionMock(...args),
+    kernelCallWithSession: (...args) => kernelCallWithSessionMock(...args),
+    kernelCall: (...args) => kernelCallMock(...args),
+    // McpError exported so update.ts can import the type (not used at runtime in tests).
+    McpError: class McpError extends Error {
+        details;
+        code;
+        constructor(message, code, details) {
+            super(message);
+            this.name = 'McpError';
+            this.code = code;
+            this.details = details;
+        }
+    },
 }));
+/**
+ * Helper to create an error that looks like McpError.
+ * The update command checks `err.name === 'McpError'` so any Error with that name works.
+ */
+function makeMcpError(message, code, details) {
+    const err = new Error(message);
+    err.name = 'McpError';
+    err.code = code;
+    err.details = details;
+    return err;
+}
 vi.mock('../lib/config.js', () => ({
     getConfigOrGuide: vi.fn(() => Promise.resolve({ apiKey: 'pb_sk_test', siteUrl: 'https://test.convex.site' })),
 }));
-// Force pretty mode for all tests so formatUpdateReceipt output is tested (not JSON)
+// Defaults to pretty mode so formatUpdateReceipt output is tested (not JSON); individual
+// tests override with mockIsJsonMode.mockReturnValue(true) to exercise the JSON branch.
 vi.mock('../lib/runner.js', () => ({
-    isJsonMode: () => false,
+    isJsonMode: vi.fn(() => false),
 }));
 // Session mock — controlled per test
 let mockSession = { sessionId: 'sess-test' };
@@ -25,13 +53,19 @@ describe('runUpdate', () => {
         vi.clearAllMocks();
         mockSession = { sessionId: 'sess-test' };
         // BET-192: updateEntry returns warnings + normalization breakdown (symmetric with createEntry)
-        mcpCallWithSessionMock.mockResolvedValue({
+        kernelCallWithSessionMock.mockResolvedValue({
             id: 'j571abc123def456',
             warnings: [],
             normalization: { remapped: {}, rejected: [], accepted: [] },
             normalizationWarnings: [],
             validationWarnings: [],
         });
+        // Post-update refresh: default to returning a minimal entry.
+        kernelCallMock.mockResolvedValue({
+            entryId: 'BET-151',
+            name: 'Test Entry',
+            status: 'active',
+        });
     });
     it('calls chain.updateEntry with correct args (happy path)', async () => {
         const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
@@ -41,8 +75,9 @@ describe('runUpdate', () => {
             note: 'Updated description',
         });
         writeSpy.mockRestore();
-        expect(mcpCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
             entryId: 'BET-151',
+            changedBy: 'agent:sess-test',
             data: { description: 'new description' },
             changeNote: 'Updated description',
         });
@@ -52,17 +87,64 @@ describe('runUpdate', () => {
         await runUpdate({
             entryId: 'TEN-703',
             name: 'New name',
-            status: 'active',
+            status: 'archived',
             note: 'Resolved',
         });
         writeSpy.mockRestore();
-        expect(mcpCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
             entryId: 'TEN-703',
+            changedBy: 'agent:sess-test',
             name: 'New name',
-            status: 'active',
+            status: 'archived',
             changeNote: 'Resolved',
         });
     });
+    // T8 (TASK-393, WP-779): --status is validated client-side against the generated write
+    // vocabulary (kernel/entries/statusCategories.ts) before the round trip.
+    it('refuses a legacy status word via --status', async () => {
+        const err = await runUpdate({ entryId: 'TEN-703', status: 'active' }).catch((e) => e);
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.VALIDATION_FAILED);
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled();
+    });
+    it('refuses an unknown status word via --status', async () => {
+        const err = await runUpdate({ entryId: 'TEN-703', status: 'not-a-real-status' }).catch((e) => e);
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.VALIDATION_FAILED);
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled();
+    });
+    // Round-1 review (Codex P2, PRRT_kwDORS4ils6mPBU8): `--status ""` is PROVIDED but blank, not
+    // ABSENT — a truthiness check let it skip the vocabulary check entirely and silently drop the
+    // status while other fields still applied (same class of bug PR #622 already fixed for --type).
+    it('refuses a blank --status "" instead of silently dropping it', async () => {
+        const err = await runUpdate({ entryId: 'TEN-703', status: '', name: 'New name' }).catch((e) => e);
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.VALIDATION_FAILED);
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled();
+    });
+    it('passes workflowStatus as root-level arg when provided', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({
+            entryId: 'BET-271',
+            workflowStatus: 'shipped',
+        });
+        writeSpy.mockRestore();
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
+            entryId: 'BET-271',
+            changedBy: 'agent:sess-test',
+            workflowStatus: 'shipped',
+        });
+    });
+    // SHOULD-FIX 4 (fix round): `--workflow-status` alone applied nothing the OLD receipt's field
+    // set could name (it only ever checked name/status) — pre-fix this printed "Updated BET-271: "
+    // with an empty list for a write that genuinely succeeded.
+    it('workflowStatus alone produces a non-empty receipt naming it (SHOULD-FIX 4)', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'BET-271', workflowStatus: 'shipped' });
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        expect(output).toContain('Updated BET-271: workflowStatus → shipped');
+    });
     it('handles --field values containing = signs', async () => {
         const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
         await runUpdate({
@@ -70,64 +152,276 @@ describe('runUpdate', () => {
             field: ['rationale=a=b=c'],
         });
         writeSpy.mockRestore();
-        expect(mcpCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
             entryId: 'DEC-264',
+            changedBy: 'agent:sess-test',
             data: { rationale: 'a=b=c' },
         });
     });
-    it('exits 1 with no active session', async () => {
+    it('throws CLIError with no active session', async () => {
         mockSession = null;
-        const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => { throw new Error('exit'); });
-        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
-        await expect(runUpdate({ entryId: 'BET-151', field: ['x=1'] })).rejects.toThrow('exit');
-        expect(exitSpy).toHaveBeenCalledWith(1);
-        const stderrOutput = stderrSpy.mock.calls.map(c => String(c[0])).join('');
-        expect(stderrOutput).toContain('No active session');
-        expect(mcpCallWithSessionMock).not.toHaveBeenCalled();
-        exitSpy.mockRestore();
-        stderrSpy.mockRestore();
-    });
-    it('exits 1 with empty entryId', async () => {
-        const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => { throw new Error('exit'); });
-        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
-        await expect(runUpdate({ entryId: '  ', field: ['x=1'] })).rejects.toThrow('exit');
-        expect(exitSpy).toHaveBeenCalledWith(1);
-        expect(mcpCallWithSessionMock).not.toHaveBeenCalled();
-        exitSpy.mockRestore();
-        stderrSpy.mockRestore();
-    });
-    it('exits 1 when nothing to update', async () => {
-        const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => { throw new Error('exit'); });
-        const stderrSpy = vi.spyOn(process.stderr, 'write').mockImplementation(() => true);
-        await expect(runUpdate({ entryId: 'BET-151' })).rejects.toThrow('exit');
-        expect(exitSpy).toHaveBeenCalledWith(1);
-        const stderrOutput = stderrSpy.mock.calls.map(c => String(c[0])).join('');
-        expect(stderrOutput).toContain('Nothing to update');
-        expect(mcpCallWithSessionMock).not.toHaveBeenCalled();
-        exitSpy.mockRestore();
-        stderrSpy.mockRestore();
+        await expect(runUpdate({ entryId: 'BET-151', field: ['x=1'] })).rejects.toThrow(CLIError);
+        await expect(runUpdate({ entryId: 'BET-151', field: ['x=1'] })).rejects.toThrow('No active session');
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled();
+    });
+    it('throws CLIError with empty entryId', async () => {
+        await expect(runUpdate({ entryId: '  ', field: ['x=1'] })).rejects.toThrow(CLIError);
+        await expect(runUpdate({ entryId: '  ', field: ['x=1'] })).rejects.toThrow('Entry ID is required');
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled();
+    });
+    it('throws CLIError when nothing to update', async () => {
+        await expect(runUpdate({ entryId: 'BET-151' })).rejects.toThrow(CLIError);
+        await expect(runUpdate({ entryId: 'BET-151' })).rejects.toThrow('Nothing to update');
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled();
+    });
+    // ── Structured validation error tests ────────────────────────────────────
+    it('throws CLIError with structured select field error message', async () => {
+        kernelCallWithSessionMock.mockRejectedValue(makeMcpError("Entry data validation failed: Field \"appetite\" must be one of: small, medium, large. Got: 'Small Batch'. Fix the values and try again.", 'VALIDATION_FAILED', [{
+                fieldKey: 'appetite',
+                fieldLabel: 'appetite',
+                invalidValue: 'Small Batch',
+                validOptions: ['small', 'medium', 'large'],
+                errorType: 'invalid_option',
+                message: "Field \"appetite\" must be one of: small, medium, large. Got: 'Small Batch'",
+            }]));
+        const err = await runUpdate({ entryId: 'BET-151', field: ['appetite=Small Batch'] }).catch((e) => e);
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.message).toContain("Field 'appetite' must be one of: small, medium, large");
+        expect(err.message).toContain("Got: 'Small Batch'");
+    });
+    it('throws CLIError with plain error message when no structured details', async () => {
+        kernelCallWithSessionMock.mockRejectedValue(makeMcpError('Entry not found.', 'NOT_FOUND'));
+        const err = await runUpdate({ entryId: 'BET-999', field: ['x=1'] }).catch((e) => e);
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.message).toContain('Entry not found.');
+    });
+    it('preserves a server authority refusal as machine-readable AUTH_DENIED', async () => {
+        kernelCallWithSessionMock.mockRejectedValue(makeMcpError('This record belongs to another team.', 'AUTHZ_PERMISSION_DENIED'));
+        const err = await runUpdate({ entryId: 'WP-OTHER-TEAM', field: ['description=no'] }).catch((e) => e);
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.AUTH_DENIED);
+        expect(err.category).toBe('auth');
+    });
+    it('preserves a returned organisational refusal and its truthful next action', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            outcome: 'refused',
+            refusal: {
+                category: 'auth',
+                code: 'role_not_owner',
+                reason: 'This person does not hold this record’s exact owning role in its owning team.',
+                requiredAction: 'Route this change to a holder of the record’s exact owning role, or ask the relevant Team Lead to change its ownership.',
+            },
+        });
+        const err = await runUpdate({ entryId: 'WP-OTHER-TEAM', field: ['description=no'] }).catch((e) => e);
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.AUTH_DENIED);
+        expect(err.category).toBe('auth');
+        expect(err.guidance).toBe('Route this change to a holder of the record’s exact owning role, or ask the relevant Team Lead to change its ownership.');
+    });
+    it('keeps a returned coherency refusal classified as validation', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            outcome: 'refused',
+            refusal: { code: 'COHERENCY_REFUSED', reason: 'This entry is not linked to the strategic spine.' },
+        });
+        const err = await runUpdate({ entryId: 'WP-UNLINKED', field: ['description=no'] }).catch((e) => e);
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.VALIDATION_FAILED);
+        expect(err.category).toBe('validation');
+        expect(err.guidance).toContain('strategic spine');
+    });
+    // ── Slice 3: post-update refresh ─────────────────────────────────────────
+    it('calls chain.getEntry after successful update and includes entry in output', async () => {
+        kernelCallMock.mockResolvedValue({
+            entryId: 'BET-151',
+            name: 'My Bet',
+            status: 'active',
+        });
+        // PR B: the receipt now reflects the SERVER's applied set, not the raw --field list — the
+        // default beforeEach mock's empty `accepted` (a realistic "nothing accepted" shape) would no
+        // longer produce a receipt here at all, so this happy-path fixture must say the server
+        // actually kept `description`, matching what the test claims to simulate.
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: [], accepted: ['description'] },
+            normalizationWarnings: [],
+            validationWarnings: [],
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'BET-151', field: ['description=new'] });
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        expect(kernelCallMock).toHaveBeenCalledWith('chain.getEntry', { entryId: 'BET-151' });
+        // Pretty output: receipt then entry block
+        expect(output).toContain('Updated BET-151');
+        expect(output).toContain('description');
+        expect(output).toContain('My Bet');
+    });
+    it('still shows update receipt when post-update getEntry fails (graceful degradation)', async () => {
+        kernelCallMock.mockRejectedValue(new Error('network error'));
+        // PR B: same fixture correction as above — the receipt is built from the server's applied
+        // set, so this "successful update, degraded refresh" scenario needs a realistic accepted list.
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: [], accepted: ['description'] },
+            normalizationWarnings: [],
+            validationWarnings: [],
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'BET-151', field: ['description=new'] });
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        // Update receipt still shown
+        expect(output).toContain('Updated BET-151');
+        // No crash — process still completes without error
     });
     // ── BET-192 / FEAT-575: Normalization warning tests ──────────────────────
-    it('displays normalization warnings when fields are rejected (BET-192)', async () => {
-        mcpCallWithSessionMock.mockResolvedValue({
+    // PR B (WP-757): every field this call named was rejected — normalization.accepted is
+    // correctly EMPTY here (the caller only ever asked for `foo`, and the server dropped it;
+    // `description` was never part of this call's own request, so a realistic server response
+    // never lists it as accepted). The receipt must print NOTHING — no false "Updated" line —
+    // only the rejection error.
+    it('every named field rejected: no "Updated" receipt at all, error only (BET-192, BET-271)', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
             id: 'j571abc123def456',
             warnings: ['Unknown field "foo" dropped. Available fields: description, doneWhen'],
-            normalization: { remapped: {}, rejected: ['foo'], accepted: ['description'] },
+            normalization: { remapped: {}, rejected: ['foo'], accepted: [] },
             normalizationWarnings: ['Unknown field "foo" dropped. Available fields: description, doneWhen'],
             validationWarnings: [],
         });
+        kernelCallMock.mockResolvedValue({ entryId: 'BET-192', name: 'Bet', status: 'active', collectionSlug: 'bets' });
         const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
-        await runUpdate({
+        const err = await runUpdate({
             entryId: 'BET-192',
             field: ['foo=bar'],
+        }).catch((e) => e);
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        // BET-271 S1: throws CLIError when fields rejected, with `pb fields` suggestion
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.message).toContain('Fields rejected');
+        expect(err.message).toContain('foo');
+        // TEN-4332: the hint names the entry's collection, so the command it gives works.
+        expect(err.guidance).toBe('Run `pb fields bets` to see valid fields.');
+        // PR B: the receipt line never printed — nothing was actually applied.
+        expect(output).not.toContain('Updated BET-192');
+        expect(output).not.toContain('View: pb get');
+    });
+    // TASK-603 (WP-802, TEN-4332): a partial strip — one field kept, one dropped. The write landed, so the
+    // command exits 0: the receipt names ONLY the applied field and carries the kernel's
+    // "Unknown fields dropped" warning with a `pb fields <collection>` hint. Before this it threw
+    // "Fields rejected" after the write, and agents retried an update that had already landed.
+    it('partial strip: a landed update exits 0, names only the applied field and the dropped one in a warning', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: ['Unknown field "foo" dropped. Available fields: description, doneWhen'],
+            normalization: { remapped: {}, rejected: ['foo'], accepted: ['description'] },
+            normalizationWarnings: ['Unknown fields dropped: foo. Expected: description (string), doneWhen (string).'],
+            validationWarnings: [],
+        });
+        kernelCallMock.mockResolvedValue({ entryId: 'BET-192', name: 'Bet', status: 'active', collectionSlug: 'bets' });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        const err = await runUpdate({
+            entryId: 'BET-192',
+            field: ['description=new value', 'foo=bar'],
+        }).catch((e) => e);
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        expect(err).toBeUndefined();
+        expect(output).not.toContain('Fields rejected');
+        expect(output).toContain('Unknown fields dropped: foo.');
+        expect(output).toContain('Run `pb fields bets` to see valid fields.');
+        // The receipt WAS printed (something applied) and names the applied field.
+        expect(output).toContain('Updated BET-192');
+        expect(output).toContain('description');
+        // The dropped field never appears in the "Updated: ..." summary line — only in the warning.
+        const summaryLine = output.split('\n').find((line) => line.startsWith('Updated BET-192'));
+        expect(summaryLine).toBeDefined();
+        expect(summaryLine).not.toContain('foo');
+    });
+    it('partial strip in JSON mode: exits 0 with droppedFields naming only the dropped field (TEN-4332)', async () => {
+        mockIsJsonMode.mockReturnValue(true);
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: ['foo'], accepted: ['description'] },
+            normalizationWarnings: ['Unknown fields dropped: foo. Expected: description (string).'],
+            validationWarnings: [],
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        const err = await runUpdate({ entryId: 'BET-192', field: ['description=new', 'foo=bar'] }).catch((e) => e);
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        mockIsJsonMode.mockReturnValue(false);
+        expect(err).toBeUndefined();
+        const parsed = JSON.parse(output.trim().split('\n').pop());
+        expect(parsed.droppedFields).toEqual(['foo']);
+        expect(parsed.fieldsRejected).toBe(true);
+    });
+    // PR B fix round (BLOCKING 1): a caller-supplied allowed system key (e.g. `source`) is a
+    // real applied change — it lands in kernel/entries/normalize.ts's `accepted`, not just
+    // `systemKeys`. Pre-fix, `pb update X --field source=manual` wrote the field but printed
+    // no receipt and exited 0 (silently), since accepted was empty for a call that only ever
+    // touched a system key.
+    it('a caller-supplied system key (source) is reported as applied, not silently dropped from the receipt', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: [], accepted: ['source'] },
+            normalizationWarnings: [],
+            validationWarnings: [],
         });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'BET-193', field: ['source=manual'] });
         const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
         writeSpy.mockRestore();
-        expect(output).toContain('Normalization warnings');
-        expect(output).toContain('foo');
+        expect(output).toContain('Updated BET-193');
+        expect(output).toContain('source');
+    });
+    // ── WP-475 E1 (FEAT-1346): coaching verdict in the update receipt ─────────
+    it('renders the coaching section when the write response carries a verdict (WP-475 E1)', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: [], accepted: ['description'] },
+            normalizationWarnings: [],
+            validationWarnings: [],
+            coaching: {
+                source: 'heuristic',
+                verdict: {
+                    entryId: 'DEC-77',
+                    canonicalKey: 'decision',
+                    tier: 'assertive',
+                    context: 'capture',
+                    passed: false,
+                    criteria: [
+                        { id: 'has_rationale', passed: true, weight: 3, hint: 'State why.', questionTemplate: 'Why this?' },
+                        { id: 'specificity', passed: false, weight: 2, hint: 'Be specific.', questionTemplate: 'What exactly?' },
+                    ],
+                    weakest: { criterion: 'specificity', hint: 'Be specific.', questionTemplate: 'What exactly?' },
+                    overridden: false,
+                },
+            },
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'DEC-77', field: ['rationale=better reason'] });
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        expect(output).toContain('Semantic quality: 1/2 criteria pass for decision (assertive tier)');
+        expect(output).toContain('[ ] specificity — Be specific.');
+        expect(output).toContain('Coaching hint: Be specific.');
+        expect(output).toContain('Consider: What exactly?');
+    });
+    it('renders no coaching section when the write response has none (backward compat)', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'BET-151', field: ['description=new'] });
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        expect(output).not.toContain('Semantic quality');
     });
     it('displays no warnings when all fields are valid (BET-192)', async () => {
-        mcpCallWithSessionMock.mockResolvedValue({
+        kernelCallWithSessionMock.mockResolvedValue({
             id: 'j571abc123def456',
             warnings: [],
             normalization: { remapped: {}, rejected: [], accepted: ['description'] },
@@ -144,5 +438,241 @@ describe('runUpdate', () => {
         expect(output).not.toContain('Normalization warnings');
         expect(output).not.toContain('Validation warnings');
     });
+    // #1026 round 3 (Codex, 2 P3 findings): the SHOULD-FIX 3 dedup filter this test used to pin
+    // drew a THIRD round of findings (comma-splitting the rewritten regex, and stale filter
+    // ordering) and is deleted outright, not patched again. Server normalizationWarnings now
+    // render verbatim and are not parsed (TEN-4332: a landed update exits 0, so the kernel's
+    // warning is the one statement of what was dropped).
+    it('renders every normalization warning verbatim, including one that repeats the rejected field', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: ['foo'], accepted: ['description'] },
+            normalizationWarnings: [
+                'Unknown fields dropped: foo. Expected: description (string), doneWhen (string).',
+                'Remapped "desc" to "description".',
+            ],
+            validationWarnings: [],
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        const err = await runUpdate({
+            entryId: 'BET-194',
+            field: ['description=new value', 'foo=bar'],
+        }).catch((e) => e);
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        // TEN-4332: something applied, so the landed write exits 0.
+        expect(err).toBeUndefined();
+        expect(output).toContain('Unknown fields dropped: foo. Expected: description (string), doneWhen (string).');
+        expect(output).toContain('Remapped "desc" to "description"');
+    });
+    // #1026 round 3 (Codex P2): a platform-owned data key (e.g. `seederId` on a schemaless
+    // collection) is accepted by normalization, then reverted by preservePlatformOwnedDataKeys —
+    // the CLI must not print "Updated ... seederId" when nothing was actually written, and must
+    // name the revert instead (mirrors the MCP surface's own consumption of the server field).
+    it('excludes a server-reverted data key from the printed receipt and renders it under Fields reverted', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: [], accepted: ['seederId', 'description'] },
+            normalizationWarnings: [],
+            validationWarnings: [],
+            revertedFields: ['seederId'],
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({
+            entryId: 'BET-194',
+            field: ['description=new value', 'seederId=forged'],
+        });
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        const summaryLine = output.split('\n').find((line) => line.startsWith('Updated'));
+        expect(summaryLine).not.toContain('seederId');
+        expect(summaryLine).toContain('description');
+        expect(output).toContain('⚠ Fields reverted (platform-owned or write-once): seederId');
+    });
+    // #1026 round 4 (Codex): a call whose ONLY named field was accepted then reverted, with no
+    // other arg applied, used to print nothing and exit 0 — a fully-failed write read as success.
+    it('all fields reverted, nothing else applied: fails with a "Fields reverted" line, not silent success', async () => {
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: [], accepted: ['seederId'] },
+            normalizationWarnings: [],
+            validationWarnings: [],
+            revertedFields: ['seederId'],
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        const err = await runUpdate({
+            entryId: 'BET-195',
+            field: ['seederId=forged'],
+        }).catch((e) => e);
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.VALIDATION_FAILED);
+        expect(err.message).toContain('Fields reverted');
+        expect(err.message).toContain('seederId');
+        expect(err.guidance).toBeTruthy();
+        // No false "Updated" line — nothing was actually written.
+        expect(output).not.toContain('Updated BET-195');
+    });
+    // #1026 round 4 (Codex): same all-reverted case in JSON mode — the receipt must carry
+    // ok:false rather than reading as a plain successful update.
+    it('all fields reverted in JSON mode: receipt carries ok:false and the call still fails', async () => {
+        mockIsJsonMode.mockReturnValueOnce(true);
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: [], accepted: ['seederId'] },
+            normalizationWarnings: [],
+            validationWarnings: [],
+            revertedFields: ['seederId'],
+        });
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        const err = await runUpdate({
+            entryId: 'BET-196',
+            field: ['seederId=forged'],
+        }).catch((e) => e);
+        const output = writeSpy.mock.calls.map(c => String(c[0])).join('');
+        writeSpy.mockRestore();
+        expect(err).toBeInstanceOf(CLIError);
+        expect(err.code).toBe(ErrorCode.VALIDATION_FAILED);
+        const parsed = JSON.parse(output.trim());
+        expect(parsed.ok).toBe(false);
+        expect(parsed.revertedFields).toEqual(['seederId']);
+    });
+});
+/**
+ * S5 of WP-634 (TASK-45) — `pb update --type <key>` threads a canonicalKey reclassification
+ * through the EXISTING `chain.updateEntry` door (convex/agentKnowledge/entries.ts:1462, arg
+ * `canonicalKey` at :1471). No new server validation: the typeMap check, BR-55, the cardinality
+ * guards and the post-commit immutability guard (convex/lib/guards.ts:190-200) all already run
+ * there, and their refusal text must reach the operator verbatim rather than being reworded or
+ * pre-empted by a client-side copy of the rule.
+ */
+describe('runUpdate --type (S5 of WP-634, TASK-45)', () => {
+    // Its OWN seeding, mirroring the `runUpdate` suite above (PR #622 review). This block is a
+    // SIBLING of that suite, so its beforeEach never ran here: the tests passed only in a
+    // whole-file run, riding whatever mock state the previous suite's last test left behind, and
+    // failed in isolation with "Cannot read properties of undefined (reading 'outcome')" — a test
+    // that depends on execution order is not a test.
+    beforeEach(() => {
+        vi.clearAllMocks();
+        mockSession = { sessionId: 'sess-test' };
+        kernelCallWithSessionMock.mockResolvedValue({
+            id: 'j571abc123def456',
+            warnings: [],
+            normalization: { remapped: {}, rejected: [], accepted: [] },
+            normalizationWarnings: [],
+            validationWarnings: [],
+        });
+        kernelCallMock.mockResolvedValue({
+            entryId: 'INS-900',
+            name: 'Test Entry',
+            status: 'draft',
+        });
+    });
+    it('relays --type as the canonicalKey arg on chain.updateEntry', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'INS-900', type: 'decision' });
+        writeSpy.mockRestore();
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
+            entryId: 'INS-900',
+            changedBy: 'agent:sess-test',
+            canonicalKey: 'decision',
+        });
+    });
+    it('counts as something to update on its own — --type alone is a valid write', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'INS-900', type: 'decision' })).resolves.toBeUndefined();
+        writeSpy.mockRestore();
+        // The point is that --type alone clears the "Nothing to update" arity check and actually
+        // reaches the write door — not a total call count, which includes other session traffic.
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', expect.objectContaining({
+            canonicalKey: 'decision',
+        }));
+    });
+    it('combines with other updates in one call', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'INS-900', type: 'decision', name: 'Renamed', note: 'Reclassified' });
+        writeSpy.mockRestore();
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
+            entryId: 'INS-900',
+            changedBy: 'agent:sess-test',
+            name: 'Renamed',
+            canonicalKey: 'decision',
+            changeNote: 'Reclassified',
+        });
+    });
+    it('trims the value — a padded --type must not reach the server as an unmatched key', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'INS-900', type: '  decision  ' });
+        writeSpy.mockRestore();
+        expect(kernelCallWithSessionMock).toHaveBeenCalledWith('chain.updateEntry', {
+            entryId: 'INS-900',
+            changedBy: 'agent:sess-test',
+            canonicalKey: 'decision',
+        });
+    });
+    /**
+     * PROVIDED-but-blank must fail loudly, never be treated as ABSENT (PR #622 review). The
+     * whitespace case is the dangerous one: paired with another flag it used to report a
+     * successful rename while silently discarding the reclassification.
+     */
+    it('refuses a whitespace-only --type instead of silently dropping it alongside another update', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'INS-900', name: 'Renamed', type: '   ' }))
+            .rejects.toThrow('--type was provided but empty.');
+        writeSpy.mockRestore();
+        expect(kernelCallWithSessionMock).not.toHaveBeenCalled(); // refused BEFORE any relay
+    });
+    it('refuses a whitespace-only --type on its own rather than reporting "Nothing to update"', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'INS-900', type: '   ' }))
+            .rejects.toThrow('--type was provided but empty.');
+        writeSpy.mockRestore();
+    });
+    it('refuses an empty-string --type', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'INS-900', type: '' }))
+            .rejects.toThrow('--type was provided but empty.');
+        writeSpy.mockRestore();
+    });
+    it('omits canonicalKey entirely when --type is not passed', async () => {
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await runUpdate({ entryId: 'INS-900', name: 'Just a rename' });
+        writeSpy.mockRestore();
+        const args = kernelCallWithSessionMock.mock.calls[0][1];
+        expect(args).not.toHaveProperty('canonicalKey');
+    });
+    /**
+     * The two guard texts are the deliverable, so they must arrive UNREWORDED. The CLI must not
+     * carry its own copy of "committed entries cannot be retyped" or of BR-55 — a client-side
+     * pre-check would drift from the server rule and is exactly what "no new server-side
+     * validation, existing guard text verbatim" rules out.
+     */
+    it('surfaces the post-commit immutability guard text verbatim', async () => {
+        const guardText = 'canonicalKey cannot be changed after an entry has been committed. '
+            + 'To reclassify, create a new entry and supersede this one.';
+        kernelCallWithSessionMock.mockRejectedValueOnce(makeMcpError(guardText, 'VALIDATION_FAILED'));
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'DEC-1', type: 'insight' })).rejects.toThrow(guardText);
+        writeSpy.mockRestore();
+    });
+    it('surfaces the BR-55 out-of-collection refusal verbatim', async () => {
+        const br55 = 'Vision and purpose entries must be in the strategy collection. This entry is in "insights".';
+        kernelCallWithSessionMock.mockRejectedValueOnce(makeMcpError(br55, 'VALIDATION_FAILED'));
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'INS-900', type: 'vision' })).rejects.toThrow(br55);
+        writeSpy.mockRestore();
+    });
+    it('surfaces the invalid-type refusal verbatim', async () => {
+        const invalid = 'Invalid canonical key "nonsense". Must be one of the 42 canonical types or null/undefined.';
+        kernelCallWithSessionMock.mockRejectedValueOnce(makeMcpError(invalid, 'VALIDATION_FAILED'));
+        const writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+        await expect(runUpdate({ entryId: 'INS-900', type: 'nonsense' })).rejects.toThrow(invalid);
+        writeSpy.mockRestore();
+    });
 });
 //# sourceMappingURL=update.test.js.map