@cleocode/core 2026.6.13 → 2026.6.15

package/dist/selfimprove/fix-gen.d.ts

@@ -0,0 +1,229 @@
+/**
+ * Fix-generation stage for the self-improvement loop (T11889 · T11975).
+ *
+ * This is the missing autonomous link the v1 loop explicitly stubbed out
+ * ("NO autonomous fix-gen in v1", see {@link "./run-loop.js"}): given a detected
+ * regression (an open `selfimprove_dhq` + its envelope-diff) plus minimal repo
+ * context, it asks the LLM to PROPOSE a unified-diff patch and writes that patch
+ * to the path the draft-PR egress ({@link "./draft-pr.js".openDraftPr}) already
+ * `existsSync`-checks: `<cwd>/selfimprove-<scenario>.patch`. Once the patch is on
+ * disk the existing egress guard opens ONE DRAFT PR — closing the
+ * DHQ → fix → draft-PR pipeline end-to-end.
+ *
+ * ## Hard safety posture (unchanged from v1 — P5 spec §B.7)
+ *
+ *   - **LLM ONLY via the E9 chokepoint.** The real generator
+ *     ({@link createLlmFixGenerator}) resolves its model strictly through
+ *     {@link "../llm/system-resolver.js".resolveLLMForSystem} → {@link ModelRunner}
+ *     (Gate-13). It constructs NO raw provider client, reads NO `*_API_KEY` env,
+ *     and hardcodes no model id — the resolver/registry is the SSoT. The
+ *     plaintext token is materialized only at the wire boundary (E10).
+ *   - **Draft-PR-ONLY, never auto-merge.** This module produces a PATCH FILE only;
+ *     the egress that consumes it always opens a `--draft` PR against a feature
+ *     branch (never `main`). This module performs NO git/gh action.
+ *   - **Graceful degrade, never a rogue mutation.** Every failure (no credential,
+ *     LLM error, empty / non-unified-diff output) returns a typed
+ *     {@link FixGenResult} of kind `'skipped'` and writes NO patch file — so the
+ *     existing egress guard (`existsSync` on the patch path) simply skips the PR.
+ *     This function NEVER throws.
+ *   - **Injectable seam.** The LLM dependency is the {@link FixGenerator} port;
+ *     unit tests inject a deterministic fake that returns a canned patch, so NO
+ *     real LLM is reached in tests.
+ *
+ * CORE-first: this engine lives in `core` and owns the `FixGenerator` port TYPE.
+ * Import-time side-effect-free.
+ *
+ * @module @cleocode/core/selfimprove/fix-gen
+ * @epic T11889
+ * @task T11975
+ */
+import type { Logger } from 'pino';
+import type { DiffEntry } from './envelope-diff.js';
+/**
+ * The structured request handed to a {@link FixGenerator}. Carries only what the
+ * generator needs to draft a patch: the DHQ identity, the scenario, the
+ * regression diff, and a minimal slice of repo context.
+ */
+export interface FixGenRequest {
+    /** The stable `'DHQ-###'` handle of the open regression. */
+    readonly dhqId: string;
+    /** The scenario whose replay diverged from the golden. */
+    readonly scenario: string;
+    /** The idempotency hash tying this request to ONE open DHQ row. */
+    readonly questionHash: string;
+    /** The structured regression entries (the evidence) from the envelope diff. */
+    readonly regressions: readonly DiffEntry[];
+    /**
+     * Minimal repo context the generator may use to ground the patch (e.g. the
+     * project root, a short description). Kept small on purpose — the loop does NOT
+     * stuff the whole repo into the prompt.
+     */
+    readonly repoContext: FixGenRepoContext;
+}
+/** Minimal repo context grounding a fix-generation request. */
+export interface FixGenRepoContext {
+    /** Absolute project root the patch is generated against. */
+    readonly projectRoot: string;
+    /** Optional one-line summary of what the scenario exercises. */
+    readonly summary?: string;
+}
+/** A generated patch, or an explicit "no usable patch" signal. */
+export type FixGenOutput = {
+    /** The generator produced a candidate unified-diff patch. */
+    readonly kind: 'patch';
+    /** The raw unified-diff text (validated by {@link generateFixPatch}). */
+    readonly diff: string;
+    /** The model id that produced it (for audit). */
+    readonly model: string;
+} | {
+    /** The generator produced no usable patch (degrade — never an error throw). */
+    readonly kind: 'none';
+    /** Machine-stable reason for the absence. */
+    readonly reason: string;
+};
+/**
+ * The injectable fix-generation port (the LLM seam).
+ *
+ * The real implementation ({@link createLlmFixGenerator}) drives the E9 chokepoint;
+ * tests inject a deterministic fake returning a canned patch. A `FixGenerator`
+ * MUST NOT throw — it encodes "no patch" as `{ kind: 'none', reason }`.
+ */
+export interface FixGenerator {
+    /**
+     * Propose a unified-diff patch for one regression.
+     *
+     * @param request - The structured {@link FixGenRequest}.
+     * @returns A {@link FixGenOutput} — a candidate patch or an explicit "none".
+     */
+    propose(request: FixGenRequest): Promise<FixGenOutput>;
+}
+/** The terminal outcome of {@link generateFixPatch}. */
+export type FixGenResult = {
+    /** A validated patch was written to {@link FixGenResultWritten.patchPath}. */
+    readonly kind: 'written';
+    /** Absolute path the patch was written to. */
+    readonly patchPath: string;
+    /** Byte length of the written patch. */
+    readonly bytes: number;
+    /** The model id that produced the patch. */
+    readonly model: string;
+} | {
+    /** No patch was written; the egress guard will skip the PR. */
+    readonly kind: 'skipped';
+    /** Machine-stable reason recorded on the DHQ evidence. */
+    readonly reason: string;
+};
+/**
+ * Options for {@link generateFixPatch}.
+ */
+export interface GenerateFixPatchOptions {
+    /** The structured fix-generation request. */
+    readonly request: FixGenRequest;
+    /** The injected generator (real LLM impl or a test fake). */
+    readonly generator: FixGenerator;
+    /**
+     * Working directory the patch path is resolved against — MUST match the `cwd`
+     * the downstream {@link "./draft-pr.js".openDraftPr} uses, so the file it writes
+     * is the file the egress finds.
+     */
+    readonly cwd?: string;
+    /** Injectable logger (defaults to the module logger). */
+    readonly logger?: Logger;
+}
+/**
+ * Compute the patch path the draft-PR egress expects for a scenario:
+ * `<cwd>/selfimprove-<scenario>.patch`. The scenario is sanitized to a safe file
+ * stem so a hostile scenario name cannot escape the cwd.
+ *
+ * @param scenario - The scenario name.
+ * @param cwd - The working directory to resolve against (defaults to `process.cwd`).
+ * @returns The absolute patch path.
+ */
+export declare function fixPatchPath(scenario: string, cwd?: string): string;
+/**
+ * Is `text` a plausible unified diff?
+ *
+ * A real `git apply`-able patch always carries at least one of the canonical
+ * unified-diff markers ({@link UNIFIED_DIFF_MARKERS}). An LLM that returns prose,
+ * an apology, or an empty string fails this guard, so the loop degrades to "no
+ * patch" rather than writing junk the egress would then fail to `git apply`.
+ *
+ * This is a cheap structural sniff, NOT a full parse — the authoritative
+ * applicability check is `git apply` inside the egress (which fails the PR cut on
+ * a bad patch, never `main`).
+ *
+ * @param text - Candidate patch text.
+ * @returns `true` when the text looks like a unified diff.
+ */
+export declare function looksLikeUnifiedDiff(text: string): boolean;
+/**
+ * Build the system + user prompt the real generator sends to the LLM. Pure
+ * (no IO) so it is unit-testable in isolation. The prompt is deliberately strict:
+ * "respond with ONLY a unified diff" — anything else fails
+ * {@link looksLikeUnifiedDiff} downstream and degrades to "no patch".
+ *
+ * @param request - The fix-generation request.
+ * @returns The `{ system, user }` prompt pair.
+ */
+export declare function buildFixGenPrompt(request: FixGenRequest): {
+    system: string;
+    user: string;
+};
+/**
+ * Run the fix-generation stage: ask the injected {@link FixGenerator} for a patch,
+ * validate it as a unified diff, and write it to the egress-expected patch path.
+ *
+ * This function NEVER throws and NEVER mutates anything but the single patch file.
+ * On ANY degrade path — generator returns `'none'`, the generator throws, or the
+ * returned text is not a unified diff — it writes NO file and returns
+ * `{ kind: 'skipped', reason }`, so the downstream `existsSync` egress guard
+ * simply skips the PR. The caller records the `reason` on the DHQ evidence.
+ *
+ * @param opts - See {@link GenerateFixPatchOptions}.
+ * @returns A {@link FixGenResult}.
+ *
+ * @example
+ * ```ts
+ * const res = await generateFixPatch({
+ *   request: { dhqId: 'DHQ-abcd1234', scenario, questionHash, regressions, repoContext },
+ *   generator: createLlmFixGenerator(),
+ *   cwd: projectRoot,
+ * });
+ * if (res.kind === 'written') { // openDraftPr will now find selfimprove-<scenario>.patch }
+ * ```
+ */
+export declare function generateFixPatch(opts: GenerateFixPatchOptions): Promise<FixGenResult>;
+/**
+ * Construct the REAL fix generator — the one that drives the E9 LLM chokepoint.
+ *
+ * Resolution funnels through {@link resolveLLMForSystem}(`'task-executor'`) →
+ * {@link ModelRunner.build} → `session.send` (ONE non-streaming completion).
+ * It constructs NO raw provider client, reads NO API-key env, and hardcodes no
+ * model id (Gate-13). The plaintext credential is materialized ONLY at the
+ * `ModelRunner` wire boundary (E10) via the sealed handle. When no credential is
+ * reachable it returns `{ kind: 'none' }` — the loop degrades to "no patch", no
+ * PR. This function constructs nothing at call time (lazy dynamic imports keep the
+ * module import-time side-effect-free + the E9 deps off the hot import path).
+ *
+ * @param opts - Optional project root threaded into the resolver.
+ * @returns A {@link FixGenerator} backed by the E9 chokepoint.
+ *
+ * @example
+ * ```ts
+ * const gen = createLlmFixGenerator({ projectRoot });
+ * const out = await gen.propose(request); // resolves model via E9, never raw client
+ * ```
+ */
+export declare function createLlmFixGenerator(opts?: {
+    projectRoot?: string;
+}): FixGenerator;
+/**
+ * Strip a single surrounding markdown code fence (```diff … ```), if present, so a
+ * model that wraps its diff still yields an applyable patch. A bare diff passes
+ * through untouched.
+ *
+ * @param text - Candidate patch text (already trimmed).
+ * @returns The fence-stripped text.
+ */
+export declare function stripCodeFences(text: string): string;
+//# sourceMappingURL=fix-gen.d.ts.map

