peaks-loop 4.0.0-beta → 4.0.0-beta.10

package/dist/services/code/dag-orchestrator.js

@@ -0,0 +1,304 @@
+/**
+ * DAG orchestrator — 2.7.0 slice-dag-dispatcher MVP (slice 1.2.a).
+ *
+ * The pure planner. Given a `SliceDag`, the orchestrator decides which
+ * slices to dispatch next (in topological order), drives the join barrier,
+ * and rolls back on any leaf failure.
+ *
+ * Design:
+ *  - **Pure dispatcher contract**: the orchestrator never calls an LLM
+ *    directly; it returns `DispatchSpec[]` per topological level and lets
+ *    the caller (the CLI / peaks-code LLM) execute the per-IDE tool calls.
+ *    This keeps the orchestrator testable end-to-end with mock sub-agents.
+ *  - **Join barrier**: between levels, the orchestrator awaits the
+ *    results of all dispatched leaves and refuses to advance if any
+ *    leaf failed.
+ *  - **Failure rollback**: a leaf failure cancels all other in-flight
+ *    slices in the same level. The orchestrator surfaces a `DagRollback`
+ *    event so the caller can re-plan.
+ *  - **Contract broadcast**: when a slice finishes successfully, the
+ *    orchestrator writes its public contract to disk via `writeContract`,
+ *    and the next dispatch's prompt is built with `formatContractInjection`.
+ *
+ * Why this lives in `services/code/`:
+ *  `peaks-code` is the natural caller. The CLI surface (`peaks sub-agent
+ *  dispatch --from-dag`) consumes the planner's output but the planner
+ *  itself is a library.
+ */
+import { hashDag, InvalidSliceDagError, topologicalLevels, validateDag } from '../dispatch/slice-dag.js';
+import { formatContractInjection, writeContract } from '../dispatch/contract-store.js';
+import { formatTestToolDetection } from '../dispatch/test-tool-detection.js';
+/** Thrown when the DAG has no feasible plan (validation error). */
+export class DagPlanError extends Error {
+    code = 'DAG_PLAN_ERROR';
+    constructor(message) {
+        super(message);
+        this.name = 'DagPlanError';
+    }
+}
+/** Default runner for tests / mocks. Returns `done` with an empty surface. */
+const defaultRunner = async (_spec) => ({
+    status: 'done',
+    publicSurface: { exports: [], types: [], publicSignatures: [] }
+});
+const defaultWriter = (projectRoot, sessionId) => (sliceId, publicSurface) => {
+    const r = writeContract(projectRoot, sessionId, {
+        sliceId,
+        sessionId,
+        exports: publicSurface.exports,
+        types: publicSurface.types,
+        publicSignatures: publicSurface.publicSignatures,
+        ...(publicSurface.broadcastTo !== undefined ? { broadcastTo: publicSurface.broadcastTo } : {})
+    });
+    return r.contract;
+};
+/**
+ * Build a single dispatch spec for `sliceId` given the current contract set.
+ *
+ * When `node.prompt` is set on the DAG node, that wins verbatim (the
+ * caller controls per-slice prompt content). Otherwise we fall back to
+ * `defaultPrompt`, then to a structured MVP prompt covering: the slice's
+ * role + id + label, the injected ancestor-contract block (if any), the
+ * MVP scope statement, and the explicit handoff protocol the LLM-side
+ * runner must follow (write contract, then re-invoke for the next
+ * topological level).
+ */
+export function buildDispatchSpec(dag, sliceId, contracts, defaultPrompt) {
+    const node = dag.nodes.find((n) => n.id === sliceId);
+    if (!node) {
+        throw new DagPlanError(`unknown slice id: ${sliceId}`);
+    }
+    const ancestors = contracts.filter((c) => c.broadcastTo?.includes(sliceId) ?? false);
+    const contractBlock = formatContractInjection(ancestors);
+    if (node.prompt !== undefined) {
+        return {
+            sliceId,
+            role: node.role,
+            label: node.label ?? null,
+            prompt: `${formatTestToolDetection()}\n\n${node.prompt}`,
+            contractBlock
+        };
+    }
+    if (defaultPrompt !== undefined) {
+        return {
+            sliceId,
+            role: node.role,
+            label: node.label ?? null,
+            prompt: defaultPrompt,
+            contractBlock
+        };
+    }
+    // MVP (1.2) structured fallback prompt. Slice 1.4 will land per-domain
+    // prompt templates (one per role), but for the MVP dogfood we ship a
+    // single structured prompt that:
+    //   1. names the slice id + role + label (so the LLM knows what to do)
+    //   2. states the MVP scope explicitly (avoid confusion with full prod)
+    //   3. includes the ancestor contract injection (so downstream slices
+    //      see their inputs)
+    //   4. states the handoff protocol (write contract, re-invoke for next level)
+    const labelFragment = node.label ? ` — ${node.label}` : '';
+    const ancestorFragment = contractBlock
+        ? `\n\n${contractBlock}`
+        : '';
+    const prompt = [
+        formatTestToolDetection(),
+        '',
+        `[slice-dag-dispatcher MVP 1.2] execute slice "${sliceId}" (role=${node.role})${labelFragment}.`,
+        '',
+        'Scope: this is the 2.7.0 MVP dogfood of peaks-loop DAG-aware dispatch. You are one leaf in a multi-slice plan; the orchestrator has already validated the DAG, built a topological order, and injected your upstream contracts above.',
+        '',
+        'Handoff protocol (REQUIRED — orchestrator depends on this):',
+        '  1. Execute the slice to completion.',
+        `  2. Write your public contract via \`peaks contract write --project <root> --session-id <sid> --slice-id ${sliceId} --exports <...> --types <...> --signatures <...>\`. The orchestrator will pick it up on the next dispatch run.`,
+        '  3. Do NOT re-invoke `peaks sub-agent dispatch --from-dag` yourself — the parent orchestrator (peaks-code) drives level advancement.',
+        '',
+        `After your contract is on disk, the orchestrator will auto-advance to the next topological level (if any) by re-invoking \`peaks sub-agent dispatch --from-dag\` with the same batch-id. Your slice will appear in its ancestors via \`formatContractInjection\`.${ancestorFragment}`
+    ].join('\n');
+    return {
+        sliceId,
+        role: node.role,
+        label: node.label ?? null,
+        prompt,
+        contractBlock
+    };
+}
+/**
+ * Run a slice DAG end-to-end. Returns a summary; throws `DagPlanError`
+ * on validation failure; any leaf failure causes an in-flight cancel
+ * signal but the function still resolves with the partial result so the
+ * caller can re-plan.
+ */
+export async function runDag(dag, opts) {
+    try {
+        validateDag(dag);
+    }
+    catch (err) {
+        if (err instanceof InvalidSliceDagError) {
+            throw new DagPlanError(err.message);
+        }
+        throw err;
+    }
+    const levels = topologicalLevels(dag);
+    const dagHash = hashDag(dag);
+    const runner = opts.runSlice ?? defaultRunner;
+    const writer = opts.writeContractFn ?? defaultWriter(opts.projectRoot, opts.sessionId);
+    const completed = new Set();
+    const contracts = [...(opts.existingContracts ?? [])];
+    const failed = [];
+    const cancelled = [];
+    const inflight = new Set();
+    for (const level of levels) {
+        const ready = level.filter((id) => !completed.has(id) && !failed.some((f) => f.sliceId === id));
+        if (ready.length === 0)
+            continue;
+        for (const id of ready)
+            inflight.add(id);
+        const settled = await Promise.all(ready.map(async (sliceId) => {
+            const spec = buildDispatchSpec(dag, sliceId, contracts);
+            try {
+                const outcome = await runner(spec);
+                return { sliceId, outcome };
+            }
+            catch (err) {
+                return {
+                    sliceId,
+                    outcome: { status: 'failed', reason: err.message }
+                };
+            }
+        }));
+        let levelHasFailure = false;
+        for (const { sliceId, outcome } of settled) {
+            inflight.delete(sliceId);
+            if (outcome.status === 'done') {
+                completed.add(sliceId);
+                const contract = writer(sliceId, outcome.publicSurface);
+                contracts.push(contract);
+            }
+            else if (outcome.status === 'failed') {
+                failed.push({ sliceId, reason: outcome.reason });
+                levelHasFailure = true;
+            }
+            else {
+                cancelled.push(sliceId);
+                levelHasFailure = true;
+            }
+        }
+        if (levelHasFailure) {
+            for (const id of inflight) {
+                cancelled.push(id);
+                inflight.delete(id);
+            }
+            break;
+        }
+    }
+    return {
+        dagHash,
+        completed: Array.from(completed).sort(),
+        failed,
+        cancelled: cancelled.sort(),
+        contracts
+    };
+}
+/**
+ * v2.15.0 follow-up — G12: layered DAG runner (foundation-first,
+ * business-parallel, upstreamSync-priority). Behavior:
+ *
+ *   1. Foundation slices run first (topological order).
+ *   2. As foundation slices complete, business slices that depend ONLY
+ *      on the completed foundation subset can start — they do NOT wait
+ *      for ALL foundation slices to complete. This is the layered-
+ *      parallelism speedup (saves 2-3 days on a 1-week+ requirement).
+ *   3. upstreamSync slices take priority within their topological
+ *      level (handled by `topologicalLevels` priority sort).
+ *   4. Cancel-on-fail semantics are preserved: any leaf failure
+ *      cancels in-flight siblings and breaks the loop.
+ *
+ * Pure planner; same I/O contract as `runDag`. The caller (CLI /
+ * peaks-code LLM) executes the per-IDE tool calls.
+ */
+export async function runLayeredDag(dag, opts) {
+    try {
+        validateDag(dag);
+    }
+    catch (err) {
+        if (err instanceof InvalidSliceDagError) {
+            throw new DagPlanError(err.message);
+        }
+        throw err;
+    }
+    const levels = topologicalLevels(dag);
+    const dagHash = hashDag(dag);
+    const runner = opts.runSlice ?? defaultRunner;
+    const writer = opts.writeContractFn ?? defaultWriter(opts.projectRoot, opts.sessionId);
+    const completed = new Set();
+    const contracts = [...(opts.existingContracts ?? [])];
+    const failed = [];
+    const cancelled = [];
+    const inflight = new Set();
+    for (const level of levels) {
+        // G12 layered parallelism: a business slice only blocks until its
+        // OWN `dependsOn` subset is complete, not all foundation slices.
+        const ready = level.filter((id) => {
+            if (completed.has(id))
+                return false;
+            if (failed.some((f) => f.sliceId === id))
+                return false;
+            // Check if all ancestors of this slice are in `completed` OR
+            // (already in `failed` — then it would never run, but we filter
+            // by `failed` above).
+            const node = dag.nodes.find((n) => n.id === id);
+            if (!node)
+                return false;
+            const ancestors = dag.edges.filter((e) => e.to === id).map((e) => e.from);
+            return ancestors.every((a) => completed.has(a));
+        });
+        if (ready.length === 0)
+            continue;
+        for (const id of ready)
+            inflight.add(id);
+        const settled = await Promise.all(ready.map(async (sliceId) => {
+            const spec = buildDispatchSpec(dag, sliceId, contracts);
+            try {
+                const outcome = await runner(spec);
+                return { sliceId, outcome };
+            }
+            catch (err) {
+                return {
+                    sliceId,
+                    outcome: { status: 'failed', reason: err.message }
+                };
+            }
+        }));
+        let levelHasFailure = false;
+        for (const { sliceId, outcome } of settled) {
+            inflight.delete(sliceId);
+            if (outcome.status === 'done') {
+                completed.add(sliceId);
+                const contract = writer(sliceId, outcome.publicSurface);
+                contracts.push(contract);
+            }
+            else if (outcome.status === 'failed') {
+                failed.push({ sliceId, reason: outcome.reason });
+                levelHasFailure = true;
+            }
+            else {
+                cancelled.push(sliceId);
+                levelHasFailure = true;
+            }
+        }
+        if (levelHasFailure) {
+            for (const id of inflight) {
+                cancelled.push(id);
+                inflight.delete(id);
+            }
+            break;
+        }
+    }
+    return {
+        dagHash,
+        completed: Array.from(completed).sort(),
+        failed,
+        cancelled: cancelled.sort(),
+        contracts
+    };
+}

