peaks-loop 3.1.0 → 3.1.1

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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

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/services/solo/job-shape-decision.d.ts

@@ -0,0 +1,71 @@
+/**
+ * v3.1.1 Step 0.8 — Job-shape decision recorder.
+ *
+ * The CLI is a *recorder and gate*, not a judge. The LLM makes the
+ * semantic call ("is this a Job?") and writes the verdict via
+ * `peaks solo detect-job`; this service persists the verdict to
+ * `.peaks/_runtime/<sessionId>/job-shape.json` and refuses downstream
+ * steps that need a decision when the file is missing.
+ *
+ * Karpathy §2 (Simplicity First): ~100 lines, pure validation + fs
+ * writes, NO keyword regex, NO LLM call inside. The LLM is the
+ * source of truth for whether the request is Job-shaped; this file
+ * just enforces that a decision was made at all.
+ *
+ * Decision file lives at `.peaks/_runtime/<sessionId>/job-shape.json`
+ * (sibling of `session.json`, NOT under `job/<jid>/` because no jid
+ * exists yet at the moment of Step 0.8).
+ */
+export type JobStrategy = 'single' | 'rotating';
+export type JobConfidence = 'high' | 'medium' | 'low';
+export interface JobShapeDecision {
+    readonly isJob: boolean;
+    readonly rationale: string;
+    readonly suggestedJobId: string;
+    readonly suggestedStrategy: JobStrategy;
+    readonly confidence: JobConfidence;
+    /** ISO 8601; stamped server-side in `writeJobShapeDecision`. */
+    readonly decidedAt: string;
+}
+export interface JobShapeRecord {
+    readonly sessionId: string;
+    /** sha1 of the user prompt (first 16 hex). */
+    readonly promptHash: string;
+    readonly decision: JobShapeDecision;
+    readonly schemaVersion: 1;
+}
+export declare const JOB_SHAPE_SCHEMA_VERSION: 1;
+export declare const JOB_SHAPE_FILE_NAME = "job-shape.json";
+export declare const JOB_SHAPE_ALREADY_DECIDED: "JOB_SHAPE_ALREADY_DECIDED";
+export declare const JOB_SHAPE_NOT_DECIDED: "JOB_SHAPE_NOT_DECIDED";
+export declare const JOB_SHAPE_INVALID: "JOB_SHAPE_INVALID";
+export declare class JobShapeDecisionError extends Error {
+    readonly code: typeof JOB_SHAPE_NOT_DECIDED | typeof JOB_SHAPE_ALREADY_DECIDED | typeof JOB_SHAPE_INVALID;
+    readonly details?: unknown;
+    constructor(opts: {
+        code: typeof JobShapeDecisionError.prototype.code;
+        message: string;
+        details?: unknown;
+    });
+}
+/** Pure validator; throws on bad input. No fs IO. */
+export declare function validateJobShapeDecision(input: unknown): JobShapeDecision;
+/** Read the canonical record; throws JOB_SHAPE_NOT_DECIDED if absent or malformed. */
+export declare function readJobShapeDecision(projectRoot: string, sessionId: string): JobShapeRecord;
+export interface WriteJobShapeDecisionInput {
+    readonly isJob: boolean;
+    readonly rationale: string;
+    readonly suggestedJobId: string;
+    readonly suggestedStrategy: JobStrategy;
+    readonly confidence: JobConfidence;
+    readonly prompt: string;
+}
+/**
+ * Persist a new decision; refuses overwrite unless `force: true`.
+ * Stamps `decidedAt` server-side via `now` (defaults to `new Date()`)
+ * so the LLM cannot back-date.
+ */
+export declare function writeJobShapeDecision(projectRoot: string, sessionId: string, decision: WriteJobShapeDecisionInput, opts?: {
+    force?: boolean;
+    now?: () => Date;
+}): JobShapeRecord;

package/dist/src/services/solo/job-shape-decision.js

