@productbrain/cli 0.1.0-beta.77 → 0.1.0-beta.7700

package/dist/commands/capture.js

@@ -3,214 +3,72 @@
  * Calls resolveCollection (classification) → createEntry (draft).
  * Shows rich receipt per FEAT-126 (capture receipts with correction affordance).
  * Requires active session (DEC-9, BR-8).
- * BET-181 Slice 0: uses isJsonMode() for output branching. Existing --json flag
- * is preserved for backward compatibility (it sets output mode via the runner).
- * WP-319 S3: Pre-write grounding via chain.suggestLinksForCapture (advisory, fail-open).
+ * BET-181 Slice 0: uses isJsonMode() for output branching. Existing --json flag is preserved for backward compatibility (it sets output mode via the runner).
+ * WP-319 S3 / WP-755 C1a (TASK-215, DEC-1717): Pre-write grounding via chain.capture, the
+ * one capture door (advisory, fail-open) — replaces the deleted chain.suggestLinksForCapture.
  */
 import { getConfigOrGuide } from '../lib/config.js';
 import { kernelCallWithSession } from '../lib/client.js';
+import { inferSourceDate } from '../lib/inferSourceDate.js';
+import { getPrefixToCollection, getDatedCollections, getCanonicalKeyToCollection } from '../lib/collectionRegistry.js';
 import { readSession, addCapturedEntry } from '../lib/session.js';
-import { isJsonMode } from '../lib/runner.js';
+import { isJsonMode, setOutputMode } from '../lib/runner.js';
 import { formatCaptureReceipt } from '../formatters/capture.js';
 import { checkActivation } from '../lib/activation.js';
 import { progress } from '../lib/style.js';
 import { CLIError, ErrorCode } from '../lib/errors.js';
