peaks-loop 4.0.53 → 4.1.0

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

@@ -23,19 +23,12 @@ import { getCurrentSessionId } from '../../services/skills/skill-presence-servic
 import { generatePromotionStub, isPromotionLayer, listPromotionExempt, listUnpromotedFeedback, missingArtifacts, parseFeedbackMemory, PROMOTION_LAYER_DETAILS, PROMOTION_LAYERS, promoteFeedback, promotionArtifactChecks } from '../../services/feedback/feedback-promotion-service.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
+import { CHECK_UNPROMOTED_DESCRIPTION, FEEDBACK_PARENT_DESCRIPTION, formatExemptHint, NO_LAYER_NEXT_ACTIONS, PROMOTE_DESCRIPTION, UNPROMOTED_NEXT_ACTIONS } from './feedback-commands-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).');
+    const feedback = program.command('feedback').description(FEEDBACK_PARENT_DESCRIPTION);
     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` and writes the promotion marker (HTML comment + sidecar .promotion.json) + an RD envelope at ' +
-        '`.peaks/_runtime/<sid>/rd/feedback-promote-<name>.json`. Layer A additionally generates and registers the SOP manifest the ' +
-        'SOP engine reads. Layers B and C live in shared files the command does not own, so it records the requirement and exits ' +
-        'non-zero (PROMOTION_NOT_EFFECTIVE) until the registration is present. ' +
-        '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).')
+        .description(PROMOTE_DESCRIPTION)
         .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)')
@@ -43,7 +36,7 @@ export function registerFeedbackCommands(program, io) {
         try {
             const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
             const memoryPath = memoryFile.endsWith('.md')
-                ? (memoryFile.startsWith('/') || memoryFile.includes(':'))
+                ? memoryFile.startsWith('/') || memoryFile.includes(':')
                     ? memoryFile
                     : resolvePath(projectRoot, memoryFile)
                 : resolvePath(projectRoot, '.peaks', 'memory', `${memoryFile}.md`);
@@ -79,13 +72,7 @@ export function registerFeedbackCommands(program, io) {
                     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);
+                }, [], NO_LAYER_NEXT_ACTIONS), opts.json);
                 return;
             }
             if (!isPromotionLayer(opts.layer)) {
@@ -120,21 +107,23 @@ export function registerFeedbackCommands(program, io) {
             printResult(io, fail('feedback.promote', 'PROMOTION_NOT_EFFECTIVE', `Promotion recorded but not effective — layer ${envelope.layer} is not backed by its artifact: ${missing.join('; ')}`, envelope, [
                 ...notes,
                 ...(envelope.layer === 'C'
-                    ? ['Layer C lives in source code: register the hard-floor category in src/services/code/mode-gate.ts, then re-run promote to record it.']
+                    ? [
+                        'Layer C lives in source code: register the hard-floor category in src/services/code/mode-gate.ts, then re-run promote to record it.'
+                    ]
                     : ['Apply the snippet to the file(s) named above, then re-run promote to record it.'])
             ]), opts.json);
             process.exitCode = 1;
         }
         catch (err) {
-            printResult(io, fail('feedback.promote', 'PROMOTE_FAILED', getErrorMessage(err), { memoryFile }, ['Verify the file is a feedback memory and re-run']), opts.json);
+            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.')
+        .description(CHECK_UNPROMOTED_DESCRIPTION)
         .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 {
@@ -144,30 +133,18 @@ export function registerFeedbackCommands(program, io) {
             if (count === 0) {
                 printResult(io, ok('feedback.check-unpromoted', { count: 0, unpromoted: [], exempt }, [], [
                     `No unpromoted feedback found in .peaks/memory/.`,
-                    ...(exempt.length === 0
-                        ? []
-                        : [`${exempt.length} memor${exempt.length === 1 ? 'y' : 'ies'} declare themselves not-to-be-promoted: ${exempt.map((e) => `${e.name} (${e.code})`).join('; ')}.`])
+                    ...(exempt.length === 0 ? [] : [formatExemptHint(exempt)])
                 ]), 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.',
-                'A marker alone does not count: the entry above names the artifact its layer still owes.',
-                'See sops/feedback-promotion-sop.md for the SOP and the layer-choice rubric.'
-            ];
+            const nextActions = UNPROMOTED_NEXT_ACTIONS;
             if (opts.strict === true) {
                 printResult(io, fail('feedback.check-unpromoted', 'UNPROMOTED_FEEDBACK_FOUND', message, { count, unpromoted, exempt }, nextActions), opts.json);
                 process.exitCode = 1;
                 return;
             }
-            printResult(io, ok('feedback.check-unpromoted', { count, unpromoted, exempt }, [
-                message,
-                ...(exempt.length === 0
-                    ? []
-                    : [`${exempt.length} memor${exempt.length === 1 ? 'y' : 'ies'} declare themselves not-to-be-promoted: ${exempt.map((e) => `${e.name} (${e.code})`).join('; ')}.`])
-            ], nextActions), opts.json);
+            printResult(io, ok('feedback.check-unpromoted', { count, unpromoted, exempt }, [message, ...(exempt.length === 0 ? [] : [formatExemptHint(exempt)])], 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);

package/dist/cli/commands/final-review-commands.d.ts

@@ -24,7 +24,7 @@
  *   - `peaks prepare-final-review` — produce a 4-dim review evidence
  *                                  pack for human acceptance
  */
-import { Command } from 'commander';
+import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 import type { FinalReviewOutput } from '../../services/final-review/final-review-types.js';
 export type FinalReviewStatus = 'scaffold-only' | 'review-complete' | 'not-applicable';

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

@@ -29,8 +29,8 @@ import { join, resolve } from 'node:path';
 import { REQUEST_ID_PATTERN } from '../../services/artifacts/request-artifact-service.js';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { fail, ok } from 'peaks-loop-shared/result';
-import { createAnthropicRunner, LlmBindingError, LlmRequestError, resolveAnthropicConfig, } from '../../services/llm/anthropic-runner.js';
-import { IncompleteFinalReviewError, prepareFinalReview, } from '../../services/final-review/final-review-service.js';
+import { createAnthropicRunner, LlmBindingError, LlmRequestError, resolveAnthropicConfig } from '../../services/llm/anthropic-runner.js';
+import { IncompleteFinalReviewError, prepareFinalReview } from '../../services/final-review/final-review-service.js';
 /** Whitelist of supported `--llm-provider` values for `peaks prepare-final-review`. */
 const SUPPORTED_LLM_PROVIDERS = ['anthropic', 'stub'];
 /**
@@ -58,7 +58,7 @@ function emptyFinalReviewData(rid, sessionId, auditGoalPath, missingEnv) {
         auditGoalPath,
         serviceWired: false,
         providerBinding: 'unknown',
-        ...(missingEnv === undefined ? {} : { missingEnv }),
+        ...(missingEnv === undefined ? {} : { missingEnv })
     };
 }
 function validateProjectRoot(projectArg) {
@@ -67,7 +67,7 @@ function validateProjectRoot(projectArg) {
         return {
             ok: false,
             code: 'PROJECT_NOT_FOUND',
-            message: `project path does not exist: ${projectArg}`,
+            message: `project path does not exist: ${projectArg}`
         };
     }
     let stat;
@@ -81,7 +81,7 @@ function validateProjectRoot(projectArg) {
         return {
             ok: false,
             code: 'INVALID_PROJECT',
-            message: `project path is not a directory: ${projectArg}`,
+            message: `project path is not a directory: ${projectArg}`
         };
     }
     return { ok: true, projectRoot };
@@ -96,14 +96,14 @@ function validateSessionId(sessionId) {
         return {
             ok: false,
             code: 'MISSING_REQUIRED_FLAG',
-            message: '`--session-id` is required and must be a non-empty string',
+            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: "..", "/", "\\")',
+            message: '`--session-id` must not contain path-traversal or path-separator characters (rejected: "..", "/", "\\")'
         };
     }
     return { ok: true, sessionId };
@@ -127,7 +127,7 @@ export function registerFinalReviewCommands(program, io) {
         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 "\\")',
+                'Pass a non-empty `--session-id` whose value is a single segment (no "..", "/", or "\\")'
             ]), options.json);
             process.exitCode = 1;
             return;
@@ -154,7 +154,7 @@ export function registerFinalReviewCommands(program, io) {
         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.',
+                'Confirm `--session-id` matches the session that wrote the goal.'
             ]), options.json);
             process.exitCode = 1;
             return;
@@ -165,7 +165,7 @@ export function registerFinalReviewCommands(program, io) {
         const provider = options.llmProvider ?? DEFAULT_LLM_PROVIDER;
         if (!isSupportedLlmProvider(provider)) {
             printResult(io, fail('final-review.prepare', 'LLM_PROVIDER_NOT_IMPLEMENTED', `LLM provider "${provider}" is not implemented. Supported providers: ${SUPPORTED_LLM_PROVIDERS.join(', ')}.`, emptyFinalReviewData(rid, sessionValidation.sessionId, auditGoalPath), [
-                `Re-run with \`--llm-provider anthropic\` for a real 4-dim review, or \`--llm-provider ${DEFAULT_LLM_PROVIDER}\` for an offline scaffold.`,
+                `Re-run with \`--llm-provider anthropic\` for a real 4-dim review, or \`--llm-provider ${DEFAULT_LLM_PROVIDER}\` for an offline scaffold.`
             ]), options.json);
             process.exitCode = 1;
             return;
