peaks-loop 4.0.23 → 4.0.25

package/dist/services/job/job-types.js

@@ -8,12 +8,32 @@ export const SliceStateSchema = z
     commitSha: z.string().optional(), // required when status=done
     finishedAt: z.string().datetime().optional(),
     failureReason: z.string().optional(), // required when status=failed
-    repairCycles: z.number().int().nonnegative().default(0),
+    repairCycles: z.number().int().gte(0).default(0),
     blockedReason: z.string().optional(), // required when status=blocked
 })
-    .refine((v) => v.status !== 'done' || !!(v.commitSha && v.commitSha.length >= 7), { message: 'commitSha required (≥7 hex) when status=done', path: ['commitSha'] })
-    .refine((v) => v.status !== 'failed' || !!(v.failureReason && v.failureReason.length >= 1), { message: 'failureReason required when status=failed', path: ['failureReason'] })
-    .refine((v) => v.status !== 'blocked' || !!(v.blockedReason && v.blockedReason.length >= 1), { message: 'blockedReason required when status=blocked', path: ['blockedReason'] });
+    .superRefine((v, ctx) => {
+    if (v.status === 'done' && !(v.commitSha && v.commitSha.length >= 7)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['commitSha'],
+            message: 'commitSha required (≥7 hex) when status=done',
+        });
+    }
+    if (v.status === 'failed' && !(v.failureReason && v.failureReason.length >= 1)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['failureReason'],
+            message: 'failureReason required when status=failed',
+        });
+    }
+    if (v.status === 'blocked' && !(v.blockedReason && v.blockedReason.length >= 1)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['blockedReason'],
+            message: 'blockedReason required when status=blocked',
+        });
+    }
+});
 export const JobStateSchema = z.object({
     jobId: z.string(),
     sessionId: z.string(),
@@ -22,8 +42,8 @@ export const JobStateSchema = z.object({
     parallelismHint: z.enum(['serial', 'llm-decides']).default('llm-decides'),
     exitPolicy: z.enum(['strict', 'best-effort']).default('strict'),
     mainLoopStrategy: z.enum(['single', 'rotating']).default('rotating'),
-    rotateEvery: z.number().int().positive().default(3),
-    mainSessionCycle: z.number().int().nonnegative().default(0),
+    rotateEvery: z.number().int().gt(0).default(3),
+    mainSessionCycle: z.number().int().gte(0).default(0),
     mainLoopOverride: z
         .object({
         from: z.literal('rotating'),
@@ -37,8 +57,8 @@ export const JobStateSchema = z.object({
 export const ResourceSnapshotSchema = z.object({
     capturedAt: z.string().datetime(),
     cpuPercent: z.number().min(0).max(100),
-    memMb: z.number().nonnegative(),
-    diskMb: z.number().nonnegative(),
+    memMb: z.number().gte(0),
+    diskMb: z.number().gte(0),
     contextRatio: z.number().min(0).max(1),
 });
 export const JobStatusSummarySchema = z.object({
@@ -62,7 +82,7 @@ export const JobInitInputSchema = z.object({
     parallelismHint: z.enum(['serial', 'llm-decides']).default('llm-decides'),
     exitPolicy: z.enum(['strict', 'best-effort']).default('strict'),
     mainLoopStrategy: z.enum(['single', 'rotating']).default('rotating'),
-    rotateEvery: z.number().int().positive().default(3),
+    rotateEvery: z.number().int().gt(0).default(3),
     project: z.string(),
     json: z.boolean().default(true),
 });
@@ -76,8 +96,23 @@ export const JobCheckpointInputSchema = z
     project: z.string(),
     json: z.boolean().default(true),
 })
-    .refine((v) => v.state !== 'done' || (v.commitSha && v.commitSha.length >= 7), { message: 'commitSha required (≥7 hex) when state=done', path: ['commitSha'] })
-    .refine((v) => v.state !== 'failed' && v.state !== 'skipped' ? true : !!(v.reason && v.reason.length >= 3), { message: 'reason required (≥3 chars) when state=failed|skipped', path: ['reason'] });
+    .superRefine((v, ctx) => {
+    if (v.state === 'done' && !(v.commitSha && v.commitSha.length >= 7)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['commitSha'],
+            message: 'commitSha required (≥7 hex) when state=done',
+        });
+    }
+    if ((v.state === 'failed' || v.state === 'skipped') &&
+        !(v.reason && v.reason.length >= 3)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['reason'],
+            message: 'reason required (≥3 chars) when state=failed|skipped',
+        });
+    }
+});
 export const JobBlockInputSchema = z.object({
     jobId: z.string(),
     sliceId: z.string(),

package/dist/services/loop/loop-bee-relation-types.d.ts

@@ -27,7 +27,12 @@ import { z } from "zod";
  *   - `created_at` is server-stamped from the system clock; the input
  *     schema does not let clients supply it (would be a backdate hole).
  */
-export declare const LoopBeeRelationRoleSchema: z.ZodEnum<["main", "supporting", "candidate", "retired"]>;
+export declare const LoopBeeRelationRoleSchema: z.ZodEnum<{
+    main: "main";
+    candidate: "candidate";
+    retired: "retired";
+    supporting: "supporting";
+}>;
 export type LoopBeeRelationRole = z.infer<typeof LoopBeeRelationRoleSchema>;
 export declare const LOOP_BEE_RELATION_ROLES: readonly LoopBeeRelationRole[];
 /**
@@ -44,19 +49,14 @@ export declare const LOOP_BEE_RELATION_ROLES: readonly LoopBeeRelationRole[];
 export declare const LoopBeeRelationInputSchema: z.ZodObject<{
     loop_release_id: z.ZodString;
     bee_release_id: z.ZodNumber;
-    role: z.ZodEnum<["main", "supporting", "candidate", "retired"]>;
+    role: z.ZodEnum<{
+        main: "main";
+        candidate: "candidate";
+        retired: "retired";
+        supporting: "supporting";
+    }>;
     reason: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    bee_release_id: number;
-    loop_release_id: string;
-    role: "main" | "candidate" | "retired" | "supporting";
-    reason: string;
-}, {
-    bee_release_id: number;
-    loop_release_id: string;
-    role: "main" | "candidate" | "retired" | "supporting";
-    reason: string;
-}>;
+}, z.core.$strip>;
 export type LoopBeeRelationInput = z.input<typeof LoopBeeRelationInputSchema>;
 /**
  * Full Zod schema for a LoopBeeRelation row as persisted. Differs from
@@ -72,29 +72,17 @@ export type LoopBeeRelationInput = z.input<typeof LoopBeeRelationInputSchema>;
 export declare const LoopBeeRelationSchema: z.ZodObject<{
     loop_release_id: z.ZodString;
     bee_release_id: z.ZodNumber;
-    role: z.ZodEnum<["main", "supporting", "candidate", "retired"]>;
+    role: z.ZodEnum<{
+        main: "main";
+        candidate: "candidate";
+        retired: "retired";
+        supporting: "supporting";
+    }>;
     reason: z.ZodString;
-} & {
     id: z.ZodNumber;
     schema_version: z.ZodDefault<z.ZodLiteral<"peaks.loop-bee-relation/1">>;
     created_at: z.ZodString;
-}, "strip", z.ZodTypeAny, {
-    schema_version: "peaks.loop-bee-relation/1";
-    id: number;
-    created_at: string;
-    bee_release_id: number;
-    loop_release_id: string;
-    role: "main" | "candidate" | "retired" | "supporting";
-    reason: string;
-}, {
-    id: number;
-    created_at: string;
-    bee_release_id: number;
-    loop_release_id: string;
-    role: "main" | "candidate" | "retired" | "supporting";
-    reason: string;
-    schema_version?: "peaks.loop-bee-relation/1" | undefined;
-}>;
+}, z.core.$strip>;
 export type LoopBeeRelation = z.infer<typeof LoopBeeRelationSchema>;
 /**
  * Convenience: strict-parse an unknown payload into a LoopBeeRelation

package/dist/services/loop/loop-bee-relation-types.js

@@ -61,7 +61,7 @@ export const LoopBeeRelationInputSchema = z.object({
     bee_release_id: z
         .number()
         .int()
-        .positive()
+        .gt(0)
         .max(2 ** 31 - 1, "bee_release_id out of 32-bit range"),
     role: LoopBeeRelationRoleSchema,
     reason: z
@@ -82,7 +82,7 @@ export const LoopBeeRelationInputSchema = z.object({
  * read paths.
  */
 export const LoopBeeRelationSchema = LoopBeeRelationInputSchema.extend({
-    id: z.number().int().positive(),
+    id: z.number().int().gt(0),
     schema_version: z
         .literal("peaks.loop-bee-relation/1")
         .default("peaks.loop-bee-relation/1"),

package/dist/services/loop/loop-release-types.d.ts

@@ -40,7 +40,11 @@ import { z } from "zod";
  *     `"peaks.bundle/1"` per the spec §7A.2 contract — no other
  *     value is accepted in this schema version.
  */
-export declare const LoopReleaseLifecycleStatusSchema: z.ZodEnum<["candidate", "stable", "retired"]>;
+export declare const LoopReleaseLifecycleStatusSchema: z.ZodEnum<{
+    candidate: "candidate";
+    stable: "stable";
+    retired: "retired";
+}>;
 export type LoopReleaseLifecycleStatus = z.infer<typeof LoopReleaseLifecycleStatusSchema>;
 /**
  * The M3 share / desktop extension fields, listed for code-search /
@@ -65,20 +69,10 @@ export declare const LOOP_RELEASE_M3_FIELDS: readonly ["shareable", "share_exclu
  */
 export declare const LoopReleaseM3ExtensionSchema: z.ZodObject<{
     shareable: z.ZodDefault<z.ZodBoolean>;
-    share_excluded_paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    share_excluded_paths: z.ZodDefault<z.ZodArray<z.ZodString>>;
     desktop_visible: z.ZodDefault<z.ZodBoolean>;
     export_bundle_format: z.ZodDefault<z.ZodLiteral<"peaks.bundle/1">>;
-}, "strip", z.ZodTypeAny, {
-    shareable: boolean;
-    share_excluded_paths: string[];
-    desktop_visible: boolean;
-    export_bundle_format: "peaks.bundle/1";
-}, {
-    shareable?: boolean | undefined;
-    share_excluded_paths?: string[] | undefined;
-    desktop_visible?: boolean | undefined;
-    export_bundle_format?: "peaks.bundle/1" | undefined;
-}>;
+}, z.core.$strip>;
 /** Convenience type for the M3 share / desktop subset. */
 export type LoopReleaseM3Extension = z.infer<typeof LoopReleaseM3ExtensionSchema>;
 /**
@@ -92,60 +86,25 @@ export declare const LoopReleaseInputSchema: z.ZodObject<{
     name: z.ZodString;
     scenario: z.ZodString;
     trigger_policy: z.ZodString;
-    success_criteria: z.ZodArray<z.ZodString, "many">;
+    success_criteria: z.ZodArray<z.ZodString>;
     interaction_policy: z.ZodString;
     feedback_policy: z.ZodString;
     evolution_policy: z.ZodString;
-    evaluator_policy: z.ZodArray<z.ZodString, "many">;
-    linked_bees: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    run_history: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    crystallization_evidence: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    lifecycle_status: z.ZodEnum<["candidate", "stable", "retired"]>;
+    evaluator_policy: z.ZodArray<z.ZodString>;
+    linked_bees: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    run_history: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    crystallization_evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    lifecycle_status: z.ZodEnum<{
+        candidate: "candidate";
+        stable: "stable";
+        retired: "retired";
+    }>;
     version: z.ZodString;
-} & {
     shareable: z.ZodDefault<z.ZodBoolean>;
-    share_excluded_paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    share_excluded_paths: z.ZodDefault<z.ZodArray<z.ZodString>>;
     desktop_visible: z.ZodDefault<z.ZodBoolean>;
     export_bundle_format: z.ZodDefault<z.ZodLiteral<"peaks.bundle/1">>;
-}, "strip", z.ZodTypeAny, {
-    version: string;
-    name: string;
-    lifecycle_status: "candidate" | "stable" | "retired";
-    id: string;
-    shareable: boolean;
-    share_excluded_paths: string[];
-    desktop_visible: boolean;
-    export_bundle_format: "peaks.bundle/1";
-    scenario: string;
-    trigger_policy: string;
-    success_criteria: string[];
-    interaction_policy: string;
-    feedback_policy: string;
-    evolution_policy: string;
-    evaluator_policy: string[];
-    linked_bees: string[];
-    run_history: string[];
-    crystallization_evidence: string[];
-}, {
-    version: string;
-    name: string;
-    lifecycle_status: "candidate" | "stable" | "retired";
-    id: string;
-    scenario: string;
-    trigger_policy: string;
-    success_criteria: string[];
-    interaction_policy: string;
-    feedback_policy: string;
-    evolution_policy: string;
-    evaluator_policy: string[];
-    shareable?: boolean | undefined;
-    share_excluded_paths?: string[] | undefined;
-    desktop_visible?: boolean | undefined;
-    export_bundle_format?: "peaks.bundle/1" | undefined;
-    linked_bees?: string[] | undefined;
-    run_history?: string[] | undefined;
-    crystallization_evidence?: string[] | undefined;
-}>;
+}, z.core.$strip>;
 /**
  * `LoopReleaseInput` is the *input* shape clients supply: defaulted
  * fields (linked_bees / run_history / crystallization_evidence) are
@@ -170,64 +129,26 @@ export declare const LoopReleaseSchema: z.ZodObject<{
     name: z.ZodString;
     scenario: z.ZodString;
     trigger_policy: z.ZodString;
-    success_criteria: z.ZodArray<z.ZodString, "many">;
+    success_criteria: z.ZodArray<z.ZodString>;
     interaction_policy: z.ZodString;
     feedback_policy: z.ZodString;
     evolution_policy: z.ZodString;
-    evaluator_policy: z.ZodArray<z.ZodString, "many">;
-    linked_bees: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    run_history: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    crystallization_evidence: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
-    lifecycle_status: z.ZodEnum<["candidate", "stable", "retired"]>;
+    evaluator_policy: z.ZodArray<z.ZodString>;
+    linked_bees: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    run_history: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    crystallization_evidence: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    lifecycle_status: z.ZodEnum<{
+        candidate: "candidate";
+        stable: "stable";
+        retired: "retired";
+    }>;
     version: z.ZodString;
-} & {
     shareable: z.ZodDefault<z.ZodBoolean>;
-    share_excluded_paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    share_excluded_paths: z.ZodDefault<z.ZodArray<z.ZodString>>;
     desktop_visible: z.ZodDefault<z.ZodBoolean>;
     export_bundle_format: z.ZodDefault<z.ZodLiteral<"peaks.bundle/1">>;
-} & {
     schema_version: z.ZodDefault<z.ZodLiteral<"peaks.loop/1">>;
-}, "strip", z.ZodTypeAny, {
-    schema_version: "peaks.loop/1";
-    version: string;
-    name: string;
-    lifecycle_status: "candidate" | "stable" | "retired";
-    id: string;
-    shareable: boolean;
-    share_excluded_paths: string[];
-    desktop_visible: boolean;
-    export_bundle_format: "peaks.bundle/1";
-    scenario: string;
-    trigger_policy: string;
-    success_criteria: string[];
-    interaction_policy: string;
-    feedback_policy: string;
-    evolution_policy: string;
-    evaluator_policy: string[];
-    linked_bees: string[];
-    run_history: string[];
-    crystallization_evidence: string[];
-}, {
-    version: string;
-    name: string;
-    lifecycle_status: "candidate" | "stable" | "retired";
-    id: string;
-    scenario: string;
-    trigger_policy: string;
-    success_criteria: string[];
-    interaction_policy: string;
-    feedback_policy: string;
-    evolution_policy: string;
-    evaluator_policy: string[];
-    schema_version?: "peaks.loop/1" | undefined;
-    shareable?: boolean | undefined;
-    share_excluded_paths?: string[] | undefined;
-    desktop_visible?: boolean | undefined;
-    export_bundle_format?: "peaks.bundle/1" | undefined;
-    linked_bees?: string[] | undefined;
-    run_history?: string[] | undefined;
-    crystallization_evidence?: string[] | undefined;
-}>;
+}, z.core.$strip>;
 export type LoopRelease = z.infer<typeof LoopReleaseSchema>;
 /**
  * Convenience: strict-parse an unknown payload into a LoopRelease row.

package/dist/services/migrate-skill-name/schema.d.ts

@@ -20,23 +20,7 @@ export declare const MigrateResultSchema: z.ZodObject<{
     modifiedFiles: z.ZodNumber;
     keyValueReplacements: z.ZodNumber;
     stringReplacements: z.ZodNumber;
-    skipped: z.ZodArray<z.ZodString, "many">;
-    errors: z.ZodArray<z.ZodString, "many">;
-}, "strip", z.ZodTypeAny, {
-    skipped: string[];
-    ok: boolean;
-    scannedFiles: number;
-    modifiedFiles: number;
-    keyValueReplacements: number;
-    stringReplacements: number;
-    errors: string[];
-}, {
-    skipped: string[];
-    ok: boolean;
-    scannedFiles: number;
-    modifiedFiles: number;
-    keyValueReplacements: number;
-    stringReplacements: number;
-    errors: string[];
-}>;
+    skipped: z.ZodArray<z.ZodString>;
+    errors: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
 export type MigrateResult = z.infer<typeof MigrateResultSchema>;

package/dist/services/migrate-skill-name/schema.js

@@ -16,10 +16,10 @@ import { z } from 'zod';
  */
 export const MigrateResultSchema = z.object({
     ok: z.boolean(),
-    scannedFiles: z.number().int().nonnegative(),
-    modifiedFiles: z.number().int().nonnegative(),
-    keyValueReplacements: z.number().int().nonnegative(),
-    stringReplacements: z.number().int().nonnegative(),
+    scannedFiles: z.number().int().gte(0),
+    modifiedFiles: z.number().int().gte(0),
+    keyValueReplacements: z.number().int().gte(0),
+    stringReplacements: z.number().int().gte(0),
     skipped: z.array(z.string()),
     errors: z.array(z.string()),
 });

package/dist/services/observability/observability-service.d.ts

@@ -28,27 +28,29 @@ export declare const ObservabilityEventSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<1>;
     ts: z.ZodString;
     sessionId: z.ZodString;
-    category: z.ZodEnum<["slice-transition", "dispatch", "checkpoint", "mode-gate", "context-trigger", "post-compact", "cycle", "token-usage", "monotonic-trigger", "lease"]>;
+    category: z.ZodEnum<{
+        dispatch: "dispatch";
+        "slice-transition": "slice-transition";
+        checkpoint: "checkpoint";
+        "mode-gate": "mode-gate";
+        "context-trigger": "context-trigger";
+        "post-compact": "post-compact";
+        cycle: "cycle";
+        "token-usage": "token-usage";
+        "monotonic-trigger": "monotonic-trigger";
+        lease: "lease";
+    }>;
     sliceRid: z.ZodOptional<z.ZodString>;
-    role: z.ZodOptional<z.ZodEnum<["rd", "qa", "code-reviewer", "karpathy-reviewer", "peaks-security-audit", "peaks-perf-audit"]>>;
+    role: z.ZodOptional<z.ZodEnum<{
+        qa: "qa";
+        rd: "rd";
+        "code-reviewer": "code-reviewer";
+        "karpathy-reviewer": "karpathy-reviewer";
+        "peaks-security-audit": "peaks-security-audit";
+        "peaks-perf-audit": "peaks-perf-audit";
+    }>>;
     detail: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-}, "strip", z.ZodTypeAny, {
-    schemaVersion: 1;
-    sessionId: string;
-    detail: Record<string, unknown>;
-    ts: string;
-    category: "dispatch" | "slice-transition" | "checkpoint" | "mode-gate" | "context-trigger" | "post-compact" | "cycle" | "token-usage" | "monotonic-trigger" | "lease";
-    role?: "qa" | "rd" | "code-reviewer" | "karpathy-reviewer" | "peaks-security-audit" | "peaks-perf-audit" | undefined;
-    sliceRid?: string | undefined;
-}, {
-    schemaVersion: 1;
-    sessionId: string;
-    detail: Record<string, unknown>;
-    ts: string;
-    category: "dispatch" | "slice-transition" | "checkpoint" | "mode-gate" | "context-trigger" | "post-compact" | "cycle" | "token-usage" | "monotonic-trigger" | "lease";
-    role?: "qa" | "rd" | "code-reviewer" | "karpathy-reviewer" | "peaks-security-audit" | "peaks-perf-audit" | undefined;
-    sliceRid?: string | undefined;
-}>;
+}, z.core.$strip>;
 export type ObservabilityEvent = z.infer<typeof ObservabilityEventSchema>;
 export type EmitOptions = {
     /** Absolute path to the project root (where `.peaks/_runtime/` lives). */

package/dist/services/observability/observability-service.js

@@ -61,7 +61,7 @@ export const ObservabilityEventSchema = z.object({
     category: z.enum(OBSERVABILITY_CATEGORIES),
     sliceRid: z.string().min(1).optional(),
     role: z.enum(OBSERVABILITY_SUBAGENT_ROLES).optional(),
-    detail: z.record(z.unknown())
+    detail: z.record(z.string(), z.unknown())
 });
 /**
  * Append a single observability event to the session's JSONL metrics

package/dist/services/prd/best-practice-auto-trigger.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Slice 2026-08-12 best-practice-scan — auto-trigger post-step (Slice F).
+ *
+ * When peaks-prd's request artifact transitions to `handed-off`, this helper
+ * extracts the `businessGoal` (first non-empty bullet under `## Goals` of the
+ * PRD body) and fires `peaks best-practice-scan --project <root> --intent "<goal>"`
+ * as a fire-and-forget post-step. The PRD → handed-off transition is the
+ * canonical moment when "businessGoal transitions to complete" (the prd state
+ * machine's terminal state).
+ *
+ * Failure modes (all non-fatal — the prd → handed-off transition MUST NOT
+ * block on BPS issues):
+ *   - Empty businessGoal        → status: 'skipped-empty-goal' (no spawn)
+ *   - Artifact missing           → status: 'skipped-artifact-missing'
+ *   - Peaks binary missing       → status: 'skipped-artifact-missing'
+ *   - Spawn 'error' event        → status: 'failed' (logged, not thrown)
+ *   - Spawn event timeout (5 s)  → status: 'failed' (logged, not thrown)
+ *   - Spawn 'spawn' event        → status: 'triggered' (resolved; child detached)
+ *
+ * Karpathy §1 (Think Before Coding): extracted from the QA verdict
+ * `verdict-rid-best-practice-scan-qa-ship.md` AC-1 PARTIAL finding. The
+ * `prd:handed-off` transition in `src/cli/commands/request-commands.ts`
+ * is the canonical hook point — peaks-prd's contract in
+ * `skills/bee/peaks-prd/SKILL.md` §"Step 2.5 sub-step" mandates this firing
+ * BEFORE peaks-rd takes over.
+ *
+ * Karpathy §2 (Simplicity First): single spawn, no retry, no async queue.
+ * Karpathy §3 (Surgical Changes): one new file, no other source files
+ * touched (the call site wiring in request-commands.ts is the only other
+ * edit; that is the "Pattern A: inline post-step" from the dispatch spec).
+ */
+export type BestPracticeTriggerStatus = 'triggered' | 'skipped-empty-goal' | 'skipped-artifact-missing' | 'failed';
+export type BestPracticeTriggerResult = {
+    readonly status: BestPracticeTriggerStatus;
+    readonly businessGoal?: string;
+    readonly pid?: number;
+    readonly reason?: string;
+};
+/** Extract the first non-empty bullet from the `## Goals` section of a PRD
+ *  body. Falls back to the `raw input (sanitized):` line at the top when
+ *  the Goals section is missing or empty. Returns null when no goal can
+ *  be derived (caller should treat as `skipped-empty-goal`).
+ *
+ *  Pure function — exported separately so unit tests can target the
+ *  extraction logic without spawning child processes. */
+export declare function extractBusinessGoal(prdBody: string): string | null;
+/** Fire-and-forget: invoke `peaks best-practice-scan --project <root>
+ *  --intent "<businessGoal>"`. Never throws — always resolves with a
+ *  BestPracticeTriggerResult envelope. The child is detached via `unref()`
+ *  on the 'spawn' event so the parent process is not blocked waiting for
+ *  the BPS scan to finish (the scan itself sleeps ~100 ms in the v1
+ *  Context7 stub).
+ *
+ *  `PEAKS_BEST_PRACTICE_STDIN` is forced to empty so the BPS catch-gate
+ *  auto-accepts the recommended option — auto-trigger is non-interactive
+ *  by design (no user at the prompt when prd → handed-off fires). */
+export declare function triggerBestPracticeScan(opts: {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    readonly requestId: string;
+}): Promise<BestPracticeTriggerResult>;

package/dist/services/prd/best-practice-auto-trigger.js

@@ -0,0 +1,126 @@
+/**
+ * Slice 2026-08-12 best-practice-scan — auto-trigger post-step (Slice F).
+ *
+ * When peaks-prd's request artifact transitions to `handed-off`, this helper
+ * extracts the `businessGoal` (first non-empty bullet under `## Goals` of the
+ * PRD body) and fires `peaks best-practice-scan --project <root> --intent "<goal>"`
+ * as a fire-and-forget post-step. The PRD → handed-off transition is the
+ * canonical moment when "businessGoal transitions to complete" (the prd state
+ * machine's terminal state).
+ *
+ * Failure modes (all non-fatal — the prd → handed-off transition MUST NOT
+ * block on BPS issues):
+ *   - Empty businessGoal        → status: 'skipped-empty-goal' (no spawn)
+ *   - Artifact missing           → status: 'skipped-artifact-missing'
+ *   - Peaks binary missing       → status: 'skipped-artifact-missing'
+ *   - Spawn 'error' event        → status: 'failed' (logged, not thrown)
+ *   - Spawn event timeout (5 s)  → status: 'failed' (logged, not thrown)
+ *   - Spawn 'spawn' event        → status: 'triggered' (resolved; child detached)
+ *
+ * Karpathy §1 (Think Before Coding): extracted from the QA verdict
+ * `verdict-rid-best-practice-scan-qa-ship.md` AC-1 PARTIAL finding. The
+ * `prd:handed-off` transition in `src/cli/commands/request-commands.ts`
+ * is the canonical hook point — peaks-prd's contract in
+ * `skills/bee/peaks-prd/SKILL.md` §"Step 2.5 sub-step" mandates this firing
+ * BEFORE peaks-rd takes over.
+ *
+ * Karpathy §2 (Simplicity First): single spawn, no retry, no async queue.
+ * Karpathy §3 (Surgical Changes): one new file, no other source files
+ * touched (the call site wiring in request-commands.ts is the only other
+ * edit; that is the "Pattern A: inline post-step" from the dispatch spec).
+ */
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { showRequestArtifact } from '../artifacts/request-artifact-service.js';
+/** Extract the first non-empty bullet from the `## Goals` section of a PRD
+ *  body. Falls back to the `raw input (sanitized):` line at the top when
+ *  the Goals section is missing or empty. Returns null when no goal can
+ *  be derived (caller should treat as `skipped-empty-goal`).
+ *
+ *  Pure function — exported separately so unit tests can target the
+ *  extraction logic without spawning child processes. */
+export function extractBusinessGoal(prdBody) {
+    const goalsMatch = /##\s+Goals\s*\n([\s\S]*?)(?=\n##\s|\n#\s|\Z)/.exec(prdBody);
+    if (goalsMatch !== null && goalsMatch[1] !== undefined) {
+        for (const raw of goalsMatch[1].split(/\r?\n/)) {
+            const line = raw.replace(/^[\s>*\-]+/, '').trim();
+            if (line.length > 0 && line !== '...')
+                return line;
+        }
+    }
+    const rawInputMatch = /^- raw input \(sanitized\):\s*(.+)$/m.exec(prdBody);
+    if (rawInputMatch !== null && rawInputMatch[1] !== undefined) {
+        const line = rawInputMatch[1].trim();
+        if (line.length > 0 && line !== '...')
+            return line;
+    }
+    return null;
+}
+/** Fire-and-forget: invoke `peaks best-practice-scan --project <root>
+ *  --intent "<businessGoal>"`. Never throws — always resolves with a
+ *  BestPracticeTriggerResult envelope. The child is detached via `unref()`
+ *  on the 'spawn' event so the parent process is not blocked waiting for
+ *  the BPS scan to finish (the scan itself sleeps ~100 ms in the v1
+ *  Context7 stub).
+ *
+ *  `PEAKS_BEST_PRACTICE_STDIN` is forced to empty so the BPS catch-gate
+ *  auto-accepts the recommended option — auto-trigger is non-interactive
+ *  by design (no user at the prompt when prd → handed-off fires). */
+export async function triggerBestPracticeScan(opts) {
+    const artifact = await showRequestArtifact({
+        projectRoot: opts.projectRoot,
+        role: 'prd',
+        requestId: opts.requestId,
+        sessionId: opts.sessionId
+    });
+    if (artifact === null) {
+        return { status: 'skipped-artifact-missing' };
+    }
+    const businessGoal = extractBusinessGoal(artifact.content);
+    if (businessGoal === null) {
+        return { status: 'skipped-empty-goal' };
+    }
+    const peaksBin = join(opts.projectRoot, 'bin', 'peaks.js');
+    if (!existsSync(peaksBin)) {
+        return { status: 'skipped-artifact-missing', reason: `peaks binary not found at ${peaksBin}` };
+    }
+    return await new Promise((resolveTrigger) => {
+        let resolved = false;
+        const resolveOnce = (result) => {
+            if (resolved)
+                return;
+            resolved = true;
+            resolveTrigger(result);
+        };
+        const child = spawn(process.execPath, [
+            peaksBin,
+            'best-practice-scan',
+            '--project',
+            opts.projectRoot,
+            '--intent',
+            businessGoal,
+            '--json'
+        ], {
+            cwd: opts.projectRoot,
+            stdio: 'ignore',
+            detached: true,
+            env: { ...process.env, PEAKS_BEST_PRACTICE_STDIN: '' }
+        });
+        child.once('error', (err) => {
+            resolveOnce({ status: 'failed', businessGoal, reason: err.message });
+        });
+        child.once('spawn', () => {
+            if (typeof child.unref === 'function')
+                child.unref();
+            resolveOnce({
+                status: 'triggered',
+                businessGoal,
+                pid: typeof child.pid === 'number' ? child.pid : -1
+            });
+        });
+        setTimeout(() => {
+            resolveOnce({ status: 'failed', businessGoal, reason: 'spawn event timeout (5s)' });
+        }, 5_000).unref();
+    });
+}