peaks-loop 4.0.0-beta.3 → 4.0.0-beta.30

package/dist/cli/commands/feedback-commands.js

@@ -0,0 +1,145 @@
+/**
+ * v2.15.0 slice 002 — AC-3: feedback promotion CLI.
+ *
+ *   - `peaks feedback promote <memory-file> [--layer A|B|C] [--dry-run]`
+ *   - `peaks feedback check-unpromoted --project <path> [--strict]`
+ *
+ * Companion to `sops/feedback-promotion-sop.md`. The promote command
+ * generates a stub for the chosen enforcement layer (A: peaks-sop
+ * gate, B: peaks-hooks PreToolUse, C: mode-gate hardFloorCategory)
+ * and writes the promotion marker + sidecar + RD envelope. The
+ * check-unpromoted command scans `.peaks/memory/*.md` for feedback
+ * memories without a promotion marker and emits a structured list.
+ * `--strict` flips exit code to non-zero when any unpromoted feedback
+ * is found — used by `peaks workflow verify-pipeline` Gate H.
+ */
+import { resolve as resolvePath } from 'node:path';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+import { generatePromotionStub, isPromotionLayer, listUnpromotedFeedback, parseFeedbackMemory, PROMOTION_LAYER_DETAILS, PROMOTION_LAYERS, promoteFeedback } from '../../services/feedback/feedback-promotion-service.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+export function registerFeedbackCommands(program, io) {
+    const feedback = program
+        .command('feedback')
+        .description('v2.15.0 slice 002 AC-3: promote user-given feedback memories to peaks-loop enforcement layers (A: sop, B: hooks, C: hard-floor).');
+    addJsonOption(feedback
+        .command('promote <memory-file>')
+        .description('Promote a feedback memory to one of the 3 enforcement layers (A=peaks-sop gate, B=peaks-hooks PreToolUse, C=mode-gate hardFloorCategory). ' +
+        'Reads `.peaks/memory/<file>.md`, generates a code stub for the chosen layer, and writes ' +
+        'the promotion marker (HTML comment + sidecar .promotion.json) + an RD envelope at ' +
+        '`.peaks/_runtime/<sid>/rd/feedback-promote-<name>.json`. ' +
+        'Without --layer, the CLI lists the 3 layer options as nextActions and exits with code 0 ' +
+        '(use --layer <A|B|C> to actually promote, or pass --dry-run to preview the stub).')
+        .option('--layer <A|B|C>', `enforcement layer (${PROMOTION_LAYERS.join(' | ')})`)
+        .option('--project <path>', 'project root (default: cwd)')
+        .option('--promoted-by <id>', 'identity string for the audit envelope (default: peaks-rd fork agent)')
+        .option('--dry-run', 'preview the stub without writing the marker / sidecar / envelope')).action((memoryFile, opts) => {
+        try {
+            const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const memoryPath = memoryFile.endsWith('.md')
+                ? (memoryFile.startsWith('/') || memoryFile.includes(':'))
+                    ? memoryFile
+                    : resolvePath(projectRoot, memoryFile)
+                : resolvePath(projectRoot, '.peaks', 'memory', `${memoryFile}.md`);
+            const parsed = parseFeedbackMemory(memoryPath);
+            if (parsed === null) {
+                printResult(io, fail('feedback.promote', 'NOT_A_FEEDBACK_MEMORY', `${memoryFile} is not a feedback memory (frontmatter metadata.type must equal "feedback")`, { memoryFile, memoryPath }, [
+                    'Verify the file is at .peaks/memory/<name>.md and its frontmatter has `metadata: { type: feedback }` or `type: feedback`',
+                    'Run `peaks memory list --project <path> --json` to see all known memories and their kinds'
+                ]), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (opts.dryRun === true) {
+                // Preview without choosing a layer: show all three stubs.
+                const previews = PROMOTION_LAYERS.map((layer) => {
+                    const stub = generatePromotionStub({
+                        layer,
+                        feedbackName: parsed.name,
+                        feedbackBody: parsed.body
+                    });
+                    return { layer, ...stub };
+                });
+                printResult(io, ok('feedback.promote', { dryRun: true, name: parsed.name, previews }, [], [
+                    `Preview generated for feedback "${parsed.name}" — 3 layer options shown above.`,
+                    'Re-run with --layer <A|B|C> to apply, or --layer <A|B|C> --dry-run to preview a single layer.'
+                ]), opts.json);
+                return;
+            }
+            if (opts.layer === undefined) {
+                // No --layer: surface the 3 options as nextActions so the
+                // LLM / human can decide. No marker written.
+                printResult(io, ok('feedback.promote', {
+                    name: parsed.name,
+                    layer: null,
+                    options: PROMOTION_LAYER_DETAILS
+                }, [], [
+                    'No --layer passed. Choose one of A / B / C and re-run.',
+                    'A: append to sops/*.md (procedural rules)',
+                    'B: append a matcher to .peaks/.claude-settings-template.json (tool-call interception)',
+                    'C: extend HardFloorCategory in mode-gate.ts (always pauses regardless of mode)',
+                    'Or pass --dry-run to preview all three stubs first.'
+                ]), opts.json);
+                return;
+            }
+            if (!isPromotionLayer(opts.layer)) {
+                printResult(io, fail('feedback.promote', 'INVALID_LAYER', `--layer must be one of ${PROMOTION_LAYERS.join(' | ')} (got "${opts.layer}")`, { provided: opts.layer }, [`Pass --layer ${PROMOTION_LAYERS.join(' | ')}`]), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            const layer = opts.layer;
+            const sessionId = getCurrentSessionId(projectRoot) ?? 'unknown-sid';
+            const promotedBy = opts.promotedBy ?? 'peaks-rd fork agent';
+            const envelope = promoteFeedback({
+                feedbackPath: memoryPath,
+                layer,
+                promotedBy,
+                sessionId,
+                projectRoot,
+                dryRun: false
+            });
+            printResult(io, ok('feedback.promote', envelope, [], [
+                `Promoted feedback "${envelope.name}" to layer ${envelope.layer} (${envelope.layerDetail}).`,
+                `Generated files: ${envelope.generatedFiles.join(', ')}`,
+                `Envelope written to .peaks/_runtime/${sessionId}/rd/feedback-promote-${envelope.name}.json`
+            ]), opts.json);
+        }
+        catch (err) {
+            printResult(io, fail('feedback.promote', 'PROMOTE_FAILED', getErrorMessage(err), { memoryFile }, ['Verify the file is a feedback memory and re-run']), opts.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(feedback
+        .command('check-unpromoted')
+        .description('Scan `.peaks/memory/*.md` and list feedback memories without a promotion marker. ' +
+        'Default: dry-run (exit 0, just warn). Pass --strict to fail with exit code 1 when any ' +
+        'unpromoted feedback is found — this is what `peaks workflow verify-pipeline` Gate H uses.')
+        .requiredOption('--project <path>', 'project root')
+        .option('--strict', 'exit non-zero when any unpromoted feedback is found (used by verify-pipeline Gate H)')).action((opts) => {
+        try {
+            const unpromoted = listUnpromotedFeedback({ projectRoot: opts.project });
+            const count = unpromoted.length;
+            if (count === 0) {
+                printResult(io, ok('feedback.check-unpromoted', { count: 0, unpromoted: [] }, [], [`No unpromoted feedback found in .peaks/memory/.`]), opts.json);
+                return;
+            }
+            const message = `${count} feedback memor${count === 1 ? 'y is' : 'ies are'} not yet promoted to an enforcement layer.`;
+            const nextActions = [
+                `Run \`peaks feedback promote <memory-file> --layer <A|B|C>\` for each entry above.`,
+                'A = peaks-sop gate, B = peaks-hooks PreToolUse, C = mode-gate hardFloorCategory.',
+                'See sops/feedback-promotion-sop.md for the SOP and the layer-choice rubric.'
+            ];
+            if (opts.strict === true) {
+                printResult(io, fail('feedback.check-unpromoted', 'UNPROMOTED_FEEDBACK_FOUND', message, { count, unpromoted }, nextActions), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('feedback.check-unpromoted', { count, unpromoted }, [message], nextActions), opts.json);
+        }
+        catch (err) {
+            printResult(io, fail('feedback.check-unpromoted', 'CHECK_FAILED', getErrorMessage(err), { project: opts.project }, ['Verify --project path and re-run']), opts.json);
+            process.exitCode = 1;
+        }
+    });
+}

package/dist/cli/commands/final-review-commands.js

@@ -0,0 +1,161 @@
+/**
+ * W5 Fix M2 — `peaks prepare-final-review <rid>` CLI wrapper.
+ *
+ * Exposes the `prepareFinalReview()` service (added in W2 T9 on
+ * `feature/slice-topology-multipass`) via the CLI surface. The service
+ * depends on an injected `LlmRunner`; this slice wires the CLI route
+ * with a `stub` provider that returns a structured "scaffold ready"
+ * envelope so CI can verify the route without a real LLM. A follow-up
+ * slice will bind a real provider. Until then, non-stub providers fail
+ * loudly with `LLM_PROVIDER_NOT_IMPLEMENTED` so callers cannot silently
+ * no-op.
+ *
+ * Per the dev-preference "Default-no on new CLI commands" rule and the
+ * W4 T14 spec, this is a NEW top-level command (`prepare-final-review`),
+ * not a subcommand of `audit`. The two primitives are distinct:
+ *   - `peaks audit goal`   — propose a 6-dim goal from a human need
+ *   - `peaks prepare-final-review` — produce a 4-dim review evidence
+ *                                  pack for human acceptance
+ */
+import { existsSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+/** Whitelist of supported `--llm-provider` values for `peaks prepare-final-review`. */
+const SUPPORTED_LLM_PROVIDERS = ['stub'];
+function isSupportedLlmProvider(value) {
+    return SUPPORTED_LLM_PROVIDERS.includes(value);
+}
+/**
+ * Empty placeholder used by `fail()` envelopes. `status` is
+ * `'not-applicable'` on the error path so consumers can tell
+ * "this is a placeholder on a failure" apart from "this is a real
+ * scaffold-only success".
+ */
+function emptyFinalReviewData(rid, sessionId, auditGoalPath) {
+    return {
+        status: 'not-applicable',
+        rid,
+        sessionId,
+        auditGoalPath,
+        serviceWired: false,
+        providerBinding: 'unknown',
+    };
+}
+function validateProjectRoot(projectArg) {
+    const projectRoot = resolve(projectArg);
+    if (!existsSync(projectRoot)) {
+        return {
+            ok: false,
+            code: 'PROJECT_NOT_FOUND',
+            message: `project path does not exist: ${projectArg}`,
+        };
+    }
+    let stat;
+    try {
+        stat = statSync(projectRoot);
+    }
+    catch (error) {
+        return { ok: false, code: 'INVALID_PROJECT', message: getErrorMessage(error) };
+    }
+    if (!stat.isDirectory()) {
+        return {
+            ok: false,
+            code: 'INVALID_PROJECT',
+            message: `project path is not a directory: ${projectArg}`,
+        };
+    }
+    return { ok: true, projectRoot };
+}
+/**
+ * Validate the session id. Rejects empty, path-traversal (`..`), and
+ * any segment separator (`/`, `\`) so the caller cannot escape
+ * `.peaks/_runtime/<sessionId>/audit-goal/` via CLI flags.
+ */
+function validateSessionId(sessionId) {
+    if (sessionId.length === 0) {
+        return {
+            ok: false,
+            code: 'MISSING_REQUIRED_FLAG',
+            message: '`--session-id` is required and must be a non-empty string',
+        };
+    }
+    if (sessionId.includes('..') || sessionId.includes('/') || sessionId.includes('\\')) {
+        return {
+            ok: false,
+            code: 'INVALID_SESSION_ID',
+            message: '`--session-id` must not contain path-traversal or path-separator characters (rejected: "..", "/", "\\")',
+        };
+    }
+    return { ok: true, sessionId };
+}
+export function registerFinalReviewCommands(program, io) {
+    addJsonOption(program
+        .command('prepare-final-review <rid>')
+        .description('Prepare the 4-dimension business review (final-review primitive) for human acceptance (W2 T9 service; CLI surface in W5 M2)')
+        .requiredOption('--project <path>', 'target project root')
+        .requiredOption('--session-id <sid>', 'session id whose .peaks/_runtime/<sid>/audit-goal/<rid>.json is the approved goal source')
+        .option('--llm-provider <name>', 'LLM provider name (default: stub)', 'stub')).action(async (rid, options) => {
+        // 1. Project root must exist and be a directory.
+        const projectValidation = validateProjectRoot(options.project);
+        if (!projectValidation.ok) {
+            printResult(io, fail('final-review.prepare', projectValidation.code, projectValidation.message, emptyFinalReviewData(rid, options.sessionId, ''), ['Verify the project path exists and is a directory']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        // 2. Session id must be a safe single-segment string.
+        const sessionValidation = validateSessionId(options.sessionId);
+        if (!sessionValidation.ok) {
+            printResult(io, fail('final-review.prepare', sessionValidation.code, sessionValidation.message, emptyFinalReviewData(rid, options.sessionId, ''), [
+                'Pass a non-empty `--session-id` whose value is a single segment (no "..", "/", or "\\")',
+            ]), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        // 3. Compute the audit-goal path the service WOULD read. We do this
+        //    in two places: the pre-flight existence check (here) and the
+        //    stub-path envelope (below). The service computes it identically
+        //    at `src/services/final-review/final-review-service.ts:45-52`.
+        const auditGoalPath = join(projectValidation.projectRoot, '.peaks', '_runtime', sessionValidation.sessionId, 'audit-goal', `${rid}.json`);
+        // 4. Pre-flight: if the audit-goal file is missing, surface a 404
+        //    BEFORE the stub/provider check so the caller learns the real
+        //    reason their request can't proceed.
+        if (!existsSync(auditGoalPath)) {
+            printResult(io, fail('final-review.prepare', 'AUDIT_GOAL_NOT_FOUND', `audit-goal file not found at expected path: ${auditGoalPath}`, emptyFinalReviewData(rid, sessionValidation.sessionId, auditGoalPath), [
+                'Run `peaks audit goal --project <path> --need <text>` first to produce the approved goal JSON.',
+                'Confirm `--session-id` matches the session that wrote the goal.',
+            ]), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        // 5. Provider check: only `stub` is wired in this slice.
+        const provider = options.llmProvider ?? 'stub';
+        if (!isSupportedLlmProvider(provider)) {
+            printResult(io, fail('final-review.prepare', 'LLM_PROVIDER_NOT_IMPLEMENTED', `Provider '${provider}' is not yet wired. The CLI surface is in place; real provider binding is a follow-up slice. Use --llm-provider stub to validate the route without invoking the LLM.`, emptyFinalReviewData(rid, sessionValidation.sessionId, auditGoalPath), [
+                'Re-run with `--llm-provider stub` (default) to validate the route.',
+                'Real provider binding is tracked as a follow-up slice.',
+            ]), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        // 6. Stub path: surface a structured "scaffold ready" envelope.
+        //    We DO NOT call the service in this slice — the service depends
+        //    on an injected `LlmRunner` interface, and no real provider is
+        //    bound yet. The envelope confirms the route is wired end-to-end
+        //    and reports the audit-goal path the service WOULD read.
+        const data = {
+            status: 'scaffold-only',
+            rid,
+            sessionId: sessionValidation.sessionId,
+            auditGoalPath,
+            serviceWired: true,
+            providerBinding: 'pending-follow-up-slice',
+        };
+        const envelope = ok('final-review.prepare', data, [], [
+            'prepareFinalReview() service is wired and reachable. The stub provider returns a scaffold envelope so CI can verify the route without a real LLM.',
+            `Audit-goal file is present at: ${auditGoalPath}`,
+            'A follow-up slice will bind a real LLM provider; until then, non-stub providers fail loudly with `LLM_PROVIDER_NOT_IMPLEMENTED`.',
+        ]);
+        printResult(io, envelope, options.json);
+    });
+}

package/dist/cli/commands/fixture-commands.js

@@ -0,0 +1,91 @@
+import { resolve } from 'node:path';
+import { captureDerivedVariant, captureHistoricalFixture, EDGE_CASE_VARIANTS, ENVELOPE_KINDS } from '../../services/fixture/index.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+function isEnvelopeKind(v) {
+    return ENVELOPE_KINDS.includes(v);
+}
+function isEdgeCaseVariant(v) {
+    return EDGE_CASE_VARIANTS.includes(v);
+}
+export function registerFixtureCommands(program, io) {
+    const fixture = program
+        .command('fixture')
+        .description('Fixture capture + replay support (v2.14.0 G1 anti-fake-green)');
+    addJsonOption(fixture
+        .command('capture')
+        .description('Capture a real envelope artifact as a replay fixture. Sanitizes secrets, computes SHA-256, writes fixture.meta.json.')
+        .option('--from-rid <rid>', 'historical rid to capture (requires --sid + --envelope)')
+        .option('--sid <sid>', 'session id under .peaks/_runtime/<sid>/', 'default')
+        .option('--envelope <kind>', `envelope kind: ${ENVELOPE_KINDS.join(' | ')}`)
+        .option('--variant-from <path>', 'parent fixture path (derived-variant mode)')
+        .option('--variant <edge-case>', `edge case: ${EDGE_CASE_VARIANTS.join(' | ')}`)
+        .option('--out <dir>', 'output dir', 'tests/fixtures/replay')
+        .option('--fixture-id <id>', 'override the fixtureId (auto-derived from rid/variant otherwise)')).action((options) => {
+        const out = resolve(process.cwd(), options.out ?? 'tests/fixtures/replay');
+        // Mode 1: derived-variant
+        if (options.variantFrom !== undefined || options.variant !== undefined) {
+            if (options.variantFrom === undefined || options.variant === undefined) {
+                printResult(io, fail('fixture.capture', 'VARIANT_ARGS_REQUIRED', '--variant-from and --variant must be supplied together', {}, ['Rerun with both --variant-from <path> --variant <edge-case>']), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (!isEdgeCaseVariant(options.variant)) {
+                printResult(io, fail('fixture.capture', 'VARIANT_UNKNOWN', `unknown variant '${options.variant}'`, { knownVariants: EDGE_CASE_VARIANTS }, [`Use one of: ${EDGE_CASE_VARIANTS.join(', ')}`]), options.json);
+                process.exitCode = 1;
+                return;
+            }
+            const fixtureId = options.fixtureId
+                ?? deriveVariantFixtureId(options.variantFrom, options.variant);
+            try {
+                const captured = captureDerivedVariant({
+                    mode: 'derived-variant',
+                    parentFixturePath: resolve(process.cwd(), options.variantFrom),
+                    variant: options.variant,
+                    fixtureId,
+                    outDir: out
+                });
+                printResult(io, ok('fixture.capture', { mode: 'derived-variant', ...captured }), options.json);
+            }
+            catch (err) {
+                printResult(io, fail('fixture.capture', 'CAPTURE_FAILED', err instanceof Error ? err.message : String(err), {}, ['Verify the parent fixture path exists']), options.json);
+                process.exitCode = 1;
+            }
+            return;
+        }
+        // Mode 2: historical
+        if (options.fromRid === undefined || options.envelope === undefined) {
+            printResult(io, fail('fixture.capture', 'CAPTURE_ARGS_REQUIRED', 'Either --variant-from/--variant OR --from-rid/--envelope must be supplied', { envelopeKinds: ENVELOPE_KINDS, edgeCases: EDGE_CASE_VARIANTS }, ['Rerun with --from-rid <rid> --envelope <kind>', 'OR --variant-from <path> --variant <edge-case>']), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        if (!isEnvelopeKind(options.envelope)) {
+            printResult(io, fail('fixture.capture', 'ENVELOPE_UNKNOWN', `unknown envelope kind '${options.envelope}'`, { knownKinds: ENVELOPE_KINDS }, [`Use one of: ${ENVELOPE_KINDS.join(', ')}`]), options.json);
+            process.exitCode = 1;
+            return;
+        }
+        const fixtureId = options.fixtureId ?? deriveHistoricalFixtureId(options.fromRid, options.envelope);
+        try {
+            const captured = captureHistoricalFixture({
+                mode: 'historical',
+                sessionId: options.sid ?? 'default',
+                envelopeKind: options.envelope,
+                fixtureId,
+                outDir: out,
+                requireSource: true
+            });
+            printResult(io, ok('fixture.capture', { mode: 'historical', ...captured }), options.json);
+        }
+        catch (err) {
+            printResult(io, fail('fixture.capture', 'CAPTURE_FAILED', err instanceof Error ? err.message : String(err), {}, ['Verify --sid / --envelope point to an existing session artifact']), options.json);
+            process.exitCode = 1;
+        }
+    });
+}
+function deriveHistoricalFixtureId(rid, envelope) {
+    return `${rid}-${envelope}`.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 80);
+}
+function deriveVariantFixtureId(parentPath, variant) {
+    const base = parentPath.replace(/\.(md|json)$/, '').split(/[/\\]/).pop() ?? 'parent';
+    return `${base}--${variant}`.toLowerCase().replace(/[^a-z0-9-]+/g, '-').slice(0, 80);
+}

package/dist/cli/commands/fork-commands.js

@@ -0,0 +1,163 @@
+/**
+ * v2.15.0 follow-up — G11: fork sync CLI.
+ *
+ *   - `peaks fork status`               — show baseline + drift + last sync
+ *   - `peaks fork upstream-check`       — recommend next stable tag
+ *   - `peaks fork sync-plan`            — generate a sync plan
+ *   - `peaks fork sync`                 — record a sync execution
+ *   - `peaks fork sync-verify`          — mark a sync as verified / failed
+ *
+ * All 5 commands are pure local reads/writes against
+ * `.peaks/fork-state.json`. The actual git fetch + merge is out of
+ * scope for this slice (deferred to 2.15.x).
+ */
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { appendSyncRecord, buildForkStatusReport, makeSyncId, readForkState, recommendStableTags, updateSyncRecordStatus, writeForkState } from '../../services/fork/fork-sync-state.js';
+import { fail, ok } from 'peaks-loop-shared/result';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+export function registerForkCommands(program, io) {
+    const fork = program
+        .command('fork')
+        .description('v2.15.0 follow-up G11: manage upstream tag sync for forked projects (hermes-style).');
+    // 1. status
+    addJsonOption(fork
+        .command('status')
+        .description('Show the current fork baseline (upstream + tag + drift) and the most recent sync. ' +
+        'Pure read of `.peaks/fork-state.json`.')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const state = readForkState(projectRoot);
+        const report = buildForkStatusReport(state);
+        printResult(io, ok('fork.status', { projectRoot, report: serializeReport(report) }, [], [
+            report.driftWarning
+                ? 'Drift exceeds 30 commits — consider `peaks fork upstream-check` to plan a sync.'
+                : 'No sync action recommended at this time.'
+        ]), opts.json ?? false);
+    });
+    // 2. upstream-check
+    addJsonOption(fork
+        .command('upstream-check')
+        .description('Recommend stable upstream tags to sync to, given a list of available tags. ' +
+        '`--tags` is a comma-separated list; pre-release tags (alpha/beta/rc/dev/preview) are filtered out. ' +
+        'Returns the list of stable tags newer than the current baseline.')
+        .requiredOption('--tags <list>', 'comma-separated list of available upstream tags')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const availableTags = opts.tags.split(',').map((s) => s.trim()).filter((s) => s.length > 0);
+        const state = readForkState(projectRoot);
+        const baselineTag = state.baseline?.basedOn ?? null;
+        const recommended = recommendStableTags(availableTags, baselineTag);
+        printResult(io, ok('fork.upstream-check', {
+            projectRoot,
+            currentBaseline: baselineTag,
+            totalAvailableTags: availableTags.length,
+            recommendedTags: recommended,
+            nextRecommended: recommended[0] ?? null
+        }, [], [
+            recommended.length === 0
+                ? 'No stable tags newer than the current baseline.'
+                : `Recommended next sync target: ${recommended[0]}`
+        ]), opts.json ?? false);
+    });
+    // 3. sync-plan
+    addJsonOption(fork
+        .command('sync-plan')
+        .description('Generate a sync plan for the given upstream tag. Records the plan in `.peaks/fork-state.json`. ' +
+        'Returns the plan id used to invoke `peaks fork sync`. Pure local write; no git operations.')
+        .requiredOption('--upstream <tag>', 'target upstream tag (e.g. v1.20.0)')
+        .option('--conflicts <list>', 'comma-separated predicted conflict file globs')
+        .option('--patches <list>', 'comma-separated business patch identifiers to replay')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const state = readForkState(projectRoot);
+        const syncId = makeSyncId(opts.upstream);
+        const conflicts = opts.conflicts ? opts.conflicts.split(',').map((s) => s.trim()).filter((s) => s.length > 0) : [];
+        const patches = opts.patches ? opts.patches.split(',').map((s) => s.trim()).filter((s) => s.length > 0) : [];
+        const record = {
+            syncId,
+            targetTag: opts.upstream,
+            plannedAt: new Date().toISOString(),
+            predictedConflicts: conflicts,
+            businessPatches: patches,
+            status: 'planned'
+        };
+        const next = appendSyncRecord(state, record);
+        writeForkState(projectRoot, next);
+        printResult(io, ok('fork.sync-plan', { projectRoot, syncId, record }, [], [
+            `Run \`peaks fork sync --sync-id ${syncId}\` to mark execution start.`,
+            `Run \`peaks fork sync-verify --sync-id ${syncId} --status verified\` after the sync completes.`
+        ]), opts.json ?? false);
+    });
+    // 4. sync (mark execution)
+    addJsonOption(fork
+        .command('sync')
+        .description('Mark a planned sync as in-progress. Records the execution start. ' +
+        'This slice does NOT perform the actual git fetch + merge — the LLM / operator runs those, ' +
+        'then calls `sync-verify` to record the result.')
+        .requiredOption('--sync-id <id>', 'sync plan id from `peaks fork sync-plan`')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const state = readForkState(projectRoot);
+        const target = state.history.find((r) => r.syncId === opts.syncId);
+        if (!target) {
+            printResult(io, fail('fork.sync', 'NOT_FOUND', `sync id "${opts.syncId}" not found in fork-state.json`, { projectRoot }, [
+                'Run `peaks fork sync-plan` first to generate a plan.'
+            ]), opts.json ?? false);
+            return;
+        }
+        const next = updateSyncRecordStatus(state, opts.syncId, 'in-progress');
+        writeForkState(projectRoot, next);
+        printResult(io, ok('fork.sync', { projectRoot, syncId: opts.syncId, status: 'in-progress', targetTag: target.targetTag }, [], [
+            'Now run the actual git fetch + merge, then call `peaks fork sync-verify` to record the result.'
+        ]), opts.json ?? false);
+    });
+    // 5. sync-verify
+    addJsonOption(fork
+        .command('sync-verify')
+        .description('Mark a sync as verified (success) or failed. Optionally records verification notes. ' +
+        'On success, the current baseline is also updated to the synced tag.')
+        .requiredOption('--sync-id <id>', 'sync plan id')
+        .requiredOption('--status <verified|failed>', 'sync verification outcome')
+        .option('--notes <text>', 'optional verification notes')
+        .option('--project <path>', 'project root (default: cwd)')).action((opts) => {
+        if (opts.status !== 'verified' && opts.status !== 'failed') {
+            printResult(io, fail('fork.sync-verify', 'INVALID_STATUS', `status must be "verified" or "failed" (got "${opts.status}")`, { projectRoot: opts.project ?? '' }, [
+                'Pass --status verified on success, --status failed on failure.'
+            ]), opts.json ?? false);
+            return;
+        }
+        const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+        const state = readForkState(projectRoot);
+        const target = state.history.find((r) => r.syncId === opts.syncId);
+        if (!target) {
+            printResult(io, fail('fork.sync-verify', 'NOT_FOUND', `sync id "${opts.syncId}" not found`, { projectRoot }, []), opts.json ?? false);
+            return;
+        }
+        let next = updateSyncRecordStatus(state, opts.syncId, opts.status, opts.notes);
+        if (opts.status === 'verified') {
+            const baseline = {
+                upstream: state.baseline?.upstream ?? 'unknown',
+                basedOn: target.targetTag,
+                recordedAt: new Date().toISOString(),
+                commitsAhead: 0,
+                filesChanged: 0
+            };
+            next = { ...next, baseline };
+        }
+        writeForkState(projectRoot, next);
+        printResult(io, ok('fork.sync-verify', {
+            projectRoot,
+            syncId: opts.syncId,
+            status: opts.status,
+            notes: opts.notes ?? null,
+            newBaseline: next.baseline
+        }, [], [
+            opts.status === 'verified'
+                ? 'Baseline updated to the synced tag.'
+                : 'Sync marked as failed. Re-run `peaks fork sync-plan` to retry.'
+        ]), opts.json ?? false);
+    });
+}
+function serializeReport(r) {
+    return r;
+}