@iodes/releasekit 0.1.7 → 0.2.0

package/dist/project.js

@@ -1,41 +1,124 @@
 import * as fs from 'node:fs/promises';
 import path from 'node:path';
 import { configSchema, historyStartSchema, releaseSchema } from './model.js';
-import { exists, identifier, readYaml, within, writeYaml, KIT_DIR } from './files.js';
+import { exists, identifier, readYaml, within, writeYaml, parseYaml, KIT_DIR } from './files.js';
 import { repoRoot, resolveCommit, resolveRange, checkPrevious } from './git.js';
+import { ref, refKey, parseRef, previousRef, link } from './refs.js';
+export function checkLimit(limit) {
+    if (limit !== undefined && (!Number.isSafeInteger(limit) || limit < 1))
+        throw new Error('History limit must be a positive safe integer.');
+}
+// Newest first. Validate every member, not just the displayed window.
+export function linearHistory(releases) {
+    if (!releases.length)
+        return [];
+    const items = new Map(releases.map(r => [refKey(r), r]));
+    if (items.size !== releases.length)
+        throw new Error('Duplicate release identity.');
+    const successors = new Set();
+    for (const release of releases) {
+        const previous = previousRef(release);
+        if (!previous)
+            continue;
+        const key = refKey(previous);
+        if (!items.has(key))
+            throw new Error(`Missing previous release: ${key}`);
+        if (successors.has(key))
+            throw new Error(`Branch in release history at ${key}`);
+        successors.add(key);
+    }
+    const heads = releases.filter(r => !successors.has(refKey(r)));
+    if (heads.length !== 1)
+        throw new Error('Release history must have one endpoint; disconnected history or cycle found.');
+    const chain = [];
+    const visited = new Set();
+    let cursor = heads[0];
+    while (cursor) {
+        const key = refKey(cursor);
+        if (visited.has(key))
+            throw new Error(`Cycle in release history at ${key}`);
+        visited.add(key);
+        chain.push(cursor);
+        const previous = previousRef(cursor);
+        cursor = previous ? items.get(refKey(previous)) : undefined;
+    }
+    if (chain.length !== releases.length)
+        throw new Error('Disconnected release history or cycle found.');
+    return chain;
+}
 export class Project {
     root;
     constructor(root) { this.root = path.resolve(root); }
     static find(cwd) { return new Project(repoRoot(cwd)); }
     async content(relative) { return within(this.root, `${KIT_DIR}/${relative}`); }
     async config() {
-        const config = await readYaml(await this.content('config.yaml'), configSchema);
+        const file = await this.content('config.yaml');
+        if (!(await exists(file)))
+            throw new Error('ReleaseKit is not initialized. Run releasekit init first.');
+        const raw = parseYaml(await fs.readFile(file, 'utf8'));
+        if (raw && typeof raw === 'object' && 'history' in raw && raw.history && typeof raw.history === 'object' && 'limit' in raw.history) {
+            throw new Error('Remove history.limit from config.yaml; use export --limit instead. Omit --limit to export all releases.');
+        }
+        const config = configSchema.parse(raw);
         if (!config.locales.includes(config.sourceLocale) || new Set(config.locales).size !== config.locales.length) {
             throw new Error('Project locales must be unique and include the source locale.');
         }
         return config;
     }
-    async releaseDir(version) {
-        return this.content(`releases/${identifier(version)}`);
+    async requireChannel(channel) {
+        ref({ channel, version: 'check' });
+        const config = await this.config();
+        if (!config.channels || !Object.hasOwn(config.channels, channel))
+            throw new Error(`Unknown channel: ${channel}. Configure it in config.yaml first.`);
     }
-    async releaseFile(version, relative) {
-        return within(await this.releaseDir(version), relative);
+    async releaseDir(value) {
+        return this.content(`releases/${refKey(value)}`);
     }
-    async release(version) {
-        const release = await readYaml(await this.releaseFile(version, 'release.yaml'), releaseSchema);
-        if (release.version !== version)
-            throw new Error(`Release directory and version disagree: ${version}`);
+    async releaseFile(value, relative) {
+        return within(await this.releaseDir(value), relative);
+    }
+    async release(value) {
+        const release = await readYaml(await this.releaseFile(value, 'release.yaml'), releaseSchema);
+        if (refKey(release) !== refKey(value))
+            throw new Error(`Release directory and identity disagree: ${refKey(value)}`);
         return release;
     }
     async save(release) {
-        await writeYaml(await this.releaseFile(release.version, 'release.yaml'), releaseSchema.parse(release));
+        await writeYaml(await this.releaseFile(release, 'release.yaml'), releaseSchema.parse(release));
     }
-    async versions() {
+    async allRefs() {
         const folder = await this.content('releases');
         if (!(await exists(folder)))
             return [];
-        const entries = await fs.readdir(folder, { withFileTypes: true });
-        return entries.filter(e => e.isDirectory()).map(e => e.name).sort();
+        const result = [];
+        for (const entry of await fs.readdir(folder, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const directory = await this.content(`releases/${identifier(entry.name)}`);
+            if (await exists(path.join(directory, 'release.yaml')))
+                result.push(ref(entry.name));
+            // An unchanneled version may also happen to be a channel name.
+            for (const child of await fs.readdir(directory, { withFileTypes: true })) {
+                if (child.isDirectory() && await exists(path.join(directory, child.name, 'release.yaml'))) {
+                    result.push(ref({ channel: entry.name, version: child.name }));
+                }
+            }
+        }
+        const keys = result.map(r => refKey(r).toLowerCase());
+        if (new Set(keys).size !== keys.length)
+            throw new Error('Release identities collide on a case-insensitive filesystem.');
+        return result.sort((a, b) => refKey(a) < refKey(b) ? -1 : 1);
+    }
+    async versions() {
+        return (await this.allRefs()).filter(r => r.channel === undefined).map(r => r.version);
+    }
+    async channelHistory() {
+        const refs = (await this.allRefs()).filter(r => r.channel !== undefined);
+        const config = await this.config();
+        for (const value of refs)
+            if (!config.channels || !Object.hasOwn(config.channels, value.channel))
+                throw new Error(`Unknown channel: ${value.channel}`);
+        return linearHistory(await Promise.all(refs.map(r => this.release(r))));
     }
     async latestVersion() {
         const versions = await this.versions();
@@ -50,21 +133,27 @@ export class Project {
             throw new Error(`Multiple latest releases found: ${latest.map(release => release.version).join(', ')}. Specify --current <version>.`);
         return latest[0].version;
     }
-    async history(version, limit) {
-        if (!Number.isInteger(limit) || limit < 1 || limit > 100)
-            throw new Error('History limit must be an integer from 1 to 100.');
+    async history(value, limit) {
+        checkLimit(limit);
+        if (ref(value).channel !== undefined) {
+            const chain = await this.channelHistory();
+            const index = chain.findIndex(r => refKey(r) === refKey(value));
+            if (index < 0)
+                throw new Error(`Missing release: ${refKey(value)}`);
+            return chain.slice(index, limit === undefined ? undefined : index + limit);
+        }
         const chain = [];
         const visited = new Set();
-        let cursor = version;
-        // Validate the entire linked lineage, including links beyond the requested display window.
+        let cursor = ref(value);
         while (cursor !== null) {
-            if (visited.has(cursor))
-                throw new Error(`Cycle in previous-release links at ${cursor}`);
-            visited.add(cursor);
+            const key = refKey(cursor);
+            if (visited.has(key))
+                throw new Error(`Cycle in previous-release links at ${key}`);
+            visited.add(key);
             const release = await this.release(cursor);
-            if (chain.length < limit)
+            if (limit === undefined || chain.length < limit)
                 chain.push(release);
-            cursor = release.previous;
+            cursor = previousRef(release);
         }
         return chain;
     }
@@ -75,9 +164,12 @@ export function editable(release) {
 }
 export async function startProject(project, options) {
     const config = await project.config();
-    if (config.history.start)
+    if (options.channel !== undefined)
+        await project.requireChannel(options.channel);
+    const settings = options.channel === undefined ? (config.history ??= {}) : (config.channels[options.channel].history ??= {});
+    if (settings.start)
         throw new Error('A history start is already configured. Reuse the saved choice; it was not overwritten.');
-    if ((await project.versions()).length)
+    if ((await project.allRefs()).some(r => r.channel === options.channel))
         throw new Error('History setup requires a project without releases. Continue an existing release line with --previous.');
     if (options.past === 'skip' && options.version !== undefined)
         throw new Error('--baseline-version is not used when --past is skip.');
@@ -87,12 +179,14 @@ export async function startProject(project, options) {
         identifier(options.version);
     const source = resolveRange(project.root, null, options.at);
     const start = historyStartSchema.parse({ ref: options.at, sha: source.toSha, past: options.past, version: options.version ?? null });
-    config.history.start = start;
+    settings.start = start;
     await writeYaml(await project.content('config.yaml'), config);
     return start;
 }
 export async function prepare(project, version, options) {
     identifier(version);
+    if (options.channel !== undefined)
+        return prepareChannel(project, version, options);
     const directory = await project.releaseDir(version);
     if (await exists(directory))
         throw new Error(`Release ${version} already exists; edit it in place instead of overwriting it.`);
@@ -102,7 +196,9 @@ export async function prepare(project, version, options) {
     if (options.firstRelease && options.previous)
         throw new Error('--first-release cannot be combined with --previous.');
     const versions = await project.versions();
-    const start = config.history.start;
+    if (versions.some(v => v.toLowerCase() === version.toLowerCase()))
+        throw new Error(`Release ${version} already exists on a case-insensitive filesystem.`);
+    const start = config.history?.start;
     let previous = options.previous ? await project.release(options.previous) : undefined;
     let from = options.fromRoot ? null : options.from ?? previous?.source.toSha;
     let to = options.to ?? 'HEAD';
@@ -151,7 +247,7 @@ export async function prepare(project, version, options) {
         await project.history(previous.version, 1);
     }
     const release = releaseSchema.parse({
-        schemaVersion: 1, version, releasedAt: options.date ?? new Date().toISOString().slice(0, 10),
+        schemaVersion: 1, version, releasedAt: options.date ?? new Date().toISOString(),
         previous: previous?.version ?? null, status: 'draft', source,
         ...(initialContent ? { initialContent } : {}),
         sourceLocale: config.sourceLocale, locales: config.locales, visuals: config.visuals,
@@ -160,3 +256,58 @@ export async function prepare(project, version, options) {
     await project.save(release);
     return release;
 }
+async function prepareChannel(project, version, options) {
+    const channel = options.channel;
+    await project.requireChannel(channel);
+    const identity = ref({ channel, version });
+    if (await exists(await project.releaseDir(identity)))
+        throw new Error(`Release ${refKey(identity)} already exists; edit it in place.`);
+    const config = await project.config();
+    const chain = await project.channelHistory();
+    if (chain.some(r => refKey(r).toLowerCase() === refKey(identity).toLowerCase()))
+        throw new Error(`Release ${refKey(identity)} already exists on a case-insensitive filesystem.`);
+    const head = chain[0];
+    const sameChannel = chain.filter(r => r.channel === channel);
+    if (options.previous !== undefined && (!head || refKey(parseRef(options.previous)) !== refKey(head)))
+        throw new Error('--previous must identify the latest release in the whole channel history.');
+    if (options.firstRelease && head)
+        throw new Error('Channel history already exists; a second independent history is not allowed.');
+    if (options.fromRoot && options.from !== undefined)
+        throw new Error('--from-root cannot be combined with --from.');
+    const start = config.channels && config.channels[channel].history?.start;
+    let from = options.fromRoot ? null : options.from ?? sameChannel[0]?.source.toSha;
+    let to = options.to ?? 'HEAD';
+    let initialContent;
+    let savedStart = false;
+    if (start && start.past !== 'skip' && version === start.version) {
+        if (sameChannel.length || options.from !== undefined)
+            throw new Error('Prepare the configured baseline before other releases in its channel.');
+        if (options.to !== undefined && resolveCommit(project.root, options.to) !== start.sha)
+            throw new Error('The requested end differs from the pinned history start.');
+        from = null;
+        to = start.sha;
+        initialContent = start.past;
+    }
+    else if (start && from === undefined) {
+        if (start.past !== 'skip' && !sameChannel.length)
+            throw new Error(`Prepare the configured baseline ${channel}/${start.version} first.`);
+        from = start.sha;
+        savedStart = true;
+    }
+    if (from === undefined)
+        throw new Error(`Specify --from or --from-root, or configure a history start for ${channel}.`);
+    const source = resolveRange(project.root, from, to);
+    if (initialContent && start)
+        source.toRef = start.ref;
+    if (savedStart && start)
+        source.fromRef = start.ref;
+    const release = releaseSchema.parse({
+        schemaVersion: 1, ...identity, previous: link(head), status: 'draft', source,
+        releasedAt: options.date ?? new Date().toISOString(),
+        ...(initialContent ? { initialContent } : {}),
+        sourceLocale: config.sourceLocale, locales: config.locales, visuals: config.visuals,
+        notes: [], emptyReason: null, contentHash: null,
+    });
+    await project.save(release);
+    return release;
+}

package/dist/refs.d.ts

@@ -0,0 +1,6 @@
+import { type Release, type ReleaseId, type ReleaseRef } from './model.js';
+export declare function ref(value: ReleaseId): ReleaseRef;
+export declare function refKey(value: ReleaseId): string;
+export declare function parseRef(value: string): ReleaseRef;
+export declare function previousRef(release: Release): ReleaseRef | null;
+export declare function link(value: ReleaseRef | undefined): Release['previous'];

package/dist/refs.js

@@ -0,0 +1,29 @@
+import { channelRefSchema } from './model.js';
+import { identifier } from './files.js';
+export function ref(value) {
+    const result = typeof value === 'string' ? { version: value } : value;
+    identifier(result.version);
+    if (result.channel !== undefined) {
+        channelRefSchema.parse({ channel: result.channel, version: result.version });
+        identifier(result.channel);
+    }
+    return result.channel === undefined ? { version: result.version } : { channel: result.channel, version: result.version };
+}
+export function refKey(value) {
+    const item = ref(value);
+    return item.channel === undefined ? item.version : `${item.channel}/${item.version}`;
+}
+export function parseRef(value) {
+    const parts = value.split('/');
+    if (parts.length === 1)
+        return ref(value);
+    if (parts.length !== 2)
+        throw new Error(`Expected channel/version: ${value}`);
+    return ref({ channel: parts[0], version: parts[1] });
+}
+export function previousRef(release) {
+    return release.previous === null ? null : ref(release.previous);
+}
+export function link(value) {
+    return value === undefined ? null : value.channel === undefined ? value.version : ref(value);
+}

package/dist/setup.d.ts

@@ -0,0 +1,7 @@
+import type { InitOptions } from './install.js';
+export declare const commaList: (value: string) => string[];
+export declare function parseTools(value: string): ("claude" | "codex" | "cursor")[];
+type Ask = (question: string) => Promise<string>;
+export declare function collectSetup(root: string, options: InitOptions, ask: Ask, report: (message: string) => void): Promise<InitOptions>;
+export declare function interactiveSetup(root: string, options: InitOptions): Promise<InitOptions>;
+export {};

package/dist/setup.js

@@ -0,0 +1,64 @@
+import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { configSchema, defaultConfig } from './model.js';
+export const commaList = (value) => value.split(',').map(s => s.trim()).filter(Boolean);
+export function parseTools(value) {
+    if (value === 'none')
+        return [];
+    const values = commaList(value);
+    if (!values.length)
+        throw new Error('Choose codex, claude, cursor, or none.');
+    return configSchema.shape.tools.parse(values);
+}
+// Collect and validate everything before initProject writes any files.
+export async function collectSetup(root, options, ask, report) {
+    const defaults = defaultConfig(path.basename(root));
+    async function field(label, fallback, parse) {
+        for (;;) {
+            const answer = (await ask(`${label} [${fallback}]: `)).trim() || fallback;
+            try {
+                return parse(answer);
+            }
+            catch (error) {
+                report(error instanceof Error ? error.message : String(error));
+            }
+        }
+    }
+    const product = options.product ?? await field('Product name', defaults.product, value => configSchema.shape.product.parse(value));
+    const tools = options.tools ?? await field('Agent tools (codex, claude, cursor; comma-separated, or none)', defaults.tools.join(','), parseTools);
+    const sourceLocale = options.sourceLocale ?? await field('Original language (locale code)', defaults.sourceLocale, value => configSchema.shape.sourceLocale.parse(value));
+    const locales = options.locales ?? await field('All languages, including the original (comma-separated locale codes)', sourceLocale, value => {
+        const values = configSchema.shape.locales.parse(commaList(value));
+        if (!values.includes(sourceLocale) || new Set(values).size !== values.length)
+            throw new Error(`Languages must be unique and include ${sourceLocale}.`);
+        return values;
+    });
+    const themes = options.themes ?? await field('Image themes (both, dark, light)', defaults.visuals.themes, value => configSchema.shape.visuals.shape.themes.parse(value));
+    return { product, tools, sourceLocale, locales, themes };
+}
+export function interactiveSetup(root, options) {
+    return withTerminal((ask, report) => collectSetup(root, options, ask, report), 'Setup cancelled. No configuration was written.');
+}
+async function withTerminal(collect, cancelled) {
+    const terminal = createInterface({ input: stdin, output: stdout });
+    const abort = new AbortController();
+    const cancel = () => abort.abort();
+    terminal.on('SIGINT', cancel);
+    terminal.on('close', cancel);
+    try {
+        return await collect(question => {
+            if (abort.signal.aborted)
+                throw new Error(cancelled);
+            return terminal.question(question, { signal: abort.signal });
+        }, message => stdout.write(`${message}\n`));
+    }
+    catch (error) {
+        if (abort.signal.aborted)
+            throw new Error(cancelled);
+        throw error;
+    }
+    finally {
+        terminal.close();
+    }
+}

package/dist/status.d.ts

@@ -0,0 +1,31 @@
+import { Project } from './project.js';
+import type { ReleaseRef } from './model.js';
+export declare function listReleases(project: Project, channel?: string): Promise<{
+    version: string;
+    channel?: string;
+    status: "draft" | "ready";
+    releasedAt: string;
+    notes: number;
+    locales: string[];
+}[]>;
+export declare function projectStatus(project: Project, selected?: ReleaseRef, channel?: string): Promise<{
+    initialized: boolean;
+    releases: never[];
+    next: string[];
+    product?: undefined;
+} | {
+    initialized: boolean;
+    product: string;
+    releases: {
+        version: string;
+        channel?: string | undefined;
+        status: "draft" | "ready";
+        notes: number;
+        valid: boolean;
+        errors: string[];
+        warnings: string[];
+        next: string;
+    }[];
+    next: string[];
+}>;
+export declare function formatStatus(result: Awaited<ReturnType<typeof projectStatus>>): string;

package/dist/status.js

@@ -0,0 +1,52 @@
+import { Project } from './project.js';
+import { exists } from './files.js';
+import { refKey } from './refs.js';
+import { validate } from './validate.js';
+export async function listReleases(project, channel) {
+    await project.config();
+    if (channel !== undefined)
+        await project.requireChannel(channel);
+    const refs = (await project.allRefs()).filter(value => channel === undefined || value.channel === channel);
+    return Promise.all(refs.map(async (value) => {
+        const release = await project.release(value);
+        return { ...value, status: release.status, releasedAt: release.releasedAt, notes: release.notes.length, locales: release.locales };
+    }));
+}
+export async function projectStatus(project, selected, channel) {
+    if (!(await exists(await project.content('config.yaml')))) {
+        return { initialized: false, releases: [], next: ['releasekit init'] };
+    }
+    const config = await project.config();
+    const releases = selected ? [await project.release(selected)] : await listReleases(project, channel);
+    const results = await Promise.all(releases.map(async (release) => {
+        const validation = await validate(project, release);
+        const identity = refKey(release);
+        const args = `${release.version}${release.channel === undefined ? '' : ` --channel ${release.channel}`}`;
+        let next;
+        if (!validation.valid)
+            next = `Use releasekit-draft or releasekit-image for ${identity} to resolve the reported issues, then run releasekit validate ${args}.`;
+        else if (release.status === 'ready')
+            next = `releasekit export --current ${args} --out <new-directory>`;
+        else {
+            const predecessors = (await project.history(release)).slice(1).filter(item => item.status !== 'ready');
+            next = release.channel === undefined && predecessors.length
+                ? `Finalize earlier releases first: ${predecessors.reverse().map(refKey).join(', ')}.`
+                : `releasekit finalize ${args}`;
+        }
+        return { version: release.version, ...(release.channel === undefined ? {} : { channel: release.channel }), status: release.status,
+            notes: typeof release.notes === 'number' ? release.notes : release.notes.length,
+            valid: validation.valid, errors: validation.errors, warnings: validation.warnings, next };
+    }));
+    return { initialized: true, product: config.product, releases: results,
+        next: results.length ? [] : ['Use releasekit-draft with a version to select the Git range and write the first draft.'] };
+}
+export function formatStatus(result) {
+    const lines = [result.initialized ? `${result.product} — release status` : 'ReleaseKit is not initialized.'];
+    for (const release of result.releases) {
+        lines.push(`\n${refKey(release)}  ${release.status}  ${release.notes} notes  ${release.valid ? 'validation passed' : 'needs attention'}`);
+        lines.push(...release.errors.map(error => `  - ${error}`), ...release.warnings.map(warning => `  Warning: ${warning}`));
+        lines.push(`  Next: ${release.next}`);
+    }
+    lines.push(...result.next.map(next => `Next: ${next}`));
+    return lines.join('\n');
+}

package/dist/validate.d.ts

@@ -1,12 +1,15 @@
+import { type ReleaseId } from './model.js';
 import { type Release } from './model.js';
 import { Project } from './project.js';
 export interface Validation {
     version: string;
+    channel?: string;
     valid: boolean;
     errors: string[];
     warnings: string[];
     contentHash: string | null;
 }
 export declare function contentHash(project: Project, release: Release): Promise<string>;
-export declare function validate(project: Project, version: string): Promise<Validation>;
-export declare function finalize(project: Project, version: string): Promise<Validation>;
+export declare function validate(project: Project, version: ReleaseId): Promise<Validation>;
+export declare function validateMany(project: Project, versions: ReleaseId[]): Promise<Validation[]>;
+export declare function finalize(project: Project, version: ReleaseId): Promise<Validation>;

package/dist/validate.js

@@ -1,27 +1,47 @@
+import {} from './model.js';
+import { ref, refKey } from './refs.js';
 import { imageSource } from './model.js';
 import { Project, editable } from './project.js';
 import { canonical, digest, readNote, noteHash, identifier } from './files.js';
 import { readVisual, checkReferenceFiles } from './content.js';
 import { validateImages } from './images.js';
-import { checkPrevious, collect, collectSnapshot } from './git.js';
+import { collect, collectSnapshot } from './git.js';
 export async function contentHash(project, release) {
     const { status: _status, contentHash: _hash, ...metadata } = release;
     const parts = [metadata];
     for (const note of release.notes) {
         for (const language of release.locales)
-            parts.push(await readNote(await project.releaseFile(release.version, `notes/${note.id}/${language}.md`)));
+            parts.push(await readNote(await project.releaseFile(release, `notes/${note.id}/${language}.md`)));
         if (note.image)
-            parts.push(await readVisual(project, release.version, note.id));
+            parts.push(await readVisual(project, release, note.id));
     }
     return digest(canonical(parts));
 }
 export async function validate(project, version) {
+    return validateOne(project, version);
+}
+// Reuse structural validation within an export or move, without caching across mutations.
+export async function validateMany(project, versions) {
+    const checkedHistory = new Set();
+    if (versions.some(v => ref(v).channel !== undefined)) {
+        for (const release of await project.channelHistory())
+            checkedHistory.add(refKey(release));
+    }
+    for (const version of versions) {
+        if (!checkedHistory.has(refKey(version))) {
+            for (const release of await project.history(version))
+                checkedHistory.add(refKey(release));
+        }
+    }
+    return Promise.all(versions.map(version => validateOne(project, version, checkedHistory)));
+}
+async function validateOne(project, version, checkedHistory) {
     const errors = [], warnings = [];
     let hash = null;
     try {
         const release = await project.release(version);
-        if (release.initialContent && (release.source.fromSha !== null || release.source.fromRef !== null || release.previous !== null)) {
-            errors.push('Initial content requires a root baseline with no previous release.');
+        if (release.initialContent && (release.source.fromSha !== null || release.source.fromRef !== null)) {
+            errors.push('Initial content requires a root baseline Git range.');
         }
         // Summaries inspect only the baseline snapshot; ready releases use their finalized fingerprint.
         const summary = release.initialContent === 'summary';
@@ -74,19 +94,13 @@ export async function validate(project, version) {
             }
         }
         try {
-            await project.history(version, 1);
+            if (!checkedHistory?.has(refKey(version)))
+                await project.history(version, 1);
         }
         catch (error) {
             errors.push(error instanceof Error ? error.message : String(error));
         }
-        if (release.status === 'draft' && release.previous) {
-            try {
-                checkPrevious(project.root, await project.release(release.previous), release.source);
-            }
-            catch (error) {
-                errors.push(error instanceof Error ? error.message : String(error));
-            }
-        }
+        // Git scope was pinned independently; display links can change during moves.
         if (!errors.length)
             hash = await contentHash(project, release);
         if (release.status === 'ready' && release.contentHash !== hash && !errors.length)
@@ -95,7 +109,7 @@ export async function validate(project, version) {
     catch (error) {
         errors.push(error instanceof Error ? error.message : String(error));
     }
-    return { version, valid: errors.length === 0, errors, warnings, contentHash: hash };
+    return { ...ref(version), valid: errors.length === 0, errors, warnings, contentHash: hash };
 }
 export async function finalize(project, version) {
     const release = await project.release(version);
@@ -103,8 +117,8 @@ export async function finalize(project, version) {
     const result = await validate(project, version);
     if (!result.valid || !result.contentHash)
         throw new Error(result.errors.join('\n'));
-    const chain = await project.history(version, 100);
-    if (chain.slice(1).some(r => r.status !== 'ready'))
+    const chain = await project.history(version);
+    if (release.channel === undefined && chain.slice(1).some(r => r.status !== 'ready'))
         throw new Error('Finalize the previous releases before finalizing this release.');
     release.status = 'ready';
     release.contentHash = result.contentHash;

package/kit/references/adoption.md

@@ -2,7 +2,9 @@
 
 Read this when a product has no ReleaseKit releases and the author is choosing where to start. Resolve the likely baseline through [repository inspection](workflow.md#resolve-release-scope-from-the-repository) before asking; a clear inferred tag interval does not require confirmation. Setup has two separate decisions: the baseline commit, and how to present the product's earlier history. A baseline is the end of the earlier period; regular change notes begin **after** it. Choosing a tag does not mean starting at the commit that created that tag's features.
 
-Read existing releases and `history.start` in the project config first. Reuse a saved selection when continuing setup. Existing releases use their explicit `previous` links. An explicitly limited Git interval or a requested full-history release already establishes the work's scope; do not add retrospective work or repeat that choice. For first-use requests with unresolved scope, gather the missing decisions using the workflow's [native question UI](workflow.md#ask-with-the-native-question-ui). Follow [the answer-waiting procedure](workflow.md#wait-for-the-users-answer) after asking. Independent inspection may continue while answers are pending, but do not save an unconfirmed choice or draft dependent copy.
+For channel-aware first drafts, choose use/non-use and the target channel through [the channel workflow](channels.md#first-draft-and-later-drafts) before applying this guide. Use `--channel` on start and prepare, scope existing-release discovery to that channel, and read its `channels.<name>.history.start`. Its display predecessor can be another channel; Git boundaries remain separate.
+
+For an unchanneled history, read existing releases and `history.start` in the project config first. Reuse a saved selection when continuing setup. Existing releases use their explicit `previous` links. An explicitly limited Git interval or a requested full-history release already establishes the work's scope; do not add retrospective work or repeat that choice. For first-use requests with unresolved scope, gather the missing decisions using the workflow's [native question UI](workflow.md#ask-with-the-native-question-ui). Follow [the answer-waiting procedure](workflow.md#wait-for-the-users-answer) after asking. Independent inspection may continue while answers are pending, but do not save an unconfirmed choice or draft dependent copy.
 
 ## Choose the baseline