package/dist/services/code/emit-handoff.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 code-commands.ts
+ * translates the verdict into exit code + JSON envelope.
+ */
+export declare const JOB_NOT_INITIALIZED: "JOB_NOT_INITIALIZED";
+export declare const JOB_REMAINING_BLOCKED: "JOB_REMAINING_BLOCKED";
+export type EmitHandoffVerdict = {
+    readonly kind: 'allow-not-job';
+} | {
+    readonly kind: 'allow-done';
+    readonly remaining: number;
+} | {
+    readonly kind: 'allow-force-override';
+    readonly remaining: number;
+} | {
+    readonly kind: 'block-not-initialized';
+    readonly code: typeof JOB_NOT_INITIALIZED;
+    readonly jobId: string;
+} | {
+    readonly kind: 'block-remaining';
+    readonly code: typeof JOB_REMAINING_BLOCKED;
+    readonly jobId: string;
+    readonly remaining: number;
+};
+export interface EvaluateEmitHandoffInput {
+    readonly projectRoot: string;
+    readonly sessionId: string;
+    /** Suggested job id — read from job-shape.json when omitted. */
+    readonly jobId?: string;
+    readonly forceUnderJob?: boolean;
+}
+export declare function evaluateEmitHandoff(input: EvaluateEmitHandoffInput): EmitHandoffVerdict;

package/dist/services/code/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 code-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/services/code/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 code 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/services/code/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 code 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 code 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 code 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 code 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 code 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;
+}