@cleocode/core 2026.6.11 → 2026.6.13

package/dist/selfimprove/dhq-adapter.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Durable DHQ adapter for the self-improvement loop (T11889 · T11889-C).
+ *
+ * This adapter sits OUTSIDE the store chokepoint (it is in `selfimprove/`, not
+ * `store/`), so it MUST NOT open a raw native handle (Gate-3). It is the lease
+ * boundary: EVERY write it performs is wrapped in
+ * {@link "../store/writer-lease.js".withWriterLease}`('project', 'bulk', …)`, which
+ * serializes the write against any other writer on the `(project, bulk)` lane. It
+ * then calls the Gate-3 accessors in
+ * {@link "../store/selfimprove-dhq-store.js"} (the ONLY native-handle toucher) —
+ * whose prepared statements target ONLY `selfimprove_dhq`.
+ *
+ * Two invariants the rest of the loop relies on:
+ *
+ *   1. **No raw / unleased write.** Reads go straight through the accessor (the
+ *      shared handle, no lease); every WRITE goes through {@link upsertOpenDhq} /
+ *      {@link recordPrUrl}, both of which acquire the lease first. There is no
+ *      code path here that mutates `cleo.db` without the lease.
+ *   2. **`selfimprove_dhq` ONLY — never a prod `tasks`/`brain` row.** The lease
+ *      SERIALIZES the write; it does NOT confine it to a table. The
+ *      table-confinement is ENTIRELY this adapter's discipline: it calls only the
+ *      `selfimprove_dhq` accessors, whose SQL references no other table. A unit
+ *      test asserts the accessor SQL targets `selfimprove_dhq` and nothing else.
+ *
+ * Lease-mode note (P5 spec §B.7): the default mode is `local` (no daemon), where a
+ * contended lease DEGRADES under `busy_timeout` rather than throwing. To get a hard
+ * denial signal for the circuit-breaker, the process runs in `require` mode
+ * (`CLEO_WRITER_LEASE_MODE=require`), where an unacquirable lease THROWS
+ * {@link "../store/writer-lease.js".LeaseUnavailableError}. This adapter does NOT
+ * swallow that throw — it propagates so {@link runSelfImprove} trips the breaker.
+ *
+ * This module is import-time side-effect-free.
+ *
+ * @module @cleocode/core/selfimprove/dhq-adapter
+ * @epic T11889
+ * @task T11913
+ */
+import { type SelfimproveDhqRow } from '../store/selfimprove-dhq-store.js';
+/**
+ * The fields the engine supplies to {@link upsertOpenDhq}. `now` and the fixed
+ * `status: 'open'` are stamped by the accessor; `dhqId` / `severity` carry through.
+ */
+export interface UpsertDhqInput {
+    /** Stable `'DHQ-###'` handle (used only on first insert for a hash). */
+    readonly dhqId: string;
+    /** The scenario name replayed. */
+    readonly scenario: string;
+    /** sha256 of the normalized regression signature — the idempotency key. */
+    readonly questionHash: string;
+    /** Human-readable DHQ title. */
+    readonly title: string;
+    /** The envelope-diff payload (the evidence) as serialized JSON. */
+    readonly regressionJson: string;
+    /** Severity classification, or `null` until triaged. */
+    readonly severity: string | null;
+    /** Ties the row to ONE loop run. */
+    readonly runId: string;
+}
+/** The durable DHQ adapter — the lease boundary for the self-improvement loop. */
+export interface DhqAdapter {
+    /**
+     * Read the open DHQ row for a `question_hash` (lease-free — readers share the
+     * handle). Returns `null` when no open row exists.
+     */
+    readOpen(questionHash: string): Promise<SelfimproveDhqRow | null>;
+    /**
+     * UPSERT exactly ONE open DHQ row for a `question_hash`, under the
+     * `(project, bulk)` writer lease. Idempotent via the partial-UNIQUE index: a
+     * repeated open regression refreshes the existing row.
+     */
+    upsertOpenDhq(input: UpsertDhqInput): Promise<void>;
+    /**
+     * Record the draft PR URL on the open DHQ row for a `question_hash`, under the
+     * `(project, bulk)` writer lease.
+     *
+     * @returns The number of rows updated (0 when no open row exists).
+     */
+    recordPrUrl(questionHash: string, prUrl: string): Promise<number>;
+}
+/**
+ * Construct the durable DHQ adapter bound to a project working directory.
+ *
+ * Every WRITE method acquires the `(project, bulk)` writer lease via
+ * {@link "../store/writer-lease.js".withWriterLease} before delegating to the
+ * Gate-3 accessor. The native handle is resolved per call through
+ * {@link "../store/selfimprove-dhq-store.js".getSelfimproveDhqNativeDb} (the
+ * chokepoint singleton — no raw open). The clock is injectable for deterministic
+ * tests; production uses `Date.now`.
+ *
+ * @param opts - Adapter options.
+ * @param opts.cwd - Project working directory for scope resolution (defaults to `cwd`).
+ * @param opts.now - Injectable clock (defaults to {@link Date.now}).
+ * @returns A {@link DhqAdapter}.
+ *
+ * @example
+ * ```ts
+ * const adapter = createDhqAdapter({ cwd: projectRoot });
+ * await adapter.upsertOpenDhq({ dhqId: 'DHQ-001', … }); // leased UPSERT
+ * ```
+ */
+export declare function createDhqAdapter(opts?: {
+    cwd?: string;
+    now?: () => number;
+}): DhqAdapter;
+//# sourceMappingURL=dhq-adapter.d.ts.map

