peaks-loop 3.1.1 → 3.1.2

package/dist/src/services/solo/emit-handoff.js

@@ -0,0 +1,79 @@
+/**
+ * v3.1.2 Step 11 / final handoff — Size-fear ban.
+ *
+ * Refuses to emit a final handoff while a Job has remaining slices.
+ * Closes the v3.1.0 incident pattern: LLM writes a fake-completion
+ * message at high context-fill before Job mode kicks in.
+ *
+ * Decision tree:
+ *   - job-shape.json missing OR isJob === false  → ALLOW (normal handoff)
+ *   - isJob === true, no state.json              → JOB_NOT_INITIALIZED (LLM
+ *     skipped `peaks job init`)
+ *   - isJob === true, state.json, remaining > 0,
+ *     no --force-under-job                        → JOB_REMAINING_BLOCKED
+ *   - isJob === true, state.json, remaining === 0 → ALLOW (Job done)
+ *   - isJob === true, state.json, remaining > 0,
+ *     --force-under-job                            → ALLOW (override path)
+ *
+ * Karpathy §2 (Simplicity First): ~70 lines, no LLM call, no regex.
+ * Pure read + arithmetic. The CLI wrapper in solo-commands.ts
+ * translates the verdict into exit code + JSON envelope.
+ */
+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 JOB_NOT_INITIALIZED = 'JOB_NOT_INITIALIZED';
+export const JOB_REMAINING_BLOCKED = 'JOB_REMAINING_BLOCKED';
+function countRemaining(statePath) {
+    let raw;
+    try {
+        raw = readFileSync(statePath, 'utf8');
+    }
+    catch {
+        return Number.NaN;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return Number.NaN;
+    }
+    if (!Array.isArray(parsed.slices))
+        return Number.NaN;
+    return parsed.slices.filter((sl) => sl.status !== 'done' && sl.status !== 'skipped').length;
+}
+function statePath(projectRoot, sessionId, jobId) {
+    return join(projectRoot, '.peaks', '_runtime', sessionId, 'job', jobId, 'state.json');
+}
+export function evaluateEmitHandoff(input) {
+    let decision = null;
+    try {
+        const record = readJobShapeDecision(input.projectRoot, input.sessionId);
+        decision = record.decision;
+    }
+    catch (err) {
+        if (err instanceof JobShapeDecisionError && err.code === JOB_SHAPE_NOT_DECIDED) {
+            return { kind: 'allow-not-job' };
+        }
+        throw err;
+    }
+    if (!decision.isJob)
+        return { kind: 'allow-not-job' };
+    const jobId = input.jobId ?? decision.suggestedJobId;
+    const path = statePath(input.projectRoot, input.sessionId, jobId);
+    if (!existsSync(path)) {
+        return { kind: 'block-not-initialized', code: JOB_NOT_INITIALIZED, jobId };
+    }
+    const remaining = countRemaining(path);
+    if (!Number.isFinite(remaining)) {
+        return { kind: 'block-not-initialized', code: JOB_NOT_INITIALIZED, jobId };
+    }
+    if (remaining === 0) {
+        return { kind: 'allow-done', remaining };
+    }
+    if (input.forceUnderJob === true) {
+        return { kind: 'allow-force-override', remaining };
+    }
+    return { kind: 'block-remaining', code: JOB_REMAINING_BLOCKED, jobId, remaining };
+}

package/dist/src/services/solo/step-08-gate.d.ts

@@ -0,0 +1,90 @@
+/**
+ * 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).
+ */
+export declare const STEP_08_GATE_FILE_NAME: "job-shape.json";
+export declare 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 declare const STEP_08_BACKUP_REGEX: RegExp;
+export interface Step08Progress {
+    readonly jobId: string;
+    readonly done: number;
+    readonly total: number;
+    readonly currentSlice: string;
+    readonly lastCommitSha: string | null;
+    readonly updatedAt: string;
+}
+export type Step08Verdict = {
+    readonly kind: 'allow-job';
+    readonly decision: import('./job-shape-decision.js').JobShapeDecision;
+    readonly progress: Step08Progress | null;
+} | {
+    readonly kind: 'allow-single';
+} | {
+    readonly kind: 'block-missing-decision';
+    readonly promptHit: boolean;
+    readonly promptSource: 'flag' | 'last-prompt-file' | 'stdin-empty';
+};
+export declare function runtimeSessionDir(projectRoot: string, sessionId: string): string;
+export interface EvaluateStep08Input {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    /**
+     * Explicit prompt text. When omitted, falls back to
+     * `.peaks/_runtime/<sid>/txt/last-prompt.txt`, then to stdin (the
+     * caller passes stdin verbatim — usually empty in tests).
+     */
+    readonly prompt?: string;
+}
+export interface EvaluateStep08Result {
+    readonly allow: boolean;
+    readonly verdict: Step08Verdict;
+    readonly nextSliceLine: string | null;
+}
+/**
+ * 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 declare function evaluateStep08(input: EvaluateStep08Input): EvaluateStep08Result;

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

package/dist/src/shared/version.js

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

package/package.json

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