peaks-loop 3.1.0 → 3.1.2

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # Changelog
 
+## 3.1.2 — 2026-07-04
+
+### Added — Mechanical Job-mode gates (Step 0.8 enforcement)
+
+The v3.1.1 recorder-only design was bypassed twice under load (2026-07-03 35-slice incident, 2026-07-04 3018-file incident): the LLM skipped `peaks solo detect-job` and ran fake-completion narratives instead of Job mode. The v3.1.2 patch converts Step 0.8 from "LLM should call" to "LLM cannot proceed without calling" through four mechanical gates — no LLM interpretation required.
+
+- **PreToolUse hook** — `peaks workspace init` now installs a `Bash` matcher in `.claude/settings.local.json` (TEMPLATE_VERSION bumped 1.2.0 → 1.3.0) that runs `peaks solo gate-step-08 --project .` before every Bash call. Exit 0 = allow, exit 2 = block. Existing `Write|Edit|MultiEdit` matcher preserved. Re-running `peaks workspace init` is idempotent (`templateContentMatches`).
+- **`peaks solo gate-step-08`** — new service `src/services/solo/step-08-gate.ts` (~120 LOC) + CLI. Reads `.peaks/_runtime/<sessionId>/job-shape.json`. When `decision.isJob=true` AND `job/<jid>/progress.json` exists, prints `Next: slice #<done+1> of <total> (<currentSlice>)` so the LLM cannot wake up cold. When the file is missing AND the user's prompt (from `--prompt` / `last-prompt.txt`) matches the fail-closed backup regex `/(until|全部|until all done|disavow cost|不用考虑费用|all of them)/i`, exits 2 with `BLOCKED:` on stderr.
+- **Size-fear ban** — `peaks solo emit-handoff`. New service `src/services/solo/emit-handoff.ts` (~70 LOC) + CLI. Under Job mode (`isJob=true`), refuses to emit a final handoff while `remaining > 0`. Codes: `JOB_NOT_INITIALIZED` (no state.json), `JOB_REMAINING_BLOCKED` (remaining > 0), allow when `remaining === 0`, allow under `--force-under-job` override.
+- **Forced auto-compact** — extended `peaks solo context-now` with `--enforce-job-mode` (auto-enabled when `job-shape.json` says `isJob=true`). At `ratio >= 0.85` returns `action: 'auto-compact-now'` (MANDATORY, not advisory); at `ratio >= 0.95` returns `action: 'red-line'`. SKILL.md Step N+2 prose updated: "in Job mode, ≥ 0.85 is MANDATORY auto-compact."
+- **On-disk slice progress** — `peaks job checkpoint --state done` now writes `.peaks/_runtime/<sessionId>/job/<jid>/progress.json` after updating state.json. New `peaks job progress --job-id <jid>` reader. `gate-step-08` reads the same file in its allow-job path so the LLM gets resume context BEFORE any Bash call. SKILL.md Step 0.7 updated: "if progress.json exists, read it FIRST and surface `Next: slice #N of M (<currentSlice>)`."
+
+### Tests (v3.1.2)
+
+- `tests/unit/solo/gate-step-08.test.ts` — 9 unit tests covering the 4 paths + Next: slice context injection + backup-regex sanity + prompt-source fallback.
+- `tests/unit/solo/emit-handoff.test.ts` — 10 unit tests covering the 4 paths + `--force-under-job` override + `JOB_NOT_INITIALIZED` + skipped-slices edge case + `--job-id` override.
+- `tests/integration/solo-gate-step-08-hook.test.ts` — 5 integration tests spawning `node bin/peaks.js solo gate-step-08` as a real child process (the hook protocol itself), asserting exit 0 / exit 2 + stderr BLOCKED line + JSON envelope shape.
+- Extended `tests/unit/solo/solo-step-08-block-guard.test.ts` to assert SKILL.md + runbook.md reference `peaks solo gate-step-08`, `peaks solo emit-handoff`, `peaks job progress`, and the Job-mode MANDATORY auto-compact prose.
+- Extended `tests/unit/workspace/workspace-init-claude-hooks.test.ts` case-A to assert both PreToolUse matchers (`Write|Edit|MultiEdit` AND `Bash`) are emitted with the new Bash command invoking `peaks solo gate-step-08`.
+
+### Memory
+
+Two consecutive ship-day incidents motivated this release: `2026-07-03-v3-1-0-job-trigger-miss.md` (35-slice app/ batch) + `2026-07-04-v3-1-1-second-incident-3018-files.md` (3018-file UT batch). Lesson: "a skill that says MUST without a mechanical gate is not a real gate." The hook is the difference between "the LLM is told to do X" and "the LLM cannot proceed without X having happened."
+
+## 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

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