package/dist/selfimprove/dhq-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dhq-adapter.d.ts","sourceRoot":"","sources":["../../src/selfimprove/dhq-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EAGL,KAAK,iBAAiB,EAIvB,MAAM,mCAAmC,CAAC;AAG3C;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kCAAkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,2EAA2E;IAC3E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,gCAAgC;IAChC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,oCAAoC;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,kFAAkF;AAClF,MAAM,WAAW,UAAU;IACzB;;;OAGG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IAClE;;;;OAIG;IACH,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD;;;;;OAKG;IACH,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACnE;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAA;CAAO,GAAG,UAAU,CAoC5F"}

package/dist/selfimprove/dhq-adapter.js

@@ -0,0 +1,95 @@
+/**
+ * Durable DHQ adapter for the self-improvement loop (T11889 · T11889-C).
+ *
+ * This adapter sits OUTSIDE the store chokepoint (it is in `selfimprove/`, not
+ * `store/`), so it MUST NOT open a raw native handle (Gate-3). It is the lease
+ * boundary: EVERY write it performs is wrapped in
+ * {@link "../store/writer-lease.js".withWriterLease}`('project', 'bulk', …)`, which
+ * serializes the write against any other writer on the `(project, bulk)` lane. It
+ * then calls the Gate-3 accessors in
+ * {@link "../store/selfimprove-dhq-store.js"} (the ONLY native-handle toucher) —
+ * whose prepared statements target ONLY `selfimprove_dhq`.
+ *
+ * Two invariants the rest of the loop relies on:
+ *
+ *   1. **No raw / unleased write.** Reads go straight through the accessor (the
+ *      shared handle, no lease); every WRITE goes through {@link upsertOpenDhq} /
+ *      {@link recordPrUrl}, both of which acquire the lease first. There is no
+ *      code path here that mutates `cleo.db` without the lease.
+ *   2. **`selfimprove_dhq` ONLY — never a prod `tasks`/`brain` row.** The lease
+ *      SERIALIZES the write; it does NOT confine it to a table. The
+ *      table-confinement is ENTIRELY this adapter's discipline: it calls only the
+ *      `selfimprove_dhq` accessors, whose SQL references no other table. A unit
+ *      test asserts the accessor SQL targets `selfimprove_dhq` and nothing else.
+ *
+ * Lease-mode note (P5 spec §B.7): the default mode is `local` (no daemon), where a
+ * contended lease DEGRADES under `busy_timeout` rather than throwing. To get a hard
+ * denial signal for the circuit-breaker, the process runs in `require` mode
+ * (`CLEO_WRITER_LEASE_MODE=require`), where an unacquirable lease THROWS
+ * {@link "../store/writer-lease.js".LeaseUnavailableError}. This adapter does NOT
+ * swallow that throw — it propagates so {@link runSelfImprove} trips the breaker.
+ *
+ * This module is import-time side-effect-free.
+ *
+ * @module @cleocode/core/selfimprove/dhq-adapter
+ * @epic T11889
+ * @task T11913
+ */
+import { getSelfimproveDhqNativeDb, readOpenSelfimproveDhq, setSelfimproveDhqPrUrl, upsertOpenSelfimproveDhq, } from '../store/selfimprove-dhq-store.js';
+import { withWriterLease } from '../store/writer-lease.js';
+/**
+ * Construct the durable DHQ adapter bound to a project working directory.
+ *
+ * Every WRITE method acquires the `(project, bulk)` writer lease via
+ * {@link "../store/writer-lease.js".withWriterLease} before delegating to the
+ * Gate-3 accessor. The native handle is resolved per call through
+ * {@link "../store/selfimprove-dhq-store.js".getSelfimproveDhqNativeDb} (the
+ * chokepoint singleton — no raw open). The clock is injectable for deterministic
+ * tests; production uses `Date.now`.
+ *
+ * @param opts - Adapter options.
+ * @param opts.cwd - Project working directory for scope resolution (defaults to `cwd`).
+ * @param opts.now - Injectable clock (defaults to {@link Date.now}).
+ * @returns A {@link DhqAdapter}.
+ *
+ * @example
+ * ```ts
+ * const adapter = createDhqAdapter({ cwd: projectRoot });
+ * await adapter.upsertOpenDhq({ dhqId: 'DHQ-001', … }); // leased UPSERT
+ * ```
+ */
+export function createDhqAdapter(opts = {}) {
+    const cwd = opts.cwd;
+    const now = opts.now ?? (() => Date.now());
+    return {
+        async readOpen(questionHash) {
+            const native = await getSelfimproveDhqNativeDb(cwd);
+            return readOpenSelfimproveDhq(native, questionHash);
+        },
+        async upsertOpenDhq(input) {
+            // EVERY write is leased — never raw / unleased. The lease serializes against
+            // other writers on (project, bulk); the table-confinement is the accessor's.
+            await withWriterLease('project', 'bulk', async () => {
+                const native = await getSelfimproveDhqNativeDb(cwd);
+                const row = {
+                    dhqId: input.dhqId,
+                    scenario: input.scenario,
+                    questionHash: input.questionHash,
+                    title: input.title,
+                    regressionJson: input.regressionJson,
+                    severity: input.severity,
+                    runId: input.runId,
+                    now: now(),
+                };
+                upsertOpenSelfimproveDhq(native, row);
+            });
+        },
+        async recordPrUrl(questionHash, prUrl) {
+            return withWriterLease('project', 'bulk', async () => {
+                const native = await getSelfimproveDhqNativeDb(cwd);
+                return setSelfimproveDhqPrUrl(native, questionHash, prUrl, now());
+            });
+        },
+    };
+}
+//# sourceMappingURL=dhq-adapter.js.map

