peaks-loop 3.1.1 → 4.0.0-beta

package/dist/src/cli/commands/workspace/init-command.js

@@ -1,5 +1,5 @@
 /**
- * `peaks workspace init` — slice 006 + 007 + 014 + 018 + 2026-06-16-peaks-solo-auto-scaffold.
+ * `peaks workspace init` — slice 006 + 007 + 014 + 018 + 2026-06-16-peaks-code-auto-scaffold.
  *
  * Extracted from `src/cli/commands/workspace-commands.ts` (slice
  * 2026-06-16-workspace-commands-split) to keep that entry file under the
@@ -44,7 +44,7 @@ export function registerWorkspaceInitCommand(workspace, io) {
         return value;
     })
         .option('--no-claude-hooks', 'do NOT materialize .claude/settings.local.json (slice 2.0.1-bug3 fact-forcing bypass). Default: hooks installed so tool calls inside .peaks/** are not blocked by the [Fact-Forcing Gate].')
-        .option('--init-standards', 'slice 2026-06-16-peaks-solo-auto-scaffold: when the consumer project\'s .claude/rules/ is missing or empty, auto-apply `peaks standards init --project <path> --apply` after emitting the diagnostic. Default: diagnostic only (no write).')).action(async (options) => {
+        .option('--init-standards', 'slice 2026-06-16-peaks-code-auto-scaffold: when the consumer project\'s .claude/rules/ is missing or empty, auto-apply `peaks standards init --project <path> --apply` after emitting the diagnostic. Default: diagnostic only (no write).')).action(async (options) => {
         try {
             // Resolve the session id. Two paths:
             //   - explicit --session-id: use it as the requested binding target
@@ -110,7 +110,7 @@ export function registerWorkspaceInitCommand(workspace, io) {
                 // `false`, so the default is "install hooks" (the bypass is
                 // on). Pass `--no-claude-hooks` to opt out.
                 noClaudeHooks: options.claudeHooks === false,
-                // Slice 2026-06-16-peaks-solo-auto-scaffold (RD#7): opt-in
+                // Slice 2026-06-16-peaks-code-auto-scaffold (RD#7): opt-in
                 // auto-apply for the missing-standards scaffold. Default false
                 // — only the diagnostic is emitted. Pass --init-standards to
                 // also run `executeProjectStandardsInit({ apply: true })`.
@@ -129,7 +129,7 @@ export function registerWorkspaceInitCommand(workspace, io) {
                     `Re-run with --no-rotate-on-outer-mismatch to suppress this rotation.`);
                 // Slice 002 (v2.15.0) AC-1: a presence marker stamped by the
                 // OLD outer session is now stale (defect A from the PRD).
-                // peaks-solo Step 1 would otherwise pick up the old `mode`
+                // peaks-code Step 1 would otherwise pick up the old `mode`
                 // field and silently lock the new session into a mode the
                 // user never explicitly chose. Clear it here so Step 1's
                 // presence:check-stale reports `reason: 'no-presence'` and
@@ -142,7 +142,7 @@ export function registerWorkspaceInitCommand(workspace, io) {
                 });
                 if (presenceClearOutcome.cleared) {
                     nextActions.push(`Auto-cleared stale skill presence (recorded outer id "${presenceClearOutcome.recordedOuter ?? '?'}" did not match the new outer session). ` +
-                        'peaks-solo Step 1 will now AskUserQuestion to confirm the mode.');
+                        'peaks-code Step 1 will now AskUserQuestion to confirm the mode.');
                 }
                 else if (presenceClearOutcome.reason === 'recorded-by-different-outer') {
                     nextActions.push(`Kept skill presence: it was recorded by a different live outer session (id "${presenceClearOutcome.recordedOuter ?? '?'}"). ` +
@@ -227,7 +227,7 @@ export function registerWorkspaceInitCommand(workspace, io) {
             else if (hooksOutcome.action === 'first-decision' && hooksOutcome.decision === 'skipped') {
                 nextActions.push('Skipped peaks-managed hook install for this project. Re-run with --install-hooks=auto (or peaks hooks install) to install later.');
             }
-            // Slice 2026-06-16-peaks-solo-auto-scaffold (RD#7):
+            // Slice 2026-06-16-peaks-code-auto-scaffold (RD#7):
             //   - When the consumer project's `.claude/rules/` is missing or
             //     empty, emit the copy-pasteable diagnostic to stderr (via
             //     the JSON envelope `warnings` array) AND surface the
@@ -246,7 +246,7 @@ export function registerWorkspaceInitCommand(workspace, io) {
                 nextActions.push(`Run \`peaks workspace init --init-standards --project ${projectRoot}\` to auto-apply the scaffold, or \`peaks standards init --project ${projectRoot} --apply\` manually.`);
             }
             if (report.standardsApplied !== undefined) {
-                nextActions.push(`Auto-applied .claude/rules/${report.standardsApplied.language}/ scaffold (slice 2026-06-16-peaks-solo-auto-scaffold): ` +
+                nextActions.push(`Auto-applied .claude/rules/${report.standardsApplied.language}/ scaffold (slice 2026-06-16-peaks-code-auto-scaffold): ` +
                     `wrote ${report.standardsApplied.writtenFiles.length} file(s), ` +
                     `kept ${report.standardsApplied.skippedFiles.length} existing file(s).`);
             }

package/dist/src/cli/program.js

@@ -1,7 +1,7 @@
 import { readdirSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
 import { Command } from 'commander';
-import { skillsDir } from '../shared/paths.js';
+import { skillsDir, repoRoot } from '../shared/paths.js';
 import { CLI_VERSION } from '../shared/version.js';
 import { registerCoreAndArtifactCommands } from './commands/core-artifact-commands.js';
 import { registerWorkflowCommands } from './commands/workflow-commands.js';
@@ -76,6 +76,12 @@ import { registerObservabilityCommands } from './commands/observability-commands
 import { registerCompactCommands } from './commands/compact-command.js';
 // Slice 2026-07-01-job-m3.1: `peaks job init|status|...` — Job orchestration CLI surface.
 import { registerJobCommands } from './commands/job-commands.js';
+// Slice 2026-07-04-cli-15a: `peaks skill sediment <verb>` + `peaks skill adapter <verb>`
+// — Task 15a 4-verb subset (add-segment / add-bee / list / rebuild-index).
+// 15b / 15c / 15d will extend sediment-commands.ts with the remaining 14 verbs.
+import { registerSedimentCommands } from './commands/sediment-commands.js';
+import { registerAdapterCommands } from './commands/adapter-commands.js';
+import { registerSkillVisibilityCommand } from './commands/skill-visibility.js';
 import { applyRetention } from '../services/log/retention.js';
 import { writeLogEntry, maybeWriteStderr } from '../services/log/logger.js';
 export { printResult } from './cli-helpers.js';
@@ -315,7 +321,7 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     // Slice 2026-06-17-2.5.0-sub-fix-C: `peaks playwright start|ls|stop`
     // (multi-terminal Playwright MCP lifecycle).
     registerPlaywrightCommands(program, io);
-    // Slice 2 (peaks-solo fast mode): `peaks solo plan [--fast] <change-id>`
+    // Slice 2 (peaks-code fast mode): `peaks solo plan [--fast] <change-id>`
     // v2.11.0 Group F (D5 + D7): also registers `peaks solo should-pause` and
     // `peaks solo post-compact-detect` for runtime-friction probes.
     registerSoloCommands(program, io);
@@ -347,5 +353,16 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     // orchestration CLI surface. M3.1 wires init + status + 2 stubs;
     // the remaining 5 subcommands land in M3.2.
     registerJobCommands(program, io);
+    // Slice 2026-07-04-cli-15a: `peaks skill sediment <verb>` — Task 15a
+    // 4-verb subset. Dispatches to runSediment; remaining verbs land in 15b/15c/15d.
+    registerSedimentCommands(program, io);
+    // Slice 2026-07-04-cli-15a: `peaks skill adapter <verb>` — adapter list / set-active.
+    registerAdapterCommands(program, io);
+    // Slice 2026-07-05-peaks-code-to-peaks-code (Task 1): `peaks skill:visibility --list --json`
+    // — read .claude-plugin/marketplace.json and report each skill's
+    // visibility (public vs internal). Used to surface which skills are
+    // user-invocable vs LLM-only internal role skills. See
+    // src/cli/commands/skill-visibility.ts.
+    registerSkillVisibilityCommand(program, repoRoot);
     return program;
 }

package/dist/src/services/adapter/adapter.d.ts

@@ -0,0 +1,27 @@
+export interface AdapterSegment {
+    name: string;
+    skillMd: string;
+    scripts: {
+        name: string;
+        content: string;
+    }[];
+}
+export interface AdapterEnvelope {
+    preamble: string;
+    refs: {
+        path: string;
+        kind: "file" | "dir" | "script";
+    }[];
+}
+export interface Adapter {
+    readonly name: "claude" | "codex" | "copilot" | "auto";
+    resolveScratchDir(beeName: string): Promise<string>;
+    materialize(beeName: string, env: AdapterEnvelope, segments: AdapterSegment[]): Promise<string>;
+    publish(scratchDir: string): Promise<string>;
+    activate(scratchDir: string): Promise<void>;
+    cleanup(scratchDir: string): Promise<void>;
+    detect(): Promise<boolean>;
+}
+export declare class ADAPTER_NOT_IMPLEMENTED extends Error {
+    constructor(adapter: string, method: string);
+}

package/dist/src/services/adapter/adapter.js

@@ -0,0 +1,5 @@
+export class ADAPTER_NOT_IMPLEMENTED extends Error {
+    constructor(adapter, method) {
+        super(`ADAPTER_NOT_IMPLEMENTED: ${adapter}.${method} — stub until later slice`);
+    }
+}

package/dist/src/services/adapter/auto-adapter.d.ts

@@ -0,0 +1,11 @@
+import { Adapter } from "./adapter.js";
+type Detectable = Pick<Adapter, "name" | "detect">;
+export declare class AutoAdapter {
+    private readonly _o;
+    private readonly _adapters;
+    constructor(_o: {
+        home: string;
+    }, _adapters: Detectable[]);
+    detectAndPick(): Promise<Detectable>;
+}
+export {};

package/dist/src/services/adapter/auto-adapter.js

@@ -0,0 +1,15 @@
+export class AutoAdapter {
+    _o;
+    _adapters;
+    constructor(_o, _adapters) {
+        this._o = _o;
+        this._adapters = _adapters;
+    }
+    async detectAndPick() {
+        for (const a of this._adapters) {
+            if (await a.detect())
+                return a;
+        }
+        throw new Error("No adapter detected. Use `peaks skill adapter set-active <name>` to force one.");
+    }
+}

package/dist/src/services/adapter/claude-adapter.d.ts

@@ -0,0 +1,14 @@
+import { Adapter, AdapterEnvelope, AdapterSegment } from "./adapter.js";
+export declare class ClaudeAdapter implements Adapter {
+    private readonly opts;
+    readonly name: "claude";
+    constructor(opts: {
+        home: string;
+    });
+    detect(): Promise<boolean>;
+    resolveScratchDir(beeName: string): Promise<string>;
+    materialize(beeName: string, env: AdapterEnvelope, segments: AdapterSegment[]): Promise<string>;
+    publish(scratchDir: string): Promise<string>;
+    activate(_scratchDir: string): Promise<void>;
+    cleanup(scratchDir: string): Promise<void>;
+}

package/dist/src/services/adapter/claude-adapter.js

@@ -0,0 +1,40 @@
+import { writeFileSync, mkdirSync, rmSync, existsSync } from "node:fs";
+import { join } from "node:path";
+export class ClaudeAdapter {
+    opts;
+    name = "claude";
+    constructor(opts) {
+        this.opts = opts;
+    }
+    async detect() {
+        return true; /* Claude is the default; ship this slice first */
+    }
+    async resolveScratchDir(beeName) {
+        return join(this.opts.home, ".claude", "skills", `peaks-bee-${beeName}.peaks-generated`);
+    }
+    async materialize(beeName, env, segments) {
+        const dir = await this.resolveScratchDir(beeName);
+        if (existsSync(dir))
+            rmSync(dir, { recursive: true, force: true });
+        mkdirSync(dir, { recursive: true });
+        const frontmatter = `---\nname: peaks-bee-${beeName}\ndescription: peaks-loop generated bee ${beeName} — see local SkillHub for source\n---\n\n`;
+        const body = `${env.preamble}\n\n` + segments.map((s) => s.skillMd).join("\n\n");
+        writeFileSync(join(dir, "SKILL.md"), frontmatter + body);
+        mkdirSync(join(dir, "scripts"), { recursive: true });
+        for (const s of segments) {
+            for (const sc of s.scripts)
+                writeFileSync(join(dir, "scripts", sc.name), sc.content);
+        }
+        return dir;
+    }
+    async publish(scratchDir) {
+        return scratchDir;
+    }
+    async activate(_scratchDir) {
+        /* no-op; runtime picks up by convention */
+    }
+    async cleanup(scratchDir) {
+        if (existsSync(scratchDir))
+            rmSync(scratchDir, { recursive: true, force: true });
+    }
+}

