@cleocode/core 2026.10.27 → 2026.11.1-canary.3

package/dist/release/ci-run-evidence.js

@@ -0,0 +1,234 @@
+/**
+ * `ci-run:<runId>` evidence (T14149): a green run of
+ * `.github/workflows/repeat-run.yml`, which runs one test file N times on the
+ * default branch. It replaces the owner AC waiver for criteria that need a
+ * heavy or repeated run the owner rule forbids locally.
+ *
+ * Validated only from GitHub, never from a file the agent supplies:
+ *
+ * - the run is this workflow, dispatched (`workflow_dispatch`) on the
+ *   repository's default branch, and its latest attempt concluded `success`;
+ * - its title names the test file and run count, and the run's uploaded
+ *   `repeat-report` artifact agrees: the same file, count and commit, every
+ *   run green (GitHub does not return dispatch inputs on the run);
+ * - the test file is relevant: one the task changed, or one a criterion this
+ *   write links names (by path or file name), so a trivial test repeated N
+ *   times cannot stand for an unrelated criterion.
+ *
+ * That the run's commit contains the task's implemented work is checked with
+ * the other bound runs (`boundHeadGapReason`). `cleo complete` re-reads the
+ * run, and a newer attempt that is not green refuses it.
+ *
+ * @task T14149
+ */
+import { execFileSync } from 'node:child_process';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+/** The workflow whose runs `ci-run:` accepts. */
+export const REPEAT_RUN_WORKFLOW = '.github/workflows/repeat-run.yml';
+/** The artifact the workflow uploads. */
+export const REPEAT_RUN_ARTIFACT = 'repeat-report';
+/** `repeat-run <test> x<N>`, the workflow's `run-name`. */
+const TITLE = /^repeat-run (\S+) x([0-9]+)$/;
+/** Whether `record` is a finished, green run of the repeat-run workflow on the default branch. */
+function runRefusal(runId, record) {
+    const refuse = (reason, codeName = 'E_EVIDENCE_INVALID') => ({
+        ok: false,
+        reason: `ci-run:${runId} ${reason}`,
+        codeName,
+    });
+    if (record.path.replace(/@.*$/, '') !== REPEAT_RUN_WORKFLOW)
+        return refuse(`is a run of ${record.path}, not ${REPEAT_RUN_WORKFLOW}`);
+    if (record.event !== 'workflow_dispatch')
+        return refuse(`was started by ${record.event}, not a workflow_dispatch`);
+    if (record.headBranch !== record.defaultBranch)
+        return refuse(`ran on ${record.headBranch}, not the default branch ${record.defaultBranch}; dispatch it on ${record.defaultBranch}`);
+    if (record.status !== 'completed')
+        return refuse(`is still ${record.status}; wait for it to finish, then verify again`);
+    if (record.conclusion !== 'success')
+        return refuse(`attempt ${record.attempt} concluded ${record.conclusion ?? 'with no conclusion'}, not success`, 
+        // @sync-invariant none:input-shape a red repeat-run is refused before anything is written
+        'E_EVIDENCE_TESTS_FAILED');
+    return null;
+}
+/**
+ * Validate a `ci-run:<runId>` atom for a task (T14149).
+ *
+ * @param runId - The GitHub Actions run id.
+ * @param roots - The evidence roots; `gh` runs in the execution root.
+ * @param options - Task context and injected fetchers.
+ * @returns The validated atom, or why it is refused.
+ * @task T14149
+ */
+export async function resolveCiRunEvidenceAtom(runId, roots, options) {
+    const cwd = roots.executionRoot;
+    const record = (options.fetchRun ?? defaultFetchRun)(runId, cwd);
+    if (record === null)
+        return {
+            ok: false,
+            reason: `ci-run:${runId} cannot be read from GitHub (gh api actions/runs/${runId} failed)`,
+            codeName: 'E_EVIDENCE_INVALID',
+        };
+    const refused = runRefusal(runId, record);
+    if (refused)
+        return refused;
+    const title = TITLE.exec(record.displayTitle);
+    if (!title)
+        return {
+            ok: false,
+            reason: `ci-run:${runId}'s title "${record.displayTitle}" does not name a test file and run count`,
+            codeName: 'E_EVIDENCE_INVALID',
+        };
+    const test = title[1];
+    const runs = Number(title[2]);
+    // GitHub does not return dispatch inputs on a run, so the title is
+    // cross-checked against what the job itself recorded.
+    const report = (options.fetchReport ?? defaultFetchReport)(runId, cwd);
+    if (report === null)
+        return {
+            ok: false,
+            reason: `ci-run:${runId} has no readable ${REPEAT_RUN_ARTIFACT} artifact (expired, or the job uploaded none), so its counts cannot be checked`,
+            codeName: 'E_EVIDENCE_INVALID',
+        };
+    const mismatch = report.test !== test
+        ? `its report ran ${report.test}, but its title names ${test}`
+        : report.runs !== runs
+            ? `its report asked for ${report.runs} runs, but its title names ${runs}`
+            : report.sha !== record.headSha
+                ? `its report tested ${report.sha ?? 'an unknown commit'}, not the run's commit ${record.headSha}`
+                : report.iterations.length !== runs
+                    ? `its report records ${report.iterations.length} runs, not ${runs}`
+                    : null;
+    if (mismatch)
+        return { ok: false, reason: `ci-run:${runId}: ${mismatch}`, codeName: 'E_EVIDENCE_INVALID' };
+    const bad = report.iterations.find((i) => i.exitCode !== 0 || i.numFailedTests > 0 || i.numPassedTests === 0);
+    if (bad)
+        return {
+            ok: false,
+            reason: `ci-run:${runId}: run ${bad.run} of ${runs} did not pass (exit ${bad.exitCode}, ${bad.numFailedTests} failed, ${bad.numPassedTests} passed)`,
+            // @sync-invariant none:input-shape a red repeat-run is refused before anything is written
+            codeName: 'E_EVIDENCE_TESTS_FAILED',
+        };
+    // Relevance: the repeated file is part of the task's change, or a linked
+    // criterion names it.
+    const changed = options.changedPaths.map((p) => p.replace(/^\.\//, ''));
+    const named = options.criteriaTexts.some((text) => text.includes(test) || text.includes(basename(test)));
+    if (!changed.includes(test) && !named)
+        return {
+            ok: false,
+            reason: `ci-run:${runId} repeated ${test}, which ${options.taskId} did not change and no criterion ` +
+                `this write links (satisfies:${options.taskId}#AC<n>) names. Repeat the test that proves the ` +
+                'criterion, or name its file in the criterion.',
+            codeName: 'E_EVIDENCE_INSUFFICIENT',
+        };
+    return {
+        ok: true,
+        atom: {
+            kind: 'ci-run',
+            runId,
+            headSha: record.headSha,
+            test,
+            runs,
+            attempt: record.attempt,
+            workflow: REPEAT_RUN_WORKFLOW,
+            taskId: options.taskId,
+        },
+    };
+}
+/**
+ * Re-check a recorded `ci-run:` atom at `cleo complete` (T14149): the run's
+ * latest attempt must still be a green run of the workflow on the default
+ * branch, at the same commit. A re-run that went red refuses.
+ *
+ * @param atom - The recorded atom.
+ * @param cwd - Repository work tree for `gh`.
+ * @param fetchRun - The run's record; defaults to the GitHub REST API.
+ * @returns Ok, or why the atom no longer stands.
+ * @task T14149
+ */
+export function recheckCiRunAtom(atom, cwd, fetchRun = defaultFetchRun) {
+    const record = fetchRun(atom.runId, cwd);
+    if (record === null)
+        return { ok: false, reason: `ci-run:${atom.runId} cannot be re-read from GitHub` };
+    const refused = runRefusal(atom.runId, record);
+    if (refused)
+        return { ok: false, reason: refused.reason };
+    if (record.headSha !== atom.headSha)
+        return {
+            ok: false,
+            reason: `ci-run:${atom.runId} now reports commit ${record.headSha}, not the recorded ${atom.headSha}`,
+        };
+    return { ok: true };
+}
+/** Run one `gh` command and parse its JSON output; null on any failure. */
+function ghJson(args, cwd) {
+    try {
+        return JSON.parse(execFileSync('gh', args, {
+            cwd,
+            encoding: 'utf-8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+            timeout: 30_000,
+        }));
+    }
+    catch {
+        return null;
+    }
+}
+/** Default {@link ResolveCiRunOptions.fetchRun}: `gh api repos/{owner}/{repo}/actions/runs/<id>`. */
+function defaultFetchRun(runId, cwd) {
+    const run = ghJson(['api', `repos/{owner}/{repo}/actions/runs/${runId}`], cwd);
+    if (run === null || typeof run !== 'object')
+        return null;
+    const repository = run.repository;
+    const str = (v) => (typeof v === 'string' ? v : '');
+    return {
+        path: str(run.path),
+        event: str(run.event),
+        headBranch: str(run.head_branch),
+        headSha: str(run.head_sha),
+        status: str(run.status),
+        conclusion: typeof run.conclusion === 'string' ? run.conclusion : null,
+        attempt: typeof run.run_attempt === 'number' ? run.run_attempt : 1,
+        displayTitle: str(run.display_title),
+        defaultBranch: str(repository?.default_branch),
+    };
+}
+/** Default {@link ResolveCiRunOptions.fetchReport}: `gh run download <id> -n repeat-report`. */
+function defaultFetchReport(runId, cwd) {
+    const dir = mkdtempSync(join(tmpdir(), 'cleo-ci-run-'));
+    try {
+        execFileSync('gh', ['run', 'download', String(runId), '-n', REPEAT_RUN_ARTIFACT, '-D', dir], {
+            cwd,
+            stdio: 'ignore',
+            timeout: 60_000,
+        });
+        const parsed = JSON.parse(readFileSync(join(dir, 'repeat-report.json'), 'utf-8'));
+        if (parsed === null || typeof parsed !== 'object')
+            return null;
+        const r = parsed;
+        if (typeof r.test !== 'string' || typeof r.runs !== 'number' || !Array.isArray(r.iterations))
+            return null;
+        return {
+            test: r.test,
+            runs: r.runs,
+            sha: typeof r.sha === 'string' ? r.sha : null,
+            iterations: r.iterations.map((raw) => {
+                const i = (raw ?? {});
+                return {
+                    run: typeof i.run === 'number' ? i.run : 0,
+                    exitCode: typeof i.exitCode === 'number' ? i.exitCode : null,
+                    numPassedTests: typeof i.numPassedTests === 'number' ? i.numPassedTests : 0,
+                    numFailedTests: typeof i.numFailedTests === 'number' ? i.numFailedTests : 0,
+                };
+            }),
+        };
+    }
+    catch {
+        return null;
+    }
+    finally {
+        rmSync(dir, { recursive: true, force: true });
+    }
+}
+//# sourceMappingURL=ci-run-evidence.js.map

package/dist/release/ci-run-evidence.js.map

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

package/dist/release/cut.d.ts

@@ -0,0 +1,231 @@
+/**
+ * `cleo release cut <version>` — one-command release from the default branch's
+ * newest commit with green CI (T14102 · epic T14099 · owner decision D11209).
+ *
+ * Replaces plan → open → bump-PR → hand-pushed tag. The cut:
+ *   1. validates the CalVer version (strictly above every release tag and the
+ *      default branch's package.json), then picks the newest first-parent
+ *      commit of `origin/<default>` whose required checks
+ *      (`release.prRequiredWorkflows`, app-pinned) all concluded `success` on
+ *      its push run (an empty conclusion is not green), or verifies a pinned
+ *      `--sha` the same way;
+ *   2. renders the notes from the changesets added since the previous release
+ *      tag, refusing a changeset no merged pull request brought in;
+ *   3. reports the packages, new migrations and each named task's status
+ *      (reported, never gated: green CI on the sha is the gate);
+ *   4. creates the annotated tag `v<version>` on that sha through the GitHub
+ *      API. Its message carries the hand-written lead (`--lead`). The tag push
+ *      starts `release.yml`, which writes the CHANGELOG section
+ *      ({@link releaseChangelog}), publishes, and opens the CHANGELOG + version
+ *      PR. No test suite reruns: CI already passed that tree.
+ *
+ * @task T14102
+ * @epic T14099
+ */
+import type { EngineResult } from '@cleocode/contracts';
+import type { MergeSweepOptions, MergeSweepResult } from '@cleocode/contracts/merge-close.js';
+import type { DocsRotResult } from '@cleocode/contracts/operations/docs.js';
+import type { MergedCleanupOpts, MergedCleanupResult } from '@cleocode/contracts/operations/worktree.js';
+/** How many first-parent commits of the default branch the cut inspects for green CI. */
+export declare const CUT_MAX_CANDIDATES = 30;
+/** Per-cut audit log (ADR-099 §Consequences), relative to the project root. */
+export declare const RELEASE_CUT_AUDIT_FILE = ".cleo/audit/release-cut.jsonl";
+/** Subprocess runners, injectable for tests. */
+export interface ReleaseCutRunner {
+    /** Run `gh <args>` in `cwd`; returns trimmed stdout, throws on failure. */
+    runGh: (args: readonly string[], cwd: string) => string;
+    /** Run `git <args>` in `cwd`; returns stdout, throws on failure. */
+    runGit: (args: readonly string[], cwd: string) => string;
+}
+/** Options for {@link releaseCut}. */
+export interface ReleaseCutOptions {
+    /** Version to release (`2026.10.28` or `v2026.10.28`). */
+    version: string;
+    /** Project whose task store, audit and grants the cut uses. */
+    projectRoot: string;
+    /**
+     * The git checkout the cut runs in (T14160): every git and gh call, the
+     * docs-rot scan and `checkoutAtMain` use it, and no other checkout is
+     * touched. Default: `projectRoot`.
+     */
+    gitRoot?: string;
+    /** Pin the commit instead of picking the newest green one; it must itself be green. */
+    sha?: string;
+    /** Markdown file whose content leads the notes ("Update now" + Highlights). */
+    leadFile?: string;
+    /** Show the commit, notes, packages and tasks without creating the tag. */
+    dryRun?: boolean;
+    /**
+     * Confirm the tag (D11212). Without it the cut only reports, with the exact
+     * confirm command. With it, a standing release authorization (T14141), the
+     * `release.agentCut` setting (D11221) or the
+     * version typed on the controlling terminal (`/dev/tty`) allows the tag.
+     */
+    yes?: boolean;
+    /** Default branch name (default `main`). */
+    branch?: string;
+    /** Test seam for the T14142 merged-work cleanup (default {@link cleanupMergedWork}). */
+    cleanup?: (opts: MergedCleanupOpts) => Promise<MergedCleanupResult>;
+    /** Test seam for the T14101 merge sweep (default {@link sweepMergedClosures}). */
+    sweep?: (projectRoot: string, opts: MergeSweepOptions) => Promise<MergeSweepResult>;
+    /** Test seam. */
+    runner?: ReleaseCutRunner;
+}
+/** CI state of one candidate commit. */
+export interface ReleaseCutCandidate {
+    /** Commit sha. */
+    sha: string;
+    /** `success`, or the first required check that is not: `<name>: <state>`. */
+    ci: string;
+}
+/** One task a changeset in range names, with its status at cut time. */
+export interface ReleaseCutTask {
+    /** Task id. */
+    id: string;
+    /** Store status, or `missing` when the task is not in this store. */
+    status: string;
+}
+/** A published package and the version it ships at. */
+export interface ReleaseCutPackage {
+    /** Directory under `packages/`. */
+    dir: string;
+    /** npm name. */
+    name: string;
+    /** Version it publishes at. */
+    version: string;
+}
+/** Result of {@link releaseCut}. */
+export interface ReleaseCutResult {
+    /** `v`-prefixed version. */
+    version: string;
+    /** Tag name (`v<version>`). */
+    tag: string;
+    /** Commit the release is cut from. */
+    sha: string;
+    /** Previous release tag the notes are computed from, or null for a first release. */
+    previousTag: string | null;
+    /** Commits checked for green CI, newest first, up to the chosen one. */
+    candidates: ReleaseCutCandidate[];
+    /** Changeset files in range. */
+    changesets: string[];
+    /** The rendered notes (lead first, then the generated sections). */
+    notes: string;
+    /** Packages `release.yml` publishes, at this version. */
+    packages: ReleaseCutPackage[];
+    /** Migration files added since the previous tag. */
+    migrations: string[];
+    /** Tasks the changesets name, with status (reported, not gated). */
+    tasks: ReleaseCutTask[];
+    /**
+     * T14142 cleanup of the release's tasks: the plan on a report run, what was
+     * removed after a confirmed tag. Besides the tasks' worktrees and `task/*`
+     * branches it removes nested repository copies proven redundant (clean, every
+     * ref on origin), only inside the worktrees of the release's done or
+     * cancelled tasks. Null when the changesets name no task.
+     */
+    cleanup: MergedCleanupResult | null;
+    /** The T14101 merge sweep run before the commit was picked (`swept: false` when it could not run). */
+    sweep: MergeSweepResult;
+    /** Docs rot of the project checkout (T14111); a real cut refuses when it has findings. */
+    docsRot: DocsRotResult;
+    /** Non-blocking findings, e.g. docs rot on a prerelease (it blocks only a stable cut). */
+    warnings: string[];
+    /** Whether the local checkout is at `origin/<default>` (the docs-rot scan reads it). */
+    checkoutAtMain: boolean;
+    /** The command that tags exactly this preview (pinned `--sha`), or null once tagged. */
+    confirmCommand: string | null;
+    /** True when no tag was created. */
+    dryRun: boolean;
+    /** True when this call created the tag (which starts `release.yml`). */
+    tagCreated: boolean;
+    /** What allowed the tag (`authorization:<id>`, `setting:release.agentCut=<level>@<scope>` or `tty-confirm`), or null. */
+    allowedBy: string | null;
+}
+/** Options for {@link releaseChangelog}. */
+export interface ReleaseChangelogOptions {
+    /** Version whose section is written. */
+    version: string;
+    /** Git checkout whose `CHANGELOG.md` is written. */
+    projectRoot: string;
+    /** Commit the release was cut from (default: tag `v<version>` when it exists, else HEAD). */
+    ref?: string;
+    /** Test seam. */
+    runner?: ReleaseCutRunner;
+}
+/** Result of {@link releaseChangelog}. */
+export interface ReleaseChangelogResult {
+    /** Path of the CHANGELOG. */
+    changelogPath: string;
+    /** False when the section already existed (a plan-PR release) or nothing changed. */
+    written: boolean;
+    /** Previous release tag the section was computed from. */
+    previousTag: string | null;
+    /** Changesets the section was built from. */
+    changesetCount: number;
+}
+/**
+ * Cut a release: tag the newest green default-branch commit and let
+ * `release.yml` publish it. `dryRun` reports without tagging.
+ *
+ * @param opts - See {@link ReleaseCutOptions}.
+ * @returns The chosen commit, notes, packages, migrations and task report.
+ *
+ * @example
+ * ```ts
+ * const preview = await releaseCut({ version: '2026.10.28', projectRoot, dryRun: true });
+ * if (preview.success) console.log(preview.data.sha, preview.data.notes);
+ * ```
+ *
+ * @task T14102
+ */
+export declare function releaseCut(opts: ReleaseCutOptions): Promise<EngineResult<ReleaseCutResult>>;
+/** Result of {@link releaseVerifyTag}. */
+export interface ReleaseVerifyTagResult {
+    /** The tag checked. */
+    tag: string;
+    /** The commit it points at. */
+    sha: string;
+    /** Required checks that were green on its push run. */
+    checks: string[];
+}
+/**
+ * Refuse to publish a tag whose commit is not a first-parent commit of
+ * `origin/<default>` with every required check green on its push run. Run by
+ * `release.yml` before anything ships, so a hand-pushed tag or a dispatched
+ * run never publishes an untested tree.
+ *
+ * @param opts - Version, project root, default branch, test seam.
+ * @returns The tag, its commit and the checks found green.
+ *
+ * @example
+ * ```ts
+ * const ok = await releaseVerifyTag({ version: '2026.10.28', projectRoot: process.cwd() });
+ * if (!ok.success) process.exit(1);
+ * ```
+ *
+ * @task T14102
+ */
+export declare function releaseVerifyTag(opts: {
+    version: string;
+    projectRoot: string;
+    branch?: string;
+    runner?: ReleaseCutRunner;
+}): Promise<EngineResult<ReleaseVerifyTagResult>>;
+/**
+ * Write the `## [<version>]` CHANGELOG section from the changesets added since
+ * the previous release tag, led by the tag's annotation (the `--lead` the cut
+ * recorded). Runs in `release.yml` on the tagged checkout. A section that
+ * already exists (a plan-PR release) is left untouched.
+ *
+ * @param opts - See {@link ReleaseChangelogOptions}.
+ * @returns Whether the section was written, and from what range.
+ *
+ * @example
+ * ```ts
+ * await releaseChangelog({ version: '2026.10.28', projectRoot: process.cwd() });
+ * ```
+ *
+ * @task T14102
+ */
+export declare function releaseChangelog(opts: ReleaseChangelogOptions): Promise<EngineResult<ReleaseChangelogResult>>;
+//# sourceMappingURL=cut.d.ts.map

package/dist/release/cut.d.ts.map

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