package/dist/selfimprove/dhq-adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dhq-adapter.js","sourceRoot":"","sources":["../../src/selfimprove/dhq-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,EACL,yBAAyB,EACzB,sBAAsB,EAGtB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AA6C3D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAA6C,EAAE;IAC9E,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;IACrB,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;IAE3C,OAAO;QACL,KAAK,CAAC,QAAQ,CAAC,YAAoB;YACjC,MAAM,MAAM,GAAG,MAAM,yBAAyB,CAAC,GAAG,CAAC,CAAC;YACpD,OAAO,sBAAsB,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QACtD,CAAC;QAED,KAAK,CAAC,aAAa,CAAC,KAAqB;YACvC,6EAA6E;YAC7E,6EAA6E;YAC7E,MAAM,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,IAAI,EAAE;gBAClD,MAAM,MAAM,GAAG,MAAM,yBAAyB,CAAC,GAAG,CAAC,CAAC;gBACpD,MAAM,GAAG,GAAyB;oBAChC,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,YAAY,EAAE,KAAK,CAAC,YAAY;oBAChC,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,cAAc,EAAE,KAAK,CAAC,cAAc;oBACpC,QAAQ,EAAE,KAAK,CAAC,QAAQ;oBACxB,KAAK,EAAE,KAAK,CAAC,KAAK;oBAClB,GAAG,EAAE,GAAG,EAAE;iBACX,CAAC;gBACF,wBAAwB,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;YACxC,CAAC,CAAC,CAAC;QACL,CAAC;QAED,KAAK,CAAC,WAAW,CAAC,YAAoB,EAAE,KAAa;YACnD,OAAO,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,IAAI,EAAE;gBACnD,MAAM,MAAM,GAAG,MAAM,yBAAyB,CAAC,GAAG,CAAC,CAAC;gBACpD,OAAO,sBAAsB,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC;YACpE,CAAC,CAAC,CAAC;QACL,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/selfimprove/draft-pr.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Draft-PR egress for the self-improvement loop (T11889 · T11889-C).
+ *
+ * On a detected regression the loop's ONLY outbound action is to open ONE DRAFT
+ * PR against the cleocode repo (ADR-065 — PRs target `main` via the Merge Queue;
+ * NEVER a direct push to `main`, NEVER an auto-merge, NEVER a publish). This module
+ * is the egress primitive, modeled on `propose-patch.ts` (the closest "agent
+ * proposes a fix PR" exemplar) with three self-dogfooding hardenings:
+ *
+ *   1. **`--draft` is ALWAYS appended** to `gh pr create` — the PR is never
+ *      ready-for-merge; a human reviews and undrafts it.
+ *   2. **Dry-run is the DEFAULT.** `openDraftPr` returns the planned `steps[]`
+ *      WITHOUT invoking git/gh unless `execute: true` is passed. So the loop is
+ *      side-effect-free at egress by default.
+ *   3. **Branch `feat/T11889-selfimprove-<scenario>-<ts>`** — a feature branch
+ *      (ADR-065); no main mutation path exists in this module.
+ *
+ * The live path wraps the git/gh shell-out in
+ * {@link "../sentient/skill-provenance.js".withProvenance}`('pr-generator', …)`
+ * (the established legal PR-cutting origin — the `SkillWriteOrigin` union is
+ * closed) and returns the `gh`-emitted PR URL so the caller can record it back
+ * into `selfimprove_dhq.pr_url` via the leased adapter.
+ *
+ * This module is import-time side-effect-free.
+ *
+ * @module @cleocode/core/selfimprove/draft-pr
+ * @epic T11889
+ * @task T11913
+ */
+/**
+ * Pluggable command runner. Returns stdout as UTF-8 text or throws on non-zero
+ * exit. Production default wraps `child_process.execFileSync` with piped stdio.
+ */
+export type CommandRunner = (file: string, args: readonly string[]) => string;
+/** Failure codes from {@link openDraftPr}. */
+export type DraftPrErrorCode = 
+/** Patch file does not exist on disk. */
+'E_NOT_FOUND'
+/** Patch file exists but is empty. */
+ | 'E_PATCH_EMPTY'
+/** `gh` CLI missing / not authenticated. */
+ | 'E_GH_UNAVAILABLE'
+/** Shell-out failure during the live PR cut. */
+ | 'E_DRAFT_PR_FAILED';
+/** Args for {@link openDraftPr}. */
+export interface OpenDraftPrArgs {
+    /** The scenario name whose regression this PR addresses (branch slug). */
+    readonly scenario: string;
+    /** Path to a unified-diff file with the proposed fix. Resolved against {@link cwd}. */
+    readonly diffPath: string;
+    /** PR title. */
+    readonly title: string;
+    /** PR body markdown (the trailer is appended automatically). */
+    readonly body: string;
+    /**
+     * When `true`, actually cut the branch + open the draft PR. DEFAULT `false`
+     * (dry-run) — the loop is side-effect-free at egress unless `--execute` flows
+     * through to here.
+     *
+     * @defaultValue false
+     */
+    readonly execute?: boolean;
+    /** Working directory for path resolution + git ops. Defaults to {@link process.cwd}. */
+    readonly cwd?: string;
+    /** Injectable command runner (tests capture the shell-out). Defaults to {@link execFileSync}. */
+    readonly run?: CommandRunner;
+    /** Injectable timestamp source for the branch suffix (tests pin it). Defaults to now. */
+    readonly timestamp?: () => string;
+}
+/** Dry-run result — the planned steps, no side effects. */
+export interface DraftPrDryRun {
+    readonly kind: 'dry-run';
+    readonly scenario: string;
+    readonly branchName: string;
+    /** The planned shell steps; the `gh pr create` step includes `--draft`. */
+    readonly steps: readonly string[];
+}
+/** Live result — the opened draft PR. */
+export interface DraftPrOk {
+    readonly kind: 'ok';
+    readonly scenario: string;
+    readonly branchName: string;
+    /** The draft PR URL emitted by `gh pr create --draft`. */
+    readonly prUrl: string;
+}
+/** Failure result. */
+export interface DraftPrFailure {
+    readonly kind: 'error';
+    readonly code: DraftPrErrorCode;
+    readonly message: string;
+}
+/** Discriminated-union result of {@link openDraftPr}. */
+export type DraftPrResult = DraftPrDryRun | DraftPrOk | DraftPrFailure;
+/**
+ * Compute the feature branch name for a scenario's draft PR (ADR-065 feature
+ * branch — `feat/T11889-selfimprove-<scenario>-<ts>`). The timestamp is
+ * colon/dot-sanitized so it is a valid git ref.
+ *
+ * @param scenario - The scenario name.
+ * @param ts - The ISO timestamp string.
+ * @returns The branch name.
+ */
+export declare function draftPrBranchName(scenario: string, ts: string): string;
+/**
+ * Open ONE DRAFT PR carrying a proposed self-improvement fix.
+ *
+ * DRY-RUN by default ({@link OpenDraftPrArgs.execute} falsey): returns the planned
+ * `steps[]` (the `gh pr create` step ALWAYS carries `--draft`) WITHOUT touching
+ * git/gh — so the loop is egress-side-effect-free unless `--execute` is threaded
+ * through. The live path (`execute: true`) cuts the feature branch, applies the
+ * diff, commits, pushes the FEATURE branch (NEVER `main`), and runs
+ * `gh pr create --base main --head <branch> --draft`, returning the PR URL.
+ *
+ * NEVER pushes `main`, NEVER auto-merges, NEVER publishes — the only egress is a
+ * draft PR against a feature branch.
+ *
+ * @param args - See {@link OpenDraftPrArgs}.
+ * @returns A {@link DraftPrResult} describing the outcome.
+ *
+ * @example
+ * ```ts
+ * // dry-run (default): no side effects, steps include `--draft`
+ * const plan = await openDraftPr({ scenario: 'x', diffPath: 'fix.patch', title, body });
+ * // live: cuts branch + opens draft PR
+ * const res = await openDraftPr({ scenario: 'x', diffPath: 'fix.patch', title, body, execute: true });
+ * ```
+ */
+export declare function openDraftPr(args: OpenDraftPrArgs): Promise<DraftPrResult>;
+//# sourceMappingURL=draft-pr.d.ts.map

package/dist/selfimprove/draft-pr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"draft-pr.d.ts","sourceRoot":"","sources":["../../src/selfimprove/draft-pr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAeH;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,KAAK,MAAM,CAAC;AAM9E,8CAA8C;AAC9C,MAAM,MAAM,gBAAgB;AAC1B,yCAAyC;AACvC,aAAa;AACf,sCAAsC;GACpC,eAAe;AACjB,4CAA4C;GAC1C,kBAAkB;AACpB,gDAAgD;GAC9C,mBAAmB,CAAC;AAExB,oCAAoC;AACpC,MAAM,WAAW,eAAe;IAC9B,0EAA0E;IAC1E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uFAAuF;IACvF,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,gBAAgB;IAChB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,wFAAwF;IACxF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,iGAAiG;IACjG,QAAQ,CAAC,GAAG,CAAC,EAAE,aAAa,CAAC;IAC7B,yFAAyF;IACzF,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,MAAM,CAAC;CACnC;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED,yCAAyC;AACzC,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,sBAAsB;AACtB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,yDAAyD;AACzD,MAAM,MAAM,aAAa,GAAG,aAAa,GAAG,SAAS,GAAG,cAAc,CAAC;AAEvE;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAItE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,CAgF/E"}

package/dist/selfimprove/draft-pr.js

@@ -0,0 +1,158 @@
+/**
+ * Draft-PR egress for the self-improvement loop (T11889 · T11889-C).
+ *
+ * On a detected regression the loop's ONLY outbound action is to open ONE DRAFT
+ * PR against the cleocode repo (ADR-065 — PRs target `main` via the Merge Queue;
+ * NEVER a direct push to `main`, NEVER an auto-merge, NEVER a publish). This module
+ * is the egress primitive, modeled on `propose-patch.ts` (the closest "agent
+ * proposes a fix PR" exemplar) with three self-dogfooding hardenings:
+ *
+ *   1. **`--draft` is ALWAYS appended** to `gh pr create` — the PR is never
+ *      ready-for-merge; a human reviews and undrafts it.
+ *   2. **Dry-run is the DEFAULT.** `openDraftPr` returns the planned `steps[]`
+ *      WITHOUT invoking git/gh unless `execute: true` is passed. So the loop is
+ *      side-effect-free at egress by default.
+ *   3. **Branch `feat/T11889-selfimprove-<scenario>-<ts>`** — a feature branch
+ *      (ADR-065); no main mutation path exists in this module.
+ *
+ * The live path wraps the git/gh shell-out in
+ * {@link "../sentient/skill-provenance.js".withProvenance}`('pr-generator', …)`
+ * (the established legal PR-cutting origin — the `SkillWriteOrigin` union is
+ * closed) and returns the `gh`-emitted PR URL so the caller can record it back
+ * into `selfimprove_dhq.pr_url` via the leased adapter.
+ *
+ * This module is import-time side-effect-free.
+ *
+ * @module @cleocode/core/selfimprove/draft-pr
+ * @epic T11889
+ * @task T11913
+ */
+import { execFileSync } from 'node:child_process';
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { cwd as processCwd } from 'node:process';
+import { withProvenance } from '../sentient/skill-provenance.js';
+/**
+ * The required Claude Code trailer every self-improvement PR body ends with.
+ * Matches the project PR-body convention.
+ */
+const PR_BODY_TRAILER = '\n\n🤖 Generated with [Claude Code](https://claude.com/claude-code)';
+/** Default command runner — wraps `execFileSync` with stdout-piped semantics. */
+const defaultRun = (file, args) => execFileSync(file, [...args], { stdio: 'pipe' }).toString('utf8');
+/**
+ * Compute the feature branch name for a scenario's draft PR (ADR-065 feature
+ * branch — `feat/T11889-selfimprove-<scenario>-<ts>`). The timestamp is
+ * colon/dot-sanitized so it is a valid git ref.
+ *
+ * @param scenario - The scenario name.
+ * @param ts - The ISO timestamp string.
+ * @returns The branch name.
+ */
+export function draftPrBranchName(scenario, ts) {
+    const safeScenario = scenario.replace(/[^a-z0-9-]/gi, '-');
+    const safeTs = ts.replace(/[:.]/g, '-');
+    return `feat/T11889-selfimprove-${safeScenario}-${safeTs}`;
+}
+/**
+ * Open ONE DRAFT PR carrying a proposed self-improvement fix.
+ *
+ * DRY-RUN by default ({@link OpenDraftPrArgs.execute} falsey): returns the planned
+ * `steps[]` (the `gh pr create` step ALWAYS carries `--draft`) WITHOUT touching
+ * git/gh — so the loop is egress-side-effect-free unless `--execute` is threaded
+ * through. The live path (`execute: true`) cuts the feature branch, applies the
+ * diff, commits, pushes the FEATURE branch (NEVER `main`), and runs
+ * `gh pr create --base main --head <branch> --draft`, returning the PR URL.
+ *
+ * NEVER pushes `main`, NEVER auto-merges, NEVER publishes — the only egress is a
+ * draft PR against a feature branch.
+ *
+ * @param args - See {@link OpenDraftPrArgs}.
+ * @returns A {@link DraftPrResult} describing the outcome.
+ *
+ * @example
+ * ```ts
+ * // dry-run (default): no side effects, steps include `--draft`
+ * const plan = await openDraftPr({ scenario: 'x', diffPath: 'fix.patch', title, body });
+ * // live: cuts branch + opens draft PR
+ * const res = await openDraftPr({ scenario: 'x', diffPath: 'fix.patch', title, body, execute: true });
+ * ```
+ */
+export async function openDraftPr(args) {
+    const cwd = args.cwd ?? processCwd();
+    const run = args.run ?? defaultRun;
+    const execute = args.execute === true;
+    const isoNow = (args.timestamp ?? (() => new Date().toISOString()))();
+    const base = 'main';
+    const body = `${args.body}${PR_BODY_TRAILER}`;
+    const resolvedDiff = resolvePath(cwd, args.diffPath);
+    if (!existsSync(resolvedDiff)) {
+        return {
+            kind: 'error',
+            code: 'E_NOT_FOUND',
+            message: `Patch file not found at '${resolvedDiff}'`,
+        };
+    }
+    const diffBytes = readFileSync(resolvedDiff, 'utf8');
+    if (diffBytes.length === 0) {
+        return {
+            kind: 'error',
+            code: 'E_PATCH_EMPTY',
+            message: `Patch file '${resolvedDiff}' is empty`,
+        };
+    }
+    if (execute) {
+        try {
+            run('gh', ['--version']);
+        }
+        catch {
+            return {
+                kind: 'error',
+                code: 'E_GH_UNAVAILABLE',
+                message: 'gh CLI not found or not authenticated — install gh and run `gh auth login`',
+            };
+        }
+    }
+    const branchName = draftPrBranchName(args.scenario, isoNow);
+    const steps = [
+        `git checkout -b ${branchName}`,
+        `git apply ${resolvedDiff}`,
+        'git add -A',
+        `git commit -m "fix(selfimprove): ${args.scenario} regression"`,
+        `git push -u origin ${branchName}`,
+        `gh pr create --base ${base} --head ${branchName} --draft --title "${args.title}" --body <stdin>`,
+    ];
+    if (!execute) {
+        return { kind: 'dry-run', scenario: args.scenario, branchName, steps };
+    }
+    try {
+        const prUrl = await withProvenance('pr-generator', () => {
+            run('git', ['checkout', '-b', branchName]);
+            run('git', ['apply', resolvedDiff]);
+            run('git', ['add', '-A']);
+            run('git', ['commit', '-m', `fix(selfimprove): ${args.scenario} regression`]);
+            run('git', ['push', '-u', 'origin', branchName]);
+            return run('gh', [
+                'pr',
+                'create',
+                '--base',
+                base,
+                '--head',
+                branchName,
+                '--draft',
+                '--title',
+                args.title,
+                '--body',
+                body,
+            ]).trim();
+        });
+        return { kind: 'ok', scenario: args.scenario, branchName, prUrl };
+    }
+    catch (err) {
+        return {
+            kind: 'error',
+            code: 'E_DRAFT_PR_FAILED',
+            message: `draft-pr failed: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+//# sourceMappingURL=draft-pr.js.map

package/dist/selfimprove/draft-pr.js.map

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