package/dist/src/services/adapter/codex-adapter.d.ts

@@ -0,0 +1,14 @@
+import { Adapter } from "./adapter.js";
+export declare class CodexAdapter implements Pick<Adapter, "name"> {
+    private readonly _o;
+    readonly name: "codex";
+    constructor(_o: {
+        home: string;
+    });
+    detect(): Promise<boolean>;
+    resolveScratchDir(): Promise<void>;
+    materialize(): Promise<void>;
+    publish(): Promise<void>;
+    activate(): Promise<void>;
+    cleanup(): Promise<void>;
+}

package/dist/src/services/adapter/codex-adapter.js

@@ -0,0 +1,14 @@
+import { ADAPTER_NOT_IMPLEMENTED } from "./adapter.js";
+export class CodexAdapter {
+    _o;
+    name = "codex";
+    constructor(_o) {
+        this._o = _o;
+    }
+    async detect() { return false; }
+    async resolveScratchDir() { throw new ADAPTER_NOT_IMPLEMENTED("codex", "resolveScratchDir"); }
+    async materialize() { throw new ADAPTER_NOT_IMPLEMENTED("codex", "materialize"); }
+    async publish() { throw new ADAPTER_NOT_IMPLEMENTED("codex", "publish"); }
+    async activate() { throw new ADAPTER_NOT_IMPLEMENTED("codex", "activate"); }
+    async cleanup() { throw new ADAPTER_NOT_IMPLEMENTED("codex", "cleanup"); }
+}

