@cleocode/core 2026.5.131 → 2026.5.132

package/dist/verification/verify-tools.js

@@ -0,0 +1,236 @@
+/**
+ * Core verification helpers: verifyTypes + verifyRuntimeBoot.
+ *
+ * These two functions are the canonical agent-facing evidence-gathering tools
+ * for type-safety and runtime-boot validation in the CLEO monorepo.
+ *
+ * ## `verifyTypes`
+ *
+ * Runs `tsc -b` (the project-reference composite build — the real
+ * cross-package type oracle). Per-package `pnpm build` FALSE-passes
+ * cross-package type breaks because esbuild transpiles without checking;
+ * only `tsc -b` exercises the full type graph.
+ *
+ * ## `verifyRuntimeBoot`
+ *
+ * Performs a cold boot sequence:
+ *   1. `node build.mjs` — rebuilds the CLI bundle from source.
+ *   2. `node packages/cleo/dist/cli/index.js version` — smoke-boots the
+ *      CLI and asserts it exits cleanly.
+ *
+ * This catches circular-import TDZ (temporal dead-zone) errors that are
+ * invisible to both `tsc` and Biome because they are runtime-only
+ * phenomena produced by ESM module evaluation order.
+ *
+ * ## Return contract
+ *
+ * Both functions return a {@link VerifyResult} with a discriminated
+ * `passed` boolean, `durationMs`, and captured `stdout` / `stderr` tails
+ * for actionable diagnostics.  Callers MUST check `passed` before treating
+ * the output as valid.
+ *
+ * ## Regression tests captured
+ *
+ * - `verifyTypes`: dual-ORM-instance type break (two `drizzle-orm` versions
+ *   resolve to different instances — tsc catches the shape mismatch; build passes).
+ * - `verifyRuntimeBoot`: leaf-hoist TDZ (circular dep between a leaf package
+ *   and a re-exported barrel causes the CLI to throw at startup; invisible to tsc).
+ *
+ * @task T11488
+ * @see packages/core/src/tasks/tool-cache.ts — runToolCached (evidence caching layer)
+ */
+import { spawn } from 'node:child_process';
+import { resolveOrCwd } from '../paths.js';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/** Maximum bytes retained from a child stream. */
+const DEFAULT_TAIL_BYTES = 4096;
+/**
+ * Minimal ring-buffer that retains the last `cap` bytes of appended data.
+ *
+ * @internal
+ */
+class TailBuffer {
+    cap;
+    chunks = [];
+    size = 0;
+    constructor(cap) {
+        this.cap = cap;
+    }
+    append(chunk) {
+        this.chunks.push(chunk);
+        this.size += chunk.length;
+        // Trim from the front when we overflow the cap.
+        while (this.size > this.cap && this.chunks.length > 0) {
+            const front = this.chunks[0];
+            if (this.size - front.length >= this.cap) {
+                this.size -= front.length;
+                this.chunks.shift();
+            }
+            else {
+                break;
+            }
+        }
+    }
+    toString() {
+        return Buffer.concat(this.chunks, this.size).toString('utf-8');
+    }
+}
+/**
+ * Spawn a command and collect stdout / stderr tails.
+ *
+ * @param cmd   - Executable name.
+ * @param args  - Argument list.
+ * @param cwd   - Working directory.
+ * @param step  - Human-readable label for the {@link VerifyResult}.
+ * @param opts  - Tail and timeout options.
+ *
+ * @internal
+ */
+async function runStep(cmd, args, cwd, step, opts) {
+    const startMs = Date.now();
+    const { tailBytes, timeoutMs } = opts;
+    return new Promise((resolve) => {
+        const stdoutBuf = new TailBuffer(tailBytes);
+        const stderrBuf = new TailBuffer(tailBytes);
+        const child = spawn(cmd, args, {
+            cwd,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: process.env,
+        });
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGTERM');
+        }, timeoutMs);
+        child.stdout?.on('data', (d) => {
+            stdoutBuf.append(d);
+        });
+        child.stderr?.on('data', (d) => {
+            stderrBuf.append(d);
+        });
+        child.on('error', () => {
+            clearTimeout(timer);
+            resolve({
+                passed: false,
+                exitCode: null,
+                stdout: stdoutBuf.toString(),
+                stderr: stderrBuf.toString(),
+                durationMs: Date.now() - startMs,
+                step,
+            });
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            const exitCode = timedOut ? null : code;
+            resolve({
+                passed: exitCode === 0,
+                exitCode,
+                stdout: stdoutBuf.toString(),
+                stderr: stderrBuf.toString(),
+                durationMs: Date.now() - startMs,
+                step: timedOut ? `${step} [timed out after ${timeoutMs}ms]` : step,
+            });
+        });
+    });
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Run `tsc -b` — the cross-package TypeScript type oracle.
+ *
+ * Per-package `pnpm build` compiles via esbuild (transpile-only) and
+ * therefore passes silently when cross-package type breaks exist.  Only
+ * `tsc -b` exercises the full composite project-reference graph.
+ *
+ * Returns a {@link VerifyResult} with `passed: true` iff `tsc` exits with
+ * code 0 (no type errors).
+ *
+ * @param opts - Optional cwd, tail size, and timeout overrides.
+ * @returns Structured pass/fail result with diagnostic output.
+ *
+ * @example
+ * ```ts
+ * const result = await verifyTypes({ cwd: '/path/to/monorepo' });
+ * if (!result.passed) {
+ *   console.error('Type errors found:', result.stderr);
+ * }
+ * ```
+ *
+ * @task T11488
+ */
+export async function verifyTypes(opts = {}) {
+    const cwd = resolveOrCwd(opts.cwd);
+    const tailBytes = opts.tailBytes ?? DEFAULT_TAIL_BYTES;
+    const timeoutMs = opts.timeoutMs ?? 300_000;
+    return runStep('node', ['node_modules/.bin/tsc', '-b'], cwd, 'tsc -b', {
+        tailBytes,
+        timeoutMs,
+    });
+}
+/**
+ * Run a cold monorepo build + CLI boot smoke.
+ *
+ * Performs two sequential steps:
+ *
+ * 1. **Build**: `node build.mjs` — rebuilds the CLI bundle from source
+ *    (catches bundler/esbuild-level issues).
+ * 2. **CLI smoke**: `node packages/cleo/dist/cli/index.js version` — boots
+ *    the CLI and asserts a clean exit (catches circular-import TDZ errors
+ *    that are invisible to the type checker).
+ *
+ * The CLI smoke step is skipped when the build step fails (there is no
+ * artefact to boot).
+ *
+ * Returns a {@link RuntimeBootResult} with `passed: true` iff BOTH steps
+ * exit with code 0.
+ *
+ * @param opts - Optional cwd, tail size, and timeout overrides.
+ * @returns Structured result containing per-step diagnostics.
+ *
+ * @example
+ * ```ts
+ * const result = await verifyRuntimeBoot({ cwd: '/path/to/monorepo' });
+ * if (!result.passed) {
+ *   if (!result.buildStep.passed) {
+ *     console.error('Build failed:', result.buildStep.stderr);
+ *   } else {
+ *     console.error('CLI boot failed:', result.cliSmokeStep.stderr);
+ *   }
+ * }
+ * ```
+ *
+ * @task T11488
+ */
+export async function verifyRuntimeBoot(opts = {}) {
+    const cwd = resolveOrCwd(opts.cwd);
+    const tailBytes = opts.tailBytes ?? DEFAULT_TAIL_BYTES;
+    const timeoutMs = opts.timeoutMs ?? 120_000;
+    // Step 1: rebuild the CLI bundle.
+    const buildStep = await runStep('node', ['build.mjs'], cwd, 'node build.mjs', {
+        tailBytes,
+        timeoutMs,
+    });
+    if (!buildStep.passed) {
+        // Skip the smoke step when build fails — there is nothing to boot.
+        const cliSmokeStep = {
+            passed: false,
+            exitCode: null,
+            stdout: '',
+            stderr: 'Skipped: build step failed.',
+            durationMs: 0,
+            step: 'node packages/cleo/dist/cli/index.js version [skipped]',
+        };
+        return { passed: false, buildStep, cliSmokeStep };
+    }
+    // Step 2: cold-boot CLI and assert `version` exits cleanly.
+    const cliSmokeStep = await runStep('node', ['packages/cleo/dist/cli/index.js', 'version'], cwd, 'node packages/cleo/dist/cli/index.js version', { tailBytes, timeoutMs });
+    return {
+        passed: cliSmokeStep.passed,
+        buildStep,
+        cliSmokeStep,
+    };
+}
+//# sourceMappingURL=verify-tools.js.map

