peaks-loop 3.0.3 → 3.1.1

package/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Changelog
 
+## 3.1.1 — 2026-07-03
+
+### Added — Step 0.8 detector-as-recorder (LLM-judged, CLI-validated)
+
+`peaks-solo` Step 0.8 is no longer prose-only: the LLM makes the Job-shape judgement, the CLI records it. The CLI is a **recorder and gate**, not a detector — no keyword regex anywhere in the service or CLI (the LLM is the source of truth). Downstream steps refuse to proceed until the decision file exists.
+
+- New service: `src/services/solo/job-shape-decision.ts` — `readJobShapeDecision` / `writeJobShapeDecision` / `validateJobShapeDecision`. Persists to `.peaks/_runtime/<sessionId>/job-shape.json`; server-side stamps `decidedAt` so the LLM cannot back-date; throws `JOB_SHAPE_NOT_DECIDED` on missing / unreadable / malformed.
+- New CLI subcommands:
+  - `peaks solo detect-job --is-job <bool> --rationale <text> --suggested-job-id <jid> [--suggested-strategy single|rotating] [--confidence high|medium|low] [--force]` — recorder. Validates `suggestedJobId` against `/^[a-z0-9][a-z0-9-]{2,40}$/`, hashes the user prompt, writes the file. Refuses overwrite without `--force`.
+  - `peaks solo read-job-shape` — downstream gate. Returns the current record or `JOB_SHAPE_NOT_DECIDED`.
+- New tests: `tests/unit/solo/job-shape-decision.test.ts` (validate happy/sad, server-stamp `decidedAt`, force semantics, missing/unreadable/malformed, round-trip, promptHash determinism), `tests/integration/solo-detect-job-command.test.ts` (CLI spawn happy / bad-flag / read-back / fresh / force), `tests/unit/solo/solo-step-08-block-guard.test.ts` (locks the SKILL.md / runbook contract: `BLOCKING on LLM judgement`, `peaks solo detect-job`, `peaks solo read-job-shape`, and runbook ordering before `# After Step 7`).
+
+### Hard red line #10 (v3.1.1)
+
+The LLM MUST NOT skip `peaks solo detect-job` even when the trigger is obvious from context. If the next step's `read-job-shape` throws `JOB_SHAPE_NOT_DECIDED`, Solo MUST record a decision before proceeding. Keyword-based "I already know it's a Job" is not a substitute — the LLM is the only authority for the Job-shape judgement, and the CLI is the only place that records it.
+
+### Memory
+
+Incident + rationale: `.peaks/memory/2026-07-03-v3-1-0-job-trigger-miss.md`. This release closes the gap identified in that memory file.
+
+## 3.1.0 — 2026-07-03
+
+### Fixed — peaks-solo external-references authority declaration
+
+- `skills/peaks-solo/SKILL.md` External-references paragraph now ends with `Peaks-Loop Solo gates and artifacts remain authoritative.` to satisfy `tests/unit/skill-external-invocation.test.ts:63` (`PEAKS_AUTHORITATIVE_PATTERN`). One-line surgical patch; no behaviour change.
+
+### Added — Peaks-Loop Job
+
+- New `peaks job *` subcommand family: init / status / checkpoint / continue / resume / block / handoff / rotate-now / subagent-cleanup (9 commands).
+- New CLI flag `--main-loop-strategy single|rotating` on `job init`, with rotating-mode hard default for ≥3 slices and `rotateEvery=3` cadence.
+- New `--watch` poll mode + statusline event stub (`emitJobEvent`) for ambient progress visibility. Real statusline wire-up deferred to a follow-up slice.
+- Sub-agent wrapper `SubAgentJobWrapper` enforces `--budget-mb 512` default + cleanup gate before slice checkpoint.
+- New peaks-solo SKILL.md Steps 0.8 / 0.81 / 0.85 / 0.86 / 0.87 wrapping the existing single-rid runbook for multi-slice jobs.
+- 9 hard-red-line rules embedded in the skill prose (cost re-ask ban, slice-coalesce ban, fake-completion ban, detached-mode ban, cleanup-skip ban, rotate-skip ban, etc).
+
+### New services
+
+- `src/services/job/job-types.ts` — Zod schemas + types for SliceState, JobState, ResourceSnapshot, JobStatusSummary, plus CLI input schemas (JobInitInput, JobCheckpointInput, JobBlockInput).
+- `src/services/job/job-state-store.ts` — on-disk state store with per-job lockfile.
+- `src/services/job/job-orchestrator.ts` — state machine with strict / best-effort exit policies.
+- `src/services/job/job-rotation.ts` — main-session rotation cadence (single / rotating mode).
+- `src/services/job/subagent-job-wrapper.ts` — budget + cleanup gate.
+- `src/services/job/job-resource-snapshot.ts` — cpu / mem / disk / context collector.
+- `src/services/job/job-event-emitter.ts` — stderr-stub event emit (real statusline wire-up pending).
+
+### Migration
+
+- Existing single-rid flows are unchanged. The Job is opt-in via peaks-solo Step 0.8 detection; users who do not invoke multi-slice requests see no behavior difference.
+- The `peaks session rotate` and `peaks session cycle-summary` subcommands referenced in the spec are NOT shipped in v1; the rotation path uses constructor-injected stub callbacks. M6.5 follow-up will add the real subcommands.
+
+### Spec / plan
+
+- Design: `docs/superpowers/specs/2026-07-03-peaks-loop-job-design.md` (v3).
+- Plans: `docs/superpowers/plans/2026-07-03-peaks-job/` (M1-M7 + README).
+
 ## [3.0.3] — 2026-07-02 — auto-compact zero-pause (ide-native pathway)
 
 **PATCH bump from 3.0.2**. Closes the user-pause gap on long Claude Code sessions: at context ratio ≥ 0.95 the runner now compacts itself via a PreToolUse hook, no human intervention required.

