peaks-loop 3.0.3 → 3.1.1

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.0.3";
+export declare const CLI_VERSION = "3.1.1";

package/dist/src/shared/version.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "peaks-loop",
-  "version": "3.0.3",
+  "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

@@ -11,7 +11,7 @@ The `.peaks/` workspace has a **single scope axis** (session-id) plus a nested *
 
 ## 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; never silently drop it. Canonical skill id: `andrej-karpathy-skills:karpathy-guidelines`. Summary: **#1 Think Before Coding** (surface assumptions, name tradeoffs), **#2 Simplicity First** (min code, no speculative features, 800-line file cap), **#3 Surgical Changes** (touch only what the request requires), **#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** (min code, no speculative features, 800-line cap), **#3 Surgical Changes**, **#4 Goal-Driven Execution** (verifiable ACs, plan + verify checkpoints).
 
 ## Hard ban (effective 2.8.3 — read every session, no exceptions)
 
@@ -31,7 +31,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. Both follow `peaks-rd` + `peaks-qa` contracts. **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`. `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 Startup sequence (MANDATORY — execute in order)
 
@@ -41,11 +41,11 @@ This skill is the **primary surface**. The `peaks <cmd>` CLI is **auxiliary**
 
 ### Peaks-Loop Step 0.75: Resume from checkpoint (BLOCKING on same-day re-invocation)
 
-When a NEW conversation opens on a session whose `lastActivity` is from today AND `.peaks/_runtime/<sessionId>/checkpoints/` contains a `*.json`, surface via `peaks session info --active --json` + `peaks session resume --from <path> --project <repo>`. Prompt via `AskUserQuestion` (resume / fresh); if "resume", prepend the block. Honors "fresh" — on-disk checkpoint stays untouched. Step 0.75 is no-op on precondition fail. See `references/checkpoint-resume.md`.
+When a NEW conversation opens on a session whose `lastActivity` is from today AND `.peaks/_runtime/<sessionId>/checkpoints/` has `*.json`, surface via `peaks session info --active --json` + `peaks session resume --from <path> --project <repo>`. Prompt via `AskUserQuestion` (resume / fresh); if "resume", prepend the block. Step 0.75 is no-op on precondition fail. See `references/checkpoint-resume.md`.
 
 ### 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. 20-call cadence locked; 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, `--reason context-fill` / `user-pause` / `user-close` as appropriate. 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)
 
@@ -67,7 +67,7 @@ After autonomous work (RD, QA, security, perf), invoke peaks-final-review for 4-
 
 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 (zero-human-intervention). **≥ 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.
+**≥ 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).
 
@@ -87,19 +87,56 @@ 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 the AskUserQuestion (D7.b — pre-compact approval carries forward). Log to `.peaks/_runtime/<sessionId>/txt/auto-decisions.md`. Applies to all 4 modes; cross-day / cross-machine resume NOT in scope (D7.g).
+**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).
 
 → see `references/resume-detection.md` for the full detection algorithm + classification table.
 
 ### 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` (`autoUpgradePrompt`: opt-in / skip-this-session / skip-forever).
+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`.
 
 → see `references/step-0-55-1x-detection.md` for the detection algorithm + AskUserQuestion options + persistence contract.
 
+### Peaks-Loop Step 0.8 — Job 启动 (BLOCKING on LLM judgement — v3.1.1 patch)
+
+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.
+
+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 收尾
+
+After commit: `peaks job checkpoint --slice-id <rid> --state done --commit-sha $(git rev-parse HEAD)` → `peaks job status` → loop (remaining>0 → Step 1; ==0 → Step 8/9/10/11; blocked → Step 0.85).
+
+### Peaks-Loop Step 0.85 — slice 阻塞处理
+
+Trigger: `repair-status` atCap=true, context-now red-line ≥5min, or `subagent-cleanup` fails twice. Action: `peaks job block --slice-id <rid> --reason "<reason>"` then STOP with TXT handoff.
+
+### 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>`.
+
+### 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.
+
 ### Peaks-Loop Step 1: Mode selection
 