package/dist/verification/verify-tools.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cleocode/core",
-  "version": "2026.5.131",
+  "version": "2026.5.132",
   "description": "CLEO core business logic kernel — tasks, sessions, memory, orchestration, lifecycle, with bundled SQLite store",
   "type": "module",
   "main": "./dist/index.js",
@@ -121,6 +121,11 @@
       "import": "./dist/gc/index.js",
       "require": "./dist/gc/index.js"
     },
+    "./db": {
+      "types": "./dist/db/index.d.ts",
+      "import": "./dist/db/index.js",
+      "require": "./dist/db/index.js"
+    },
     "./doctor": {
       "types": "./dist/doctor/index.d.ts",
       "import": "./dist/doctor/index.js",
@@ -394,16 +399,16 @@
     "write-file-atomic": "^7.0.1",
     "yaml": "^2.8.3",
     "zod": "^4.3.6",
-    "@cleocode/adapters": "2026.5.131",
-    "@cleocode/agents": "2026.5.131",
-    "@cleocode/contracts": "2026.5.131",
-    "@cleocode/caamp": "2026.5.131",
-    "@cleocode/lafs": "2026.5.131",
-    "@cleocode/nexus": "2026.5.131",
-    "@cleocode/paths": "2026.5.131",
-    "@cleocode/skills": "2026.5.131",
+    "@cleocode/adapters": "2026.5.132",
+    "@cleocode/agents": "2026.5.132",
+    "@cleocode/caamp": "2026.5.132",
+    "@cleocode/contracts": "2026.5.132",
+    "@cleocode/lafs": "2026.5.132",
+    "@cleocode/nexus": "2026.5.132",
+    "@cleocode/paths": "2026.5.132",
+    "@cleocode/skills": "2026.5.132",
     "@cleocode/utils": "2026.5.122",
-    "@cleocode/worktree": "2026.5.131"
+    "@cleocode/worktree": "2026.5.132"
   },
   "engines": {
     "node": ">=24.16.0"
@@ -435,7 +440,7 @@
   },
   "optionalDependencies": {
     "llmtxt": "^2026.5.15",
-    "@cleocode/studio": "^2026.5.131"
+    "@cleocode/studio": "^2026.5.132"
   },
   "scripts": {
     "build": "tsc",

package/templates/CLEO-INJECTION.md

@@ -285,7 +285,8 @@ cleo verify T### --gate testsPassed --evidence "tool:test"
 # qaPassed — lint + typecheck
 cleo verify T### --gate qaPassed --evidence "tool:lint;tool:typecheck"
 
-# retroactive PR atom (PR MERGED + CI green) satisfies testsPassed AND qaPassed
+# retroactive PR atom (PR MERGED + CI green) satisfies implemented + testsPassed + qaPassed
+cleo verify T### --gate implemented --evidence "pr:357"
 cleo verify T### --gate testsPassed --evidence "pr:357"
 cleo verify T### --gate qaPassed --evidence "pr:357"
 
@@ -325,7 +326,7 @@ All overrides append a line to `.cleo/audit/force-bypass.jsonl`. Use sparingly.
 
 ### `pr:<number>` retroactive atom (T9764)
 
-Accepts IFF PR `state=MERGED` AND required-workflow checks are `SUCCESS`/`SKIPPED`. Single atom satisfies BOTH `testsPassed` + `qaPassed`. Cache under `.cleo/cache/evidence/pr-<num>.json`.
+Accepts IFF PR `state=MERGED` AND required-workflow checks are `SUCCESS`/`SKIPPED`. Single atom satisfies `implemented` + `testsPassed` + `qaPassed` simultaneously (T9838). Cache under `.cleo/cache/evidence/pr-<num>.json`.
 
 ### Anti-patterns to avoid
 

package/templates/workflows/release-prepare.yml.tmpl

@@ -50,6 +50,11 @@ on:
           - beta
           - alpha
           - rc
+      skip-tests:
+        description: 'Skip the full test suite in Preflight (use when main CI is already green — avoids the 10min+ timeout). Lint and typecheck still run.'
+        type: boolean
+        required: false
+        default: false
 
 # R-202: contents:write (commit + branch), pull-requests:write (gh pr create),
 # id-token:write (signed tags only). MUST NOT request packages:write — npm
@@ -73,10 +78,17 @@ defaults:
 jobs:
   # R-204: lint + typecheck + test + build BEFORE any commit. Failure here
   # MUST fail the workflow and prevent `prepare` from running.
-  preflight:
-    name: Preflight (lint + typecheck + test + build)
+  #
+  # T11490 — DHQ-042: the full unsharded test suite can exceed 10 min and
+  # time out the preflight. Two mitigations:
+  #   (a) `skip-tests` input (default false) — when the caller knows main CI
+  #       is already green, tests can be skipped to avoid the redundant run.
+  #   (b) The test step is sharded across 2 parallel matrix workers, keeping
+  #       each shard under 10 min even without skipping.
+  preflight-lint-typecheck:
+    name: Preflight (lint + typecheck)
     runs-on: ubuntu-latest
-    timeout-minutes: 20
+    timeout-minutes: 15
     steps:
       # R-263: third-party Actions pinned to major+minor.
       - name: Checkout
@@ -107,10 +119,68 @@ jobs:
         run: {{TYPECHECK_CMD}}
         timeout-minutes: 5
 
-      - name: Test
-        run: {{TEST_CMD}}
+  # T11490 — DHQ-042: test shards run in parallel to stay under 10 min.
+  # Skipped when skip-tests=true (e.g. dispatched after a green main CI).
+  preflight-test:
+    name: Preflight (test shard ${{ matrix.shard }}/2)
+    if: ${{ inputs.skip-tests != true }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    strategy:
+      fail-fast: true
+      matrix:
+        shard: [1, 2]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+        timeout-minutes: 5
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+        timeout-minutes: 2
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '{{NODE_VERSION}}'
+        timeout-minutes: 3
+
+      - name: Install dependencies
+        run: {{INSTALL_CMD}}
+        timeout-minutes: 5
+
+      - name: Test (shard ${{ matrix.shard }}/2)
+        run: pnpm exec vitest run --shard=${{ matrix.shard }}/2
         timeout-minutes: 10
 
+  preflight-build:
+    name: Preflight (build)
+    runs-on: ubuntu-latest
+    needs: [preflight-lint-typecheck]
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+        timeout-minutes: 5
+
+      - name: Set up pnpm
+        uses: pnpm/action-setup@v4
+        timeout-minutes: 2
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '{{NODE_VERSION}}'
+        timeout-minutes: 3
+
+      - name: Install dependencies
+        run: {{INSTALL_CMD}}
+        timeout-minutes: 5
+
       - name: Build
         run: {{BUILD_CMD}}
         timeout-minutes: 10
@@ -121,10 +191,17 @@ jobs:
 
   # R-203: prepare needs preflight.
   # R-205: plan resolution → version bump → CHANGELOG → commit → push → bump-PR.
+  # T11490: needs both lint/typecheck and build to pass; test shards are
+  # independent (always() used so prepare can run even when tests are skipped).
   prepare:
     name: Prepare bump-PR
     runs-on: ubuntu-latest
-    needs: preflight
+    needs: [preflight-lint-typecheck, preflight-test, preflight-build]
+    if: |
+      always() &&
+      needs.preflight-lint-typecheck.result == 'success' &&
+      needs.preflight-build.result == 'success' &&
+      (needs.preflight-test.result == 'success' || needs.preflight-test.result == 'skipped')
     timeout-minutes: 20
     outputs:
       branch: ${{ steps.branch.outputs.name }}
@@ -263,7 +340,9 @@ jobs:
     name: Cleanup on failure
     runs-on: ubuntu-latest
     needs:
-      - preflight
+      - preflight-lint-typecheck
+      - preflight-test
+      - preflight-build
       - prepare
     if: failure()
     timeout-minutes: 10