package/dist/src/cli/commands/job-commands.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+import { type ProgramIO } from '../cli-helpers.js';
+export declare function registerJobCommands(program: Command, io?: ProgramIO): void;

package/dist/src/cli/commands/job-commands.js

@@ -0,0 +1,236 @@
+// src/cli/commands/job-commands.ts
+import { join } from 'node:path';
+import { Command } from 'commander';
+import { fail, ok } from '../../shared/result.js';
+import { addJsonOption, printResult } from '../cli-helpers.js';
+import { JobStateStore } from '../../services/job/job-state-store.js';
+import { JobOrchestrator } from '../../services/job/job-orchestrator.js';
+import { JobRotation } from '../../services/job/job-rotation.js';
+import { SubAgentJobWrapper } from '../../services/job/subagent-job-wrapper.js';
+import { emitJobEvent } from '../../services/job/job-event-emitter.js';
+import { JobInitInputSchema, JobCheckpointInputSchema, JobBlockInputSchema, } from '../../services/job/job-types.js';
+import { getCurrentSessionId } from '../../services/skills/skill-presence-service.js';
+function projectRoot(opts) {
+    // Reuse the workspace root resolver from peaks CLI; for now, CWD as a safe placeholder.
+    return opts.project ?? process.cwd();
+}
+/**
+ * Resolves the on-disk root for Job state files.
+ *
+ * Per spec §3.3 + §4.5 (2.7.1 single-scope-axis layout), Job state lives at:
+ *   `<projectRoot>/.peaks/_runtime/<sessionId>/job/<jobId>/state.json`
+ *
+ * The `JobStateStore` itself only knows its `rootDir` + `jobId` and joins them. We
+ * compute the canonical root here (per-call) so the store can stay layout-agnostic.
+ *
+ * Resolution order:
+ * 1. `--session-id` flag (explicit override)
+ * 2. `getCurrentSessionId(project)` — reads `.peaks/_runtime/session.json` per peaks-solo
+ * 3. Error (NO_ACTIVE_SESSION) — must never silently fall back to a random uuid
+ */
+function resolveJobStateRoot(opts) {
+    const project = projectRoot(opts);
+    const sessionId = opts.sessionId ?? getCurrentSessionId(project);
+    if (!sessionId) {
+        throw new Error('NO_ACTIVE_SESSION: peaks job requires --session-id or an active peaks-solo session via peaks workspace init');
+    }
+    const rootDir = join(project, '.peaks', '_runtime', sessionId, 'job');
+    return { rootDir, sessionId, projectRoot: project };
+}
+export function registerJobCommands(program, io = { stdout: (t) => process.stdout.write(t), stderr: (t) => process.stderr.write(t) }) {
+    const job = new Command('job').description('Drive long multi-slice work as one Job (peaks-solo Step 0.8+)');
+    job
+        .command('init')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--slice-list <list>')
+        .option('--parallelism-hint <serial|llm-decides>', 'llm-decides')
+        .option('--exit-policy <strict|best-effort>', 'strict')
+        .option('--main-loop-strategy <single|rotating>', 'rotating')
+        .option('--rotate-every <n>', 'rotate every N slices (rotating mode)', '3')
+        .option('--session-id <sid>', 'session id (default: read from .peaks/_runtime/session.json; required to land in the 2.7.1 single-scope-axis layout)')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const project = projectRoot(opts);
+        // Resolve sessionId: explicit flag > canonical session binding > FAIL.
+        // Per spec §3.3, Job state lives at .peaks/_runtime/<sessionId>/job/<jobId>/state.json —
+        // a random UUID would scatter state across dirs and break resume/auto-compact.
+        let sessionId = opts.sessionId ?? getCurrentSessionId(project);
+        if (!sessionId) {
+            return printResult(io, fail('init', 'NO_ACTIVE_SESSION', 'peaks job init requires --session-id (or an active peaks-solo session via peaks workspace init)', { project }, [
+                'Re-run with --session-id <sid>',
+                'Or run `peaks workspace init` to create a session first'
+            ]), opts);
+        }
+        const parsed = JobInitInputSchema.safeParse({
+            jobId: opts.jobId,
+            sessionId,
+            sliceList: opts.sliceList.split(',').map((s) => s.trim()).filter(Boolean),
+            parallelismHint: opts.parallelismHint,
+            exitPolicy: opts.exitPolicy,
+            mainLoopStrategy: opts.mainLoopStrategy,
+            rotateEvery: Number(opts.rotateEvery),
+            project,
+            json: opts.json,
+        });
+        if (!parsed.success)
+            return printResult(io, fail('init', 'INVALID_INIT', parsed.error.message, {}), opts);
+        const jobRoot = resolveJobStateRoot(opts);
+        const store = new JobStateStore(jobRoot.rootDir);
+        const orch = new JobOrchestrator(store);
+        const state = orch.init({
+            jobId: parsed.data.jobId,
+            sessionId: parsed.data.sessionId,
+            sliceList: parsed.data.sliceList,
+            parallelismHint: parsed.data.parallelismHint,
+            exitPolicy: parsed.data.exitPolicy,
+            mainLoopStrategy: parsed.data.mainLoopStrategy,
+            rotateEvery: parsed.data.rotateEvery,
+        });
+        try {
+            emitJobEvent({ kind: 'job-started', jobId: state.jobId, total: state.slices.length, strategy: state.mainLoopStrategy });
+        }
+        catch (e) {
+            // best-effort: event emission failures must not abort job init
+            void e;
+        }
+        printResult(io, ok('init', { jobId: state.jobId, sliceCount: state.slices.length, statePath: `${jobRoot.rootDir}/${state.jobId}/state.json` }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'init'));
+    job
+        .command('status')
+        .requiredOption('--job-id <jid>')
+        .option('--watch', 'poll every 3s')
+        .option('--show-cost', 'overlay cost from peaks budget')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        const s = orch.status(opts.jobId);
+        if (opts.watch) {
+            const draw = () => {
+                const bar = `[${'='.repeat(s.done)}${' '.repeat(s.total - s.done)}]`;
+                process.stdout.write(`\rjob ${opts.jobId}: ${bar} ${s.done}/${s.total}${s.currentSlice ? ` next=${s.currentSlice}` : ''}    `);
+            };
+            draw();
+            const iv = setInterval(() => { const u = orch.status(opts.jobId); Object.assign(s, u); draw(); if (u.done + u.failed + u.skipped + u.blocked >= u.total)
+                clearInterval(iv); }, 3000);
+            process.on('SIGINT', () => { clearInterval(iv); process.stdout.write('\n'); process.exit(0); });
+            return;
+        }
+        try {
+            emitJobEvent({ kind: 'job-progress', jobId: opts.jobId, done: s.done, total: s.total, ...(s.currentSlice ? { currentSlice: s.currentSlice } : {}) });
+        }
+        catch (e) {
+            // best-effort: event emission failures must not abort job status
+            void e;
+        }
+        printResult(io, ok('status', s), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'status'));
+    // M4.2: wire rotate-now to JobRotation (session-rotate callbacks are stubs pending M6.5 batch-fix).
+    job.command('rotate-now')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const rotation = new JobRotation(store, async (_jid) => { /* delegate to peaks session rotate — implementation wired in M6.5 batch-fix */ return { rotated: true }; }, async (jid) => ({ jobId: jid, cycle: 0 }));
+        const r = await rotation.rotateNow(opts.jobId);
+        printResult(io, ok('rotate-now', r), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'rotate-now'));
+    job.command('subagent-cleanup')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--batch-id <bid>')
+        .option('--force')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const wrapper = new SubAgentJobWrapper(new JobStateStore(resolveJobStateRoot(opts).rootDir), async () => ({ batchId: opts.batchId }));
+        const r = await wrapper.cleanup({ jobId: opts.jobId, batchId: opts.batchId, force: !!opts.force });
+        printResult(io, ok('subagent-cleanup', r), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'subagent-cleanup'));
+    // M3.2: wire the remaining 5 subcommand slots — block, checkpoint, continue, handoff, resume.
+    job
+        .command('checkpoint')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--slice-id <rid>')
+        .requiredOption('--state <done|failed|skipped>')
+        .option('--commit-sha <sha>')
+        .option('--reason <text>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const parsed = JobCheckpointInputSchema.safeParse({
+            jobId: opts.jobId, sliceId: opts.sliceId, state: opts.state,
+            commitSha: opts.commitSha, reason: opts.reason,
+            project: projectRoot(opts), json: opts.json,
+        });
+        if (!parsed.success)
+            return printResult(io, fail('checkpoint', 'INVALID_CHECKPOINT', parsed.error.message, {}), opts);
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        if (parsed.data.state === 'done') {
+            await orch.checkpointDone({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, ...(parsed.data.commitSha ? { commitSha: parsed.data.commitSha } : {}) });
+        }
+        else if (parsed.data.state === 'skipped') {
+            await orch.checkpointSkipped({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, reason: parsed.data.reason });
+        }
+        else {
+            await orch.checkpointFailed({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, reason: parsed.data.reason });
+        }
+        printResult(io, ok('checkpoint', { sliceId: parsed.data.sliceId, status: parsed.data.state }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'checkpoint'));
+    job
+        .command('block')
+        .requiredOption('--job-id <jid>')
+        .requiredOption('--slice-id <rid>')
+        .requiredOption('--reason <text>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const parsed = JobBlockInputSchema.safeParse({
+            jobId: opts.jobId, sliceId: opts.sliceId, reason: opts.reason,
+            project: projectRoot(opts), json: opts.json,
+        });
+        if (!parsed.success)
+            return printResult(io, fail('block', 'INVALID_BLOCK', parsed.error.message, {}), opts);
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        await orch.blockSlice(parsed.data);
+        printResult(io, ok('block', { blocked: parsed.data.sliceId, reason: parsed.data.reason }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'block'));
+    job
+        .command('continue')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        const r = orch.continueNow(opts.jobId);
+        printResult(io, ok('continue', r), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'continue'));
+    job
+        .command('resume')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        const s = orch.status(opts.jobId);
+        printResult(io, ok('resume', { resumed: opts.jobId, ...s }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'resume'));
+    job
+        .command('handoff')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .action(async (opts) => {
+        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const orch = new JobOrchestrator(store);
+        const s = orch.status(opts.jobId);
+        printResult(io, ok('handoff', { handoffFor: opts.jobId, ...s }), opts);
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'handoff'));
+    program.addCommand(job);
+}

