peaks-loop 3.1.0 → 3.1.2

package/dist/src/services/solo/step-08-gate.js

@@ -0,0 +1,136 @@
+/**
+ * v3.1.2 Step 0.8 — Mechanical PreToolUse gate.
+ *
+ * Wire-installed by `peaks workspace init` (extends the existing hook
+ * installer; does NOT replace the Write|Edit|MultiEdit fact-forcing
+ * bypass). The hook runs `peaks solo gate-step-08 --project .` before
+ * every Bash tool call. Exit code is the load-bearing contract:
+ *
+ *   exit 0 → allow (with structured stdout describing the decision)
+ *   exit 2 → block (stderr contains the BLOCKED: ... reason)
+ *
+ * Three decision paths:
+ *
+ *   1. `job-shape.json` exists with `decision.isJob === true`.
+ *      → allow, print `{ ok, allow, mode: 'job', decision }`. When a
+ *        matching `job/<jid>/progress.json` exists, also print
+ *        `Next: slice #<N+1> of <M> (<currentSlice>)` so the LLM sees
+ *        its resume context BEFORE any Bash call lands.
+ *   2. `job-shape.json` exists with `decision.isJob === false`.
+ *      → allow, print `{ ok, allow, mode: 'single' }`.
+ *   3. `job-shape.json` is MISSING — fail-closed guard. The LLM is the
+ *      source of truth, but if it never recorded a decision we run a
+ *      lightweight backup regex against the user's prompt:
+ *        /until|全部|until all done|disavow cost|不用考虑费用|all of them/i
+ *      match → block (exit 2) with the BLOCKED: stderr message.
+ *      no match → allow (exit 0) — most prompts are not Job-shaped.
+ *
+ * Karpathy §2 (Simplicity First): ~120 lines, no LLM call inside. The
+ * regex is the FIRST time peaks-loop accepts hardcoded keywords —
+ * explicitly scoped as a *fail-closed backup* (case 3), NOT a primary
+ * judgement. The LLM still owns the semantic call via
+ * `peaks solo detect-job`. The regex is a safety net for the v3.1.1
+ * incident class (LLM under load never records the decision at all).
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { readJobShapeDecision, JobShapeDecisionError, JOB_SHAPE_NOT_DECIDED } from './job-shape-decision.js';
+export const STEP_08_GATE_FILE_NAME = 'job-shape.json';
+export const STEP_08_PROGRESS_FILE_NAME = 'progress.json';
+/**
+ * Fail-closed backup regex — see module docstring case 3 for why this
+ * exists. Kept short and explicit; if the prompt mentions any of these
+ * triggers and `job-shape.json` is missing, the LLM is treated as
+ * having skipped `peaks solo detect-job` and the gate blocks.
+ *
+ * The list mirrors the v3.1.0 / v3.1.1 incident triggers verbatim:
+ *   继续执行下个 slice (until next slice) → until / 直到
+ *   全部添加完 / all of them            → 全部 / all of them
+ *   不用考虑费用                        → 不用考虑费用 / disavow cost
+ *   until all done                      → until all done
+ */
+export const STEP_08_BACKUP_REGEX = /直到|全部|until all done|disavow cost|不用考虑费用|all of them/i;
+export function runtimeSessionDir(projectRoot, sessionId) {
+    return join(projectRoot, '.peaks', '_runtime', sessionId);
+}
+function progressPath(projectRoot, sessionId, jid) {
+    // The progress file lives under job/<jid>/progress.json. The jid
+    // comes from job-shape.json (decision.suggestedJobId) — there is
+    // exactly one canonical jid per session under Job mode, so we read
+    // the matching path directly rather than enumerating the job/ dir.
+    // (Rotating mode spawns new jids but only one is "active" at a time;
+    // the active jid is the latest write to job-shape.json.)
+    return join(runtimeSessionDir(projectRoot, sessionId), 'job', jid, STEP_08_PROGRESS_FILE_NAME);
+}
+function readProgressIfAny(projectRoot, sessionId, jid) {
+    const path = progressPath(projectRoot, sessionId, jid);
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.jobId === 'string' &&
+            typeof parsed.done === 'number' &&
+            typeof parsed.total === 'number' &&
+            typeof parsed.currentSlice === 'string' &&
+            typeof parsed.updatedAt === 'string') {
+            return {
+                jobId: parsed.jobId,
+                done: parsed.done,
+                total: parsed.total,
+                currentSlice: parsed.currentSlice,
+                lastCommitSha: typeof parsed.lastCommitSha === 'string' ? parsed.lastCommitSha : null,
+                updatedAt: parsed.updatedAt
+            };
+        }
+        return null;
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}
+function readPromptFromLastPromptFile(projectRoot, sessionId) {
+    const path = join(runtimeSessionDir(projectRoot, sessionId), 'txt', 'last-prompt.txt');
+    if (!existsSync(path))
+        return '';
+    try {
+        return readFileSync(path, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Pure evaluator — does NOT write, does NOT exit. CLI wrapper in
+ * `src/cli/commands/solo-commands.ts` reads `allow` to set the process
+ * exit code (0 allow / 2 block) and prints the structured envelope.
+ */
+export function evaluateStep08(input) {
+    try {
+        const record = readJobShapeDecision(input.projectRoot, input.sessionId);
+        if (record.decision.isJob) {
+            const progress = readProgressIfAny(input.projectRoot, input.sessionId, record.decision.suggestedJobId);
+            const nextSliceLine = progress !== null
+                ? `Next: slice #${progress.done + 1} of ${progress.total} (${progress.currentSlice})`
+                : null;
+            return {
+                allow: true,
+                verdict: { kind: 'allow-job', decision: record.decision, progress },
+                nextSliceLine
+            };
+        }
+        return { allow: true, verdict: { kind: 'allow-single' }, nextSliceLine: null };
+    }
+    catch (err) {
+        if (err instanceof JobShapeDecisionError && err.code === JOB_SHAPE_NOT_DECIDED) {
+            const promptText = input.prompt ?? readPromptFromLastPromptFile(input.projectRoot, input.sessionId);
+            const hit = promptText.length > 0 && STEP_08_BACKUP_REGEX.test(promptText);
+            const source = input.prompt !== undefined ? 'flag' : promptText.length > 0 ? 'last-prompt-file' : 'stdin-empty';
+            if (hit) {
+                return { allow: false, verdict: { kind: 'block-missing-decision', promptHit: true, promptSource: source }, nextSliceLine: null };
+            }
+            return { allow: true, verdict: { kind: 'block-missing-decision', promptHit: false, promptSource: source }, nextSliceLine: null };
+        }
+        throw err;
+    }
+}

package/dist/src/services/workspace/claude-settings-template.d.ts

@@ -50,8 +50,13 @@ export declare const CLAUDE_SETTINGS_LOCAL_FILENAME = ".claude/settings.local.js
  *   1.2.0 — removed the `Bash` matcher; Edit/Write fact-forcing
  *           bypass is the only emit. Bash enforcement is owned by
  *           `peaks gate enforce` in `settings.json`.
+ *   1.3.0 — added the v3.1.2 `Bash` PreToolUse matcher that runs
+ *           `peaks solo gate-step-08 --project .` (Step 0.8 mechanical
+ *           gate). The existing Write|Edit|MultiEdit matcher is
+ *           preserved. The new matcher's exit code is the load-bearing
+ *           signal: 0 = allow, 2 = block (with stderr BLOCKED reason).
  */
-export declare const TEMPLATE_VERSION = "1.2.0";
+export declare const TEMPLATE_VERSION = "1.3.0";
 /**
  * Compare two serialized template strings for semantic equivalence.
  *

package/dist/src/services/workspace/claude-settings-template.js

@@ -50,8 +50,13 @@ export const CLAUDE_SETTINGS_LOCAL_FILENAME = '.claude/settings.local.json';
  *   1.2.0 — removed the `Bash` matcher; Edit/Write fact-forcing
  *           bypass is the only emit. Bash enforcement is owned by
  *           `peaks gate enforce` in `settings.json`.
+ *   1.3.0 — added the v3.1.2 `Bash` PreToolUse matcher that runs
+ *           `peaks solo gate-step-08 --project .` (Step 0.8 mechanical
+ *           gate). The existing Write|Edit|MultiEdit matcher is
+ *           preserved. The new matcher's exit code is the load-bearing
+ *           signal: 0 = allow, 2 = block (with stderr BLOCKED reason).
  */
-export const TEMPLATE_VERSION = '1.2.0';
+export const TEMPLATE_VERSION = '1.3.0';
 /**
  * Compare two serialized template strings for semantic equivalence.
  *
@@ -208,8 +213,42 @@ export function buildClaudeSettingsLocalJson() {
                             command: buildWriteHookCommand()
                         }
                     ]
+                },
+                {
+                    // v3.1.2 Step 0.8 — Mechanical PreToolUse gate. Runs
+                    // `peaks solo gate-step-08 --project .` before every Bash
+                    // tool call. Exit 0 = allow (with structured stdout
+                    // describing the decision + optional `Next: slice #N+1 of
+                    // M (<currentSlice>)` line when progress.json exists). Exit
+                    // 2 = block (stderr contains the BLOCKED: ... reason).
+                    // The existing Write|Edit|MultiEdit matcher is preserved.
+                    matcher: 'Bash',
+                    hooks: [
+                        {
+                            type: 'command',
+                            command: buildBashGateStep08Command()
+                        }
+                    ]
                 }
             ]
         }
     };
 }
+/**
+ * v3.1.2: build the Bash matcher command that runs `peaks solo
+ * gate-step-08`. We invoke the CLI directly (not via `node -e "..."`)
+ * because the CLI is the only legitimate source of the structured
+ * decision + Next: slice context. Exit code is the load-bearing
+ * signal — 0 = allow, 2 = block. The hook installer is idempotent:
+ * `templateContentMatches` compares the parsed matcher entries, so
+ * re-running `peaks workspace init` on a project that already has the
+ * Bash hook is a no-op (already-current).
+ */
+function buildBashGateStep08Command() {
+    // The hook receives the tool call on stdin. We ignore stdin and
+    // delegate entirely to `peaks solo gate-step-08`, which reads
+    // .peaks/_runtime/<sessionId>/job-shape.json and last-prompt.txt.
+    // `${CLAUDE_PROJECT_DIR}` resolves to the consumer project's root
+    // (Claude Code's standard convention).
+    return 'peaks solo gate-step-08 --project "${CLAUDE_PROJECT_DIR}"';
+}

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

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

package/dist/src/shared/version.js

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

package/package.json

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

package/skills/peaks-solo/SKILL.md

@@ -5,17 +5,15 @@ description: Full-auto orchestration facade for the Peaks-Loop skill family. Use
 
 ## Single-scope-axis naming convention (2.7.1)
 
-The `.peaks/` workspace has a **single scope axis** (session-id) plus a nested **sub-agent axis** under `.peaks/_sub_agents/<sessionId>/...`. Use `<sessionId>` (NEVER bare `<sid>`). The change-id axis is gone as of slice `2026-06-29-change-id-root-removal` — reviewable artifacts now live at `.peaks/_runtime/<sessionId>/<role>/...` (gitignored) with the change-id optionally embedded as a filename slug. CLI surface: session-id → `peaks session *`; sub-agent → `peaks sub-agent *`. OpenSpec's independent `openspec/changes/<change-id>/` vocabulary (L4) is preserved untouched.
-
-**2.7.1:** `recordBypass` / `isBypassLimitReached` had a legacy write path that bypassed `.peaks/_runtime/` (slice 2.7.1 fix in `request-commands.ts:410`). Now writes canonical `.peaks/_runtime/<sid>/`. `getChangeArtifactRoot` removed. Test `skills-skill-md-naming.test.ts` enforces (a) zero bare `<sid>`, (b) axis labels, (c) this callout.
+The `.peaks/` workspace has a **single scope axis** (session-id) plus a nested **sub-agent axis** under `.peaks/_sub_agents/<sessionId>/...`. Use `<sessionId>` (NEVER bare `<sid>`). Reviewable artifacts live at `.peaks/_runtime/<sessionId>/<role>/...` (gitignored); the change-id is an optional filename slug and does NOT route filesystem writes. CLI: session-id → `peaks session *`; sub-agent → `peaks sub-agent *`. OpenSpec's `openspec/changes/<change-id>/` vocabulary (L4) is preserved. Test `skills-skill-md-naming.test.ts` enforces (a) zero bare `<sid>`, (b) axis labels, (c) this callout.
 
 ## Karpathy guidance (Slice 1/6 — karpathy prompt-injection-lift)
 
-Every sub-agent dispatch (`peaks-prd`, `peaks-rd`, `peaks-qa`, `peaks-ui`, `peaks-sc`, `peaks-txt`) MUST receive the 4 Karpathy guidelines. Append the verbatim block from `peaks-rd/references/rd-sub-agent-dispatch.md` §"Karpathy-guidelines context" to the dispatch prompt. Canonical skill id: `andrej-karpathy-skills:karpathy-guidelines`. Summary: **#1 Think Before Coding**, **#2 Simplicity First** (min code, no speculative features, 800-line cap), **#3 Surgical Changes**, **#4 Goal-Driven Execution** (verifiable ACs, plan + verify checkpoints).
+Every sub-agent dispatch (`peaks-prd`, `peaks-rd`, `peaks-qa`, `peaks-ui`, `peaks-sc`, `peaks-txt`) MUST receive the 4 Karpathy guidelines. Append the verbatim block from `peaks-rd/references/rd-sub-agent-dispatch.md` §"Karpathy-guidelines context" to the dispatch prompt. Canonical skill id: `andrej-karpathy-skills:karpathy-guidelines`. Summary: **#1 Think Before Coding**, **#2 Simplicity First**, **#3 Surgical Changes**, **#4 Goal-Driven Execution**.
 
 ## Hard ban (effective 2.8.3 — read every session, no exceptions)
 
-Never create `.peaks/_runtime/<YYYY-MM-DD-*>/` at the top level of `.peaks/`. The post-v2.19.0 single-scope-axis convention requires ALL reviewable artifact dirs to live under `.peaks/_runtime/<sessionId>/<role>/...` (gitignored) — never as siblings of `.peaks/_runtime/`. The `peaks workspace init` flow creates only `.peaks/_runtime/<sessionId>/session.json`; reviewable artifact files are placed under that same dir by the writer. The change-id is preserved as an optional filename slug inside `.peaks/_runtime/<sessionId>/<role>/requests/<rid>-<change-id>.md` but does NOT route filesystem writes. If you find yourself about to write a date-prefixed directory directly under `.peaks/`, STOP and reroute under `.peaks/_runtime/<sessionId>/`. The `.gitignore` rule `.peaks/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]-*/` will block the write at commit time; the vitest guard at `tests/unit/workspace/top-level-change-id-guard.test.ts` (8 cases, including CLI help-text) will fail the suite if a regression sneaks through.
+Never create `.peaks/_runtime/<YYYY-MM-DD-*>/` at the top level of `.peaks/`. ALL reviewable artifact dirs live under `.peaks/_runtime/<sessionId>/<role>/...` (gitignored) — never as siblings of `.peaks/_runtime/`. `peaks workspace init` creates only `.peaks/_runtime/<sessionId>/session.json`. If you find yourself about to write a date-prefixed directory directly under `.peaks/`, STOP and reroute under `.peaks/_runtime/<sessionId>/`. The `.gitignore` rule + vitest guard at `tests/unit/workspace/top-level-change-id-guard.test.ts` enforce this.
 
 # Peaks-Loop Solo
 
@@ -31,7 +29,7 @@ This skill is the **primary surface**. The `peaks <cmd>` CLI is **auxiliary**
 
 ## Code-Change Red Line (BLOCKING — read before ANY tool call)
 
-**Peaks-Loop Solo is an orchestrator, NOT an implementer. You MUST NOT write, edit, or modify any application source code directly.** Every code change goes through `peaks-solo → RD → QA → verdict`. `full-auto`/`swarm` use `peaks sub-agent dispatch <role>`; `assisted`/`strict`/inline-fallback executes inline. **If you catch yourself about to write code, STOP.** Hand off to RD. Before declaring workflow complete, run `peaks workflow verify-pipeline --rid <rid> --project <repo> --json`.
+**Peaks-Loop Solo is an orchestrator, NOT an implementer. You MUST NOT write, edit, or modify any application source code directly.** Every code change goes through `peaks-solo → RD → QA → verdict`. **If you catch yourself about to write code, STOP.** Hand off to RD. Before declaring workflow complete, run `peaks workflow verify-pipeline --rid <rid> --project <repo> --json`.
 
 ## Peaks-Loop Startup sequence (MANDATORY — execute in order)
 
@@ -45,7 +43,7 @@ When a NEW conversation opens on a session whose `lastActivity` is from today AN
 
 ### Peaks-Loop Step N: Periodic checkpoint (auto-fire, no user action)
 
-Proactive context-overflow defense. CLI: `peaks session checkpoint [--reason <r>] [...flags]`. Fire `--reason periodic` every 20 tool calls (G1 hard-coded), `--reason artifact-written` per PRD/RD/QA/TXT write, `--reason context-fill` / `user-pause` / `user-close` as appropriate. See `references/periodic-checkpoint.md` (otherwise `tests/unit/solo/checkpoint-periodic-frequency.test.ts` fails).
+Proactive context-overflow defense. CLI: `peaks session checkpoint [--reason <r>] [...flags]`. Fire `--reason periodic` every 20 tool calls (G1 hard-coded), `--reason artifact-written` per PRD/RD/QA/TXT write. See `references/periodic-checkpoint.md` (otherwise `tests/unit/solo/checkpoint-periodic-frequency.test.ts` fails).
 
 ### Peaks-Loop Step 0.5: OpenSpec first-run opt-in (conditional)
 
@@ -55,9 +53,7 @@ Run when `openspec/` is absent and `.peaks/.peaks-openspec-opt-in.json` is missi
 
 ### Peaks-Loop Step 0.6: Audit + Goal (NEW)
 
-Invoke peaks-audit after need expressed; store approved goal at `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json`. **All autonomous work requires approved goal.** (v2.15.0+ business vs tech goal separated; see `.peaks/memory/peaks-loop-user-role-and-tech-decision.md`.)
-
-→ see `references/audit-goal-gate.md`.
+Invoke peaks-audit after need expressed; store approved goal at `.peaks/_runtime/<sessionId>/audit-goal/<rid>.json`. **All autonomous work requires approved goal.** → `references/audit-goal-gate.md`.
 
 ### Peaks-Loop Step N+1: Final Review (NEW)
 
@@ -65,11 +61,7 @@ After autonomous work (RD, QA, security, perf), invoke peaks-final-review for 4-
 
 ### Peaks-Loop Step N+2: Main-session context monitor (D6 + slice 2026-07-02)
 
-After every 4th tool call, probe via `peaks solo context-now --project <repo> --json`. Thresholds: 50% / **0.85 pre-compact / 0.95 red-line** (v2.13.0).
-
-**≥ 0.85**, LLM MUST fire `peaks solo auto-compact --execute --project <repo>` autonomously. **≥ 0.95** red line: next Bash/Task tool call fires `peaks session auto-compact-hook` (PreToolUse), which in-band spawns `claude --compact` against the current runner.
-
-**Karpathy §4 exception**: compact red line keeps runner alive → zero-intervention wins. LLM does NOT ask user to run `/compact`. Honor `--in-flight-batch` (D6.e).
+After every 4th tool call, probe via `peaks solo context-now --project <repo> --json`. Thresholds: 50% / **0.85 pre-compact / 0.95 red-line** (v2.13.0). **In Job mode ≥ 0.85 is MANDATORY auto-compact** (not advisory): Solo MUST call `peaks session auto-compact --execute --project <repo>` autonomously. Pass `--enforce-job-mode` to force the MANDATORY semantics in single-rid mode too (`job-shape.json` auto-enables it). **≥ 0.95** red line: next Bash/Task call fires `peaks session auto-compact-hook` (PreToolUse), in-band spawning `claude --compact`. **Karpathy §4 exception**: compact red line keeps runner alive → zero-intervention wins; LLM MUST NOT ask user to run `/compact`. Honor `--in-flight-batch` (D6.e).
 
 ### Peaks-Loop Step 0: Anchor the workflow (MANDATORY FIRST ACTIONS — no bail-out)
 
@@ -87,21 +79,30 @@ Run `peaks workspace init` + `peaks skill presence:set peaks-solo` BEFORE any an
 
 After Step 0, run the resume-detection probe; surface via `AskUserQuestion` if a slice is in flight.
 
-**v2.11.0 D7 override:** if the user just `/compact`ed, run `peaks solo post-compact-detect --project <repo> --json` FIRST. If `shouldAutoResume: true`, skip AskUserQuestion (D7.b). Log to `.peaks/_runtime/<sessionId>/txt/auto-decisions.md`. Cross-day / cross-machine resume NOT in scope (D7.g).
+**v3.1.2 resume rule:** if `.peaks/_runtime/<sessionId>/job/<jid>/progress.json` exists, read it FIRST and surface `Next: slice #N of M (<currentSlice>)`. `peaks job progress --job-id <jid> [--allow-missing]` is the canonical reader; the same JSON is surfaced by `peaks solo gate-step-08` on every Bash call.
+
+**v2.11.0 D7 override:** if user just `/compact`ed, run `peaks solo post-compact-detect --project <repo> --json` FIRST; `shouldAutoResume: true` skips AskUserQuestion (D7.b). Log to `.peaks/_runtime/<sessionId>/txt/auto-decisions.md`.
 
-→ see `references/resume-detection.md` for the full detection algorithm + classification table.
+→ see `references/resume-detection.md`.
 
 ### Peaks-Loop Step 0.55: 1.x → 2.0 detection (BLOCKING on first invocation per session, when the project is not on a 2.0 layout)
 
-Per the "one-key completion" tenet, peaks-loop 2.0 detects 1.x consumers and prompts upgrade. After Step 0.7 returns "fresh", run `peaks upgrade --detect-1x --project <root> --json`. If `isOneX: true`, surface `AskUserQuestion`. Persist to `.peaks/preferences.json`.
+After Step 0.7 returns "fresh", run `peaks upgrade --detect-1x --project <root> --json`. If `isOneX: true`, surface `AskUserQuestion`. Persist to `.peaks/preferences.json`. → `references/step-0-55-1x-detection.md`.
+
+### Peaks-Loop Step 0.8 — Job 启动 (BLOCKING on LLM judgement — v3.1.1 patch + v3.1.2 mechanical gates)
 
-→ see `references/step-0-55-1x-detection.md` for the detection algorithm + AskUserQuestion options + persistence contract.
+The CLI is a **recorder + gate** for job-shape (the LLM judges). LLM calls `peaks solo detect-job --is-job <bool> --rationale <text> --suggested-job-id <jid> --suggested-strategy <single|rotating> --confidence <high|medium|low>`, which writes `.peaks/_runtime/<sessionId>/job-shape.json`. Downstream steps call `read-job-shape` and refuse if missing.
 
-### Peaks-Loop Step 0.8 — Job 启动
+**Hard rule (v3.1.1 red-line #10):** LLM MUST NOT skip `peaks solo detect-job`. If `read-job-shape` throws `JOB_SHAPE_NOT_DECIDED`, record a decision before proceeding.
 
-Trigger: user mentions N parallel targets, "全部完成"/"until all done", or disavows cost.
+**v3.1.2 mechanical gates** (recorder-only was bypassed twice):
 
-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.
+- **PreToolUse hook** — `peaks workspace init` installs the `Bash` matcher `peaks solo gate-step-08 --project .`. Exits 0 when `job-shape.json` exists (also emits `Next: slice #N+1 of M` from `progress.json`); exits 2 BLOCKED when missing AND prompt matches a fail-closed backup regex; otherwise 0 (allow).
+- **Size-fear ban** — `peaks solo emit-handoff` refuses a final handoff while `remaining > 0` under Job mode.
+- **Forced auto-compact** — `peaks solo context-now --enforce-job-mode` (auto-enabled on `isJob=true`) returns `auto-compact-now` at ≥ 0.85; **In Job mode ≥ 0.85 is MANDATORY auto-compact** (not advisory).
+- **On-disk slice progress** — `peaks job checkpoint --state done` writes `progress.json`; `peaks job progress --job-id <jid> [--allow-missing]` is the canonical reader.
+
+Full mechanics (judgement criteria, hook table, backup-regex rationale, hook wiring) at `references/step-0-8-gate.md`.
 
 ### Peaks-Loop Step 0.81 — per-slice 收尾
 
@@ -113,37 +114,29 @@ Trigger: `repair-status` atCap=true, context-now red-line ≥5min, or `subagent-
 
 ### Peaks-Loop Step 0.86 — main session rotation
 
-Active in rotating mode; fires every `rotateEvery` slices or on-demand. Sequence: cycle-summary → checkpoint rotate-marker → `peaks session rotate` → next turn resumes via `peaks session resume --job-id <jid>`.
+Active in rotating mode; fires every `rotateEvery` slices or on-demand via `peaks job rotate-now`. Sequence: cycle-summary → checkpoint rotate-marker → `peaks session rotate` → next turn resumes via `peaks session resume --job-id <jid>`.
 
 ### Peaks-Loop Step 0.87 — sub-agent cleanup gate
 
 After every `peaks sub-agent dispatch --batch-id <id>` inside a Job, BEFORE next slice checkpoint: `peaks job subagent-cleanup --job-id <jid> --batch-id <id> --force`. Non-zero → block.
 
-→ see `references/job-loop.md` for state machine, visibility table, rotation cadence, cleanup gate, cross-day recovery, 9 red lines.
+→ see `references/job-loop.md` for state machine, visibility, rotation cadence, cross-day recovery, 9 red lines.
 
 ### Peaks-Loop Step 1: Mode selection
 
-Use `AskUserQuestion` with `Full auto (Recommended)` first when user did not name a profile OR skill presence is stale (run `peaks skill presence:check-stale --project <path> --json` first; `stale: true` ⇒ re-ask).
-
-→ see `references/mode-selection.md`, `references/fast-mode.md`, `references/mode-selection-with-stale-presence.md`.
+Use `AskUserQuestion` with `Full auto (Recommended)` first when user did not name a profile OR skill presence is stale (run `peaks skill presence:check-stale --project <path> --json` first; `stale: true` ⇒ re-ask). → `references/mode-selection.md`, `references/fast-mode.md`, `references/mode-selection-with-stale-presence.md`.
 
 ### Peaks-Loop Step 2: Re-set skill presence with the chosen mode
 
-Re-run `peaks skill presence:set peaks-solo --mode <mode-value> --gate startup`. Install statusline on first run (`peaks statusline install`).
-
-→ see `references/skill-presence-and-title.md`.
+Re-run `peaks skill presence:set peaks-solo --mode <mode-value> --gate startup`. Install statusline on first run (`peaks statusline install`). → `references/skill-presence-and-title.md`.
 
 ### Peaks-Loop Step 2.3: Load project memory (durable, LLM-authored memories)
 
-Run `peaks project memories --project <repo> --json` to read decisions / conventions / modules / rules / lessons from `.peaks/memory`. Use this to understand what exists, what was decided, what to avoid re-litigating.
-
-→ see `references/project-memory-loading.md` for the kind table.
+Run `peaks project memories --project <repo> --json` to read decisions / conventions / modules / rules / lessons from `.peaks/memory`. → `references/project-memory-loading.md`.
 
 ### Peaks-Loop Step 2.5: Set session title
 
-Extract a short title from the user's first request (8-20 Chinese chars or 4-10 English words). Run `peaks session title` with the active sid. Skip if a title is already set.
-
-→ see `references/skill-presence-and-title.md` (same file as Step 2).
+Extract a short title from the user's first request (8-20 Chinese chars or 4-10 English words). Run `peaks session title` with the active sid. Skip if a title is already set. → `references/skill-presence-and-title.md` (same file as Step 2).
 
 ## Sub-agent session sharing (MANDATORY — one conversation = one sid)
 
@@ -151,11 +144,7 @@ When peaks-solo dispatches a sub-agent (peaks-rd, peaks-qa, peaks-ui, peaks-txt,
 
 ## Boundaries
 
-Peaks-Loop Solo may: identify scenarios (refactor, bugfix, QA hardening, release validation, incident response); recommend profiles; coordinate role skills through artifacts; coordinate project memory extraction; request user confirmation at risk and commit boundaries.
-
-Peaks-Loop Solo must NOT silently install hooks, create agents, enable MCP servers, modify Claude settings, create GitHub repos, or bypass role-skill artifacts.
-
-→ see `references/boundaries.md` for the do / don't list.
+Peaks-Loop Solo may: identify scenarios, recommend profiles, coordinate role skills through artifacts, coordinate project memory extraction, request user confirmation at risk/commit boundaries. Peaks-Loop Solo must NOT silently install hooks / create agents / enable MCP / modify Claude settings / create GitHub repos / bypass role-skill artifacts. → `references/boundaries.md`.
 
 ## Peaks-Loop GStack integration
 
@@ -163,7 +152,7 @@ Map gstack stages to Peaks-Loop role artifacts; preserve confirmation gates. →
 
 ## Peaks-Loop Local intermediate artifact workspace (MANDATORY)
 
-Step 0 creates the workspace; all intermediate artifacts land under `.peaks/_runtime/<sessionId>/`. NEVER write Peaks-Loop intermediate artifacts to the project root directory.
+Step 0 creates the workspace; all intermediate artifacts land under `.peaks/_runtime/<sessionId>/`. NEVER write Peaks-Loop intermediate artifacts to the project root.
 
 ## Peaks-Loop Pre-RD project scan checklist (MANDATORY)
 
@@ -171,9 +160,7 @@ Before handing off to `peaks-rd`, scan the project and record findings to `.peak
 
 ## Peaks-Loop Frontend-only development mode
 
-When the project has no live backend (no swagger.json, no API server), Solo must activate frontend-only mode. The CLI is authoritative — read `frontendOnly` and `frontendOnlyReason` from `peaks scan archetype --json`.
-
-→ see `references/frontend-only-mode.md` for the mode contract, mock-data strategy, and the pre-flight keyword scan.
+When the project has no live backend (no swagger.json, no API server), Solo must activate frontend-only mode. The CLI is authoritative — read `frontendOnly` and `frontendOnlyReason` from `peaks scan archetype --json`. → `references/frontend-only-mode.md`.
 
 ## Peaks-Loop Request type classification + Workflow order + Transition verification gates
 
@@ -183,27 +170,23 @@ The contract for the 6-type classification table, the 11-step workflow order, an
 
 > **Slice 5:** when the slice DAG has ≥ 2 leaves at one topological level, dispatch via `peaks sub-agent dispatch --from-dag <dag-file>` (wall-time ≈ max, not sum).
 
-Write DAG → `.peaks/_runtime/<sessionId>/sc/slice-dag.json`, run `peaks sub-agent dispatch --from-dag <dag-file> --batch-id <id>` once; orchestrator emits N parallel `buildToolCall` (`dispatchCount === N`). No N serial `peaks sub-agent dispatch <role>` calls `--prompt`.
+Write DAG → `.peaks/_runtime/<sessionId>/sc/slice-dag.json`, run `peaks sub-agent dispatch --from-dag <dag-file> --batch-id <id>` once; orchestrator emits N parallel `buildToolCall` (`dispatchCount === N`).
 
-> **2026-06-28 校准:** 主路径 = 唯一蜂群;config/docs/chore 跳过不打断。assisted/strict 在 24h 场景下是反模式。详见 `.peaks/memory/peaks-loop-24h-ai-programmer-positioning.md`。
+> **2026-06-28 校准:** 主路径 = 唯一蜂群;config/docs/chore 跳过不打断。详见 `.peaks/memory/peaks-loop-24h-ai-programmer-positioning.md`。
 
 ### Hard constraint: fan-out is mandatory (slice 2026-06-24-audit-5th-p2)
 
-> **No serial opt-out.** `preferences.fanout.defaultMode = 'serial'`
-> was removed in 2.8.4; legacy values auto-migrate to `fan-out`. See
-> `references/fanout-mandatory.md` for the rationale + migration contract.
+> **No serial opt-out.** `preferences.fanout.defaultMode = 'serial'` was removed in 2.8.4; legacy values auto-migrate to `fan-out`.
 
-→ see `references/swarm-dispatch-contract.md` for the canonical gate logic + degradation tables, `references/sub-agent-dispatch.md` for the dispatch mechanism (NOT `Skill` tool), and `references/fanout-mandatory.md` for the hard-constraint rationale + migration contract.
+→ see `references/swarm-dispatch-contract.md`, `references/sub-agent-dispatch.md` (NOT `Skill` tool), `references/fanout-mandatory.md`.
 
 ## Slice 调度:分层并行 + 上游同步(2026-06-28 校准)
 
-> 分层并行(G12,基础先行/业务并行)+ 上游同步(G11,tag 断点/独立排期窗口)见 `.peaks/memory/peaks-loop-fork-sync-and-layered-parallel.md`。
+> 分层并行(G12)+ 上游同步(G11)见 `.peaks/memory/peaks-loop-fork-sync-and-layered-parallel.md`。
 
 ## Peaks-Loop Mandatory RD QA repair loop (AUTO-PROCEED)
 
-After `peaks-rd` finishes implementation, repair, or code-output, Solo MUST auto-route to `peaks-qa` without waiting for confirmation. Cap: 3 cycles; on 3rd failure emit blocked TXT handoff.
-
-→ see `references/micro-cycle.md` for the full 5-step procedure (transition, re-launch, fix, re-run, restore presence) + 3-cycle cap.
+After `peaks-rd` finishes, Solo MUST auto-route to `peaks-qa` without waiting for confirmation. Cap: 3 cycles; on 3rd failure emit blocked TXT handoff. Full 5-step procedure at `references/micro-cycle.md`.
 
 ## Default runbook
 
@@ -213,14 +196,11 @@ When adding new CLI commands, mirror into `references/runbook.md` and `tests/uni
 
 ## RD micro-cycle (TDD small-step rapid-test loop)
 
-> **Slice 内部**的修复 / refactor / lint 修复走 micro-cycle（5-10s/cycle）。
-> Slice 边界走 `peaks slice check`（一次性 4 项自检）。
-> 不要把 micro-cycle 跟边界 check 混用——前者 100ms 反馈循环，后者 30s+ 全套。
-> 完整手册：`references/micro-cycle.md`。
+> **Slice 内部**的修复 / refactor / lint 修复走 micro-cycle（5-10s/cycle）；Slice 边界走 `peaks slice check`。完整手册：`references/micro-cycle.md`。
 
 ## Peaks-Loop Project standards preflight
 
-Gather the project standards preflight status via `peaks standards init --project <path> --dry-run` and `peaks standards update --project <path> --dry-run`. Standards must reflect the project scan (component library, CSS, build tool, state, routing) — never emit a generic template.
+Gather via `peaks standards init/update --project <path> --dry-run`. Standards must reflect the project scan (component library, CSS, build tool, state, routing) — never emit a generic template.
 
 ## Peaks-Loop Refactor mode
 
@@ -232,7 +212,7 @@ Five CLI commands harden the workflow against silent skips: `peaks request lint`
 
 ## Peaks-Loop Completion handoff
 
-After final validation, refresh project-local standards via `peaks standards init/update` (never hand-write). Use Peaks-Loop TXT for the compact handoff capsule: mode, validated decisions, artifact paths, standards deltas, open questions, next action. **Presence management is delegated to the last downstream skill** — peaks-solo does not call `peaks skill presence:clear` itself.
+After final validation, refresh project-local standards via `peaks standards init/update` (never hand-write). Use Peaks-Loop TXT for the compact handoff capsule. **Presence management is delegated to the last downstream skill** — peaks-solo does not call `peaks skill presence:clear` itself.
 
 ## Peaks-Loop Step 11: Memory sediment (BLOCKING on workflow complete)
 
@@ -240,45 +220,27 @@ After final validation, refresh project-local standards via `peaks standards ini
 
 ### Substeps (BLOCKING)
 
-**11a — Gate A (txt/ inventory):**
-
-```bash
-find .peaks/_runtime/<sessionId>/txt/ -type f -name '*.md' | head
-```
-
-If **0 files** → STOP. Dispatch `peaks-txt` first to write `handoff.md`, then return to 11c.
-
-**11b — Gate B (memory block embed scan, skill-side only):**
-
-```bash
-grep -c 'peaks-memory:start' .peaks/_runtime/<sessionId>/txt/handoff.md || true
-```
-
-If **0 AND this session surfaced a stable project fact** (decision / convention / approved refactor / hard rule), STOP and tell peaks-txt to embed at least one `<!-- peaks-memory:start -->` block first.
-
-**11c — Canonical extract (the only CLI that writes `.peaks/memory/`):**
+**11a — Gate A (txt/ inventory):** `find .peaks/_runtime/<sessionId>/txt/ -type f -name '*.md' | head`. If **0 files** → STOP. Dispatch `peaks-txt` first to write `handoff.md`, then return to 11c.
 
-```bash
-peaks memory extract --project <repo> --artifact .peaks/_runtime/<sessionId>/txt/handoff.md --apply --json
-```
+**11b — Gate B (memory block embed scan):** `grep -c 'peaks-memory:start' .peaks/_runtime/<sessionId>/txt/handoff.md || true`. If **0 AND this session surfaced a stable project fact** (decision / convention / approved refactor / hard rule), STOP and tell peaks-txt to embed at least one `<!-- peaks-memory:start -->` block first.
 
-`--apply` is REQUIRED. Without it the command only previews — no files land in `.peaks/memory/`.
+**11c — Canonical extract** (the only CLI that writes `.peaks/memory/`): `peaks memory extract --project <repo> --artifact .peaks/_runtime/<sessionId>/txt/handoff.md --apply --json`. `--apply` is REQUIRED (without it the command only previews — no files land).
 
 **11d — Gate C (zero-write outcome):** If `extractedCount === 0` after 11c, fire AskUserQuestion:
 
 > "本次 solo 未沉淀任何 `.peaks/memory` 文件。可选: (a) 回去在 handoff.md 嵌入至少 1 个 `peaks-memory:start` block 后重试; (b) 显式接受 no-sediment 并记录为 lesson; (c) 取消完成。"
 
-Default option = (a). Solo MUST NOT silently accept (b) without user pick.
+Default option = (a). Solo MUST NOT silently accept (b) without user pick. Full bash + flow at `references/runbook.md` §Step 11.
 
-**Why this step exists:** audit 2026-07-03 confirmed 2 consecutive sessions produced zero `.peaks/memory/` files despite completing RD + QA + handoff artifacts. `assisted` mode silently skipped runbook Step 10 (no STOP condition). Step 11 makes the BLOCKING semantics explicit. **Why `peaks memory extract` (not `peaks project memories:extract`):** artifact-scoped extract is canonical; the batch-scoped sibling is for non-handoff flows. Always use `peaks memory extract --apply`.
+**Why this step exists:** audit 2026-07-03 confirmed 2 consecutive sessions produced zero `.peaks/memory/` files despite completing RD + QA + handoff artifacts; `assisted` mode silently skipped runbook Step 10 (no STOP condition). **Why `peaks memory extract` (not `peaks project memories:extract`):** the artifact-scoped extract is canonical; the batch-scoped sibling is for non-handoff flows. Always use `peaks memory extract --apply`.
 
 ## Peaks-Loop External references and lifecycle
 
-3rd-party integrations (codegraph, mattpocock/skills, shadcn/ui, MCPs, Context7) follow Discovery → Reference → Side effect through Peaks CLI only. Run `peaks capabilities` for capability discovery; treat external skills as reference material only. MCP servers (Playwright / Chrome DevTools / Figma) are user-installed — check the tool list for `mcp__<server>__*` entries. Do not execute upstream installer / run upstream commands / persist sensitive examples / install upstream resources directly — funnel side effects through the Peaks CLI surface. Peaks-Loop Solo gates and artifacts remain authoritative. → `references/external-references.md` + `references/external-skill-invocation.md`.
+3rd-party integrations (codegraph, mattpocock/skills, shadcn/ui, MCPs, Context7) follow Discovery → Reference → Side effect through Peaks CLI only. Run `peaks capabilities` for capability discovery; treat external skills as reference material only. MCP servers (Playwright / Chrome DevTools / Figma) are user-installed — check the tool list for `mcp__<server>__*` entries. Do not execute upstream installer / run upstream commands / persist sensitive examples / install upstream resources directly — funnel side effects through the Peaks CLI surface. Peaks-Loop Solo gates remain authoritative. → `references/external-references.md` + `references/external-skill-invocation.md`.
 
 ## Codegraph orchestration context
 
-`peaks codegraph affected` is an optional project-analysis enhancement (untrusted supporting evidence) used during role handoff. Solo must not treat codegraph output as approval for scope, design, or QA verdict. Never mutate agent settings / hooks from codegraph; do not commit `.codegraph/` artifacts. RD writes `.peaks/_runtime/<sessionId>/rd/codegraph-context.md`; QA / TXT consume the same envelope. → `references/codegraph-orchestration.md`.
+`peaks codegraph affected` is an optional project-analysis enhancement (untrusted supporting evidence) for role handoff. Solo must not treat codegraph output as approval for scope, design, or QA verdict. Never mutate agent settings / hooks from codegraph; do not commit `.codegraph/` artifacts. RD writes `.peaks/_runtime/<sessionId>/rd/codegraph-context.md`; QA / TXT consume the same envelope. → `references/codegraph-orchestration.md`.
 
 ## Sub-agent context governance (G7 + G7.7 + G8 + G9 — slice #010)
 
@@ -286,7 +248,7 @@ Main LLM reducer sees metadata-only view (~200 chars/sub-agent); on-demand `Read
 
 ## Sub-agent cross-batch signal — G8.4 share / shared-read / await (slice 2026-06-23-audit-3rd)
 
-Three CLI primitives let sibling sub-agents coordinate within a batch without peer-to-peer messaging: `peaks sub-agent share / shared-read / await` (last-write-wins channel ≤ 1KB warn / ≥ 64KB reject). Channel file gitignored under `.peaks/_sub_agents/<sessionId>/shared/`.
+Three CLI primitives let sibling sub-agents coordinate: `peaks sub-agent share / shared-read / await` (last-write-wins, ≤ 1KB warn / ≥ 64KB reject). Channel file gitignored under `.peaks/_sub_agents/<sessionId>/shared/`.
 
 ## References
 

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

@@ -192,8 +192,36 @@ 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)
+# v3.1.2: `peaks job checkpoint --state done` ALSO writes
+# .peaks/_runtime/<sid>/job/<jid>/progress.json. Read it on resume:
+peaks job progress --job-id <jid> --json
 peaks job status --job-id <jid> --json
 peaks job subagent-cleanup --job-id <jid> --batch-id <bid> --force   # Step 0.87 gate
 # Loop control:
@@ -201,4 +229,21 @@ peaks job subagent-cleanup --job-id <jid> --batch-id <bid> --force   # Step 0.87
 #   remaining == 0 → Step 8/9/10/11 (original tail)
 #   blocked (strict) → peaks job block + STOP
 # Rotating-mode: every rotateEvery slices → Step 0.86 (peaks session rotate + resume)
+
+# v3.1.2 size-fear ban: refuse to emit a final handoff while remaining > 0.
+# The LLM cannot bypass this; --force-under-job requires explicit user approval.
+peaks solo emit-handoff --project <repo> --job-id <jid> --json
+
+# v3.1.2 forced auto-compact: when --enforce-job-mode is set OR
+# job-shape.json says isJob=true, ≥0.85 is MANDATORY auto-compact.
+# Solo MUST call this without confirmation under Job mode.
+peaks solo context-now --project <repo> --enforce-job-mode --json
+peaks session auto-compact --execute --project <repo> --json
+
+# v3.1.2 PreToolUse gate (installed by `peaks workspace init`):
+# every Bash tool call runs `peaks solo gate-step-08` automatically.
+# Exit 0 = allow (with optional Next: slice #N+1 of M line when
+# progress.json exists). Exit 2 = BLOCKED; LLM must call
+# `peaks solo detect-job` first.
+peaks solo gate-step-08 --project <repo> --json
 ```