peaks-loop 4.0.54 → 4.1.0

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

@@ -22,14 +22,14 @@
  * rules (AC-8 / AC-10 / AC-11); the CLI only translates flags
  * into the service payload.
  */
-import { existsSync, mkdirSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { openStateDb } from "../../services/skillhub/sqlite-store.js";
-import { EvolutionService, EvolutionIntegrityError, } from "../../services/evolution/evolution-service.js";
-import { EVOLUTION_TARGET_KINDS, } from "../../services/evolution/evolution-types.js";
-import { findProjectRoot } from "../../services/config/config-safety.js";
-import { runIndependentEvaluator, } from "../../services/evolution/independent-evaluator-runner.js";
-import { addJsonOption, getErrorMessage, printResult } from "../cli-helpers.js";
+import { existsSync, mkdirSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { openStateDb } from '../../services/skillhub/sqlite-store.js';
+import { EvolutionService, EvolutionIntegrityError } from '../../services/evolution/evolution-service.js';
+import { EVOLUTION_TARGET_KINDS } from '../../services/evolution/evolution-types.js';
+import { findProjectRoot } from '../../services/config/config-safety.js';
+import { runIndependentEvaluator } from '../../services/evolution/independent-evaluator-runner.js';
+import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { fail, ok } from 'peaks-loop-shared/result';
 /**
  * Parse `--target <kind:id>`. Returns the kind + id, or `null` on
@@ -37,7 +37,7 @@ import { fail, ok } from 'peaks-loop-shared/result';
  * union.
  */
 function parseTargetFlag(raw) {
-    const idx = raw.indexOf(":");
+    const idx = raw.indexOf(':');
     if (idx <= 0 || idx === raw.length - 1)
         return null;
     const kind = raw.slice(0, idx);
@@ -50,24 +50,27 @@ export function registerEvolutionCommands(program, io) {
     // Reuse the existing `evolution` parent if one is registered;
     // otherwise create it. The add-a-new-subcommand-check-for-existing-
     // top-level-first rule requires this guard.
-    const existing = program.commands.find((c) => c.name() === "evolution");
-    const evolution = existing ?? program.command("evolution").description("Darwin-style ratchet: propose / evaluate / revert / status (spec §6)");
+    const existing = program.commands.find((c) => c.name() === 'evolution');
+    const evolution = existing ??
+        program
+            .command('evolution')
+            .description('Darwin-style ratchet: propose / evaluate / revert / status (spec §6)');
     // peaks evolution propose
     addJsonOption(evolution
-        .command("propose")
+        .command('propose')
         .description("M4: persist a new evolution proposal. Enforces AC-8 (single object + single dimension). The proposal's verdict starts at 'needs-user-decision' until the scoring + skeptic step lands.")
-        .requiredOption("--target <kind:id>", "target asset, e.g. 'loop:loop-onboarding-research' or 'bee:42'")
-        .requiredOption("--dimension <name>", "single optimization dimension (e.g. 'clarity')")
-        .requiredOption("--before-score <n>", "score on the 0..10 scale BEFORE the change")
-        .requiredOption("--after-score <n>", "score on the 0..10 scale AFTER the change (LLM-claimed)")
-        .option("--delta-min <n>", `minimum score delta for promotion (default: 1.0; spec §6.1 #5)`, "1.0")
-        .requiredOption("--author <id>", "author agent id (the LLM proposing the change)")
-        .option("--brief-pointer <ptr>", "pointer to the evidence brief used in the recommendation (spec §4.7 / §4.4)")
-        .option("--project <path>", "project root (default: cwd)")).action((options) => {
+        .requiredOption('--target <kind:id>', "target asset, e.g. 'loop:loop-onboarding-research' or 'bee:42'")
+        .requiredOption('--dimension <name>', "single optimization dimension (e.g. 'clarity')")
+        .requiredOption('--before-score <n>', 'score on the 0..10 scale BEFORE the change')
+        .requiredOption('--after-score <n>', 'score on the 0..10 scale AFTER the change (LLM-claimed)')
+        .option('--delta-min <n>', `minimum score delta for promotion (default: 1.0; spec §6.1 #5)`, '1.0')
+        .requiredOption('--author <id>', 'author agent id (the LLM proposing the change)')
+        .option('--brief-pointer <ptr>', 'pointer to the evidence brief used in the recommendation (spec §4.7 / §4.4)')
+        .option('--project <path>', 'project root (default: cwd)')).action((options) => {
         try {
             const target = parseTargetFlag(options.target);
             if (!target) {
-                printResult(io, fail("evolution.propose", "EVOLUTION_INVALID_TARGET", `--target must be '<kind>:<id>' where kind ∈ {${EVOLUTION_TARGET_KINDS.join(",")}}`, { target: options.target }, ["Pass --target loop:<loop-id> or --target bee:<bee-id>."]), options.json);
+                printResult(io, fail('evolution.propose', 'EVOLUTION_INVALID_TARGET', `--target must be '<kind>:<id>' where kind ∈ {${EVOLUTION_TARGET_KINDS.join(',')}}`, { target: options.target }, ['Pass --target loop:<loop-id> or --target bee:<bee-id>.']), options.json);
                 process.exitCode = 1;
                 return;
             }
@@ -75,27 +78,27 @@ export function registerEvolutionCommands(program, io) {
             const after = Number(options.afterScore);
             const deltaMin = Number(options.deltaMin);
             if (!Number.isFinite(before) || before < 0 || before > 10) {
-                printResult(io, fail("evolution.propose", "EVOLUTION_INVALID_BEFORE_SCORE", `before_score must be a finite number in [0, 10] (got "${options.beforeScore}")`, { beforeScore: options.beforeScore }, ["Pass a numeric --before-score in [0, 10]."]), options.json);
+                printResult(io, fail('evolution.propose', 'EVOLUTION_INVALID_BEFORE_SCORE', `before_score must be a finite number in [0, 10] (got "${options.beforeScore}")`, { beforeScore: options.beforeScore }, ['Pass a numeric --before-score in [0, 10].']), options.json);
                 process.exitCode = 1;
                 return;
             }
             if (!Number.isFinite(after) || after < 0 || after > 10) {
-                printResult(io, fail("evolution.propose", "EVOLUTION_INVALID_AFTER_SCORE", `after_score must be a finite number in [0, 10] (got "${options.afterScore}")`, { afterScore: options.afterScore }, ["Pass a numeric --after-score in [0, 10]."]), options.json);
+                printResult(io, fail('evolution.propose', 'EVOLUTION_INVALID_AFTER_SCORE', `after_score must be a finite number in [0, 10] (got "${options.afterScore}")`, { afterScore: options.afterScore }, ['Pass a numeric --after-score in [0, 10].']), options.json);
                 process.exitCode = 1;
                 return;
             }
             if (!Number.isFinite(deltaMin) || deltaMin < 0) {
-                printResult(io, fail("evolution.propose", "EVOLUTION_INVALID_DELTA_MIN", `delta_min must be a finite number >= 0 (got "${options.deltaMin}")`, { deltaMin: options.deltaMin }, ["Pass a numeric --delta-min >= 0 (default 1.0)."]), options.json);
+                printResult(io, fail('evolution.propose', 'EVOLUTION_INVALID_DELTA_MIN', `delta_min must be a finite number >= 0 (got "${options.deltaMin}")`, { deltaMin: options.deltaMin }, ['Pass a numeric --delta-min >= 0 (default 1.0).']), options.json);
                 process.exitCode = 1;
                 return;
             }
             const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-            if (!existsSync(join(projectRoot, ".peaks"))) {
+            if (!existsSync(join(projectRoot, '.peaks'))) {
                 // The CLI is allowed to bootstrap an empty .peaks dir so
                 // tests do not need a full peaks project.
-                mkdirSync(join(projectRoot, ".peaks"), { recursive: true });
+                mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
             }
-            const db = openStateDb(join(projectRoot, ".peaks", "state.db"));
+            const db = openStateDb(join(projectRoot, '.peaks', 'state.db'));
             try {
                 const svc = new EvolutionService(db);
                 const input = {
@@ -113,10 +116,10 @@ export function registerEvolutionCommands(program, io) {
                     single_optimization_dimension: true,
                     rubric: {},
                     red_lines: [],
-                    source_traces: [],
+                    source_traces: []
                 };
                 const proposal = svc.createProposal(input);
-                printResult(io, ok("evolution.propose", {
+                printResult(io, ok('evolution.propose', {
                     proposal: {
                         id: proposal.id,
                         target_kind: proposal.target_kind,
@@ -127,12 +130,14 @@ export function registerEvolutionCommands(program, io) {
                         score_delta: proposal.score_delta,
                         score_delta_min: proposal.score_delta_min,
                         author_id: proposal.author_id,
-                        verdict: "needs-user-decision",
-                        ...(options.briefPointer !== undefined ? { brief_pointer: options.briefPointer } : {}),
+                        verdict: 'needs-user-decision',
+                        ...(options.briefPointer !== undefined
+                            ? { brief_pointer: options.briefPointer }
+                            : {})
                     },
                     nextActions: [
-                        `Run \`peaks evolution evaluate --proposal ${proposal.id} --evaluator <id> --skeptic <id> --evaluator-score <n> --json\` to score the proposal.`,
-                    ],
+                        `Run \`peaks evolution evaluate --proposal ${proposal.id} --evaluator <id> --skeptic <id> --evaluator-score <n> --json\` to score the proposal.`
+                    ]
                 }, [], []), options.json);
             }
             finally {
@@ -141,48 +146,48 @@ export function registerEvolutionCommands(program, io) {
         }
         catch (err) {
             if (err instanceof EvolutionIntegrityError) {
-                printResult(io, fail("evolution.propose", err.code, err.message, { findings: err.findings }, [
-                    "Re-shape the proposal per spec §6: single object, single dimension, separate scorer.",
-                    "If you intended a multi-object change, split it into multiple rounds.",
+                printResult(io, fail('evolution.propose', err.code, err.message, { findings: err.findings }, [
+                    'Re-shape the proposal per spec §6: single object, single dimension, separate scorer.',
+                    'If you intended a multi-object change, split it into multiple rounds.'
                 ]), options.json);
                 process.exitCode = 1;
                 return;
             }
-            printResult(io, fail("evolution.propose", "EVOLUTION_PROPOSE_FAILED", getErrorMessage(err), {}, [
-                "Verify the target flag and dimension."
+            printResult(io, fail('evolution.propose', 'EVOLUTION_PROPOSE_FAILED', getErrorMessage(err), {}, [
+                'Verify the target flag and dimension.'
             ]), options.json);
             process.exitCode = 1;
         }
     });
     // peaks evolution evaluate
     addJsonOption(evolution
-        .command("evaluate")
+        .command('evaluate')
         .description("M4: score a proposal with an independent evaluator (AC-12/AC-13) and a regression skeptic (AC-14). The result is the FINAL verdict: 'keep' (after user confirmation), 'revert' (skeptic blocker or score delta below threshold), or 'needs-user-decision'.")
-        .requiredOption("--proposal <id>", "proposal id returned by `peaks evolution propose`")
-        .requiredOption("--evaluator <id>", "independent scorer id (MUST differ from --author; AC-10)")
-        .requiredOption("--skeptic <id>", "regression skeptic id (MUST differ from --evaluator and --author; AC-12/AC-14)")
-        .requiredOption("--evaluator-score <n>", "the independent scorer's score on the 0..10 scale (LLM-derived; NOT the author's after_score)")
-        .option("--refute-paragraph <text>", "the independent scorer's one-paragraph refute (LLM-authored)", "")
-        .option("--risk-tag <tag>", "add a risk tag emitted by the evaluator (repeatable)", collectRepeatable, [])
-        .option("--brief-pointer <ptr>", "pointer to the evidence brief (spec §4.7 / §4.4)")
-        .option("--project <path>", "project root (default: cwd)")).action(async (options) => {
+        .requiredOption('--proposal <id>', 'proposal id returned by `peaks evolution propose`')
+        .requiredOption('--evaluator <id>', 'independent scorer id (MUST differ from --author; AC-10)')
+        .requiredOption('--skeptic <id>', 'regression skeptic id (MUST differ from --evaluator and --author; AC-12/AC-14)')
+        .requiredOption('--evaluator-score <n>', "the independent scorer's score on the 0..10 scale (LLM-derived; NOT the author's after_score)")
+        .option('--refute-paragraph <text>', "the independent scorer's one-paragraph refute (LLM-authored)", '')
+        .option('--risk-tag <tag>', 'add a risk tag emitted by the evaluator (repeatable)', collectRepeatable, [])
+        .option('--brief-pointer <ptr>', 'pointer to the evidence brief (spec §4.7 / §4.4)')
+        .option('--project <path>', 'project root (default: cwd)')).action(async (options) => {
         try {
             const score = Number(options.evaluatorScore);
             if (!Number.isFinite(score) || score < 0 || score > 10) {
-                printResult(io, fail("evolution.evaluate", "EVOLUTION_INVALID_EVALUATOR_SCORE", `evaluator-score must be a finite number in [0, 10] (got "${options.evaluatorScore}")`, { evaluatorScore: options.evaluatorScore }, ["Pass a numeric --evaluator-score in [0, 10]."]), options.json);
+                printResult(io, fail('evolution.evaluate', 'EVOLUTION_INVALID_EVALUATOR_SCORE', `evaluator-score must be a finite number in [0, 10] (got "${options.evaluatorScore}")`, { evaluatorScore: options.evaluatorScore }, ['Pass a numeric --evaluator-score in [0, 10].']), options.json);
                 process.exitCode = 1;
                 return;
             }
             const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-            if (!existsSync(join(projectRoot, ".peaks"))) {
-                mkdirSync(join(projectRoot, ".peaks"), { recursive: true });
+            if (!existsSync(join(projectRoot, '.peaks'))) {
+                mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
             }
-            const db = openStateDb(join(projectRoot, ".peaks", "state.db"));
+            const db = openStateDb(join(projectRoot, '.peaks', 'state.db'));
             try {
                 const svc = new EvolutionService(db);
                 const proposal = svc.read(options.proposal);
                 if (!proposal) {
-                    printResult(io, fail("evolution.evaluate", "EVOLUTION_PROPOSAL_NOT_FOUND", `proposal '${options.proposal}' not found`, { proposalId: options.proposal }, ["Verify the proposal id and that you have run `peaks evolution propose` first."]), options.json);
+                    printResult(io, fail('evolution.evaluate', 'EVOLUTION_PROPOSAL_NOT_FOUND', `proposal '${options.proposal}' not found`, { proposalId: options.proposal }, ['Verify the proposal id and that you have run `peaks evolution propose` first.']), options.json);
                     process.exitCode = 1;
                     return;
                 }
@@ -196,10 +201,7 @@ export function registerEvolutionCommands(program, io) {
                     evaluatorResult.refuteParagraph = options.refuteParagraph;
                 }
                 if (Array.isArray(options.riskTag) && options.riskTag.length > 0) {
-                    evaluatorResult.riskTags = [
-                        ...evaluatorResult.riskTags,
-                        ...options.riskTag,
-                    ];
+                    evaluatorResult.riskTags = [...evaluatorResult.riskTags, ...options.riskTag];
                 }
                 const evaluation = svc.score(options.proposal, {
                     evaluator_id: options.evaluator,
@@ -208,11 +210,11 @@ export function registerEvolutionCommands(program, io) {
                     skeptic_result: {
                         driftRisks: [],
                         overfitRisks: [],
-                        safetyRegressionRisks: [],
+                        safetyRegressionRisks: []
                     },
-                    ...(options.briefPointer !== undefined ? { brief_pointer: options.briefPointer } : {}),
+                    ...(options.briefPointer !== undefined ? { brief_pointer: options.briefPointer } : {})
                 });
-                printResult(io, ok("evolution.evaluate", {
+                printResult(io, ok('evolution.evaluate', {
                     proposalId: evaluation.id,
                     verdict: evaluation.verdict,
                     evaluator_id: evaluation.evaluator_id,
@@ -222,19 +224,19 @@ export function registerEvolutionCommands(program, io) {
                     score_delta: evaluation.proposal.score_delta,
                     score_delta_min: evaluation.proposal.score_delta_min,
                     after_score: evaluation.proposal.after_score,
-                    nextActions: evaluation.verdict === "needs-user-decision"
+                    nextActions: evaluation.verdict === 'needs-user-decision'
                         ? [
-                            `User confirmation required. Run \`peaks evolution mark-keep --proposal ${evaluation.id} --user-confirmation <ptr> --json\` after the user picks "keep", OR \`peaks evolution revert --proposal ${evaluation.id} --json\`.`,
+                            `User confirmation required. Run \`peaks evolution mark-keep --proposal ${evaluation.id} --user-confirmation <ptr> --json\` after the user picks "keep", OR \`peaks evolution revert --proposal ${evaluation.id} --json\`.`
                         ]
-                        : evaluation.verdict === "revert"
+                        : evaluation.verdict === 'revert'
                             ? [
-                                "Proposal reverted. Investigate the skeptic blocker or the score delta below threshold.",
+                                'Proposal reverted. Investigate the skeptic blocker or the score delta below threshold.'
                             ]
                             : [
-                                "Proposal kept. The target asset remains unchanged on disk; full promotion lands in a later slice.",
-                            ],
+                                'Proposal kept. The target asset remains unchanged on disk; full promotion lands in a later slice.'
+                            ]
                 }, [], []), options.json);
-                if (evaluation.verdict === "revert")
+                if (evaluation.verdict === 'revert')
                     process.exitCode = 1;
             }
             finally {
@@ -243,45 +245,43 @@ export function registerEvolutionCommands(program, io) {
         }
         catch (err) {
             if (err instanceof EvolutionIntegrityError) {
-                printResult(io, fail("evolution.evaluate", err.code, err.message, { findings: err.findings }, [
-                    "Re-shape per spec §6: evaluator and skeptic MUST be separate from the author; the score delta MUST be >= score_delta_min for keep.",
+                printResult(io, fail('evolution.evaluate', err.code, err.message, { findings: err.findings }, [
+                    'Re-shape per spec §6: evaluator and skeptic MUST be separate from the author; the score delta MUST be >= score_delta_min for keep.'
                 ]), options.json);
                 process.exitCode = 1;
                 return;
             }
-            printResult(io, fail("evolution.evaluate", "EVOLUTION_EVALUATE_FAILED", getErrorMessage(err), { proposalId: options.proposal }, [
-                "Verify the proposal id and the evaluator / skeptic ids.",
-            ]), options.json);
+            printResult(io, fail('evolution.evaluate', 'EVOLUTION_EVALUATE_FAILED', getErrorMessage(err), { proposalId: options.proposal }, ['Verify the proposal id and the evaluator / skeptic ids.']), options.json);
             process.exitCode = 1;
         }
     });
     // peaks evolution mark-keep — explicit user confirmation.
     addJsonOption(evolution
-        .command("mark-keep")
-        .description("M4: explicit user-confirmed `keep` verdict. Requires --user-confirmation <ptr> and a score_delta >= score_delta_min (AC-11/AC-15).")
-        .requiredOption("--proposal <id>", "proposal id")
-        .option("--user-confirmation <ptr>", "pointer to the user choice record (AC-15) — omit to surface the EVOLUTION_MISSING_USER_CONFIRMATION service-layer error")
-        .option("--project <path>", "project root (default: cwd)")).action((options) => {
+        .command('mark-keep')
+        .description('M4: explicit user-confirmed `keep` verdict. Requires --user-confirmation <ptr> and a score_delta >= score_delta_min (AC-11/AC-15).')
+        .requiredOption('--proposal <id>', 'proposal id')
+        .option('--user-confirmation <ptr>', 'pointer to the user choice record (AC-15) — omit to surface the EVOLUTION_MISSING_USER_CONFIRMATION service-layer error')
+        .option('--project <path>', 'project root (default: cwd)')).action((options) => {
         try {
             const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-            if (!existsSync(join(projectRoot, ".peaks"))) {
-                mkdirSync(join(projectRoot, ".peaks"), { recursive: true });
+            if (!existsSync(join(projectRoot, '.peaks'))) {
+                mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
             }
-            const db = openStateDb(join(projectRoot, ".peaks", "state.db"));
+            const db = openStateDb(join(projectRoot, '.peaks', 'state.db'));
             try {
                 const svc = new EvolutionService(db);
-                const updated = svc.markVerdict(options.proposal, "keep", options.userConfirmation);
+                const updated = svc.markVerdict(options.proposal, 'keep', options.userConfirmation);
                 if (!updated) {
-                    printResult(io, fail("evolution.mark-keep", "EVOLUTION_PROPOSAL_NOT_FOUND", `proposal '${options.proposal}' not found`, { proposalId: options.proposal }, ["Verify the proposal id."]), options.json);
+                    printResult(io, fail('evolution.mark-keep', 'EVOLUTION_PROPOSAL_NOT_FOUND', `proposal '${options.proposal}' not found`, { proposalId: options.proposal }, ['Verify the proposal id.']), options.json);
                     process.exitCode = 1;
                     return;
                 }
-                printResult(io, ok("evolution.mark-keep", {
+                printResult(io, ok('evolution.mark-keep', {
                     proposalId: updated.id,
                     verdict: updated.verdict,
                     user_confirmation_pointer: updated.user_confirmation_pointer ?? null,
                     score_delta: updated.proposal.score_delta,
-                    score_delta_min: updated.proposal.score_delta_min,
+                    score_delta_min: updated.proposal.score_delta_min
                 }, [], []), options.json);
             }
             finally {
@@ -290,43 +290,41 @@ export function registerEvolutionCommands(program, io) {
         }
         catch (err) {
             if (err instanceof EvolutionIntegrityError) {
-                printResult(io, fail("evolution.mark-keep", err.code, err.message, { findings: err.findings }, [
-                    "Re-shape the proposal or the score so score_delta >= score_delta_min.",
+                printResult(io, fail('evolution.mark-keep', err.code, err.message, { findings: err.findings }, [
+                    'Re-shape the proposal or the score so score_delta >= score_delta_min.'
                 ]), options.json);
                 process.exitCode = 1;
                 return;
             }
-            printResult(io, fail("evolution.mark-keep", "EVOLUTION_MARK_KEEP_FAILED", getErrorMessage(err), { proposalId: options.proposal }, [
-                "Verify the proposal id.",
-            ]), options.json);
+            printResult(io, fail('evolution.mark-keep', 'EVOLUTION_MARK_KEEP_FAILED', getErrorMessage(err), { proposalId: options.proposal }, ['Verify the proposal id.']), options.json);
             process.exitCode = 1;
         }
     });
     // peaks evolution revert
     addJsonOption(evolution
-        .command("revert")
-        .description("M4: revert a proposal (universal recovery; spec §6.1 #8). Always allowed; the user may supply --user-confirmation for audit.")
-        .requiredOption("--proposal <id>", "proposal id")
-        .option("--user-confirmation <ptr>", "optional pointer to the user choice record")
-        .option("--project <path>", "project root (default: cwd)")).action((options) => {
+        .command('revert')
+        .description('M4: revert a proposal (universal recovery; spec §6.1 #8). Always allowed; the user may supply --user-confirmation for audit.')
+        .requiredOption('--proposal <id>', 'proposal id')
+        .option('--user-confirmation <ptr>', 'optional pointer to the user choice record')
+        .option('--project <path>', 'project root (default: cwd)')).action((options) => {
         try {
             const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-            if (!existsSync(join(projectRoot, ".peaks"))) {
-                mkdirSync(join(projectRoot, ".peaks"), { recursive: true });
+            if (!existsSync(join(projectRoot, '.peaks'))) {
+                mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
             }
-            const db = openStateDb(join(projectRoot, ".peaks", "state.db"));
+            const db = openStateDb(join(projectRoot, '.peaks', 'state.db'));
             try {
                 const svc = new EvolutionService(db);
                 const updated = svc.revert(options.proposal, options.userConfirmation);
                 if (!updated) {
-                    printResult(io, fail("evolution.revert", "EVOLUTION_PROPOSAL_NOT_FOUND", `proposal '${options.proposal}' not found`, { proposalId: options.proposal }, ["Verify the proposal id."]), options.json);
+                    printResult(io, fail('evolution.revert', 'EVOLUTION_PROPOSAL_NOT_FOUND', `proposal '${options.proposal}' not found`, { proposalId: options.proposal }, ['Verify the proposal id.']), options.json);
                     process.exitCode = 1;
                     return;
                 }
-                printResult(io, ok("evolution.revert", {
+                printResult(io, ok('evolution.revert', {
                     proposalId: updated.id,
                     verdict: updated.verdict,
-                    user_confirmation_pointer: updated.user_confirmation_pointer ?? null,
+                    user_confirmation_pointer: updated.user_confirmation_pointer ?? null
                 }, [], []), options.json);
             }
             finally {
@@ -334,46 +332,42 @@ export function registerEvolutionCommands(program, io) {
             }
         }
         catch (err) {
-            printResult(io, fail("evolution.revert", "EVOLUTION_REVERT_FAILED", getErrorMessage(err), { proposalId: options.proposal }, [
-                "Verify the proposal id.",
-            ]), options.json);
+            printResult(io, fail('evolution.revert', 'EVOLUTION_REVERT_FAILED', getErrorMessage(err), { proposalId: options.proposal }, ['Verify the proposal id.']), options.json);
             process.exitCode = 1;
         }
     });
     // peaks evolution status
     addJsonOption(evolution
-        .command("status")
-        .description("M4: read the status snapshot for a target (counts of evaluations by verdict + latest evaluation id).")
-        .requiredOption("--target <kind:id>", "target asset, e.g. 'loop:loop-onboarding-research'")
-        .option("--project <path>", "project root (default: cwd)")).action((options) => {
+        .command('status')
+        .description('M4: read the status snapshot for a target (counts of evaluations by verdict + latest evaluation id).')
+        .requiredOption('--target <kind:id>', "target asset, e.g. 'loop:loop-onboarding-research'")
+        .option('--project <path>', 'project root (default: cwd)')).action((options) => {
         try {
             const target = parseTargetFlag(options.target);
             if (!target) {
-                printResult(io, fail("evolution.status", "EVOLUTION_INVALID_TARGET", `--target must be '<kind>:<id>' where kind ∈ {${EVOLUTION_TARGET_KINDS.join(",")}}`, { target: options.target }, ["Pass --target loop:<loop-id> or --target bee:<bee-id>."]), options.json);
+                printResult(io, fail('evolution.status', 'EVOLUTION_INVALID_TARGET', `--target must be '<kind>:<id>' where kind ∈ {${EVOLUTION_TARGET_KINDS.join(',')}}`, { target: options.target }, ['Pass --target loop:<loop-id> or --target bee:<bee-id>.']), options.json);
                 process.exitCode = 1;
                 return;
             }
             const projectRoot = options.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
-            if (!existsSync(join(projectRoot, ".peaks"))) {
-                mkdirSync(join(projectRoot, ".peaks"), { recursive: true });
+            if (!existsSync(join(projectRoot, '.peaks'))) {
+                mkdirSync(join(projectRoot, '.peaks'), { recursive: true });
             }
-            const db = openStateDb(join(projectRoot, ".peaks", "state.db"));
+            const db = openStateDb(join(projectRoot, '.peaks', 'state.db'));
             try {
                 const svc = new EvolutionService(db);
                 const status = svc.status({
                     target_kind: target.kind,
-                    target_release_id: target.id,
+                    target_release_id: target.id
                 });
-                printResult(io, ok("evolution.status", status, [], []), options.json);
+                printResult(io, ok('evolution.status', status, [], []), options.json);
             }
             finally {
                 db.close();
             }
         }
         catch (err) {
-            printResult(io, fail("evolution.status", "EVOLUTION_STATUS_FAILED", getErrorMessage(err), { target: options.target }, [
-                "Verify the target flag.",
-            ]), options.json);
+            printResult(io, fail('evolution.status', 'EVOLUTION_STATUS_FAILED', getErrorMessage(err), { target: options.target }, ['Verify the target flag.']), options.json);
             process.exitCode = 1;
         }
     });

package/dist/cli/commands/feedback-commands-helpers.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Support constants + option schema + hint renderer extracted verbatim from
+ * `feedback-commands.ts` (file-size cap campaign). Mechanical move only: the
+ * command descriptions, the promote action option schema, the two next-action
+ * lists, and the exempt-entries hint line.
+ */
+export declare const FEEDBACK_PARENT_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).";
+export declare const PROMOTE_DESCRIPTION: string;
+export declare const CHECK_UNPROMOTED_DESCRIPTION: string;
+export interface FeedbackPromoteOpts {
+    layer?: string;
+    project?: string;
+    promotedBy?: string;
+    dryRun?: boolean;
+    json?: boolean;
+}
+export declare const NO_LAYER_NEXT_ACTIONS: string[];
+export declare const UNPROMOTED_NEXT_ACTIONS: string[];
+export declare function formatExemptHint(exempt: readonly {
+    name: string;
+    code: string;
+}[]): string;

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

@@ -0,0 +1,33 @@
+/**
+ * Support constants + option schema + hint renderer extracted verbatim from
+ * `feedback-commands.ts` (file-size cap campaign). Mechanical move only: the
+ * command descriptions, the promote action option schema, the two next-action
+ * lists, and the exempt-entries hint line.
+ */
+export const FEEDBACK_PARENT_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).';
+export const PROMOTE_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).';
+export const 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.';
+export const NO_LAYER_NEXT_ACTIONS = [
+    '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.'
+];
+export const UNPROMOTED_NEXT_ACTIONS = [
+    `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.'
+];
+export function formatExemptHint(exempt) {
+    return `${exempt.length} memor${exempt.length === 1 ? 'y' : 'ies'} declare themselves not-to-be-promoted: ${exempt.map((e) => `${e.name} (${e.code})`).join('; ')}.`;
+}

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);