-/**
- * Infer an ISO date (YYYY-MM-DD) from free-text values.
- *
- * NOTE: This function is duplicated in packages/mcp-server/src/tools/smart-capture.ts.
- * The two packages build in isolation (TEN-174, BR-25) so they cannot share source.
- * If you change the logic here, update the MCP server copy too.
- */
-function inferSourceDate(...values) {
-    const combined = values
-        .filter((value) => typeof value === 'string' && value.trim().length > 0)
-        .join('\n');
-    if (!combined)
-        return undefined;
-    const isoMatch = combined.match(/\b(20\d{2}-\d{2}-\d{2})\b/);
-    if (isoMatch)
-        return isoMatch[1];
-    const monthMatch = combined.match(/\b(january|february|march|april|may|june|july|august|september|october|november|december)\s+(\d{1,2})(?:st|nd|rd|th)?(?:,?\s+(20\d{2}))?\b/i);
-    if (!monthMatch)
-        return undefined;
-    const monthIndex = [
-        'january',
-        'february',
-        'march',
-        'april',
-        'may',
-        'june',
-        'july',
-        'august',
-        'september',
-        'october',
-        'november',
-        'december',
-    ].indexOf(monthMatch[1].toLowerCase());
-    if (monthIndex < 0)
-        return undefined;
-    const inferredYear = monthMatch[3] ?? combined.match(/\b(20\d{2})\b/)?.[1] ?? String(new Date().getUTCFullYear());
-    return `${inferredYear}-${String(monthIndex + 1).padStart(2, '0')}-${monthMatch[2].padStart(2, '0')}`;
-}
-/**
- * Known entry ID prefix → collection slug mapping.
- * Mirrors idPrefix values from SEED_CLASSIFICATION_REGISTRY (convex/lib/seedClassificationRegistry.ts).
- * CLI can't import from Convex (separate build, BR-25), so this is a local copy.
- * If a new collection is added, update both places.
- */
-const PREFIX_TO_COLLECTION = {
-    PRI: 'principles', STD: 'standards', BR: 'business-rules', POL: 'policies',
-    PAT: 'patterns', GLO: 'glossary', FEAT: 'features', ARCH: 'architecture',
-    DEC: 'decisions', STR: 'strategy', ST: 'semantic-types', MAP: 'maps',
-    TEN: 'tensions', TEAM: 'teams', ROL: 'roles', ASM: 'assumptions',
-    LAND: 'landscape', INS: 'insights', TASK: 'tasks', MIL: 'milestones',
-    WS: 'workstreams', INI: 'initiatives', WP: 'work-packages', BET: 'work-packages',
-    AUD: 'audiences', KEY: 'key-results', QUE: 'questions', PROD: 'products',
-    OPP: 'opportunities', EXP: 'experiments', FLO: 'flows',
-};
-/**
- * Extract a known ID prefix hint from capture text.
- * Pattern: "FLO: description" or "TEN: something broken" — prefix must be uppercase,
- * followed by colon and optional whitespace, then the actual text.
- * Returns the resolved collection slug and the cleaned text (prefix stripped).
- */
-function extractPrefixHint(text) {
-    const match = text.match(/^([A-Z]{2,4}):\s*(.+)$/s);
-    if (!match)
-        return { resolvedCollection: null, cleanText: text };
-    const [, prefix, rest] = match;
-    const slug = PREFIX_TO_COLLECTION[prefix];
-    if (!slug)
-        return { resolvedCollection: null, cleanText: text };
-    return { resolvedCollection: slug, cleanText: rest.trim() };
-}
-// WP-319 S3: Grounding helpers — advisory output, stderr only.
-/** Print advisory grounding banner to stderr. Suppressed when grounding has no matches. */
-function printGroundingBanner(grounding) {
-    const possibleDuplicates = grounding.duplicates.filter((d) => d.matchType === 'possible_duplicate');
-    const related = [
-        ...grounding.related,
-        ...grounding.duplicates.filter((d) => d.matchType === 'related'),
-    ];
-    const governance = grounding.governance ?? [];
-    const hasGovernance = governance.length > 0;
-    if (possibleDuplicates.length === 0 && related.length === 0 && !hasGovernance) {
-        return; // Zero-noise floor: nothing to show
-    }
-    const lines = ['\n  Grounding:'];
-    if (possibleDuplicates.length > 0) {
-        const label = possibleDuplicates.length === 1 ? 'Possible duplicate' : 'Possible duplicates';
-        const items = possibleDuplicates.map((d) => `${d.entryId} "${d.name}"`).join(', ');
-        lines.push(`  ⚠ ${label}: ${items}`);
-    }
-    if (related.length > 0) {
-        const items = related
-            .slice(0, 3)
-            .map((r) => `${r.entryId} "${r.name}"`)
-            .join(', ');
-        lines.push(`  ~ Related: ${items}`);
-    }
-    for (const gov of governance) {
-        const icon = gov.severity === 'block' ? '✗' : gov.severity === 'warn' ? '⚠' : 'ℹ';
-        lines.push(`  ${icon} Governance [${gov.severity}]: ${gov.entryId} "${gov.name}"`);
-    }
-    lines.push('');
-    process.stderr.write(lines.join('\n') + '\n');
-}
-/** Print dry-run grounding preview to stdout (--suggest-only). */
-function printGroundingPreview(grounding, entryName, collectionSlug) {
-    process.stdout.write(`\n  Grounding preview for: ${entryName.slice(0, 80)}\n`);
-    process.stdout.write(`  Collection: ${collectionSlug}\n\n`);
-    if (!grounding) {
-        process.stdout.write('  No grounding data available (timeout or unavailable).\n\n');
-        return;
-    }
-    const possibleDuplicates = grounding.duplicates.filter((d) => d.matchType === 'possible_duplicate');
-    const related = [
-        ...grounding.related,
-        ...grounding.duplicates.filter((d) => d.matchType === 'related'),
-    ];
-    const govCandidates = grounding.governance ?? [];
-    if (possibleDuplicates.length === 0 && related.length === 0 && govCandidates.length === 0) {
-        process.stdout.write('  No matches found — capture looks unique.\n\n');
-        return;
-    }
-    if (possibleDuplicates.length > 0) {
-        process.stdout.write('  Possible duplicates:\n');
-        for (const d of possibleDuplicates) {
-            process.stdout.write(`    · ${d.entryId} "${d.name}" (overlap: ${Math.round(d.overlapRatio * 100)}%)\n`);
-        }
-        process.stdout.write('\n');
-    }
-    if (related.length > 0) {
-        process.stdout.write('  Related entries:\n');
-        for (const r of related.slice(0, 5)) {
-            const relType = 'recommendedRelationType' in r ? r.recommendedRelationType : 'related';
-            process.stdout.write(`    · ${r.entryId} "${r.name}" → ${relType}\n`);
-        }
-        process.stdout.write('\n');
-    }
-    if (govCandidates.length > 0) {
-        process.stdout.write('  Governance:\n');
-        for (const g of govCandidates) {
-            process.stdout.write(`    · [${g.severity}] ${g.entryId} "${g.name}"\n`);
-        }
-        process.stdout.write('\n');
-    }
-    process.stdout.write('  Run without --suggest-only to create the entry.\n\n');
-}
-/** Prompt the user with a y/N question. Resolves true for "y", false otherwise. */
-async function promptYN(message) {
-    return new Promise((resolve) => {
-        process.stderr.write(message);
-        process.stdin.once('data', (data) => {
-            const answer = data.toString().trim().toLowerCase();
-            resolve(answer === 'y');
-        });
-    });
-}
+import { parseFields } from '../lib/parseFields.js';
+import { emitEffectiveTenantNotice } from '../lib/workspaceNotice.js';
+import { isPreviewCreateEntryResult } from '../lib/createEntryResult.js';
+import { extractPrefixHint, printGroundingBanner, printGroundingPreview, promptYN, highestVerdictScore } from '../lib/captureGrounding.js';
+import { runVersionCapture } from '../lib/captureVersion.js';
+import { applyCaptureLink } from '../lib/captureLink.js';
 export async function runCapture(options) {
     const config = await getConfigOrGuide(() => runCapture(options));
     if (!config)
         return;
-    // Support both legacy --json flag and global output mode (DEC-299, backward compat)
+    // Support both legacy --json flag and global output mode (DEC-299, backward compat).
+    // Propagate the local flag to global mode too — a thrown CLIError below renders via the
+    // global handler's isJsonMode(), which wouldn't otherwise see this local-only flag.
     const json = isJsonMode() || options.json === true;
+    if (options.json === true && !isJsonMode())
+        setOutputMode('json');
     // Require active session (DEC-9, BR-8)
     const session = readSession();
     if (!session) {
         throw new CLIError('No active session.', {
             code: ErrorCode.SESSION_REQUIRED,
             category: 'session',
-            guidance: 'Run `pb session start` first. Write access requires a tracked session (DEC-9).',
+            // DEC-9
+            guidance: 'Run `pb session start` first. Write access requires a tracked session.',
         });
     }
-    // BET-277 fix: Extract known ID prefix hints (e.g. "FLO: description" → collection=flows).
-    // When the user explicitly prefixes with a known entry ID prefix, treat it as a collection
-    // override — strip the prefix from the name and route directly. No classification needed.
-    const { resolvedCollection: prefixCollection, cleanText } = extractPrefixHint(options.text);
+    // BET-277 fix: Extract known ID prefix hints (e.g. "FLO: description" → collection=flows). When the user explicitly prefixes with a known entry ID prefix, treat it as a collection override — strip the prefix from the name and route directly. No classification needed. FEAT-885: prefix map derived from collectionRegistry (runtime DB query, fail-open to SEED).
+    const prefixMap = await getPrefixToCollection();
+    const { resolvedCollection: prefixCollection, cleanText } = extractPrefixHint(options.text, prefixMap);
     const entryName = options.name ?? cleanText;
     const entryDescription = options.description ?? cleanText;
-    // WP-319 S3: Phase 1.5 — Pre-write grounding (advisory, fail-open).
-    // Start the grounding call IN PARALLEL with collection resolution so it
-    // does not add serial latency.
-    // Normal capture: 300ms post-classification cap (classification latency = free parallel time).
-    // --suggest-only: 2000ms absolute cap from grounding start (user explicitly waiting for data).
+    // WP-319 S3 / WP-755 C1a: Phase 1.5 — Pre-write grounding via the one capture door
+    // (advisory, fail-open, started IN PARALLEL with collection resolution). Normal capture:
+    // 300ms post-classification cap. --suggest-only: 2000ms absolute cap from grounding start.
     const GROUNDING_TIMEOUT_MS = 300;
     const GROUNDING_SUGGEST_ONLY_TOTAL_MS = 2000;
     const groundingStart = Date.now();
     const skipGrounding = process.env.PB_GROUNDING_MODE === 'off';
     let groundingResult = null;
     const groundingPromise = (!skipGrounding && (entryName || entryDescription))
-        ? kernelCallWithSession('chain.suggestLinksForCapture', {
-            entries: [{ name: entryName, description: entryDescription, collectionHint: options.collection ?? '' }],
-            limit: 5,
-            threshold: 2,
-        }).then((res) => (Array.isArray(res) ? res[0] ?? null : null)).catch(() => null)
+        ? kernelCallWithSession('chain.capture', {
+            name: entryName,
+            description: entryDescription,
+            collectionSlug: options.collection,
+        }).then((res) => res ?? null).catch(() => null)
         : Promise.resolve(null);
-    // Phase 1: Resolve collection (classification)
+    // Phase 1: Resolve collection (classification). Review bclZ9: normalized the same way resolveCreateEntryCanonicalKey does server-side.
+    const normalizedEntryType = options.entryType?.toLowerCase().trim();
     let collectionSlug;
     let classification = null;
+    // Ruling #13: fast-path derives from the SAME 1:1 registry the server enforces, not a hand-picked pair of literal branches.
+    const derivedEntryTypeSlug = normalizedEntryType ? (await getCanonicalKeyToCollection())[normalizedEntryType] : undefined;
     if (options.collection) {
         // Explicit collection — skip classification
         collectionSlug = options.collection;
@@ -219,6 +77,10 @@ export async function runCapture(options) {
         // Prefix hint detected (e.g. "FLO:" → flows) — treat as explicit collection
         collectionSlug = prefixCollection;
     }
+    else if (derivedEntryTypeSlug) {
+        // Review bcI42/bclZ9/PR #713 cQP_I: --entry-type bypasses classification (normalized like the server) — derive the slug from the live registry, never hard-code it.
+        collectionSlug = derivedEntryTypeSlug;
+    }
     else {
         if (!json)
             progress('Classifying...');
@@ -243,10 +105,7 @@ export async function runCapture(options) {
     const groundingTimeoutMs = options.suggestOnly
         ? Math.max(0, GROUNDING_SUGGEST_ONLY_TOTAL_MS - groundingElapsed)
         : GROUNDING_TIMEOUT_MS;
-    groundingResult = await Promise.race([
-        groundingPromise,
-        new Promise((resolve) => setTimeout(() => resolve(null), groundingTimeoutMs)),
-    ]);
+    groundingResult = await Promise.race([groundingPromise, new Promise((resolve) => setTimeout(() => resolve(null), groundingTimeoutMs))]);
     // WP-319 S3: --suggest-only dry-run — show advisory preview and exit without creating entry.
     if (options.suggestOnly) {
         if (!json) {
@@ -262,60 +121,162 @@ export async function runCapture(options) {
     if (!json && groundingResult) {
         printGroundingBanner(groundingResult);
     }
-    // WP-319 S3: --strict prompt — y/N confirmation when possible_duplicate found.
-    // Non-TTY skips prompt and auto-proceeds (fail-open on non-interactive).
-    if (options.strict && !json && groundingResult?.duplicates.some((d) => d.matchType === 'possible_duplicate')) {
+    // WP-319 S3 (narrowed C2/TASK-216): --strict now prompts only on "ask" — genuine ambiguity. "version" is silent, no --strict gate (DEC-1717). Non-TTY skips.
+    if (options.strict && !json && groundingResult?.kind === 'ask') {
         const isTTY = process.stdin.isTTY;
         if (isTTY) {
-            const answer = await promptYN('  Possible duplicate found. Proceed with capture? [y/N] ');
+            const answer = await promptYN('  Possible match found. Proceed with capture? [y/N] ');
             if (!answer) {
                 process.stderr.write('  Capture cancelled.\n');
                 return;
             }
         }
     }
-    // Phase 2: Create entry as draft
-    if (!json)
-        progress(`Capturing to ${collectionSlug}...`);
-    const data = { description: entryDescription };
-    // Only set date when we can infer a source date from the capture itself.
-    const datedCollections = ['tensions', 'decisions', 'insights', 'standards', 'business-rules'];
-    const inferredSourceDate = inferSourceDate(entryName, entryDescription, options.sourceRef, options.sourceExcerpt);
-    if (datedCollections.includes(collectionSlug) && inferredSourceDate) {
-        data.date = inferredSourceDate;
+    // WP-1: name the target workspace before the write so a wrong-Chain capture is never silent. After the --suggest-only/--strict abort paths; the TEN-2311 WHY check below can still throw without writing, so the user sees the target line then the validation error. stderr-only (WP-721).
+    await emitEffectiveTenantNotice();
+    // WP-755 C2 (TASK-216, DEC-1717): the version branch sits WHERE the create call sits — same
+    // option parsing, same --link/--source-ref/--field the create would have sent — and replaces
+    // createEntry with updateEntry via captureVersion.ts. Narrowed once so every branch below
+    // (link handling, output) shares one entryId/entryStatus/... set regardless of path.
+    const versionVerdict = groundingResult?.kind === 'version' ? groundingResult : null;
+    let entryId;
+    let receiptName = entryName;
+    let entryStatus;
+    let warnings = [];
+    let normalization;
+    let qualityHints = [];
+    let spineFloor;
+    let relationSuggestions;
+    let coaching;
+    if (versionVerdict) {
+        if (!json)
+            progress(`Saving as a new version of ${versionVerdict.entryId}...`);
+        const versionResult = await runVersionCapture({
+            groundingResult: versionVerdict,
+            // Only an EXPLICIT --name is a real title (kernel/capture/versionWrite.ts's own contract:
+            // a placeholder must never rename the target). entryName's cleanText fallback is the
+            // capture's prose body, never a title — forwarding it here renamed the target on every
+            // version write with no --name given.
+            name: options.name,
+            prose: entryDescription,
+            fields: options.field?.length ? parseFields(options.field) : undefined,
+            sourceRef: options.sourceRef,
+            sourceExcerpt: options.sourceExcerpt,
+            sessionId: session.sessionId,
+            skipGrounding,
+            groundingStart,
+            groundingElapsed,
+        });
+        entryId = versionResult.entryId;
+        receiptName = versionResult.name;
+        warnings = versionResult.warnings;
+        normalization = versionResult.normalization;
+        // No entryStatus: chain.updateEntry's return carries no status field, and the target's real
+        // status (which a version write never changes) can be draft or accepted — never guess.
+    }
+    else {
+        // Phase 2: Create entry as draft
+        if (!json)
+            progress(`Capturing to ${collectionSlug}...`);
+        const data = { description: entryDescription };
+        // Only set date when we can infer a source date from the capture itself.
+        const datedCollections = await getDatedCollections();
+        const inferredSourceDate = inferSourceDate(entryName, entryDescription, options.sourceRef, options.sourceExcerpt);
+        if (datedCollections.has(collectionSlug) && inferredSourceDate) {
+            data.date = inferredSourceDate;
+        }
+        if (options.field?.length) {
+            Object.assign(data, parseFields(options.field));
+        }
+        // TEN-2311: live, fail-open WHY guidance — the server remains the arbiter, this only prevents a doomed governed capture when the required field is absent. The contract fetch is the ONLY fail-open surface (network or server 4xx/5xx, an McpError/CLIError, is swallowed so chain.createEntry's server gate arbitrates); the deliberate guidance throw lives OUTSIDE the try so it is never misclassified as a swallowed transport failure.
+        let contract = null;
+        try {
+            contract = await kernelCallWithSession('chain.getCollectionFields', { slug: collectionSlug });
+        }
+        catch {
+            contract = null; // fail open — let the server gate arbitrate
+        }
+        // WP-770 W2a (DEC-1787 ruling A): gated on `whyField` alone, not `governed` — the server's
+        // WHY hard-gate now also fires for the six why-required collections (purpose/vision/
+        // strategy/objective/decision/rule), not only the two `governed` (steering-shared) subjects.
+        // `getCollectionFields` already widens `whyField` the same way, so this stays a pure mirror.
+        if (contract?.whyField) {
+            const isNonEmpty = (v) => typeof v === 'string' && v.trim().length > 0;
+            // TEN-1258: the server remaps data.description → the collection's primary field before the
+            // WHY gate (createEntryPreparation.remapDescriptionField), so a bare `pb capture "DEC: …"`
+            // satisfies the WHY when that primary field IS the why field (e.g. decisions→rationale).
+            // Mirror that here so the pre-flight does not false-block captures the server would accept.
+            const remapSatisfiesWhy = contract.descriptionFieldKey === contract.whyField && isNonEmpty(data.description);
+            const present = isNonEmpty(data[contract.whyField]) || remapSatisfiesWhy;
+            if (!present) {
+                throw new CLIError(`"${collectionSlug}" needs a WHY in "${contract.whyField}".`, {
+                    code: ErrorCode.VALIDATION_FAILED,
+                    category: 'validation',
+                    guidance: `Add it: --field ${contract.whyField}="<at least ${contract.minChars} characters of why>"`,
+                });
+            }
+        }
+        // WP-475 E1 (deterministic --link fix): when this capture will create a relation, the post-relation re-eval below owns the single LLM run — defer the LLM schedule at create time (relation-blind, race-prone otherwise); plain captures omit the flag. WP-688 S4: requires BOTH --link AND --link-type — a --link with no --link-type is refused (element 11) and never reaches the re-eval branch, so deferring there would strand llmStatus:'skipped' forever.
+        const willRelate = Boolean(options.link?.trim() && options.linkType);
+        const rawResult = await kernelCallWithSession('chain.createEntry', {
+            collectionSlug,
+            name: entryName,
+            // DEC-896 / BR-76: omit status — server resolves from governanceMode (Open→active, else draft).
+            // WP-456 E1 / TEN-2226: `--draft` opt-in forces 'draft' regardless of governanceMode.
+            // Omit entirely when absent so the default-path wire payload is byte-identical to today.
+            ...(options.draft ? { forceDraft: true } : {}),
+            data,
+            sessionId: session.sessionId,
+            createdBy: `agent:${session.sessionId}`,
+            // BET-240 E2: source provenance — pass through when provided
+            ...(options.sourceRef ? { sourceRef: options.sourceRef } : {}),
+            ...(options.sourceExcerpt ? { sourceExcerpt: options.sourceExcerpt } : {}),
+            ...(willRelate ? { deferLLMSchedule: true } : {}),
+            ...(options.ownerRole ? { ownerRoleEntryId: options.ownerRole } : {}), // WP-513 rung-2 override; WP-753 O1b: team derives server-side.
+            ...(options.entryType ? { canonicalKey: options.entryType } : {}), // WP-684 TASK-77 (E1.3): one-step typed create.
+        });
+        // WP-577 / TEN-2918 fallout: `pb capture` never sends `preview: true` above, so this
+        // never fires at runtime — but the declared return type is now honestly a union, so
+        // fail loudly rather than silently reading undefined preview-shaped fields below.
+        if (isPreviewCreateEntryResult(rawResult)) {
+            throw new CLIError('Unexpected preview response from chain.createEntry — pb capture never requests preview mode.', { code: ErrorCode.INTERNAL, category: 'internal' });
+        }
+        const result = rawResult;
+        entryId = result.entryId;
+        entryStatus = result.status;
+        warnings = result.warnings;
+        normalization = result.normalization;
+        qualityHints = result.qualityHints ?? [];
+        spineFloor = result.spineFloor;
+        relationSuggestions = result.relationSuggestions;
+        coaching = result.coaching;
     }
-    const result = await kernelCallWithSession('chain.createEntry', {
-        collectionSlug,
-        name: entryName,
-        status: 'draft',
-        data,
-        sessionId: session.sessionId,
-        createdBy: `agent:${session.sessionId}`,
-        // BET-240 E2: source provenance — pass through when provided
-        ...(options.sourceRef ? { sourceRef: options.sourceRef } : {}),
-        ...(options.sourceExcerpt ? { sourceExcerpt: options.sourceExcerpt } : {}),
-    });
-    // Track in session state
-    addCapturedEntry(result.entryId);
-    // WP-319 S3: Record grounding outcome for observability (STD-155, done-when 5).
-    // Fire-and-forget — never block capture on observability failure.
-    if (!skipGrounding && groundingStart > 0) {
+    // Track in session state — a version write is still a capture this session touched.
+    addCapturedEntry(entryId);
+    // WP-319 S3 / WP-755 C1a: Record grounding outcome for observability (STD-155, done-when 5).
+    // Fire-and-forget — never block capture (TEN-2924: no retry, its timer would hold the loop).
+    // hadGovernance is always false post-C1a: the old suggestLinksForCapture route's per-candidate
+    // governed-collection severity (block/warn/inform) has no equivalent in the new door — a cited
+    // narrowing (see captureGrounding.ts's header), not a silent drop. Version already fired its
+    // own call (inside runVersionCapture) — never double-record.
+    if (!versionVerdict && !skipGrounding && groundingStart > 0) {
         void kernelCallWithSession('chain.recordGroundingOutcome', {
             surface: 'cli',
-            promptShown: (groundingResult?.governance?.length ?? 0) > 0,
-            highestRatio: Math.max(...(groundingResult?.duplicates?.map((d) => d.overlapRatio) ?? []), ...(groundingResult?.related?.map((r) => r.overlapRatio) ?? []), 0),
-            hadGovernance: (groundingResult?.governance?.length ?? 0) > 0,
+            promptShown: groundingResult?.kind === 'ask',
+            highestRatio: highestVerdictScore(groundingResult),
+            hadGovernance: false,
             grounding_ms: groundingElapsed,
-        }).catch(() => undefined);
+        }, { retryOnRateLimit: false }).catch(() => undefined);
     }
-    // WP-301 S4: Activation ceremony — show contextual retrieval after first capture
-    if (!json) {
+    // WP-301 S4: Activation ceremony — show contextual retrieval after first capture. Create only:
+    // a version write edits an already-accepted entry, never a "first capture".
+    if (!json && !versionVerdict) {
         try {
-            const activation = await checkActivation(result.entryId);
+            const activation = await checkActivation(entryId);
             if (activation?.isFirst && activation.relatedEntries.length > 0) {
                 process.stdout.write('\n  Your first capture is on the Chain. Here\'s how it connects:\n');
                 for (const rel of activation.relatedEntries.slice(0, 3)) {
-                    process.stdout.write(`    \u2192 ${rel.entryId}: ${rel.name} (${rel.relation})\n`);
+                    process.stdout.write(`    → ${rel.entryId}: ${rel.name} (${rel.relation})\n`);
                 }
                 process.stdout.write('\n');
             }
@@ -327,59 +288,98 @@ export async function runCapture(options) {
             // Activation is additive — never blocks capture
         }
     }
-    // BET-272 S3: Advisory quality hints — from createEntryWithClassification result (BR-144)
-    const qualityHints = result.qualityHints ?? [];
-    // Phase 3: Link to existing entry if --link provided (TEN-705)
-    if (options.link) {
-        const linkTarget = options.link.trim();
-        const relationType = options.type ?? 'surfaces_tension_in';
-        if (linkTarget) {
-            await kernelCallWithSession('chain.createEntryRelation', {
-                fromEntryId: result.entryId,
-                toEntryId: linkTarget,
-                type: relationType,
-            });
-        }
-    }
+    // Phase 3: Link to existing entry if --link provided (TEN-705) — applies to a version write
+    // the same as a create; entryId names whichever entry this run actually wrote (the created
+    // draft, or the version's target). Extracted to captureLink.ts (500-LOC budget, STD-2/DEC-1504).
+    const linkResult = await applyCaptureLink({ entryId, link: options.link, linkType: options.linkType, coaching });
+    const actualLinkedTo = linkResult.actualLinkedTo;
+    const actualRelationType = linkResult.actualRelationType;
+    const linkTypeRefusal = linkResult.linkTypeRefusal;
+    coaching = linkResult.coaching;
     // BET-271 S1: Determine if any fields were rejected by normalization.
-    const rejectedFields = result.normalization?.rejected ?? [];
+    const rejectedFields = normalization?.rejected ?? [];
     const hasRejected = rejectedFields.length > 0;
     // Output
     if (json) {
-        // Machine-readable output (TEN-709, DEC-299)
-        const output = {
-            id: result.entryId,
-            collection: collectionSlug,
-            confidence: classification?.tier ?? 'explicit',
-        };
+        // Machine-readable output (TEN-709, DEC-299). Version's shape is intentionally smaller
+        // (no classification/confidence — the target's collection was never classified this run).
+        const output = versionVerdict
+            ? { id: entryId, collection: versionVerdict.collectionSlug, kind: 'version' }
+            : { id: entryId, collection: collectionSlug, status: entryStatus, confidence: classification?.tier ?? 'explicit' };
         if (hasRejected) {
             output.fieldsRejected = true;
         }
+        // WP-475 E1: raw heuristic coaching verdict in machine output (BR-144: advisory).
+        // Post-relation re-eval (when --link ran) takes precedence over the create-response verdict.
+        if (coaching) {
+            output.coaching = coaching;
+        }
+        // WP-688 S4 (element 11): echo the verb ACTUALLY WRITTEN — absent when no relation was
+        // written (refused or --link never supplied), never guessed, never defaulted.
+        if (actualRelationType) {
+            output.relationType = actualRelationType;
+        }
+        if (spineFloor)
+            output.spineFloor = spineFloor;
         process.stdout.write(JSON.stringify(output) + '\n');
     }
+    else if (versionVerdict) {
+        // WP-755 C2: a distinct, concise receipt — entry id + name from the verdict, never the
+        // create-shaped formatCaptureReceipt (classification/confidence don't apply to an edit of
+        // an already-accepted entry). stdout carries the raw entry id (scripting contract, mirrors
+        // `pb capture ... | xargs pb get`).
+        process.stderr.write(`  Saved as a new version of ${entryId} "${receiptName}".\n`);
+        if (warnings.length > 0)
+            process.stderr.write(`  Warnings: ${warnings.join('; ')}\n`);
+        if (actualLinkedTo)
+            process.stderr.write(`  Linked to ${actualLinkedTo} (${actualRelationType}).\n`);
+        process.stdout.write(`${entryId}\n`);
+    }
     else {
         process.stdout.write('\n');
         process.stdout.write(formatCaptureReceipt({
-            entryId: result.entryId,
+            entryId,
             name: entryName,
             collection: collectionSlug,
-            status: 'draft',
+            status: entryStatus, // always set in the create branch above (result.status) — only the version branch leaves it undefined, and that branch never reaches here.
             classification,
-            warnings: result.warnings,
-            normalization: result.normalization,
-            linkedTo: options.link,
-            relationType: options.link ? (options.type ?? 'surfaces_tension_in') : undefined,
+            warnings,
+            normalization: normalization ?? undefined,
+            linkedTo: actualLinkedTo,
+            relationType: actualRelationType,
             qualityHints,
-            relationSuggestions: result.relationSuggestions,
+            relationSuggestions,
+            coaching,
+            spineFloor,
         }) + '\n');
     }
-    // BET-271 S1: Throw when fields were rejected — signals "not everything you asked for happened."
+    // BET-271 S1: fields rejected + link refused can both be true — aggregate, don't drop one.
+    // WP-745 round 3 (PRRT_kwDORS4ils6h0e82): preserve linkTypeRefusal's OWN code/category (a
+    // NETWORK_TIMEOUT/rate-limit/auth failure preserved earlier in this file) rather than always
+    // relabeling the combined error VALIDATION_FAILED, which discarded that signal exactly when
+    // both partial failures land together.
+    // A version write's fields were validated against the TARGET's own collection, never the
+    // capture's classified one (they can differ — decide() matches across every collection).
+    const fieldsGuidanceCollection = versionVerdict ? versionVerdict.collectionSlug : collectionSlug;
+    if (hasRejected && linkTypeRefusal) {
+        throw new CLIError(`Fields rejected: ${rejectedFields.join(', ')}. ${linkTypeRefusal.message}`, {
+            code: linkTypeRefusal.code,
+            category: linkTypeRefusal.category,
+            guidance: `Run \`pb fields ${fieldsGuidanceCollection}\` to see valid fields. ${linkTypeRefusal.guidance ?? ''}`,
+        });
+    }
     if (hasRejected) {
         throw new CLIError(`Fields rejected: ${rejectedFields.join(', ')}.`, {
             code: ErrorCode.VALIDATION_FAILED,
             category: 'validation',
-            guidance: `Run \`pb fields ${collectionSlug}\` to see valid fields.`,
+            guidance: `Run \`pb fields ${fieldsGuidanceCollection}\` to see valid fields.`,
         });
     }
+    // WP-688 S4 (element 11): --link without --link-type — refuses non-zero identically in
+    // both TTY and --json mode, thrown AFTER the (successful) capture output above so the
+    // created id is never orphaned silently.
+    if (linkTypeRefusal) {
+        throw linkTypeRefusal;
+    }
 }
 //# sourceMappingURL=capture.js.map