-Use `AskUserQuestion` with `Full auto (Recommended)` as the first option when EITHER the user did not name a profile OR the recorded skill presence is stale (v2.15.0 slice 002 AC-2: run `peaks skill presence:check-stale --project <path> --json` first; `stale: true` ⇒ re-ask. `peaks solo should-pause --step step-1-mode-select` returns `reason: 'stale-presence'` in this case).
+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`.
 
@@ -153,7 +190,7 @@ When the project has no live backend (no swagger.json, no API server), Solo must
 
 ## Peaks-Loop Request type classification + Workflow order + Transition verification gates
 
-The contract for the 6-type classification table, the 11-step workflow order, and the 7 transition verification gates (A through G with their `ls` / `grep` shell snippets) lives in `references/workflow-gates-and-types.md`. The peaks-solo narrative in this SKILL.md references those gate numbers (Gate A through Gate G) — keep both files in lockstep when adding or renaming a gate. The reference file is the canonical contract; SKILL.md keeps the prose.
+The contract for the 6-type classification table, the 11-step workflow order, and the 7 transition verification gates (A through G with their `ls` / `grep` shell snippets) lives in `references/workflow-gates-and-types.md`. The peaks-solo narrative references those gate numbers (Gate A through Gate G) — keep both files in lockstep when adding or renaming a gate.
 
 ## Peaks-Loop Default sub-agent fan-out (≥ 2 leaves/topological level → `--from-dag`)
 
@@ -212,7 +249,7 @@ After final validation, refresh project-local standards via `peaks standards ini
 
 ## Peaks-Loop Step 11: Memory sediment (BLOCKING on workflow complete)
 
-> **Hard rule.** Solo MUST NOT declare a workflow complete until Step 11 has produced ≥ 1 file in `.peaks/memory/` (the durable, LLM-authored memory store) OR the user has explicitly approved a no-sediment outcome via AskUserQuestion. This applies to **all modes** including `assisted` and `strict` — `assisted` previously skipped Step 10 because there was no `[CONFIRM]` gate; Step 11 fixes that.
+> **Hard rule.** Solo MUST NOT declare a workflow complete until Step 11 has produced ≥ 1 file in `.peaks/memory/` (the durable, LLM-authored memory store) OR the user has explicitly approved a no-sediment outcome via AskUserQuestion. Applies to **all modes** including `assisted` and `strict` — `assisted` previously skipped Step 10 because there was no `[CONFIRM]` gate; Step 11 fixes that.
 
 ### Substeps (BLOCKING)
 
@@ -246,15 +283,15 @@ peaks memory extract --project <repo> --artifact .peaks/_runtime/<sessionId>/txt
 
 Default option = (a). Solo MUST NOT silently accept (b) without user pick.
 