package/dist/src/cli/commands/solo-commands.js

@@ -15,6 +15,8 @@
  *   - `peaks solo should-pause --step <step> --mode <mode>` (D5)
  *   - `peaks solo post-compact-detect --project <path>` (D7)
  */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
 import { addJsonOption, getErrorMessage, printResult } from '../cli-helpers.js';
 import { fail, ok } from '../../shared/result.js';
 import { emitObservabilityEvent } from '../../services/observability/observability-service.js';
@@ -23,6 +25,7 @@ import { GATED_STEPS, isHardFloorCategory, isSoloMode, isCommitBoundaryAction, s
 import { getSkillPresence, checkStalePresence } from '../../services/skills/skill-presence-service.js';
 import { detectPostCompactResume, formatPostCompactResumeLogLine } from '../../services/solo/post-compact-detector.js';
 import { runAutoCompact } from '../../services/solo/auto-compact-orchestrator.js';
+import { readJobShapeDecision, writeJobShapeDecision, JobShapeDecisionError, JOB_SHAPE_NOT_DECIDED, JOB_SHAPE_ALREADY_DECIDED } from '../../services/solo/job-shape-decision.js';
 const STEP_ORDER = [
     'load-memory',
     'standards-preflight',
@@ -421,6 +424,140 @@ export function registerSoloCommands(program, io) {
             process.exitCode = 1;
         }
     });
