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

package/dist/src/services/{solo → code}/post-compact-detector.js

@@ -7,7 +7,7 @@
  *   1. `.peaks/_runtime/<sessionId>/` is bound
  *   2. Latest checkpoint mtime is from today (UTC date)
  *   3. Latest checkpoint has a parseable `mode` field
- *   4. The peak-solo skill is the active skill
+ *   4. The peak-code skill is the active skill
  *   5. Exactly one session has a today's checkpoint (no ambiguity)
  *
  * On a hit, the LLM MUST auto-resume (D7.b override of "never silently
@@ -25,7 +25,7 @@ import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { getSkillPresence } from '../skills/skill-presence-service.js';
 import { emitObservabilityEvent } from '../observability/observability-service.js';
-import { isSoloMode } from './mode-gate.js';
+import { isCodeMode } from './mode-gate.js';
 export const POST_COMPACT_RESUME_REASONS = [
     'post-compact-match',
     'sid-unbound',
@@ -160,7 +160,7 @@ export async function detectPostCompactResume(opts) {
     // Mode: prefer the checkpoint's mode; fall back to the presence override
     // (test seam) or to a fresh skill-presence read.
     let mode;
-    if (isSoloMode(checkpointMode)) {
+    if (isCodeMode(checkpointMode)) {
         mode = checkpointMode;
     }
     else if (opts.presenceModeOverride !== undefined) {
@@ -170,7 +170,7 @@ export async function detectPostCompactResume(opts) {
         try {
             const presence = getSkillPresence(opts.projectRoot);
             const presenceMode = presence?.mode;
-            if (presenceMode !== undefined && isSoloMode(presenceMode)) {
+            if (presenceMode !== undefined && isCodeMode(presenceMode)) {
                 mode = presenceMode;
             }
         }

package/dist/src/services/{solo → code}/step-08-gate.d.ts

@@ -3,7 +3,7 @@
  *
  * Wire-installed by `peaks workspace init` (extends the existing hook
  * installer; does NOT replace the Write|Edit|MultiEdit fact-forcing
- * bypass). The hook runs `peaks solo gate-step-08 --project .` before
+ * bypass). The hook runs `peaks code gate-step-08 --project .` before
  * every Bash tool call. Exit code is the load-bearing contract:
  *
  *   exit 0 → allow (with structured stdout describing the decision)
@@ -29,7 +29,7 @@
  * regex is the FIRST time peaks-loop accepts hardcoded keywords —
  * explicitly scoped as a *fail-closed backup* (case 3), NOT a primary
  * judgement. The LLM still owns the semantic call via
- * `peaks solo detect-job`. The regex is a safety net for the v3.1.1
+ * `peaks code detect-job`. The regex is a safety net for the v3.1.1
  * incident class (LLM under load never records the decision at all).
  */
 export declare const STEP_08_GATE_FILE_NAME: "job-shape.json";
@@ -38,7 +38,7 @@ export declare const STEP_08_PROGRESS_FILE_NAME: "progress.json";
  * Fail-closed backup regex — see module docstring case 3 for why this
  * exists. Kept short and explicit; if the prompt mentions any of these
  * triggers and `job-shape.json` is missing, the LLM is treated as
- * having skipped `peaks solo detect-job` and the gate blocks.
+ * having skipped `peaks code detect-job` and the gate blocks.
  *
  * The list mirrors the v3.1.0 / v3.1.1 incident triggers verbatim:
  *   继续执行下个 slice (until next slice) → until / 直到
@@ -84,7 +84,7 @@ export interface EvaluateStep08Result {
 }
 /**
  * Pure evaluator — does NOT write, does NOT exit. CLI wrapper in
- * `src/cli/commands/solo-commands.ts` reads `allow` to set the process
+ * `src/cli/commands/code-commands.ts` reads `allow` to set the process
  * exit code (0 allow / 2 block) and prints the structured envelope.
  */
 export declare function evaluateStep08(input: EvaluateStep08Input): EvaluateStep08Result;

package/dist/src/services/{solo → code}/step-08-gate.js

@@ -3,7 +3,7 @@
  *
  * Wire-installed by `peaks workspace init` (extends the existing hook
  * installer; does NOT replace the Write|Edit|MultiEdit fact-forcing
- * bypass). The hook runs `peaks solo gate-step-08 --project .` before
+ * bypass). The hook runs `peaks code gate-step-08 --project .` before
  * every Bash tool call. Exit code is the load-bearing contract:
  *
  *   exit 0 → allow (with structured stdout describing the decision)
@@ -29,7 +29,7 @@
  * regex is the FIRST time peaks-loop accepts hardcoded keywords —
  * explicitly scoped as a *fail-closed backup* (case 3), NOT a primary
  * judgement. The LLM still owns the semantic call via
- * `peaks solo detect-job`. The regex is a safety net for the v3.1.1
+ * `peaks code detect-job`. The regex is a safety net for the v3.1.1
  * incident class (LLM under load never records the decision at all).
  */
 import { existsSync, readFileSync } from 'node:fs';
@@ -41,7 +41,7 @@ export const STEP_08_PROGRESS_FILE_NAME = 'progress.json';
  * Fail-closed backup regex — see module docstring case 3 for why this
  * exists. Kept short and explicit; if the prompt mentions any of these
  * triggers and `job-shape.json` is missing, the LLM is treated as
- * having skipped `peaks solo detect-job` and the gate blocks.
+ * having skipped `peaks code detect-job` and the gate blocks.
  *
  * The list mirrors the v3.1.0 / v3.1.1 incident triggers verbatim:
  *   继续执行下个 slice (until next slice) → until / 直到
@@ -102,7 +102,7 @@ function readPromptFromLastPromptFile(projectRoot, sessionId) {
 }
 /**
  * Pure evaluator — does NOT write, does NOT exit. CLI wrapper in
- * `src/cli/commands/solo-commands.ts` reads `allow` to set the process
+ * `src/cli/commands/code-commands.ts` reads `allow` to set the process
  * exit code (0 allow / 2 block) and prints the structured envelope.
  */
 export function evaluateStep08(input) {

package/dist/src/services/{solo → code}/user-touchpoint-classifier.d.ts

@@ -2,7 +2,7 @@
  * v2.15.0 follow-up — G4: user touchpoint classifier.
  *
  * 12 Gaps positioning memory: "user 介入 = 业务/产品审阅,不是技术决策".
- * This service classifies every Solo gate by the kind of decision it
+ * This service classifies every Code gate by the kind of decision it
  * represents, so the CLI / status line can show user which gates
  * actually need their attention vs which are technical defaults
  * (AI auto-decides in full-auto).

package/dist/src/services/{solo → code}/user-touchpoint-classifier.js

@@ -2,7 +2,7 @@
  * v2.15.0 follow-up — G4: user touchpoint classifier.
  *
  * 12 Gaps positioning memory: "user 介入 = 业务/产品审阅,不是技术决策".
- * This service classifies every Solo gate by the kind of decision it
+ * This service classifies every Code gate by the kind of decision it
  * represents, so the CLI / status line can show user which gates
  * actually need their attention vs which are technical defaults
  * (AI auto-decides in full-auto).

package/dist/src/services/context/auto-compact-dispatcher.d.ts

@@ -7,11 +7,11 @@ export interface DispatchIdeCompactInput {
     /** Spawn timeout (ms). Default 30s — Claude Code `/compact` is sync. */
     readonly timeoutMs?: number | undefined;
     /**
-     * Slice 2026-06-28-solo-mode-bypass-fix (defect #4): which session
+     * Slice 2026-06-28-code-mode-bypass-fix (defect #4): which session
      * the compact should target. Default `'main'` — the orchestrator
      * (peaks-code body) runs in the main-session Claude Code window and
      * wants to compress *its* context, not a sub-agent's. Sub-agent
-     * shells that spawn their own `peaks solo auto-compact` flow pass
+     * shells that spawn their own `peaks code auto-compact` flow pass
      * `'sub-agent'` to preserve the legacy shell-spawn behaviour.
      *
      * Behaviour matrix (claude-code MVP):

package/dist/src/services/context/auto-compact-dispatcher.js

@@ -47,7 +47,7 @@ export async function dispatchIdeCompact(input) {
     // See auto-compact-reader.ts for the IdeKind→IdeId cast rationale.
     const ideId = (detected === 'unknown' ? 'claude-code' : detected);
     const adapter = getAdapter(ideId);
-    // Slice 2026-06-28-solo-mode-bypass-fix (defect #4): default to
+    // Slice 2026-06-28-code-mode-bypass-fix (defect #4): default to
     // `'main'` so the orchestrator's auto-compact actually compresses
     // the main-session context. The orchestrator passes `'sub-agent'`
     // explicitly when a sub-agent shell dispatches the call.
@@ -123,7 +123,7 @@ export async function dispatchIdeCompact(input) {
                 });
             }
             // Lazy install: we only get here when the caller explicitly
-            // invokes `peaks solo auto-compact --execute`, so the user has
+            // invokes `peaks code auto-compact --execute`, so the user has
             // already opted in. No zero-touch surprise on workspace init.
             return await dispatchIdeNativeHook({
                 projectRoot: input.projectRoot,

package/dist/src/services/context/auto-compact-types.d.ts

@@ -107,7 +107,7 @@ export type AutoCompactResult = {
         readonly convergencePlan?: ConvergencePlan;
         readonly dispatch?: CompactDispatchResult;
         /**
-         * Slice 2026-06-28-solo-mode-bypass-fix (defect #4): which
+         * Slice 2026-06-28-code-mode-bypass-fix (defect #4): which
          * session the compact targeted. `'main'` (default) means the
          * main-session Claude Code window will fire `/compact` on its
          * next turn; `'sub-agent'` means the dispatcher shell-spawned

package/dist/src/services/crystallization/crystallization-service.d.ts

@@ -0,0 +1,239 @@
+import type Database from "better-sqlite3";
+import { z } from "zod";
+import { type CrystallizationEvent, type CrystallizationEventInput, type CrystallizationEventStatus, type EvidenceBrief } from "./crystallization-types.js";
+import { listCrystallizationEvents } from "./crystallization-store.js";
+import { type LoopReleaseInput } from "../loop/loop-release-types.js";
+/**
+ * CrystallizationService — spec §5 (post-run crystallization)
+ * + §4.5 + §4.7 + §10 RL-2 / RL-3 / RL-7.
+ *
+ * Hard rules enforced at THIS layer (defense in depth; the Zod
+ * schemas above and the brief refine guard add the second wall):
+ *
+ *   - AC-4 / RL-2: a crystallization_event is written only when the
+ *     candidate task has `task_status === 'completed'` AND
+ *     `gates_passed === true` AND `evidence_collected === true`.
+ *     Any pre-run attempt (status !== 'completed') is rejected
+ *     with `CRYSTALLIZATION_PRE_RUN`. This is the pre-run block
+ *     enforced by AC-4, AC-5, AC-6, AC-15, AC-16, AC-17 of the M5
+ *     slice.
+ *   - AC-6 / RL-3: writing a (loop_release, main_bee_release,
+ *     loop_bee_relation) pair happens in a SINGLE TRANSACTION. The
+ *     brief persist on crystallization_event also lives inside
+ *     the same transaction (the brief is the durable evidence;
+ *     dropping either side would break consistency).
+ *   - AC-7 / RL-1: this layer never asks the user to hand-author
+ *     JSON / manifest / CLI verb; all inputs are typed payloads
+ *     the LLM submits on the user's behalf.
+ *   - AC-15 / RL-7: the brief is mandatory; the
+ *     `EvidenceBriefSchema.refine` guard rejects partial briefs
+ *     at the parse boundary.
+ *   - AC-16 / RL-7: the brief has all 4 sections
+ *     (what_happened / why_it_matters / what_learned /
+ *     what_action). The service throws `BriefSectionError` if the
+ *     payload fails the guard.
+ *
+ * Sub-domain error codes:
+ *
+ *   - CRYSTALLIZATION_PRE_RUN: task_status / gates_passed /
+ *     evidence_collected precondition failed.
+ *   - CRYSTALLIZATION_INVALID_TASK_STATE: a task input field is
+ *     malformed (e.g. unknown task_status).
+ *   - MISSING_BRIEF_SECTION: a brief is missing at least one of
+ *     its 4 sections (raised from the evidence-brief-builder
+ *     refine; surfaced as-is by the service).
+ *   - CRYSTALLIZATION_TX_FAILED: a transaction-side effect failed
+ *     (FK constraint, duplicate key, …). The service re-raises
+ *     richer domain errors first; this is the catch-all for
+ *     unexpected SQL errors.
+ */
+export declare const CRYSTALLIZATION_TASK_STATUSES: readonly ["completed", "in_progress", "scratch", "blocked", "failed"];
+export type CrystallizationTaskStatus = (typeof CRYSTALLIZATION_TASK_STATUSES)[number];
+/**
+ * The pre-run task state the service requires. Crystallization is
+ * GATED on these three flags. The validator rejects any input that
+ * does not match. Adding a new flag means a schema-version bump; for
+ * now the three are required.
+ */
+export declare const CrystallizationTaskStateSchema: z.ZodObject<{
+    task_id: z.ZodString;
+    task_status: z.ZodLiteral<"completed">;
+    gates_passed: z.ZodLiteral<true>;
+    evidence_collected: z.ZodLiteral<true>;
+}, "strip", z.ZodTypeAny, {
+    task_id: string;
+    task_status: "completed";
+    gates_passed: true;
+    evidence_collected: true;
+}, {
+    task_id: string;
+    task_status: "completed";
+    gates_passed: true;
+    evidence_collected: true;
+}>;
+export type CrystallizationTaskState = z.infer<typeof CrystallizationTaskStateSchema>;
+export type CrystallizationIntegrityErrorCode = "CRYSTALLIZATION_PRE_RUN" | "CRYSTALLIZATION_INVALID_TASK_STATE" | "CRYSTALLIZATION_TX_FAILED" | "MISSING_BRIEF_SECTION";
+export declare class CrystallizationIntegrityError extends Error {
+    readonly code: CrystallizationIntegrityErrorCode | "MISSING_BRIEF_SECTION";
+    readonly findings: ReadonlyArray<{
+        path: string;
+        message: string;
+    }>;
+    constructor(code: CrystallizationIntegrityErrorCode, message: string, findings?: ReadonlyArray<{
+        path: string;
+        message: string;
+    }>);
+}
+export interface CrystallizePayload {
+    /** The candidate task state. Must satisfy the pre-run gate. */
+    task: CrystallizationTaskState;
+    /** The loop_release to create (new). Must include main bee via relation. */
+    loop_input: LoopReleaseInput;
+    /**
+     * The main bee_release to create. Note: bee_release requires a
+     * manifest row to keep the existing 4.x schema consistent;
+     * `bee_input` here carries ONLY the manifest-level fields the
+     * service uses. A future slice will swap in the full
+     * retainRelease() flow.
+     */
+    bee_input: BeeCrystallizeInput;
+    /**
+     * Optional NL reason the LLM authored; surfaced on the
+     * loop_bee_relation row (spec §4.6 `reason`).
+     */
+    bee_relation_reason: string;
+    /**
+     * The 4-section evidence brief (spec §4.7).
+     */
+    evidence_brief: EvidenceBrief;
+    /** Optional structured bullets (RL-7: counts may support the brief, not replace it). */
+    evidence_bullets?: string[];
+    /** Source trace pointers for the brief (spec §4.5). */
+    source_trace_pointers?: string[];
+    /** Optional evaluator summary (independent scorers — spec §4.5). */
+    evaluator_summary?: string;
+    /** Optional user decision summary (spec §4.5). */
+    user_decision_summary?: string;
+    /** Trigger classification (spec §5.4). */
+    trigger: CrystallizationEventInput["trigger"];
+}
+/**
+ * Minimum bee_release payload the service needs to create a main bee
+ * alongside a loop. The full bee_release schema (see
+ * `src/services/skillhub/release-retain.ts`) carries manifest rows,
+ * segment refs, file rows, etc.; M5 only writes the bee_release header
+ * + a single bee_manifest row sufficient to keep the 4.x FK
+ * constraints green. Full bee retaining lands in a future slice.
+ *
+ * Schema definition is hoisted above the interface so the typed
+ * interface can reference the inferred Zod type without forward-
+ * reference gymnastics.
+ */
+declare const BeeNameSchema: z.ZodString;
+export interface BeeCrystallizeInput {
+    bee_name: z.infer<typeof BeeNameSchema>;
+    version: string;
+    description: string;
+    user_intent_raw?: string;
+    parent_version?: string;
+    changelog?: string;
+}
+/**
+ * The crystallization result. The brief is returned AS PERSISTED
+ * (re-parsed through the schema) so callers receive the canonical
+ * shape, not the loose payload.
+ */
+export interface CrystallizationResult {
+    loop_release_id: string;
+    bee_release_id: number;
+    loop_bee_relation_id: number;
+    crystallization_event_id: string;
+    loop_release_lifecycle_status: CrystallizationEventStatus;
+}
+/**
+ * Service interface for the post-run crystallization flow.
+ */
+export declare class CrystallizationService {
+    private readonly db;
+    constructor(db: Database.Database);
+    /**
+     * Read a CrystallizationEvent by id.
+     */
+    read(id: string): CrystallizationEvent | undefined;
+    /**
+     * List events. Filter by lifecycle_status and/or the FK pointer
+     * columns. When no filters are supplied, lists ALL events
+     * (newest-first).
+     */
+    list(opts?: Parameters<typeof listCrystallizationEvents>[1]): {
+        schema_version: "peaks.crystallization/1";
+        id: string;
+        lifecycle_status: "candidate" | "stable" | "retired";
+        trigger: "user_explicit" | "llm_suggested" | "success_default_prompt" | "similar_task_recurrence";
+        evidence_brief: {
+            what_happened: string;
+            why_it_matters: string;
+            what_learned: string;
+            what_action: string;
+        };
+        evidence_bullets: string[];
+        source_trace_pointers: string[];
+        evaluator_summary: string;
+        user_decision_summary: string;
+        created_at: string;
+        created_loop_release_id?: string | undefined;
+        updated_loop_release_id?: string | undefined;
+        created_bee_release_id?: number | undefined;
+        updated_bee_release_id?: number | undefined;
+    }[];
+    /**
+     * Update a crystallization event's lifecycle_status. Always allowed
+     * (no schema-version gate). Returns the updated row or undefined if
+     * the id is absent.
+     *
+     * A `stable` transition is the natural post-crystallization state;
+     * the service does NOT enforce user-confirmation here (per spec
+     * §5.6 promotion happens on a separate `peaks loop promote` path).
+     * `retired` is the dispose path (`peaks asset dispose`).
+     */
+    updateStatus(id: string, next: CrystallizationEventStatus): CrystallizationEvent | undefined;
+    /**
+     * Pre-run gate: throws if any of `task_status`, `gates_passed`,
+     * `evidence_collected` is not as required. Called from
+     * `crystallize` BEFORE the transaction begins.
+     *
+     * Reachable as a public method so the CLI / tests can probe the
+     * gate in isolation.
+     */
+    assertReady(task: CrystallizationTaskState): CrystallizationTaskState;
+    /**
+     * Run the post-run crystallization flow.
+     *
+     * Steps (all in ONE better-sqlite3 transaction, atomic):
+     *
+     *   1. Pre-run gate (task must be completed / gates_passed /
+     *      evidence_collected).
+     *   2. Re-validate the 4-section brief (EvidenceBriefSchema.parse,
+     *      EvidenceBriefSchema.refine).
+     *   3. Insert loop_release.
+     *   4. Insert bee_release header (+ a single bee_manifest row to
+     *      keep the 4.x FK contract).
+     *   5. Insert loop_bee_relation row with role='main'.
+     *   6. Insert crystallization_event with the brief persisted.
+     *
+     * Returns the four ids + the new loop's lifecycle_status. On any
+     * failure the transaction is rolled back and the partial rows
+     * disappear.
+     *
+     * Throws:
+     *   - CrystallizationIntegrityError(CRYSTALLIZATION_PRE_RUN) on
+     *     the pre-run gate.
+     *   - BriefSectionError or ZodError if the brief is malformed;
+     *     surfaced as
+     *     CrystallizationIntegrityError(MISSING_BRIEF_SECTION).
+     *   - CrystallizationIntegrityError(CRYSTALLIZATION_TX_FAILED)
+     *     on any SQL transaction failure.
+     */
+    crystallize(payload: CrystallizePayload): CrystallizationResult;
+}
+export {};