@@ -5,6 +5,7 @@ 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 { writeJobProgress, readJobProgress, tryReadJobProgress } from '../../services/job/job-progress-store.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';
@@ -166,10 +167,25 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         });
         if (!parsed.success)
             return printResult(io, fail('checkpoint', 'INVALID_CHECKPOINT', parsed.error.message, {}), opts);
-        const store = new JobStateStore(resolveJobStateRoot(opts).rootDir);
+        const jobRoot = resolveJobStateRoot(opts);
+        const store = new JobStateStore(jobRoot.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 } : {}) });
+            // v3.1.2: after each --state done, mirror slice progress to
+            // .peaks/_runtime/<sessionId>/job/<jid>/progress.json so the
+            // next LLM turn (or peaks solo gate-step-08 hook) can read it.
+            const project = projectRoot(opts);
+            const sessId = jobRoot.sessionId;
+            const state = orch.status(parsed.data.jobId);
+            writeJobProgress(project, sessId, {
+                jobId: parsed.data.jobId,
+                done: state.done,
+                total: state.total,
+                currentSlice: state.currentSlice ?? `slice-${state.done + 1}`,
+                lastCommitSha: parsed.data.commitSha ?? null,
+                updatedAt: new Date().toISOString()
+            });
         }
         else if (parsed.data.state === 'skipped') {
             await orch.checkpointSkipped({ jobId: parsed.data.jobId, sliceId: parsed.data.sliceId, reason: parsed.data.reason });
@@ -221,6 +237,43 @@ export function registerJobCommands(program, io = { stdout: (t) => process.stdou
         printResult(io, ok('resume', { resumed: opts.jobId, ...s }), opts);
     });
     addJsonOption(job.commands.find(c => c.name() === 'resume'));
+    // v3.1.2: read the on-disk slice progress mirror written by `peaks
+    // job checkpoint --state done`. Used by peaks solo gate-step-08 and
+    // by peaks-solo Step 0.7 (resume) to surface `Next: slice #N of M
+    // (<currentSlice>)` without re-deriving from state.json.
+    job
+        .command('progress')
+        .description('v3.1.2: read the on-disk slice progress mirror (.peaks/_runtime/<sid>/job/<jid>/progress.json). ' +
+        'Returns { jobId, done, total, currentSlice, lastCommitSha, updatedAt }.')
+        .requiredOption('--job-id <jid>')
+        .option('--project <repo>')
+        .option('--allow-missing', 'return done=0/total=0 envelope instead of failing when progress.json is absent')
+        .action(async (opts) => {
+        try {
+            const jobRoot = resolveJobStateRoot(opts);
+            const sessId = jobRoot.sessionId;
+            const project = projectRoot(opts);
+            const progress = opts.allowMissing === true
+                ? tryReadJobProgress(project, sessId, opts.jobId)
+                : readJobProgress(project, sessId, opts.jobId);
+            if (progress === null) {
+                printResult(io, fail('progress', 'NO_PROGRESS', `No progress.json for job ${opts.jobId} at .peaks/_runtime/${sessId}/job/${opts.jobId}/progress.json`, { jobId: opts.jobId, sessionId: sessId }, [
+                    'Run `peaks job checkpoint --state done ...` at least once to seed progress.json.',
+                    'Or pass --allow-missing to return a zero-progress envelope.'
+                ]), opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            printResult(io, ok('progress', progress, [], [
+                `Next: slice #${progress.done + 1} of ${progress.total} (${progress.currentSlice})`
+            ]), opts.json);
+        }
+        catch (err) {
+            printResult(io, fail('progress', 'PROGRESS_READ_FAILED', err instanceof Error ? err.message : String(err), { jobId: opts.jobId }, ['Verify the job id and try again']), opts.json);
+            process.exitCode = 1;
+        }
+    });
+    addJsonOption(job.commands.find(c => c.name() === 'progress'));
     job
         .command('handoff')
         .requiredOption('--job-id <jid>')

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,9 @@ 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';
+import { evaluateStep08, STEP_08_BACKUP_REGEX } from '../../services/solo/step-08-gate.js';
+import { evaluateEmitHandoff, JOB_NOT_INITIALIZED, JOB_REMAINING_BLOCKED } from '../../services/solo/emit-handoff.js';
 const STEP_ORDER = [
     'load-memory',
     'standards-preflight',
@@ -380,38 +385,88 @@ export function registerSoloCommands(program, io) {
         'without requiring the LLM to pass --prompt-size <bytes> manually. ' +
         'Adapter-driven (no hard-coded IDE names): Claude Code is the MVP ' +
         'implementation; trae / codex / cursor / qoder / tongyi-lingma / ' +
-        'hermes / openclaw register their own env-var via IdeAdapter.compact.')
+        'hermes / openclaw register their own env-var via IdeAdapter.compact. ' +
+        'v3.1.2: when --enforce-job-mode is set OR job-shape.json says isJob=true, ' +
+        '≥0.85 emits action=auto-compact-now (MANDATORY, not advisory) and ' +
+        '≥0.95 emits action=red-line (forced hook fires next turn).')
         .requiredOption('--project <path>', 'target project root')
-        .option('--session-id <sid>', 'override session id (default: read from active presence)')).action(async (opts) => {
+        .option('--session-id <sid>', 'override session id (default: read from active presence)')
+        .option('--enforce-job-mode', 'v3.1.2: treat ≥0.85 as MANDATORY auto-compact (not advisory). Auto-enabled when job-shape.json says isJob=true.')).action(async (opts) => {
         try {
             const { readContextPercent } = await import('../../services/context/auto-compact-reader.js');
+            // v3.1.2: detect Job mode from job-shape.json when --enforce-job-mode
+            // is not explicitly passed. The LLM is the source of truth for
+            // whether the request is Job-shaped; the recorded decision is.
+            let isJobMode = opts.enforceJobMode === true;
+            if (!isJobMode) {
+                try {
+                    const sessionIdForDecision = opts.sessionId ?? readActiveSid(opts.project);
+                    if (sessionIdForDecision !== null) {
+                        const record = readJobShapeDecision(opts.project, sessionIdForDecision);
+                        if (record.decision.isJob)
+                            isJobMode = true;
+                    }
+                }
+                catch (err) {
+                    if (!(err instanceof JobShapeDecisionError))
+                        throw err;
+                    // missing/malformed decision file is fine — fall back to advisory.
+                }
+            }
             const probe = readContextPercent({
                 projectRoot: opts.project,
                 sessionId: opts.sessionId ?? readActiveSid(opts.project) ?? 'unknown',
                 env: process.env
             });
             const ratioPct = (probe.ratio * 100).toFixed(1);
-            const verdict = probe.ratio >= 0.95 ? 'red-line'
-                : probe.ratio >= 0.85 ? 'pre-compact'
-                    : probe.ratio >= 0.5 ? 'soft-warn'
+            let action = 'ok';
+            let next = null;
+            if (probe.ratio >= 0.95) {
+                action = isJobMode ? 'red-line' : 'red-line';
+                next = 'peaks session auto-compact-hook';
+            }
+            else if (probe.ratio >= 0.85) {
+                if (isJobMode) {
+                    action = 'auto-compact-now';
+                    next = 'peaks session auto-compact --execute';
+                }
+                else {
+                    action = 'soft-warn';
+                }
+            }
+            else if (probe.ratio >= 0.5) {
+                action = 'soft-warn';
+            }
+            const verdict = action === 'red-line' ? 'red-line'
+                : action === 'auto-compact-now' ? 'pre-compact'
+                    : action === 'soft-warn' ? 'soft-warn'
                         : 'ok';
+            const jobModeNotice = isJobMode
+                ? 'Job mode enforced: ≥0.85 is MANDATORY auto-compact (v3.1.2).'
+                : 'Advisory mode (single-rid): ≥0.85 is recommended, not mandatory.';
             printResult(io, ok('solo.context-now', {
                 ratio: probe.ratio,
                 ratioPct: `${ratioPct}%`,
                 verdict,
+                action,
+                next,
+                jobMode: isJobMode,
                 source: probe.source,
                 ide: probe.ide,
                 capacityBytes: probe.capacityBytes,
                 rawBytes: probe.rawBytes ?? null,
                 capturedAt: probe.capturedAt
             }, [], [
-                verdict === 'red-line'
-                    ? `RED LINE: ≥ 95%. Run \`peaks solo auto-compact\` immediately (next sub-agent dispatch will be blocked).`
-                    : verdict === 'pre-compact'
-                        ? `Pre-compact zone (85–95%). Run \`peaks solo auto-compact\` to converge now.`
-                        : verdict === 'soft-warn'
-                            ? `Soft warn (50–85%). Continue working; the next \`peaks context now\` will re-check.`
-                            : `Below 50%. No action required.`
+                action === 'red-line'
+                    ? `RED LINE: ≥ 95%. Next: \`${next}\` (PreToolUse hook fires next turn).`
+                    : action === 'auto-compact-now'
+                        ? `Job-mode MANDATORY auto-compact. Solo MUST call \`${next}\` WITHOUT confirmation.`
+                        : action === 'soft-warn'
+                            ? isJobMode
+                                ? `Job mode soft-warn (50–85%). Continue working; the next \`peaks context now\` will re-check.`
+                                : `Soft warn (50–85%). Continue working; the next \`peaks context now\` will re-check.`
+                            : `Below 50%. No action required.`,
+                jobModeNotice
             ]), true);
         }
         catch (err) {
@@ -421,6 +476,314 @@ 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;
+        }
+    });
+    // v3.1.2 Step 0.8 — Mechanical PreToolUse gate.
+    // Wire-installed by `peaks workspace init` (extends the existing hook
+    // installer). Exit code is the load-bearing contract:
+    //   exit 0 → allow (with structured stdout describing the decision)
+    //   exit 2 → block (stderr contains the BLOCKED: ... reason)
+    addJsonOption(solo
+        .command('gate-step-08')
+        .description('v3.1.2: PreToolUse gate for Step 0.8 — allow when job-shape.json exists; ' +
+        'fail-closed backup regex when missing. Exit 0 = allow, exit 2 = block. ' +
+        'When the decision says isJob=true AND progress.json exists, the stdout ' +
+        'also carries `Next: slice #N+1 of M (<currentSlice>)` so the LLM cannot ' +
+        'wake up cold.')
+        .requiredOption('--project <path>', 'target project root (the hook passes "." so resolveCanonicalProjectRoot promotes it to the git root)')
+        .option('--session-id <sid>', 'override session id (default: read from active presence)')
+        .option('--prompt <text>', 'explicit prompt text (default: read last-prompt.txt; stdin ignored)')).action((opts) => {
+        try {
+            const sessionId = opts.sessionId ?? readActiveSid(opts.project);
+            if (sessionId === null) {
+                // No session binding — treat as allow (single-rid mode). The
+                // LLM has not yet anchored; we have nothing to gate against.
+                const envelope = ok('solo.gate-step-08', {
+                    allow: true,
+                    mode: 'no-session',
+                    decision: null,
+                    nextSlice: null
+                }, [], [
+                    'No active session id; gate passes through (single-rid mode).'
+                ]);
+                printResult(io, envelope, opts.json);
+                return;
+            }
+            const evalInput = {
+                projectRoot: opts.project,
+                sessionId
+            };
+            if (opts.prompt !== undefined)
+                evalInput.prompt = opts.prompt;
+            const result = evaluateStep08(evalInput);
+            const verdict = result.verdict;
+            if (verdict.kind === 'allow-job') {
+                const envelope = ok('solo.gate-step-08', {
+                    allow: true,
+                    mode: 'job',
+                    decision: verdict.decision,
+                    progress: verdict.progress,
+                    nextSlice: result.nextSliceLine
+                }, [], result.nextSliceLine !== null ? [result.nextSliceLine] : []);
+                printResult(io, envelope, opts.json);
+                return;
+            }
+            if (verdict.kind === 'allow-single') {
+                const envelope = ok('solo.gate-step-08', {
+                    allow: true,
+                    mode: 'single',
+                    decision: null,
+                    nextSlice: null
+                }, [], [
+                    'job-shape.json says isJob=false; single-rid mode (gate allows).'
+                ]);
+                printResult(io, envelope, opts.json);
+                return;
+            }
+            // block-missing-decision
+            if (verdict.promptHit) {
+                // Block: backup regex hit. Exit code 2 is the load-bearing
+                // signal for the PreToolUse hook.
+                const blockMessage = 'BLOCKED: prompt looks Job-shaped but peaks solo detect-job has not been called. Run `peaks solo detect-job --is-job true ...` to record your Job-shape verdict, then retry.';
+                const envelope = fail('solo.gate-step-08', 'STEP_08_BLOCKED', blockMessage, {
+                    promptSource: verdict.promptSource,
+                    backupRegex: STEP_08_BACKUP_REGEX.toString()
+                }, [
+                    'Run `peaks solo detect-job --is-job true --rationale <text> --suggested-job-id <slug>` to record the Job-shape verdict.',
+                    'Then re-run the Bash tool call.'
+                ]);
+                io.stderr(`${blockMessage}\n`);
+                printResult(io, envelope, opts.json);
+                process.exitCode = 2;
+                return;
+            }
+            // No decision + no regex hit → allow.
+            const envelope = ok('solo.gate-step-08', {
+                allow: true,
+                mode: 'undecided-no-regex-hit',
+                decision: null,
+                nextSlice: null,
+                promptSource: verdict.promptSource
+            }, [], [
+                'No job-shape.json AND no backup-regex match on prompt → allow (most prompts are not Job-shaped).'
+            ]);
+            printResult(io, envelope, opts.json);
+            return;
+        }
+        catch (err) {
+            printResult(io, fail('solo.gate-step-08', 'GATE_STEP_08_FAILED', getErrorMessage(err), null, [
+                'Verify the project path and try again'
+            ]), opts.json);
+            process.exitCode = 1;
+        }
+    });
+    // v3.1.2 Step 11 / final handoff — Size-fear ban.
+    // Refuses to emit a final handoff while a Job has remaining slices.
+    addJsonOption(solo
+        .command('emit-handoff')
+        .description('v3.1.2 Step 11 size-fear ban: under Job mode, refuse to emit a final ' +
+        'handoff while remaining > 0. Exit 0 = allow, exit 1 = block. Pass ' +
+        '--force-under-job to override (requires explicit user approval).')
+        .requiredOption('--project <path>', 'target project root')
+        .option('--session-id <sid>', 'override session id (default: read from active presence)')
+        .option('--job-id <jid>', 'override job id (default: read from job-shape.json decision.suggestedJobId)')
+        .option('--force-under-job', 'override the remaining>0 block (explicit user approval required)')).action((opts) => {
+        try {
+            const sessionId = opts.sessionId ?? readActiveSid(opts.project);
+            if (sessionId === null) {
+                const envelope = ok('solo.emit-handoff', { allow: true, mode: 'no-session' }, [], [
+                    'No active session id; gate passes through (single-rid mode).'
+                ]);
+                printResult(io, envelope, opts.json);
+                return;
+            }
+            const evalInput = {
+                projectRoot: opts.project,
+                sessionId
+            };
+            if (opts.jobId !== undefined)
+                evalInput.jobId = opts.jobId;
+            if (opts.forceUnderJob === true)
+                evalInput.forceUnderJob = true;
+            const verdict = evaluateEmitHandoff(evalInput);
+            if (verdict.kind === 'allow-not-job') {
+                const envelope = ok('solo.emit-handoff', { allow: true, mode: 'single' }, [], [
+                    'job-shape.json says isJob=false (or absent); normal handoff allowed.'
+                ]);
+                printResult(io, envelope, opts.json);
+                return;
+            }
+            if (verdict.kind === 'allow-done') {
+                const envelope = ok('solo.emit-handoff', { allow: true, mode: 'job-done', remaining: verdict.remaining }, [], [
+                    `Job is complete (remaining=0); handoff allowed.`
+                ]);
+                printResult(io, envelope, opts.json);
+                return;
+            }
+            if (verdict.kind === 'allow-force-override') {
+                const envelope = ok('solo.emit-handoff', { allow: true, mode: 'job-force-override', remaining: verdict.remaining }, [], [
+                    `Job has ${verdict.remaining} remaining slices; --force-under-job override applied. Handoff allowed (explicit user approval).`
+                ]);
+                printResult(io, envelope, opts.json);
+                return;
+            }
+            if (verdict.kind === 'block-not-initialized') {
+                const envelope = fail('solo.emit-handoff', JOB_NOT_INITIALIZED, `Job ${verdict.jobId} has no state.json; peaks job init was skipped.`, { jobId: verdict.jobId }, [`Run \`peaks job init --job-id ${verdict.jobId} --slice-list <...>\` before emitting handoff.`]);
+                printResult(io, envelope, opts.json);
+                process.exitCode = 1;
+                return;
+            }
+            // block-remaining
+            const blockMessage = `BLOCKED: Job ${verdict.jobId} has ${verdict.remaining} remaining slices. Run \`peaks job status\`. Use --force-under-job only with explicit user approval.`;
+            const envelope = fail('solo.emit-handoff', JOB_REMAINING_BLOCKED, blockMessage, { jobId: verdict.jobId, remaining: verdict.remaining }, [
+                `Run \`peaks job status --job-id ${verdict.jobId}\` to see remaining slices.`,
+                'Resume Step 0.81 (per-slice checkpoint loop) and continue until remaining === 0.',
+                'Use --force-under-job only with explicit user approval (size-fear ban override).'
+            ]);
+            io.stderr(`${blockMessage}\n`);
+            printResult(io, envelope, opts.json);
+            process.exitCode = 1;
+            return;
+        }
+        catch (err) {
+            printResult(io, fail('solo.emit-handoff', 'EMIT_HANDOFF_FAILED', getErrorMessage(err), null, [
+                'Verify the project path and try again'
+            ]), opts.json);
+            process.exitCode = 1;
+        }
+    });
 }
 function readActiveSid(projectRoot) {
     try {

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;