+    // v3.1.1 Step 0.8 — Job-shape decision recorder.
+    // The CLI is a *recorder*, not a judge. The LLM supplies the verdict
+    // (--is-job, --rationale, --suggested-job-id, --suggested-strategy,
+    // --confidence); the CLI validates the shape, stamps `decidedAt`
+    // server-side, and writes to `.peaks/_runtime/<sessionId>/job-shape.json`.
+    addJsonOption(solo
+        .command('detect-job')
+        .description('v3.1.1 Step 0.8: record the LLM\'s Job-shape judgement. CLI is a recorder, NOT a detector. ' +
+        'Pass --is-job true|false, --rationale <text>, --suggested-job-id <slug>. ' +
+        'Downstream steps call `peaks solo read-job-shape` and refuse to proceed if missing.')
+        .requiredOption('--is-job <bool>', 'true | false (the LLM\'s semantic verdict)')
+        .requiredOption('--rationale <text>', '1-3 sentences the LLM writes explaining the call')
+        .requiredOption('--suggested-job-id <jid>', 'LLM-chosen stable id, slug-safe (/^[a-z0-9][a-z0-9-]{2,40}$/)')
+        .option('--suggested-strategy <single|rotating>', 'single | rotating', 'single')
+        .option('--confidence <high|medium|low>', 'high | medium | low', 'medium')
+        .option('--force', 'overwrite an existing decision file')
+        .option('--session-id <sid>', 'override session id (default: read from active presence)')
+        .option('--project <path>', 'target project root (default: findProjectRoot(cwd))')
+        .option('--prompt <text>', 'override the prompt hashed into promptHash (default: read last-prompt.txt if present, else empty)')).action(async (opts) => {
+        try {
+            if (opts.isJob !== 'true' && opts.isJob !== 'false') {
+                printResult(io, fail('solo.detect-job', 'INVALID_FLAG', `--is-job must be true | false (got "${opts.isJob}")`, { provided: opts.isJob }, ['Pass --is-job true or --is-job false']), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (opts.suggestedStrategy !== 'single' && opts.suggestedStrategy !== 'rotating') {
+                printResult(io, fail('solo.detect-job', 'INVALID_FLAG', `--suggested-strategy must be single | rotating (got "${opts.suggestedStrategy}")`, { provided: opts.suggestedStrategy }, ['Pass --suggested-strategy single or --suggested-strategy rotating']), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            if (opts.confidence !== 'high' && opts.confidence !== 'medium' && opts.confidence !== 'low') {
+                printResult(io, fail('solo.detect-job', 'INVALID_FLAG', `--confidence must be high | medium | low (got "${opts.confidence}")`, { provided: opts.confidence }, ['Pass --confidence high | medium | low']), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            const jidRe = /^[a-z0-9][a-z0-9-]{2,40}$/;
+            if (!jidRe.test(opts.suggestedJobId)) {
+                printResult(io, fail('solo.detect-job', 'INVALID_FLAG', `--suggested-job-id must match /^[a-z0-9][a-z0-9-]{2,40}$/ (got "${opts.suggestedJobId}")`, { provided: opts.suggestedJobId }, ['Pass a slug-safe id (lowercase, digits, dashes; 3-41 chars)']), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const sessionId = opts.sessionId ?? readActiveSid(projectRoot);
+            if (sessionId === null) {
+                printResult(io, fail('solo.detect-job', 'NO_ACTIVE_SESSION', 'no active session id; pass --session-id or set presence via `peaks skill presence:set peaks-solo`', null, ['Re-run with --session-id <sid>']), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            // Prompt source: explicit --prompt > last-prompt.txt > empty.
+            let promptText = opts.prompt ?? '';
+            if (opts.prompt === undefined) {
+                const lastPromptPath = join(projectRoot, '.peaks', '_runtime', sessionId, 'txt', 'last-prompt.txt');
+                if (existsSync(lastPromptPath)) {
+                    try {
+                        promptText = readFileSync(lastPromptPath, 'utf8');
+                    }
+                    catch { // TODO(g2): legacy silent catch — grace: 1 minor release
+                        promptText = '';
+                    }
+                }
+            }
+            const record = writeJobShapeDecision(projectRoot, sessionId, {
+                isJob: opts.isJob === 'true',
+                rationale: opts.rationale,
+                suggestedJobId: opts.suggestedJobId,
+                suggestedStrategy: opts.suggestedStrategy,
+                confidence: opts.confidence,
+                prompt: promptText
+            }, { force: opts.force === true });
+            printResult(io, ok('solo.detect-job', {
+                sessionId: record.sessionId,
+                promptHash: record.promptHash,
+                decision: record.decision,
+                schemaVersion: record.schemaVersion
+            }, [], [
+                `Decision recorded: isJob=${record.decision.isJob} strategy=${record.decision.suggestedStrategy} confidence=${record.decision.confidence}`,
+                `File: .peaks/_runtime/${record.sessionId}/job-shape.json`
+            ]), opts.json);
+        }
+        catch (err) {
+            if (err instanceof JobShapeDecisionError) {
+                const code = err.code === JOB_SHAPE_ALREADY_DECIDED ? JOB_SHAPE_ALREADY_DECIDED : err.code === JOB_SHAPE_NOT_DECIDED ? JOB_SHAPE_NOT_DECIDED : err.code;
+                printResult(io, fail('solo.detect-job', code, err.message, err.details ?? null, [
+                    err.code === JOB_SHAPE_ALREADY_DECIDED
+                        ? 'Re-run with --force to overwrite the existing decision.'
+                        : 'Re-run with valid flags.'
+                ]), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, fail('solo.detect-job', 'DETECT_JOB_FAILED', getErrorMessage(err), null, ['Verify the flags and try again']), opts.json);
+            process.exitCode = 1;
+        }
+    });
+    // v3.1.1 Step 0.8 — read-only validator. Downstream steps call this
+    // to refuse to proceed if the LLM has not yet recorded a decision.
+    addJsonOption(solo
+        .command('read-job-shape')
+        .description('v3.1.1 Step 0.8: return the recorded Job-shape decision. ' +
+        'Returns JOB_SHAPE_NOT_DECIDED when the LLM has not yet recorded a verdict.')
+        .option('--session-id <sid>', 'override session id (default: read from active presence)')
+        .option('--project <path>', 'target project root (default: findProjectRoot(cwd))')).action((opts) => {
+        try {
+            const projectRoot = opts.project ?? findProjectRoot(process.cwd()) ?? process.cwd();
+            const sessionId = opts.sessionId ?? readActiveSid(projectRoot);
+            if (sessionId === null) {
+                printResult(io, fail('solo.read-job-shape', 'NO_ACTIVE_SESSION', 'no active session id; pass --session-id or set presence via `peaks skill presence:set peaks-solo`', null, ['Re-run with --session-id <sid>']), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            const record = readJobShapeDecision(projectRoot, sessionId);
+            printResult(io, ok('solo.read-job-shape', {
+                sessionId: record.sessionId,
+                promptHash: record.promptHash,
+                decision: record.decision,
+                schemaVersion: record.schemaVersion
+            }, [], [
+                `Decision on file: isJob=${record.decision.isJob} strategy=${record.decision.suggestedStrategy} confidence=${record.decision.confidence}`
+            ]), opts.json);
+        }
+        catch (err) {
+            if (err instanceof JobShapeDecisionError) {
+                printResult(io, fail('solo.read-job-shape', err.code, err.message, err.details ?? null, [
+                    err.code === JOB_SHAPE_NOT_DECIDED
+                        ? 'Run `peaks solo detect-job` to record a decision.'
+                        : 'Investigate the decision file integrity.'
+                ]), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, fail('solo.read-job-shape', 'READ_JOB_SHAPE_FAILED', getErrorMessage(err), null, ['Verify the project path and try again']), opts.json);
+            process.exitCode = 1;
+        }
+    });
 }
 function readActiveSid(projectRoot) {
     try {

package/dist/src/cli/program.js

@@ -74,6 +74,8 @@ import { registerObservabilityCommands } from './commands/observability-commands
 // CLI primitives. See src/services/compact/ and
 // src/cli/commands/compact-command.ts.
 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';
 import { applyRetention } from '../services/log/retention.js';
 import { writeLogEntry, maybeWriteStderr } from '../services/log/logger.js';
 export { printResult } from './cli-helpers.js';
@@ -341,5 +343,9 @@ Run peaks (no arguments) for a quickstart. You likely want one of:
     // suggest|recommend|survival|dry-run|force` — strategic-compact CLI
     // primitives. See src/cli/commands/compact-command.ts.
     registerCompactCommands(program, io);
+    // Slice 2026-07-01-job-m3.1: `peaks job init|status|...` — Job
+    // orchestration CLI surface. M3.1 wires init + status + 2 stubs;
+    // the remaining 5 subcommands land in M3.2.
+    registerJobCommands(program, io);
     return program;
 }

package/dist/src/services/job/job-event-emitter.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Stub Job event emitter. Logs to stderr so Job lifecycle is visible during CLI runs.
+ * M7.5 batch-fix task will wire to a real statusline event bus if/when the project
+ * adds one. Until then, this is the only Job-event surface.
+ */
+export type JobEvent = {
+    kind: 'job-started';
+    jobId: string;
+    total: number;
+    strategy: 'single' | 'rotating';
+} | {
+    kind: 'job-progress';
+    jobId: string;
+    done: number;
+    total: number;
+    currentSlice?: string;
+} | {
+    kind: 'job-blocked';
+    jobId: string;
+    sliceId: string;
+    reason: string;
+} | {
+    kind: 'job-completed';
+    jobId: string;
+    done: number;
+    failed: number;
+    blocked: number;
+    skipped: number;
+};
+export declare function emitJobEvent(event: JobEvent): void;

package/dist/src/services/job/job-event-emitter.js

@@ -0,0 +1,5 @@
+export function emitJobEvent(event) {
+    // Write to stderr so it doesn't pollute the JSON-envelope stdout that the CLI emits.
+    // Prepend a tag so downstream tools can grep for it.
+    process.stderr.write(`[job-event] ${JSON.stringify(event)}\n`);
+}

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

@@ -0,0 +1,50 @@
+import { JobStateStore, type JobInitInput } from './job-state-store.js';
+import { type JobState, type JobStatusSummary } from './job-types.js';
+export interface CheckpointDoneInput {
+    jobId: string;
+    sliceId: string;
+    commitSha?: string;
+}
+export interface CheckpointSkipInput {
+    jobId: string;
+    sliceId: string;
+    reason: string;
+}
+export interface BlockInput {
+    jobId: string;
+    sliceId: string;
+    reason: string;
+}
+export declare class JobOrchestrator {
+    private readonly store;
+    constructor(store: JobStateStore);
+    init(input: JobInitInput): JobState;
+    /**
+     * Atomically apply a mutation to a job's state under a single-process lock.
+     *
+     * Uses the M2.1 single-process lock model (lock file checked with `existsSync`).
+     * State is loaded before lock acquisition, so `fn` receives a consistent snapshot;
+     * if `tryAcquireLock` throws because the job is already locked, `fn` is never called
+     * and the error bubbles to the caller. Concurrent `mutate` calls in the same process
+     * will collide, so callers MUST serialize externally or wrap calls in a higher-level
+     * mutex if multi-process support is added later.
+     *
+     * @param jobId - The job identifier whose state will be mutated.
+     * @param fn - Pure transform applied to the loaded state to produce the next state.
+     * @returns The new state after the mutation is persisted.
+     */
+    private mutate;
+    checkpointDone(input: CheckpointDoneInput): Promise<JobState>;
+    checkpointSkipped(input: CheckpointSkipInput): Promise<JobState>;
+    checkpointFailed(input: {
+        jobId: string;
+        sliceId: string;
+        reason: string;
+    }): Promise<JobState>;
+    blockSlice(input: BlockInput): Promise<JobState>;
+    status(jobId: string): JobStatusSummary;
+    continueNow(jobId: string): {
+        remaining: number;
+        next: string | undefined;
+    };
+}