@@ -0,0 +1,151 @@
+/**
+ * v3.1.1 Step 0.8 — Job-shape decision recorder.
+ *
+ * The CLI is a *recorder and gate*, not a judge. The LLM makes the
+ * semantic call ("is this a Job?") and writes the verdict via
+ * `peaks solo detect-job`; this service persists the verdict to
+ * `.peaks/_runtime/<sessionId>/job-shape.json` and refuses downstream
+ * steps that need a decision when the file is missing.
+ *
+ * Karpathy §2 (Simplicity First): ~100 lines, pure validation + fs
+ * writes, NO keyword regex, NO LLM call inside. The LLM is the
+ * source of truth for whether the request is Job-shaped; this file
+ * just enforces that a decision was made at all.
+ *
+ * Decision file lives at `.peaks/_runtime/<sessionId>/job-shape.json`
+ * (sibling of `session.json`, NOT under `job/<jid>/` because no jid
+ * exists yet at the moment of Step 0.8).
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+export const JOB_SHAPE_SCHEMA_VERSION = 1;
+export const JOB_SHAPE_FILE_NAME = 'job-shape.json';
+export const JOB_SHAPE_ALREADY_DECIDED = 'JOB_SHAPE_ALREADY_DECIDED';
+export const JOB_SHAPE_NOT_DECIDED = 'JOB_SHAPE_NOT_DECIDED';
+export const JOB_SHAPE_INVALID = 'JOB_SHAPE_INVALID';
+const SUGGESTED_JID_RE = /^[a-z0-9][a-z0-9-]{2,40}$/;
+const JobShapeDecisionSchema = z.object({
+    isJob: z.boolean(),
+    rationale: z.string().min(1).max(2000),
+    suggestedJobId: z.string().regex(SUGGESTED_JID_RE, 'suggestedJobId must match /^[a-z0-9][a-z0-9-]{2,40}$/'),
+    suggestedStrategy: z.enum(['single', 'rotating']),
+    confidence: z.enum(['high', 'medium', 'low']),
+    decidedAt: z.string().datetime()
+});
+const JobShapeRecordSchema = z.object({
+    sessionId: z.string().min(1),
+    promptHash: z.string().regex(/^[a-f0-9]{16}$/, 'promptHash must be 16 hex chars'),
+    decision: JobShapeDecisionSchema,
+    schemaVersion: z.literal(JOB_SHAPE_SCHEMA_VERSION)
+});
+export class JobShapeDecisionError extends Error {
+    code;
+    details;
+    constructor(opts) {
+        super(opts.message);
+        this.name = 'JobShapeDecisionError';
+        this.code = opts.code;
+        if (opts.details !== undefined)
+            this.details = opts.details;
+    }
+}
+function runtimeDir(projectRoot, sessionId) {
+    return join(projectRoot, '.peaks', '_runtime', sessionId);
+}
+function decisionPath(projectRoot, sessionId) {
+    return join(runtimeDir(projectRoot, sessionId), JOB_SHAPE_FILE_NAME);
+}
+function sha1Prefix16(input) {
+    return createHash('sha1').update(input, 'utf8').digest('hex').slice(0, 16);
+}
+/** Pure validator; throws on bad input. No fs IO. */
+export function validateJobShapeDecision(input) {
+    return JobShapeDecisionSchema.parse(input);
+}
+function validateRecord(input) {
+    return JobShapeRecordSchema.parse(input);
+}
+/** Read the canonical record; throws JOB_SHAPE_NOT_DECIDED if absent or malformed. */
+export function readJobShapeDecision(projectRoot, sessionId) {
+    const path = decisionPath(projectRoot, sessionId);
+    if (!existsSync(path)) {
+        throw new JobShapeDecisionError({
+            code: JOB_SHAPE_NOT_DECIDED,
+            message: `No Job-shape decision recorded for session ${sessionId}. Run \`peaks solo detect-job\` to record a decision.`,
+            details: { path }
+        });
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        throw new JobShapeDecisionError({
+            code: JOB_SHAPE_NOT_DECIDED,
+            message: `Job-shape decision file is unreadable for session ${sessionId}. Run \`peaks solo detect-job\` to re-record.`,
+            details: { path, cause: err instanceof Error ? err.message : String(err) }
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new JobShapeDecisionError({
+            code: JOB_SHAPE_NOT_DECIDED,
+            message: `Job-shape decision file is malformed JSON for session ${sessionId}. Run \`peaks solo detect-job --force\` to overwrite.`,
+            details: { path, cause: err instanceof Error ? err.message : String(err) }
+        });
+    }
+    try {
+        return validateRecord(parsed);
+    }
+    catch (err) {
+        throw new JobShapeDecisionError({
+            code: JOB_SHAPE_NOT_DECIDED,
+            message: `Job-shape decision file is schema-invalid for session ${sessionId}. Run \`peaks solo detect-job --force\` to overwrite.`,
+            details: { path, cause: err instanceof Error ? err.message : String(err) }
+        });
+    }
+}
+/**
+ * Persist a new decision; refuses overwrite unless `force: true`.
+ * Stamps `decidedAt` server-side via `now` (defaults to `new Date()`)
+ * so the LLM cannot back-date.
+ */
+export function writeJobShapeDecision(projectRoot, sessionId, decision, opts = {}) {
+    const path = decisionPath(projectRoot, sessionId);
+    if (existsSync(path) && opts.force !== true) {
+        throw new JobShapeDecisionError({
+            code: JOB_SHAPE_ALREADY_DECIDED,
+            message: `Job-shape decision already exists for session ${sessionId}. Re-run with --force to overwrite.`,
+            details: { path }
+        });
+    }
+    // Validate the LLM-supplied fields first so a bad call fails loud
+    // before we touch the filesystem.
+    const partial = {
+        isJob: decision.isJob,
+        rationale: decision.rationale,
+        suggestedJobId: decision.suggestedJobId,
+        suggestedStrategy: decision.suggestedStrategy,
+        confidence: decision.confidence
+    };
+    // Validate the LLM-supplied shape (decidedAt is server-stamped).
+    JobShapeDecisionSchema.omit({ decidedAt: true }).parse(partial);
+    const now = opts.now ?? (() => new Date());
+    const stamped = { ...partial, decidedAt: now().toISOString() };
+    const promptHash = sha1Prefix16(decision.prompt);
+    const record = {
+        sessionId,
+        promptHash,
+        decision: stamped,
+        schemaVersion: JOB_SHAPE_SCHEMA_VERSION
+    };
+    const dir = runtimeDir(projectRoot, sessionId);
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, JSON.stringify(record, null, 2) + '\n', 'utf8');
+    return record;
+}

package/dist/src/shared/version.d.ts

@@ -1 +1 @@
-export declare const CLI_VERSION = "3.1.0";
+export declare const CLI_VERSION = "3.1.1";

package/dist/src/shared/version.js

@@ -1 +1 @@
-export const CLI_VERSION = "3.1.0";
+export const CLI_VERSION = "3.1.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "Loop Engineering CLI — workflow primitive / loop guards / evaluators / slice orchestration",
   "author": "SquabbyZ",
   "license": "MIT",

package/skills/peaks-solo/SKILL.md

@@ -97,11 +97,24 @@ Per the "one-key completion" tenet, peaks-loop 2.0 detects 1.x consumers and pro
 
 → see `references/step-0-55-1x-detection.md` for the detection algorithm + AskUserQuestion options + persistence contract.
 
-### Peaks-Loop Step 0.8 — Job 启动
+### Peaks-Loop Step 0.8 — Job 启动 (BLOCKING on LLM judgement — v3.1.1 patch)
 
-Trigger: user mentions N parallel targets, "全部完成"/"until all done", or disavows cost.
+The CLI does NOT judge whether the request is Job-shaped — that's the LLM's job. Keyword regexes are wrong here (too brittle, miss natural-language variants, shift the LLM's semantic understanding into code). The CLI is a **recorder and gate**: the LLM makes the judgement, writes it via `peaks solo detect-job`, and downstream steps refuse to proceed until the decision file exists.
 
-Action: parse slice list → choose strategy (≤2 single / ≥3 rotating) → `peaks job init --job-id <jid> --slice-list <...> --main-loop-strategy rotating --rotate-every 3` → Step 1.
+LLM judgement criteria (read once, then call the recorder):
+- N parallel targets (`app/components/*`, `app/modules/*`, `for each subdir`, "以目录为维度", "把剩下的也跑了").
+- Completion phrase implying batch continuation (`until all done`, "继续执行下个 slice", "全部添加完", "all of them").
+- Cost / length disavowal (`不用考虑费用`, "don't worry about cost", "一直跑").
+- Explicit slice count (`25 slices`, "切分成 N 段", "拆成 N 块").
+
+Action:
+1. LLM reads the user prompt and applies judgement → `isJob: boolean + rationale + suggestedJobId + suggestedStrategy + confidence`.
+2. LLM calls `peaks solo detect-job --is-job <bool> --rationale <text> --suggested-job-id <jid> --suggested-strategy <single|rotating> --confidence <high|medium|low> [--force]`.
+3. CLI records to `.peaks/_runtime/<sessionId>/job-shape.json`.
+4. If `isJob: true` → `peaks job init --job-id <jid> --slice-list <...> --main-loop-strategy <strategy> --rotate-every 3` (BEFORE Step 1).
+5. Downstream steps (Step 1, Step 0.81, etc.) call `read-job-shape` to refuse if missing.
+
+**Hard rule (v3.1.1 red-line #10):** 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.
 
 ### Peaks-Loop Step 0.81 — per-slice 收尾
 

package/skills/peaks-solo/references/runbook.md

@@ -192,7 +192,32 @@ Repair loop details: see `## Mandatory RD QA repair loop` in SKILL.md for the fu
 
 # Peaks-Loop Default runbook — Job path (excerpt; full flow in references/job-loop.md)
 
-# After Step 7 (RD+QA commit) lands AND the user request was Job-shaped (Step 0.8 triggered):
+# Step 0.8 (BLOCKING): LLM judges Job-shape, CLI records it.
+# This is a RECORDER, not a detector. The LLM supplies --is-job + --rationale;
+# the CLI writes .peaks/_runtime/<sid>/job-shape.json. Downstream steps call
+# `peaks solo read-job-shape` to enforce the decision exists.
+
+# (The LLM does the semantic judgement, e.g.:)
+#   "The user named N=35 parallel app/ subdirs, said 'continue until all done',
+#    and disavowed cost. isJob=true, rationale=..., suggestedJobId=app-ut-batch,
+#    suggestedStrategy=rotating, confidence=high."
+peaks solo detect-job \
+  --is-job true \
+  --rationale "35 parallel app/ subdirs + 'until all done' + '不用考虑费用'" \
+  --suggested-job-id app-ut-batch \
+  --suggested-strategy rotating \
+  --confidence high
+
+# Step 0.81-init: if Job-shaped, init BEFORE Step 1.
+DECISION=$(peaks solo read-job-shape --json)
+if [ "$(echo "$DECISION" | jq -r '.data.decision.isJob')" = "true" ]; then
+  JID=$(echo "$DECISION" | jq -r '.data.decision.suggestedJobId')
+  STRATEGY=$(echo "$DECISION" | jq -r '.data.decision.suggestedStrategy')
+  # LLM-derived slice list (not CLI-derived).
+  peaks job init --job-id "$JID" --slice-list "<LLM_DERIVED>" --main-loop-strategy "$STRATEGY" --rotate-every 3 --json
+fi
+
+# After Step 7 (RD+QA commit) lands AND Step 0.8 fired (state.json exists):
 peaks job checkpoint --slice-id <rid> --state done --commit-sha $(git rev-parse HEAD)
 peaks job status --job-id <jid> --json
 peaks job subagent-cleanup --job-id <jid> --batch-id <bid> --force   # Step 0.87 gate