-**Why this step exists:** audit 2026-07-03 confirmed 2 consecutive sessions produced zero `.peaks/memory/` files despite completing RD + QA + handoff artifacts. Root cause: `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`):** the artifact-scoped extract is the canonical command next to its capsule; the batch-scoped sibling is for non-handoff flows (out of scope). For Step 11, **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). 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`.
 
 ## 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. → `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 and artifacts 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 / Claude 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) 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`.
 
 ## Sub-agent context governance (G7 + G7.7 + G8 + G9 — slice #010)
 
@@ -297,6 +334,7 @@ Index of every `references/` file. Read on demand.
 | `references/refactor-mode.md` | Refactor mode + red lines. |
 | `references/resume-detection.md` | Step 0.7 unfinished-work. |
 | `references/runbook.md` | End-to-end CLI sequence. |
+| `references/job-loop.md` | Step 0.8 / 0.81 / 0.85 / 0.86 / 0.87 deep-dive. |
 | `references/skill-presence-and-title.md` | Step 2 + Step 2.5. |
 | `references/standards-preflight.md` | Standards preflight. |
 | `references/sub-agent-dispatch.md` | IDE-agnostic dispatch. |

package/skills/peaks-solo/references/job-loop.md

@@ -0,0 +1,68 @@
+# Peaks-Loop Solo — Job Loop Deep-Dive
+
+> Read alongside `SKILL.md` Steps 0.8 / 0.81 / 0.85 / 0.86 / 0.87.
+
+## State machine
+
+```
+       init ─────────► pending ─► in-progress ─┐
+                          │                     │
+                          ▼                     ▼
+                       blocked (one slice)    done ──► (next slice)
+                          │                     ▲
+                          ▼                     │
+                       (strict: STOP,           │
+                        best-effort: skipped)   │
+```
+
+## Visibility
+
+| Layer | Tool | Cost | User reads |
+|---|---|---|---|
+| LLM-runner transcript | (the chat) | free | always |
+| `--watch` poll | peaks job status --watch | 1% CPU | when in a 2nd terminal pane |
+| Statusline | peaks statusline install | ambient | in IDE bottom bar |
+
+## Rotation cadence
+
+- `len(slices) ≤ 2` → single-mode (auto-compact passively).
+- `len(slices) ≥ 3` → rotating-mode, K=3 default.
+- LLM-initiated override (rotating→single) is **strongly discouraged**; if used, must record `mainLoopOverride` in state.json with `reason ≥ 10 chars` and predicted wall-time ≤ 30 min.
+
+## Cleanup gate
+
+Every `peaks sub-agent dispatch` inside a Job scope MUST be matched by a `peaks job subagent-cleanup --force` BEFORE the next slice checkpoint. The wrapper (M5) refuses dispatch return-success without matching cleanup.
+
+## Cross-day recovery
+
+`peaks session resume --job-id <jid>` reads:
+1. `job/<jid>/state.json` — current job state
+2. `session/cycle-<n>.md` — main-session cycle summary (rotating mode)
+3. `session/auto-decisions.md` — auto-compact history
+4. `session/checkpoints/*.json` — generic session checkpoints
+
+The resume endpoint cross-checks all four before offering continuation; if any layer is stale, the user gets an AskUserQuestion (resume / restart / skip).
+
+## Visibility prose
+
+The Job loop is foreground. Three visibility layers, all on by default:
+1. **LLM-runner transcript** — primary surface; user reads the chat to see active step.
+2. **`peaks job status --watch`** — terminal poll, ANSI bar, refresh every 3 s.
+3. **Statusline** — ambient `job: <jid> [done/total] currentSlice ETA m:s context main%. cycle`.
+
+No detached workers, no `nohup`, no `disown`. Any attempt to spawn a background job → red line violation → block.
+
+## Red lines (9 hard rules)
+
+The LLM-runner MUST NOT:
+1. Enter Step 11 / write final handoff while job has remaining slices.
+2. Re-ask the user about cost / length / context.
+3. Coalesce multiple slices into one rid.
+4. Modify a committed slice (`git commit --amend` on `done`).
+5. Fake completion (CLI verifies commit-sha exists in git log).
+6. Use detached / background / daemon-mode sub-agents inside a Job.
+7. Skip `peaks job subagent-cleanup` between dispatch and slice checkpoint.
+8. Skip or postpone a scheduled `peaks session rotate`.
+9. Suppress visibility — no silencing statusline / `--watch`.
+
+Violations trigger a `peaks job block` event with the specific red-line number.

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

@@ -187,3 +187,43 @@ peaks skill doctor --json
 ```
 
 Repair loop details: see `## Mandatory RD QA repair loop` in SKILL.md for the full 5-step procedure and the 3-cycle cap. Append transition notes via `--reason` rather than rewriting artifacts during repair cycles.
+
+```bash
+
+# Peaks-Loop Default runbook — Job path (excerpt; full flow in references/job-loop.md)
+
+# 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
+# Loop control:
+#   remaining > 0  → return to Step 1 (next slice)
+#   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)
+```