package/dist/src/services/adapter/copilot-adapter.d.ts

@@ -0,0 +1,14 @@
+import { Adapter } from "./adapter.js";
+export declare class CopilotAdapter implements Pick<Adapter, "name"> {
+    private readonly _o;
+    readonly name: "copilot";
+    constructor(_o: {
+        home: string;
+    });
+    detect(): Promise<boolean>;
+    resolveScratchDir(): Promise<void>;
+    materialize(): Promise<void>;
+    publish(): Promise<void>;
+    activate(): Promise<void>;
+    cleanup(): Promise<void>;
+}

package/dist/src/services/adapter/copilot-adapter.js

@@ -0,0 +1,14 @@
+import { ADAPTER_NOT_IMPLEMENTED } from "./adapter.js";
+export class CopilotAdapter {
+    _o;
+    name = "copilot";
+    constructor(_o) {
+        this._o = _o;
+    }
+    async detect() { return false; }
+    async resolveScratchDir() { throw new ADAPTER_NOT_IMPLEMENTED("copilot", "resolveScratchDir"); }
+    async materialize() { throw new ADAPTER_NOT_IMPLEMENTED("copilot", "materialize"); }
+    async publish() { throw new ADAPTER_NOT_IMPLEMENTED("copilot", "publish"); }
+    async activate() { throw new ADAPTER_NOT_IMPLEMENTED("copilot", "activate"); }
+    async cleanup() { throw new ADAPTER_NOT_IMPLEMENTED("copilot", "cleanup"); }
+}