package/dist/selfimprove/fix-gen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fix-gen.d.ts","sourceRoot":"","sources":["../../src/selfimprove/fix-gen.ts"],"names":[],"mappings":"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"}

package/dist/selfimprove/fix-gen.js

@@ -0,0 +1,266 @@
+/**
+ * Fix-generation stage for the self-improvement loop (T11889 · T11975).
+ *
+ * This is the missing autonomous link the v1 loop explicitly stubbed out
+ * ("NO autonomous fix-gen in v1", see {@link "./run-loop.js"}): given a detected
+ * regression (an open `selfimprove_dhq` + its envelope-diff) plus minimal repo
+ * context, it asks the LLM to PROPOSE a unified-diff patch and writes that patch
+ * to the path the draft-PR egress ({@link "./draft-pr.js".openDraftPr}) already
+ * `existsSync`-checks: `<cwd>/selfimprove-<scenario>.patch`. Once the patch is on
+ * disk the existing egress guard opens ONE DRAFT PR — closing the
+ * DHQ → fix → draft-PR pipeline end-to-end.
+ *
+ * ## Hard safety posture (unchanged from v1 — P5 spec §B.7)
+ *
+ *   - **LLM ONLY via the E9 chokepoint.** The real generator
+ *     ({@link createLlmFixGenerator}) resolves its model strictly through
+ *     {@link "../llm/system-resolver.js".resolveLLMForSystem} → {@link ModelRunner}
+ *     (Gate-13). It constructs NO raw provider client, reads NO `*_API_KEY` env,
+ *     and hardcodes no model id — the resolver/registry is the SSoT. The
+ *     plaintext token is materialized only at the wire boundary (E10).
+ *   - **Draft-PR-ONLY, never auto-merge.** This module produces a PATCH FILE only;
+ *     the egress that consumes it always opens a `--draft` PR against a feature
+ *     branch (never `main`). This module performs NO git/gh action.
+ *   - **Graceful degrade, never a rogue mutation.** Every failure (no credential,
+ *     LLM error, empty / non-unified-diff output) returns a typed
+ *     {@link FixGenResult} of kind `'skipped'` and writes NO patch file — so the
+ *     existing egress guard (`existsSync` on the patch path) simply skips the PR.
+ *     This function NEVER throws.
+ *   - **Injectable seam.** The LLM dependency is the {@link FixGenerator} port;
+ *     unit tests inject a deterministic fake that returns a canned patch, so NO
+ *     real LLM is reached in tests.
+ *
+ * CORE-first: this engine lives in `core` and owns the `FixGenerator` port TYPE.
+ * Import-time side-effect-free.
+ *
+ * @module @cleocode/core/selfimprove/fix-gen
+ * @epic T11889
+ * @task T11975
+ */
+import { writeFileSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { cwd as processCwd } from 'node:process';
+/**
+ * The E9 system-of-use label the fix-generator resolves its model under. Maps to
+ * the `judgement` role (see `SYSTEM_ROLE_MAP`) — the closest standing role for
+ * "reason about a regression and propose a code change".
+ */
+const FIXGEN_SYSTEM = 'task-executor';
+/** A leading marker every unified-diff hunk header / file header carries. */
+const UNIFIED_DIFF_MARKERS = ['diff --git ', '--- ', '+++ ', '@@ '];
+/**
+ * Compute the patch path the draft-PR egress expects for a scenario:
+ * `<cwd>/selfimprove-<scenario>.patch`. The scenario is sanitized to a safe file
+ * stem so a hostile scenario name cannot escape the cwd.
+ *
+ * @param scenario - The scenario name.
+ * @param cwd - The working directory to resolve against (defaults to `process.cwd`).
+ * @returns The absolute patch path.
+ */
+export function fixPatchPath(scenario, cwd) {
+    const safeScenario = scenario.replace(/[^a-z0-9-]/gi, '-');
+    return resolvePath(cwd ?? processCwd(), `selfimprove-${safeScenario}.patch`);
+}
+/**
+ * Is `text` a plausible unified diff?
+ *
+ * A real `git apply`-able patch always carries at least one of the canonical
+ * unified-diff markers ({@link UNIFIED_DIFF_MARKERS}). An LLM that returns prose,
+ * an apology, or an empty string fails this guard, so the loop degrades to "no
+ * patch" rather than writing junk the egress would then fail to `git apply`.
+ *
+ * This is a cheap structural sniff, NOT a full parse — the authoritative
+ * applicability check is `git apply` inside the egress (which fails the PR cut on
+ * a bad patch, never `main`).
+ *
+ * @param text - Candidate patch text.
+ * @returns `true` when the text looks like a unified diff.
+ */
+export function looksLikeUnifiedDiff(text) {
+    if (text.trim().length === 0)
+        return false;
+    return UNIFIED_DIFF_MARKERS.some((marker) => text.includes(marker));
+}
+/**
+ * Build the system + user prompt the real generator sends to the LLM. Pure
+ * (no IO) so it is unit-testable in isolation. The prompt is deliberately strict:
+ * "respond with ONLY a unified diff" — anything else fails
+ * {@link looksLikeUnifiedDiff} downstream and degrades to "no patch".
+ *
+ * @param request - The fix-generation request.
+ * @returns The `{ system, user }` prompt pair.
+ */
+export function buildFixGenPrompt(request) {
+    const system = 'You are an autonomous software-maintenance agent. You are given a detected ' +
+        'regression in a TypeScript monorepo (a divergence between a replayed scenario ' +
+        'and its golden expected output). Produce a MINIMAL fix as a single unified diff ' +
+        '(`git diff` format, with `diff --git`, `---`, `+++`, and `@@` hunk headers). ' +
+        'Respond with ONLY the unified diff and NOTHING else — no prose, no code fences, ' +
+        'no explanation. If you cannot propose a safe fix, respond with the single token ' +
+        'NO_PATCH.';
+    const lines = request.regressions.map((r) => `- op ${r.opCoord} (#${r.opIndex}) at path \`${r.path}\`: ` +
+        `actual=${JSON.stringify(r.actual)} expected=${JSON.stringify(r.expected)}`);
+    const user = `Regression ${request.dhqId} in scenario \`${request.scenario}\` ` +
+        `(${request.regressions.length} diverging path(s)).\n` +
+        (request.repoContext.summary ? `Scenario summary: ${request.repoContext.summary}\n` : '') +
+        `Project root: ${request.repoContext.projectRoot}\n\n` +
+        `Diverging paths:\n${lines.join('\n')}\n\n` +
+        'Produce the unified diff that resolves these divergences.';
+    return { system, user };
+}
+/**
+ * Lazily-resolved module logger (import-time side-effect-free).
+ */
+let cachedLogger;
+async function getModuleLogger() {
+    if (cachedLogger === undefined) {
+        const { getLogger } = await import('../logger.js');
+        cachedLogger = getLogger('selfimprove-fix-gen');
+    }
+    return cachedLogger;
+}
+/**
+ * Run the fix-generation stage: ask the injected {@link FixGenerator} for a patch,
+ * validate it as a unified diff, and write it to the egress-expected patch path.
+ *
+ * This function NEVER throws and NEVER mutates anything but the single patch file.
+ * On ANY degrade path — generator returns `'none'`, the generator throws, or the
+ * returned text is not a unified diff — it writes NO file and returns
+ * `{ kind: 'skipped', reason }`, so the downstream `existsSync` egress guard
+ * simply skips the PR. The caller records the `reason` on the DHQ evidence.
+ *
+ * @param opts - See {@link GenerateFixPatchOptions}.
+ * @returns A {@link FixGenResult}.
+ *
+ * @example
+ * ```ts
+ * const res = await generateFixPatch({
+ *   request: { dhqId: 'DHQ-abcd1234', scenario, questionHash, regressions, repoContext },
+ *   generator: createLlmFixGenerator(),
+ *   cwd: projectRoot,
+ * });
+ * if (res.kind === 'written') { // openDraftPr will now find selfimprove-<scenario>.patch }
+ * ```
+ */
+export async function generateFixPatch(opts) {
+    const logger = opts.logger ?? (await getModuleLogger());
+    const { request, generator } = opts;
+    const patchPath = fixPatchPath(request.scenario, opts.cwd);
+    let output;
+    try {
+        output = await generator.propose(request);
+    }
+    catch (err) {
+        const reason = `fixgen-threw:${err instanceof Error ? err.message : String(err)}`;
+        logger.warn({ dhqId: request.dhqId, scenario: request.scenario, reason }, 'fix-gen degraded');
+        return { kind: 'skipped', reason };
+    }
+    if (output.kind === 'none') {
+        logger.info({ dhqId: request.dhqId, scenario: request.scenario, reason: output.reason }, 'fix-gen produced no patch (graceful skip — no PR)');
+        return { kind: 'skipped', reason: `fixgen-none:${output.reason}` };
+    }
+    if (!looksLikeUnifiedDiff(output.diff)) {
+        logger.warn({ dhqId: request.dhqId, scenario: request.scenario }, 'fix-gen output is not a unified diff (graceful skip — no PR)');
+        return { kind: 'skipped', reason: 'fixgen-not-a-diff' };
+    }
+    // Normalize a trailing newline so `git apply` accepts the hunk.
+    const diff = output.diff.endsWith('\n') ? output.diff : `${output.diff}\n`;
+    writeFileSync(patchPath, diff, 'utf8');
+    const bytes = Buffer.byteLength(diff, 'utf8');
+    logger.info({ dhqId: request.dhqId, scenario: request.scenario, patchPath, bytes, model: output.model }, 'fix-gen wrote candidate patch — egress will open a DRAFT PR');
+    return { kind: 'written', patchPath, bytes, model: output.model };
+}
+/**
+ * Construct the REAL fix generator — the one that drives the E9 LLM chokepoint.
+ *
+ * Resolution funnels through {@link resolveLLMForSystem}(`'task-executor'`) →
+ * {@link ModelRunner.build} → `session.send` (ONE non-streaming completion).
+ * It constructs NO raw provider client, reads NO API-key env, and hardcodes no
+ * model id (Gate-13). The plaintext credential is materialized ONLY at the
+ * `ModelRunner` wire boundary (E10) via the sealed handle. When no credential is
+ * reachable it returns `{ kind: 'none' }` — the loop degrades to "no patch", no
+ * PR. This function constructs nothing at call time (lazy dynamic imports keep the
+ * module import-time side-effect-free + the E9 deps off the hot import path).
+ *
+ * @param opts - Optional project root threaded into the resolver.
+ * @returns A {@link FixGenerator} backed by the E9 chokepoint.
+ *
+ * @example
+ * ```ts
+ * const gen = createLlmFixGenerator({ projectRoot });
+ * const out = await gen.propose(request); // resolves model via E9, never raw client
+ * ```
+ */
+export function createLlmFixGenerator(opts = {}) {
+    return {
+        async propose(request) {
+            const logger = await getModuleLogger();
+            // Lazy imports: keep E9 deps off the module import path + side-effect-free.
+            const { resolveLLMForSystem } = await import('../llm/system-resolver.js');
+            const { ModelRunner } = await import('../llm/model-runner.js');
+            // 1. E9 resolution chokepoint. Never throws (resolver contract).
+            const projectRoot = opts.projectRoot ?? request.repoContext.projectRoot;
+            const resolved = await resolveLLMForSystem(FIXGEN_SYSTEM, { projectRoot });
+            if (!resolved.sealedCredential && resolved.authType !== 'aws_sdk') {
+                return { kind: 'none', reason: 'no-credential-resolved' };
+            }
+            // 2. Materialize the plaintext ONLY at the wire boundary (E10), build a
+            //    clean descriptor, and construct the transport inside ModelRunner.
+            const apiKey = resolved.sealedCredential
+                ? (await resolved.sealedCredential.fetch()).value
+                : null;
+            const built = await ModelRunner.build({
+                provider: resolved.provider,
+                model: resolved.model,
+                credential: resolved.credential
+                    ? {
+                        provider: resolved.credential.provider,
+                        apiKey,
+                        source: resolved.credential.source,
+                        authType: resolved.credential.authType,
+                    }
+                    : null,
+                source: resolved.source,
+                ...(resolved.credentialLabel !== undefined
+                    ? { credentialLabel: resolved.credentialLabel }
+                    : {}),
+                apiMode: resolved.apiMode,
+                baseUrl: resolved.baseUrl,
+                authType: resolved.authType,
+                ...(resolved.capabilities !== undefined ? { capabilities: resolved.capabilities } : {}),
+            });
+            // 3. ONE non-streaming completion. The system prompt is threaded onto the
+            //    request via `systemSuffix` (ConcreteSession maps it to
+            //    `TransportRequest.system`); the user turn carries the regression detail.
+            const { system, user } = buildFixGenPrompt(request);
+            try {
+                const response = await built.session.send([{ role: 'user', content: user }], {
+                    systemSuffix: system,
+                });
+                const text = (response.content ?? '').trim();
+                if (text.length === 0 || text === 'NO_PATCH') {
+                    return { kind: 'none', reason: 'model-declined' };
+                }
+                return { kind: 'patch', diff: stripCodeFences(text), model: response.model };
+            }
+            catch (err) {
+                logger.warn({ system: FIXGEN_SYSTEM, err: err instanceof Error ? err.message : String(err) }, 'fix-gen LLM call failed — degrading to no-patch');
+                return { kind: 'none', reason: 'llm-call-failed' };
+            }
+        },
+    };
+}
+/**
+ * Strip a single surrounding markdown code fence (```diff … ```), if present, so a
+ * model that wraps its diff still yields an applyable patch. A bare diff passes
+ * through untouched.
+ *
+ * @param text - Candidate patch text (already trimmed).
+ * @returns The fence-stripped text.
+ */
+export function stripCodeFences(text) {
+    const fence = /^```[a-z]*\n([\s\S]*?)\n```$/i;
+    const m = text.match(fence);
+    return m?.[1] !== undefined ? m[1].trim() : text;
+}
+//# sourceMappingURL=fix-gen.js.map

package/dist/selfimprove/fix-gen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fix-gen.js","sourceRoot":"","sources":["../../src/selfimprove/fix-gen.ts"],"names":[],"mappings":"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"}

package/dist/selfimprove/run-loop.d.ts

@@ -17,8 +17,15 @@
  *   4. on a regression, **emit ONE DHQ** row via the leased
  *      {@link "./dhq-adapter.js".DhqAdapter} (UPSERT under
  *      `withWriterLease('project','bulk',…)`) — ONLY when `execute` is set;
+ *   4b. **generate a fix** ({@link "./fix-gen.js".generateFixPatch}, T11975) — ONLY
+ *      when `execute` AND `CLEO_PI_RUNNER_ENABLED=1`. Drives the LLM strictly via
+ *      the E9 chokepoint to produce a unified-diff patch at the path the egress
+ *      expects (`<cwd>/selfimprove-<scenario>.patch`). Degrades gracefully (no
+ *      patch ⇒ the egress guard skips the PR); the outcome is recorded back onto
+ *      the DHQ row. NEVER throws a rogue mutation, NEVER auto-merges;
  *   5. **open ONE DRAFT PR** ({@link "./draft-pr.js".openDraftPr}, dry-run unless
- *      `execute`) and record its URL back on the DHQ row.
+ *      `execute`) and record its URL back on the DHQ row — fires only when the
+ *      fix-gen stage wrote a patch file (the existing `existsSync` egress guard).
  *
  * Self-dogfooding guardrails (NON-NEGOTIABLE, P5 spec §B.7):
  *   - **Default OFF.** Mutation + egress require `opts.execute === true`. Without