@@ -183,12 +183,12 @@ export function registerFinalReviewCommands(program, io) {
                 sessionId: sessionValidation.sessionId,
                 auditGoalPath,
                 serviceWired: true,
-                providerBinding: 'stub',
+                providerBinding: 'stub'
             };
             const envelope = ok('final-review.prepare', data, [], [
                 'Stub provider: no 4-dim review was performed. This envelope only proves the route is wired and reachable.',
                 `Audit-goal file is present at: ${auditGoalPath}`,
-                'Re-run with `--llm-provider anthropic` to produce a real review.',
+                'Re-run with `--llm-provider anthropic` to produce a real review.'
             ]);
             printResult(io, envelope, options.json);
             return;
@@ -205,7 +205,7 @@ export function registerFinalReviewCommands(program, io) {
                 projectRoot: projectValidation.projectRoot,
                 sessionId: sessionValidation.sessionId,
                 llmRunner,
-                ...(options.base === undefined ? {} : { baseRef: options.base }),
+                ...(options.base === undefined ? {} : { baseRef: options.base })
             });
             const data = {
                 status: 'review-complete',
@@ -215,13 +215,15 @@ export function registerFinalReviewCommands(program, io) {
                 serviceWired: true,
                 providerBinding: 'anthropic-messages-api',
                 model: config.model,
-                review,
+                review
             };
-            const envelope = ok('final-review.prepare', data, review.allPass ? [] : [
-                `Dimensions needing human attention: ${review.needsAttention.join(', ') || 'none flagged'}.`,
-            ], [
+            const envelope = ok('final-review.prepare', data, review.allPass
+                ? []
+                : [
+                    `Dimensions needing human attention: ${review.needsAttention.join(', ') || 'none flagged'}.`
+                ], [
                 `4-dim review produced by anthropic-messages-api (model: ${config.model}).`,
-                `allPass: ${String(review.allPass)}.`,
+                `allPass: ${String(review.allPass)}.`
             ]);
             printResult(io, envelope, options.json);
         }
@@ -251,19 +253,19 @@ function finalReviewNextActions(code) {
         case 'LLM_CREDENTIAL_MISSING':
             return [
                 'Export ANTHROPIC_AUTH_TOKEN (or ANTHROPIC_API_KEY) in the environment that launches peaks, then re-run.',
-                'For an offline scaffold instead of a review, re-run with `--llm-provider stub` — it performs NO review.',
+                'For an offline scaffold instead of a review, re-run with `--llm-provider stub` — it performs NO review.'
             ];
         case 'LLM_MODEL_MISSING':
             return [
-                'Export ANTHROPIC_MODEL (or CLAUDE_CODE_SUBAGENT_MODEL) in the environment that launches peaks, then re-run.',
+                'Export ANTHROPIC_MODEL (or CLAUDE_CODE_SUBAGENT_MODEL) in the environment that launches peaks, then re-run.'
             ];
         case 'LLM_REQUEST_FAILED':
             return [
-                'Check ANTHROPIC_BASE_URL and network reachability, then re-run — a transport failure produces no review.',
+                'Check ANTHROPIC_BASE_URL and network reachability, then re-run — a transport failure produces no review.'
             ];
         case 'INCOMPLETE_FINAL_REVIEW':
             return [
-                'The LLM reply was not valid JSON or omitted a required dimension; re-run so the gate is never read as complete.',
+                'The LLM reply was not valid JSON or omitted a required dimension; re-run so the gate is never read as complete.'
             ];
         default:
             return ['Re-run with `--llm-provider stub` to validate the CLI route without a real LLM.'];

package/dist/cli/commands/fixture-commands.d.ts

@@ -27,6 +27,6 @@
  *
  * File budget: ≤ 200 lines (Karpathy §2).
  */
-import { Command } from 'commander';
+import type { Command } from 'commander';
 import { type ProgramIO } from '../cli-helpers.js';
 export declare function registerFixtureCommands(program: Command, io: ProgramIO): void;

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

@@ -35,8 +35,7 @@ export function registerFixtureCommands(program, io) {
                 process.exitCode = 1;
                 return;
             }
-            const fixtureId = options.fixtureId
-                ?? deriveVariantFixtureId(options.variantFrom, options.variant);
+            const fixtureId = options.fixtureId ?? deriveVariantFixtureId(options.variantFrom, options.variant);
             try {
                 const captured = captureDerivedVariant({
                     mode: 'derived-variant',
@@ -55,7 +54,10 @@ export function registerFixtureCommands(program, io) {
         }
         // 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);
+            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;
         }
@@ -83,9 +85,18 @@ export function registerFixtureCommands(program, io) {
     });
 }
 function deriveHistoricalFixtureId(rid, envelope) {
-    return `${rid}-${envelope}`.toLowerCase().replace(/[^a-z0-9]+/g, '-').slice(0, 80);
+    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);
+    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-sync-verify.d.ts

@@ -0,0 +1,12 @@
+/**
+ * v2.15.0 follow-up — G11: fork sync CLI, `peaks fork sync-verify`.
+ *
+ * Extracted from fork-commands.ts (C wave 4 near-cap split). Owns: the
+ * `sync-verify` command — mark a planned sync verified/failed and, on success,
+ * move the fork baseline to the synced tag. Command name, options, emitted
+ * message text, on-disk writes and the print/return order are unchanged from
+ * the predecessor's inline action.
+ */
+import type { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerForkSyncVerifyCommand(fork: Command, io: ProgramIO): void;

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

@@ -0,0 +1,72 @@
+/**
+ * v2.15.0 follow-up — G11: fork sync CLI, `peaks fork sync-verify`.
+ *
+ * Extracted from fork-commands.ts (C wave 4 near-cap split). Owns: the
+ * `sync-verify` command — mark a planned sync verified/failed and, on success,
+ * move the fork baseline to the synced tag. Command name, options, emitted
+ * message text, on-disk writes and the print/return order are unchanged from
+ * the predecessor's inline action.
+ */
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { readForkState, 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 registerForkSyncVerifyCommand(fork, io) {
+    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) => {
+        runForkSyncVerify(io, opts);
+    });
+}
+function runForkSyncVerify(io, opts) {
+    if (opts.status !== 'verified' && opts.status !== 'failed') {
+        printSyncVerifyInvalidStatus(io, opts);
+        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) {
+        printSyncVerifyNotFound(io, opts, projectRoot);
+        return;
+    }
+    let next = updateSyncRecordStatus(state, opts.syncId, opts.status, opts.notes);
+    if (opts.status === 'verified') {
+        next = { ...next, baseline: syncedBaseline(state, target) };
+    }
+    writeForkState(projectRoot, next);
+    printSyncVerifyResult(io, opts, projectRoot, next.baseline);
+}
+function printSyncVerifyInvalidStatus(io, opts) {
+    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);
+}
+function printSyncVerifyNotFound(io, opts, projectRoot) {
+    printResult(io, fail('fork.sync-verify', 'NOT_FOUND', `sync id "${opts.syncId}" not found`, { projectRoot }, []), opts.json ?? false);
+}
+function printSyncVerifyResult(io, opts, projectRoot, newBaseline) {
+    printResult(io, ok('fork.sync-verify', {
+        projectRoot,
+        syncId: opts.syncId,
+        status: opts.status,
+        notes: opts.notes ?? null,
+        newBaseline
+    }, [], [
+        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 syncedBaseline(state, target) {
+    return {
+        upstream: state.baseline?.upstream ?? 'unknown',
+        basedOn: target.targetTag,
+        recordedAt: new Date().toISOString(),
+        commitsAhead: 0,
+        filesChanged: 0
+    };
+}

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

@@ -15,6 +15,7 @@ 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';
+import { registerForkSyncVerifyCommand } from './fork-commands-sync-verify.js';
 export function registerForkCommands(program, io) {
     const fork = program
         .command('fork')
@@ -43,7 +44,10 @@ export function registerForkCommands(program, io) {
         .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 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);
@@ -71,8 +75,18 @@ export function registerForkCommands(program, io) {
         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 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,
@@ -100,9 +114,7 @@ export function registerForkCommands(program, io) {
         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);
+            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');
@@ -112,51 +124,7 @@ export function registerForkCommands(program, io) {
         ]), 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);
-    });
+    registerForkSyncVerifyCommand(fork, io);
 }
 function serializeReport(r) {
     return r;

package/dist/cli/commands/fresh-context-commands.js

@@ -17,7 +17,9 @@ export function registerFreshContextCommands(program, io) {
             printResult(io, ok('fresh-context.preflight', result), options.json);
         }
         catch (error) {
-            printResult(io, fail('fresh-context.preflight', 'PREFLIGHT_FAILED', getErrorMessage(error), {}, ['Verify ~/.peaks/config.json is valid JSON']), options.json);
+            printResult(io, fail('fresh-context.preflight', 'PREFLIGHT_FAILED', getErrorMessage(error), {}, [
+                'Verify ~/.peaks/config.json is valid JSON'
+            ]), options.json);
             process.exitCode = 1;
         }
     });

package/dist/cli/commands/gate-commands-enforce.d.ts

@@ -0,0 +1,82 @@
+import { type EnforceDecision } from '../../services/sop/gate-enforce-service.js';
+import { type ToolCallKind } from '../../services/hooks/worktree-authorization-gate.js';
+import { type ProgramIO } from '../cli-helpers.js';
+export type GateEnforceCliOptions = {
+    project: string;
+    json?: boolean;
+};
+/** The SOP deny variant of the enforcement decision. */
+type SopDeny = Extract<EnforceDecision, {
+    decision: 'deny';
+}>;
+/** The SOP allow variant of the enforcement decision. */
+type SopAllow = Extract<EnforceDecision, {
+    decision: 'allow';
+}>;
+/**
+ * Parse the raw stdin payload, failing open to `null` on malformed JSON.
+ */
+export declare function parseHookStdin(raw: string): unknown;
+/**
+ * Map Claude Code tool name to the gate's internal `ToolCallKind`. Anything we don't recognize
+ * returns `'Other'` — the worktree gate is opt-in by tool, so unknown tools short-circuit to allow.
+ */
+export declare function classifyTool(toolName: string | undefined): ToolCallKind;
+/**
+ * Detect the IDE + adapter and return the adapter's tool matcher. For slice #1 only the Claude
+ * adapter is registered, so the payload parser is Claude-shaped. Future slices dispatch on `ide`
+ * to pick a per-adapter parser; the parser entry-point (`parseXxxShapeStdin`) is the only change
+ * required.
+ *
+ * The Bash-surface predicate itself stays in `runGateEnforceAction`: TypeScript's aliased-condition
+ * narrowing needs `isBashSurface` (which embeds `typeof command === 'string'`) computed in the same
+ * scope where `command` is later read, so the extraction stops at the adapter lookup.
+ */
+export declare function resolveToolMatcher(parsedStdin: unknown): string;
+/**
+ * Run the fail-closed worktree authorization gate for a gated tool kind. Returns `true` when the
+ * call was denied (a hard block has already been emitted and the handler must stop) and `false`
+ * when the flow should continue to the SOP gate. `Other` tool kinds are not gated at all.
+ *
+ * slice 2026-07-27-worktree-user-auth: BEFORE the SOP gate runs, check the worktree authorization
+ * gate. The worktree gate is narrower than the SOP gate (it only inspects a small set of
+ * worktree-mutating operations) and is fail-CLOSED. The two layers are complementary: SOP gates
+ * decide "may this command run under this SOP's state", the worktree gate decides "did the user
+ * explicitly authorize this worktree-mutating operation in the current task". The worktree gate is
+ * cheap and self-contained, so it runs first to give the LLM a clear error reason before the SOP
+ * gate would otherwise allow.
+ *
+ * wtDecision may have arrived via lease (viaLease != null); the SOP gate does not care which path
+ * granted, only that the worktree gate said allow.
+ */
+export declare function handleWorktreeGate(io: ProgramIO, options: GateEnforceCliOptions, toolKind: ToolCallKind, payload: {
+    command: string | undefined;
+    parsedStdin: unknown;
+}): boolean;
+/**
+ * Not a guarded surface — allow. Emit minimal JSON on stdout so Claude Code's PreToolUse hook
+ * validator accepts the response. Empty stdout is rejected with "Hook JSON output validation
+ * failed — Invalid input" in Claude Code 2.x; `{}` is the canonical no-op marker.
+ */
+export declare function emitAllowSkipped(io: ProgramIO, options: GateEnforceCliOptions): void;
+/** Worktree gate allowed and this is not a Bash surface — allow without running the SOP gate. */
+export declare function emitAllowWorktree(io: ProgramIO, options: GateEnforceCliOptions): void;
+/**
+ * PRD#2 (2026-06-16-fact-forcing-gate-format): a true SOP gate failure is a HARD block. emitBlock
+ * writes the Claude Code permissionDecision:"deny" JSON to stdout (the hook's decision signal),
+ * sets process.exitCode = 2 (Claude Code's block exit code), AND surfaces the reason to stderr so
+ * the LLM sees it on the next turn. This prevents the previous behaviour where Claude Code wrapped
+ * the output as "PreToolUse:Bash hook error".
+ */
+export declare function emitSopDeny(io: ProgramIO, options: GateEnforceCliOptions, decision: SopDeny): void;
+/** Surface any SOP-gate warnings as hints before the allow decision is emitted. */
+export declare function emitSopWarnings(io: ProgramIO, decision: SopAllow): void;
+/**
+ * SOP gate allowed the command. --json mode emits the canonical envelope on stdout (the documented
+ * contract for downstream tooling). The hook decision (allow/deny) is still signalled via
+ * process.exitCode + the minimal `{}` on stdout in non-`--json` mode. Slice 2026-07-30-nightshift:
+ * emitHint here was wrong — emitHint writes to stderr, but the AC5 contract expects the JSON
+ * envelope on stdout. Switch to printResult(asJson=true).
+ */
+export declare function emitSopAllow(io: ProgramIO, options: GateEnforceCliOptions, decision: SopAllow): void;
+export {};