package/dist/src/services/audit/enforcers/solo-code-ban.d.ts

@@ -2,7 +2,7 @@
  * Solo-code-ban enforcer — PreToolUse Bash guard.
  *
  * Per L2 redesign §5.4. Deny `git commit` or `git apply` invocations from
- * a peaks-* skill. The Solo Code-Change Red Line says peaks-solo / peaks-rd
+ * a peaks-* skill. The Solo Code-Change Red Line says peaks-code / peaks-rd
  * are orchestrators, not implementers; the actual `git commit` step must
  * go through `peaks request transition`, which itself enforces spec-locked
  * + tech-doc-presence.

package/dist/src/services/audit/enforcers/solo-code-ban.js

@@ -2,7 +2,7 @@
  * Solo-code-ban enforcer — PreToolUse Bash guard.
  *
  * Per L2 redesign §5.4. Deny `git commit` or `git apply` invocations from
- * a peaks-* skill. The Solo Code-Change Red Line says peaks-solo / peaks-rd
+ * a peaks-* skill. The Solo Code-Change Red Line says peaks-code / peaks-rd
  * are orchestrators, not implementers; the actual `git commit` step must
  * go through `peaks request transition`, which itself enforces spec-locked
  * + tech-doc-presence.
@@ -12,7 +12,7 @@
  * never bricked by a peaks bug.
  */
 const COMMIT_APPLY_PATTERN = /^\s*git\s+(commit|apply)\b/;