@@ -30,8 +37,12 @@
  *   - **Budget caps** (in-code): `maxTokens` / `maxUsd` / `maxPrs = 1` /
  *     `maxWorktrees = 1`, checked PRE-FLIGHT before each costed step. `MemoryMax=32G`
  *     is an operational launch-wrapper, not an in-code cap.
- *   - **NO autonomous fix-gen, NO auto-merge, NO end-user mode in v1.** The loop
- *     surfaces regressions as DHQs + draft PRs; a human drives the fix.
+ *   - **Fix-gen is GATED + DRAFT-PR-ONLY (T11975).** The autonomous fix-generation
+ *     stage runs ONLY behind BOTH `execute` AND `CLEO_PI_RUNNER_ENABLED=1` (the
+ *     same gates guarding the rest of the loop). It produces a candidate patch via
+ *     the E9 LLM chokepoint and lets the EXISTING egress open a DRAFT PR — NEVER
+ *     an auto-merge, NEVER an end-user mode, NEVER a `main` push. A failed or empty
+ *     fix-gen degrades to "no patch" and the egress simply skips the PR.
  *
  * CORE-first: this engine lives in `core` and owns the `ReplayDispatch` port TYPE;
  * the cleo dispatch handler supplies the concrete adapter (dependency inversion —
@@ -45,8 +56,9 @@ import { type ExecutionEnvBackend } from '../llm/pi/resolve-execution-env.js';
 import { type ToolGuard } from '../tools/guard.js';
 import { type CircuitBreakerState, DEFAULT_BUDGET, type SelfImproveBudget } from './budget.js';
 import { type DhqAdapter } from './dhq-adapter.js';
-import { type DraftPrResult } from './draft-pr.js';
+import { type CommandRunner, type DraftPrResult } from './draft-pr.js';
 import { type DiffEntry } from './envelope-diff.js';
+import { type FixGenerator, type FixGenResult } from './fix-gen.js';
 import { type ReplayDispatch } from './replay.js';
 /** Options for {@link runSelfImprove}. */
 export interface RunSelfImproveOptions {
@@ -87,6 +99,27 @@ export interface RunSelfImproveOptions {
     readonly gateRedCheck?: () => Promise<boolean>;
     /** Test seam: inject a DHQ adapter (defaults to the real leased adapter). */
     readonly adapter?: DhqAdapter;
+    /**
+     * Test seam: inject the fix generator (the LLM dependency). Defaults to the real
+     * {@link "./fix-gen.js".createLlmFixGenerator} backed by the E9 chokepoint — unit
+     * tests inject a deterministic fake returning a canned patch so NO real LLM is
+     * reached. The fix-gen stage only runs when BOTH `execute` is set AND the
+     * Pi-runner gate (`CLEO_PI_RUNNER_ENABLED=1`) is on, unless `piRunnerEnabled` is
+     * supplied (test seam) to override the env read.
+     */
+    readonly fixGenerator?: FixGenerator;
+    /**
+     * Test seam: override the `CLEO_PI_RUNNER_ENABLED` env gate that arms fix-gen.
+     * Defaults to `process.env.CLEO_PI_RUNNER_ENABLED === '1'`. Supplied explicitly
+     * by tests so the deterministic fake runs without mutating process env.
+     */
+    readonly piRunnerEnabled?: boolean;
+    /**
+     * Test seam: inject the draft-PR egress command runner (captures the git/gh
+     * shell-out). Defaults to the real `execFileSync`-backed runner. Supplied by
+     * tests so the capstone proves the egress WITHOUT a real `gh`/`git` invocation.
+     */
+    readonly draftPrRun?: CommandRunner;
     /** Test seam: inject the guard backing the in-process fallback env. */
     readonly guard?: ToolGuard;
     /** Test seam: inject the run id (defaults to a timestamped id). */
@@ -120,6 +153,13 @@ export interface SelfImproveResult {
     readonly questionHash: string | null;
     /** The draft-PR egress result, or `null` when none fired (green / dry-run-no-egress). */
     readonly draftPr: DraftPrResult | null;
+    /**
+     * The fix-generation outcome (T11975), or `null` when the stage did not run
+     * (green run, dry-run, gate off, or breaker tripped before persist). `'written'`
+     * means a candidate patch was produced and the egress was armed; `'skipped'`
+     * means fix-gen degraded gracefully (no patch ⇒ no PR).
+     */
+    readonly fixGen: FixGenResult | null;
     /** The final circuit-breaker state. */
     readonly breaker: CircuitBreakerState;
 }

package/dist/selfimprove/run-loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-loop.d.ts","sourceRoot":"","sources":["../../src/selfimprove/run-loop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAGH,OAAO,EAAE,KAAK,mBAAmB,EAAuB,MAAM,oCAAoC,CAAC;AAGnG,OAAO,EAAmB,KAAK,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACpE,OAAO,EAGL,KAAK,mBAAmB,EACxB,cAAc,EAEd,KAAK,iBAAiB,EACvB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAoB,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACrE,OAAO,EAAE,KAAK,aAAa,EAAe,MAAM,eAAe,CAAC;AAChE,OAAO,EAAuB,KAAK,SAAS,EAAiB,MAAM,oBAAoB,CAAC;AACxF,OAAO,EAAE,KAAK,cAAc,EAAkB,MAAM,aAAa,CAAC;AAGlE,0CAA0C;AAC1C,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,oFAAoF;IACpF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,mBAAmB,CAAC;IACvC,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,8EAA8E;IAC9E,QAAQ,CAAC,MAAM,CAAC,EAAE,OAAO,CAAC,iBAAiB,CAAC,CAAC;IAC7C;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,6EAA6E;IAC7E,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;IAC9B,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAC;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,gEAAgE;IAChE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,qDAAqD;AACrD,MAAM,MAAM,UAAU;AACpB,gEAAgE;AAC9D,OAAO;AACT,4DAA4D;GAC1D,oBAAoB;AACtB,sEAAsE;GACpE,kBAAkB;AACpB,0CAA0C;GACxC,QAAQ,CAAC;AAEb,gEAAgE;AAChE,MAAM,WAAW,iBAAiB;IAChC,4BAA4B;IAC5B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,6BAA6B;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,yDAAyD;IACzD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,uDAAuD;IACvD,QAAQ,CAAC,WAAW,EAAE,SAAS,SAAS,EAAE,CAAC;IAC3C,oFAAoF;IACpF,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,yFAAyF;IACzF,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,IAAI,CAAC;IACvC,uCAAuC;IACvC,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;CACvC;AAcD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CA8J5F;AA2CD,OAAO,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"run-loop.d.ts","sourceRoot":"","sources":["../../src/selfimprove/run-loop.ts"],"names":[],"mappings":"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"}