-const DENY_REASON = 'Solo Code-Change Red Line: peaks-* skills must go through peaks-solo / peaks-rd. ' +
+const DENY_REASON = 'Solo Code-Change Red Line: peaks-* skills must go through peaks-code / peaks-rd. ' +
     'Use `peaks request transition` instead of `git commit` / `git apply` directly.';
 export function isSoloCodeCommit(skill, command) {
     if (!skill.startsWith('peaks-'))

package/dist/src/services/audit/red-line-catalog.js

@@ -13,7 +13,7 @@ export const RED_LINE_CATALOG = [
         rule: 'Solo Code-Change Red Line',
         markers: ['BLOCKING', 'MANDATORY'],
         phrases: [
-            'peaks-solo',
+            'peaks-code',
             'orchestrator, NOT an implementer',
             'solo',
         ],

package/dist/src/services/audit/scanners/skills-tree-scanner.js

@@ -39,6 +39,28 @@ export function scanSkillsTree(input) {
     for (const entry of entries) {
         if (!entry.isDirectory() || entry.name.startsWith('.'))
             continue;
+        // LLM-internal skills live under `skills/bee/<name>/` per spec 2026-07-05.
+        // Recurse one level into `bee/` to cover all 9 demoted role/audit skills.
+        if (entry.name === 'bee') {
+            let subEntries;
+            try {
+                subEntries = readdirSync(join(skillsRoot, 'bee'), { withFileTypes: true });
+            }
+            catch (error) {
+                warnings.push({
+                    file: 'skills/bee',
+                    message: `readdir failed: ${error instanceof Error ? error.message : String(error)}`,
+                });
+                continue;
+            }
+            for (const subEntry of subEntries) {
+                if (!subEntry.isDirectory() || subEntry.name.startsWith('.'))
+                    continue;
+                const skillMd = readSkillFile(input.projectRoot, join('bee', subEntry.name), 'SKILL.md');
+                lines.push(...skillMd);
+            }
+            continue;
+        }
         const skillMd = readSkillFile(input.projectRoot, entry.name, 'SKILL.md');
         lines.push(...skillMd);
     }

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

@@ -9,7 +9,7 @@ export interface DispatchIdeCompactInput {
     /**
      * Slice 2026-06-28-solo-mode-bypass-fix (defect #4): which session
      * the compact should target. Default `'main'` — the orchestrator
-     * (peaks-solo body) runs in the main-session Claude Code window and
+     * (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
      * `'sub-agent'` to preserve the legacy shell-spawn behaviour.

package/dist/src/services/dispatch/batch-counter.js

@@ -3,7 +3,7 @@
  *
  * Empirical upper bound for one Dispatcher × one batch: 6 sub-agents.
  * Above 6, the LLM / human is encouraged to split into multiple
- * batches with an explicit reducer step in between. peaks-solo's
+ * batches with an explicit reducer step in between. peaks-code's
  * swarm phase dispatches 3; peaks-rd's 4-way fan-out dispatches 4;
  * peaks-qa's 3-way fan-out dispatches 3. The 6 limit leaves headroom
  * for "qa-business-api" / "qa-business-frontend" / "qa-business-regression"

package/dist/src/services/dispatch/leak-detector.js

@@ -1,7 +1,7 @@
 /**
  * Slice #009 / G5 RL-7 — dispatch record leak detector.
  *
- * After peaks-solo's reducer consumes a batch, any dispatch record that
+ * After peaks-code's reducer consumes a batch, any dispatch record that
  * is still `disposed === false` AND was created more than `thresholdMs`
  * ago is a **leak**. This helper scans the on-disk records under
  * `.peaks/_sub_agents/<sid>/` and returns the leaked ones. The CLI or

package/dist/src/services/doctor/doctor-service.js

@@ -538,7 +538,7 @@ export async function runDoctor(options = {}) {
             }
         }
     }
-    // Workspace guard: an active workflow presence (peaks-solo) with no workspace
+    // Workspace guard: an active workflow presence (peaks-code) with no workspace
     // session means the skill was anchored but `peaks workspace init` never ran —
     // the #1 reported failure where .peaks/ artifacts are never created. This
     // turns the SKILL.md "MUST create the workspace" prose into an executable check.
@@ -554,7 +554,7 @@ export async function runDoctor(options = {}) {
         checks.push({
             id: 'skill-presence:workspace',
             ok: false,
-            message: `Skill ${presence.skill} is active but no workspace session exists (.peaks/_runtime/session.json missing); run \`peaks workspace init --project <repo>\` — peaks-solo Step 0 must anchor the workspace before any work`
+            message: `Skill ${presence.skill} is active but no workspace session exists (.peaks/_runtime/session.json missing); run \`peaks workspace init --project <repo>\` — peaks-code Step 0 must anchor the workspace before any work`
         });
     }
     else {

package/dist/src/services/job/job-progress-store.d.ts

@@ -0,0 +1,60 @@
+/**
+ * v3.1.2 — On-disk slice progress mirror.
+ *
+ * After each `peaks job checkpoint --state done`, the orchestrator writes
+ * `.peaks/_runtime/<sessionId>/job/<jid>/progress.json` so the next LLM
+ * turn (after compact or resume) can read it before any Bash call lands.
+ *
+ * Shape (schemaVersion 1):
+ *   {
+ *     jobId, done, total, currentSlice, lastCommitSha, updatedAt
+ *   }
+ *
+ * The `peaks solo gate-step-08` hook reads this file in its case-1 path
+ * (job-shape.json says isJob=true) and surfaces `Next: slice #N+1 of M
+ * (<currentSlice>)` to stdout. The LLM cannot "wake up cold" — the
+ * next-slice context is mechanically injected on every Bash call.
+ *
+ * Karpathy §2 (Simplicity First): ~50 lines, single-purpose writer +
+ * reader. Schema is zod-validated on read so a stale on-disk copy
+ * from an earlier peaks-loop release fails loud (no silent fallback).
+ */
+import { z } from 'zod';
+export declare const JOB_PROGRESS_SCHEMA_VERSION: 1;
+export declare const JobProgressSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    jobId: z.ZodString;
+    done: z.ZodNumber;
+    total: z.ZodNumber;
+    currentSlice: z.ZodString;
+    lastCommitSha: z.ZodNullable<z.ZodString>;
+    updatedAt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    updatedAt: string;
+    done: number;
+    schemaVersion: 1;
+    jobId: string;
+    total: number;
+    currentSlice: string;
+    lastCommitSha: string | null;
+}, {
+    updatedAt: string;
+    done: number;
+    schemaVersion: 1;
+    jobId: string;
+    total: number;
+    currentSlice: string;
+    lastCommitSha: string | null;
+}>;
+export type JobProgress = z.infer<typeof JobProgressSchema>;
+export interface WriteProgressInput {
+    readonly jobId: string;
+    readonly done: number;
+    readonly total: number;
+    readonly currentSlice: string;
+    readonly lastCommitSha: string | null;
+    readonly updatedAt?: string;
+}
+export declare function writeJobProgress(projectRoot: string, sessionId: string, input: WriteProgressInput): JobProgress;
+export declare function readJobProgress(projectRoot: string, sessionId: string, jobId: string): JobProgress;
+export declare function tryReadJobProgress(projectRoot: string, sessionId: string, jobId: string): JobProgress | null;

package/dist/src/services/job/job-progress-store.js

@@ -0,0 +1,70 @@
+/**
+ * v3.1.2 — On-disk slice progress mirror.
+ *
+ * After each `peaks job checkpoint --state done`, the orchestrator writes
+ * `.peaks/_runtime/<sessionId>/job/<jid>/progress.json` so the next LLM
+ * turn (after compact or resume) can read it before any Bash call lands.
+ *
+ * Shape (schemaVersion 1):
+ *   {
+ *     jobId, done, total, currentSlice, lastCommitSha, updatedAt
+ *   }
+ *
+ * The `peaks solo gate-step-08` hook reads this file in its case-1 path
+ * (job-shape.json says isJob=true) and surfaces `Next: slice #N+1 of M
+ * (<currentSlice>)` to stdout. The LLM cannot "wake up cold" — the
+ * next-slice context is mechanically injected on every Bash call.
+ *
+ * Karpathy §2 (Simplicity First): ~50 lines, single-purpose writer +
+ * reader. Schema is zod-validated on read so a stale on-disk copy
+ * from an earlier peaks-loop release fails loud (no silent fallback).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+export const JOB_PROGRESS_SCHEMA_VERSION = 1;
+export const JobProgressSchema = z.object({
+    schemaVersion: z.literal(JOB_PROGRESS_SCHEMA_VERSION),
+    jobId: z.string(),
+    done: z.number().int().nonnegative(),
+    total: z.number().int().positive(),
+    currentSlice: z.string(),
+    lastCommitSha: z.string().nullable(),
+    updatedAt: z.string().datetime()
+});
+export function writeJobProgress(projectRoot, sessionId, input) {
+    const dir = join(projectRoot, '.peaks', '_runtime', sessionId, 'job', input.jobId);
+    mkdirSync(dir, { recursive: true });
+    const record = {
+        schemaVersion: JOB_PROGRESS_SCHEMA_VERSION,
+        jobId: input.jobId,
+        done: input.done,
+        total: input.total,
+        currentSlice: input.currentSlice,
+        lastCommitSha: input.lastCommitSha,
+        updatedAt: input.updatedAt ?? new Date().toISOString()
+    };
+    const path = join(dir, 'progress.json');
+    writeFileSync(path, JSON.stringify(record, null, 2) + '\n', 'utf8');
+    return record;
+}
+export function readJobProgress(projectRoot, sessionId, jobId) {
+    const path = join(projectRoot, '.peaks', '_runtime', sessionId, 'job', jobId, 'progress.json');
+    if (!existsSync(path)) {
+        throw new Error(`JobProgressStore: no progress for ${jobId} at ${path}`);
+    }
+    const raw = readFileSync(path, 'utf8');
+    return JobProgressSchema.parse(JSON.parse(raw));
+}
+export function tryReadJobProgress(projectRoot, sessionId, jobId) {
+    const path = join(projectRoot, '.peaks', '_runtime', sessionId, 'job', jobId, 'progress.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        return JobProgressSchema.parse(JSON.parse(raw));
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}

package/dist/src/services/job/job-resource-snapshot.js

@@ -26,10 +26,37 @@ export function collectResourceSnapshot(jobDir) {
         contextRatio,
     };
 }
-function dirSizeMb(dir) {
+// Non-enumerable internal attachment for test-time access via
+// `collectResourceSnapshot.dirSizeMb`. NOT a public export — keeps
+// the prod module surface clean per PRD while still allowing
+// targeted AC-1/AC-2/AC-3 unit tests to drive `dirSizeMb` directly.
+Object.defineProperty(collectResourceSnapshot, 'dirSizeMb', {
+    value: dirSizeMb,
+    enumerable: false,
+    writable: false,
+    configurable: false,
+});
+/**
+ * Best-effort, non-recursive size of one directory level, in rounded megabytes.
+ *
+ * - Missing directory → 0.
+ * - Per-entry stat failures (race with deletion, EBUSY on Windows) → silently skipped.
+ * - When `opts.maxEntries` > 0 and the directory has more entries than the cap,
+ *   the returned value is a partial sum (a lower bound), and no further `stat`
+ *   calls are issued past the cap. Callers must treat the value as a lower bound.
+ * - `opts.maxEntries` defaults to 0 (unbounded, legacy behaviour).
+ *
+ * NOTE: when maxEntries > 0 and the directory contains more entries than the
+ * cap, this is a partial sum. Callers must treat the value as a lower bound.
+ */
+function dirSizeMb(dir, opts) {
+    const cap = opts?.maxEntries ?? 0;
     let total = 0;
+    let index = 0;
     try {
         for (const name of readdirSync(dir)) {
+            if (cap > 0 && index >= cap)
+                break;
             try {
                 total += statSync(join(dir, name)).size;
             }
@@ -37,6 +64,7 @@ function dirSizeMb(dir) {
                 // best-effort: missing entries (race with deletion) are silently skipped
                 void e;
             }
+            index++;
         }
     }
     catch (e) {

package/dist/src/services/job/job-types.d.ts

@@ -192,6 +192,7 @@ export declare const JobStateSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     sessionId: string;
     startedAt: string;
+    jobId: string;
     slices: {
         status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
         label: string;
@@ -202,7 +203,6 @@ export declare const JobStateSchema: z.ZodObject<{
         failureReason?: string | undefined;
         blockedReason?: string | undefined;
     }[];
-    jobId: string;
     lastCheckpointAt: string;
     parallelismHint: "serial" | "llm-decides";
     exitPolicy: "strict" | "best-effort";
@@ -218,6 +218,7 @@ export declare const JobStateSchema: z.ZodObject<{
 }, {
     sessionId: string;
     startedAt: string;
+    jobId: string;
     slices: {
         status: "pending" | "skipped" | "done" | "failed" | "blocked" | "in-progress";
         label: string;
@@ -228,7 +229,6 @@ export declare const JobStateSchema: z.ZodObject<{
         repairCycles?: number | undefined;
         blockedReason?: string | undefined;
     }[];
-    jobId: string;
     lastCheckpointAt: string;
     parallelismHint?: "serial" | "llm-decides" | undefined;
     exitPolicy?: "strict" | "best-effort" | undefined;
@@ -296,9 +296,9 @@ export declare const JobStatusSummarySchema: z.ZodObject<{
     done: number;
     failed: number;
     blocked: number;
+    total: number;
     mainLoopStrategy: "single" | "rotating";
     mainSessionCycle: number;
-    total: number;
     lastCheckpoint: string;
     currentSlice?: string | undefined;
     etaSec?: number | undefined;
@@ -314,9 +314,9 @@ export declare const JobStatusSummarySchema: z.ZodObject<{
     done: number;
     failed: number;
     blocked: number;
+    total: number;
     mainLoopStrategy: "single" | "rotating";
     mainSessionCycle: number;
-    total: number;
     lastCheckpoint: string;
     currentSlice?: string | undefined;
     etaSec?: number | undefined;

package/dist/src/services/memory/project-memory-service.js

@@ -600,7 +600,7 @@ export function executeProjectMemoryExtract(options) {
         const safeMemoryDir = assertSafeProjectMemoryDir(plan.projectRoot);
         // Idempotency: skip writes for memories whose slug already lives in
         // .peaks/memory/. Re-running `peaks memory extract --apply` on the
-        // same handoff is a normal peaks-solo / peaks-txt retry pattern (the
+        // same handoff is a normal peaks-code / peaks-txt retry pattern (the
         // skill prompt may invoke extract more than once when a handoff is
         // edited and re-extracted). Without this, writeNewFile's O_EXCL
         // throws EEXIST and aborts the whole batch. Symmetric with