@gitkraken/compose-tools 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/) and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-04-23
+
+### Added
+
+- Adds `compose(input)` — one-call sugar that runs planning and apply together; ideal when the consumer does not need to surface the plan for review
+- Adds `composePlan(input)` and `applyComposePlan(input)` — a two-phase API for consumers (e.g. GitLens's webview) that surface the plan for user review or editing before applying; `applyComposePlan` reverifies the workdir matches the plan's snapshot before mutating
+- Adds `split(input)` — partitions an existing multi-commit branch into a stack of smaller, reviewable branches
+- Adds `undoCompose(input)` and `validateUndoCompose(input)` — surgical reversal of only the git mutations a compose operation recorded, plus a dry-run validator that reports blockers and warnings without mutating the repo
+- Adds `ComposeGitPort` — the git surface used by every workflow; accepts raw `exec`, a hybrid of `exec` plus targeted high-level op overrides (e.g. a signing-aware `commitTree`), or an ops-only implementation for libgit2-backed consumers; missing ops throw `ComposeGitPortMissingOpError` naming the missing op
+- Adds source types for selecting what to compose — `{ type: 'workdir' }` (staged, unstaged, and untracked changes with optional `stagedOnly` and `noUntracked` filters), `{ type: 'branch' }` (merge-base to tip), and `{ type: 'commit-range' }` (a contiguous range with per-hunk author info preserved for attribution on rewritten commits)
+- Adds target types for deciding where composed output lands — `{ type: 'head' }`, `{ type: 'branch' }`, `{ type: 'branch-replace' }` (replace the source branch in place), `{ type: 'auto' }` (one branch per concern, optionally subdivided into stacked sub-branches), and `{ type: 'rewrite-range' }` (rewrite a contiguous range in the middle of a branch while preserving the commits before and after)
+- Adds a `depth` option that tunes how many AI passes run and how deeply each reasons over the input
+- Adds an `onProgress` callback that surfaces phase transitions, per-call token usage, and call IDs in real time — suitable for wiring progress UI
+- Adds an `onBeforeApply` hook that lets consumers inspect the plan and gate or cancel application before anything is mutated
+- Adds a `session` parameter that resumes a prior planning conversation by passing the session returned from an earlier `composePlan` result
+- Adds a `feedbackTargetCallId` on results — a stable ID for the model's "decision" call, for wiring thumbs-up/thumbs-down telemetry on specific outputs
+- Adds safety-snapshot verification between plan and apply — `applyComposePlan` rehashes the workdir before mutating, and drift throws `WorkflowError('SAFETY_CHECK_FAILED')`
+- Adds cancellation support via `AbortSignal` — propagates from every workflow input into every git `exec` and AI `generate` call
+- Adds a typed error taxonomy — `GitError`, `AiError`, `TaskError`, `WorkflowError`, and `ComposeGitPortMissingOpError`, each carrying a `code` property so consumers can branch on failure modes

package/LICENSE

@@ -0,0 +1,19 @@
+Core Tools License
+
+Copyright (c) 2025-2026 Axosoft, LLC dba GitKraken ("GitKraken")
+
+This software and associated documentation files (the "Software") may be compiled as part of GitKraken software products, including the gitkraken/vscode-gitlens open source project (collectively, the "GitKraken Products"), to the extent the Software is a required component of the GitKraken Products; provided, however, that the Software and its functionality may only be used if you (and any entity that you represent) have agreed to, and are in compliance with, the GitKraken End User License Agreement, available at https://gitkraken.com/eula (the "EULA"), or other agreement governing the use of the Software, as agreed by you and GitKraken, and otherwise have a valid subscription for the correct number of user seats for the applicable version of the Software (e.g., GitLens Free+, GitLens Pro, GitLens Teams, and GitLens Enterprise).
+
+The Software is licensed, not sold. This license only gives you some rights to use the Software. GitKraken reserves all other rights. Unless applicable law gives you more rights despite this limitation, you may use the Software only as expressly permitted in this license. In doing so, you must comply with any technical limitations in the Software that only allow you to use it in certain ways. You may not (i) work around any technical limitations in the Software, (ii) reverse engineer, decompile or disassemble the Software, or otherwise attempt to derive the source code for the Software, except and to the extent required by third party licensing terms governing use of certain open source components that may be included with the Software, (iii) remove, minimize, block or modify any notices of GitKraken or its suppliers in the Software, (iv) use the software in any way that is against the law, (v) host, share, publish, rent or lease the Software; (vi) distribute the Software as a stand-alone or integrated offering or combine it with any of your applications for others to use, (vii) use the Software other than in connection with validly licensed GitKraken Products or (viii) use any portion of the Software to create software with the same or similar functionality.
+
+You agree that GitKraken and/or its licensors (as applicable) retain all right, title and interest in and to the Software and all modifications and/or patches thereto. You are not granted any other rights beyond what is expressly stated herein. Except as set forth above, it is forbidden to copy, merge, publish, distribute, sublicense, modify and/or sell the Software.
+
+If you give feedback about the Software to GitKraken, you give to GitKraken, without charge, the right to use, share and commercialize your feedback in any way and for any purpose. You will not give feedback that is subject to a license that requires GitKraken to license its software or documentation to third parties because we include your feedback in them. These rights survive this License.
+
+The full text of this Core Tools License shall be included in all copies or substantial portions of the Software.
+
+This License and the EULA, if applicable, are the entire agreement for the Software. You must comply with all domestic and international export laws and regulations that apply to the Software, which include restrictions on destinations, end users and end use. This License is governed and construed by the laws of the State of Arizona, United States without regard to any choice or conflict of law principles or rules.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL GITKRAKEN, THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+For all third party components incorporated into the Software, those components are licensed under the original license provided by the owner of the applicable component.

package/README.md

@@ -0,0 +1,543 @@
+# @gitkraken/compose-tools
+
+AI-powered git change organization. Takes a messy working directory or a branch full of interleaved commits and restructures them into clean, atomic commits on well-named branches — ready for code review.
+
+## What it does
+
+`compose()` collects your changes, sends the diffs through an AI pipeline that understands the logical structure of code changes, and produces clean commits grouped by concern. Depending on configuration, it can:
+
+- Rewrite a working directory's staged / unstaged / untracked changes into atomic commits on the current branch
+- Reorganize a branch's commit history into logically grouped commits
+- Rewrite a contiguous range of commits in the middle of a branch, preserving the commits before and after the range
+- Split changes across multiple new branches (one per concern)
+- Subdivide branches into stacked sub-branches for incremental review
+
+`split()` is a focused variant — it takes an existing multi-commit branch and partitions it into a stack of smaller branches.
+
+Every operation that mutates the repository returns an `undoId` that can be passed to `undoCompose()` to surgically reverse only the git mutations that were recorded.
+
+## Install
+
+```bash
+pnpm add @gitkraken/compose-tools @gitkraken/shared-tools
+```
+
+The library is runtime-agnostic — it never executes git or AI calls directly. Consumers provide adapters for their own git and AI backends.
+
+## Implement the ports
+
+### `ComposeGitPort`
+
+The git surface the library needs. Two ways to provide it:
+
+**Minimal — raw `exec` only.** Fine for a CLI-git consumer.
+
+```typescript
+import type { ComposeGitPort } from '@gitkraken/compose-tools';
+
+const git: ComposeGitPort = {
+    exec: async (args, options) => {
+        const result = await yourGitBackend.run(args, {
+            cwd: '/path/to/repo',
+            env: options?.env,
+            stdin: options?.stdin,
+            signal: options?.signal,
+        });
+        if (result.exitCode !== 0) throw new Error(`git ${args[0]} failed: ${result.stderr}`);
+        return result.stdout;
+    },
+};
+```
+
+The library builds every git operation it needs (diff, write-tree, commit-tree, update-ref, stash, cherry-pick, etc.) from `exec`.
+
+**Hybrid — `exec` plus targeted high-level ops.** Provide a high-level op when your backend has a better implementation. The library prefers the high-level op over routing through `exec`.
+
+```typescript
+const git: ComposeGitPort = {
+    exec: async (args, options) => { /* ... */ },
+
+    // Consumer has a signing-aware commit creator; library should prefer it.
+    commitTree: async (tree, parents, message, opts) => {
+        return yourSigningCommitCreator({ tree, parents, message, signing: opts?.signing });
+    },
+};
+```
+
+**Libgit2-style — high-level ops only, no `exec`.** A libgit2-backed consumer implements the specific ops used by its flow. If a flow needs an op the consumer didn't provide and `exec` isn't available either, the library throws `ComposeGitPortMissingOpError` naming the missing op.
+
+The full list of high-level ops is in the `ComposeGitOps` type; the most commonly overridden are `commitTree`, `readTree`, `writeTree`, `applyPatchToIndex`, `diffTree`, `stageAll`. Every op takes an `OpOptions` with `signal?: AbortSignal`.
+
+### `AiModelPort`
+
+Stateless text generation — the caller passes the full message history each call.
+
+```typescript
+import type { AiModelPort } from '@gitkraken/shared-tools';
+
+const model: AiModelPort = {
+    generate: async (params) => {
+        const response = await yourLLM.chat({
+            system: params.system,
+            messages: params.messages,
+            maxTokens: params.maxTokens,
+            temperature: params.temperature,
+            signal: params.signal,
+        });
+        return {
+            text: response.text,
+            usage: { inputTokens: response.inputTokens, outputTokens: response.outputTokens },
+        };
+    },
+};
+```
+
+The adapter doesn't track sessions — session state is managed inside the library.
+
+## Entry points
+
+The library exposes three flavors of the main workflow plus split and undo.
+
+### `compose(input)` — one-call sugar
+
+Runs planning and apply together. Ideal when the consumer doesn't need to surface the plan for review.
+
+```typescript
+import { compose } from '@gitkraken/compose-tools';
+
+const result = await compose({
+    git,
+    model,
+    source: { type: 'workdir' },
+    onProgress: (event) => console.log(event.phase, event.message),
+});
+
+// result.plan                  — AI's analysis, grouping, ordering
+// result.commitShas            — { 'commit-1': 'abc123…', … }
+// result.undoId                — pass to undoCompose() to reverse
+// result.phases                — timing/usage/callIds per phase
+// result.usage                 — aggregated token counts
+// result.feedbackTargetCallId  — stable ID of the "decision" model call (for thumbs up/down events)
+```
+
+### `composePlan(input)` + `applyComposePlan(input)` — two-phase
+
+Returns the plan without mutating the repo, lets the user review/edit it, then applies. This is the shape GitLens-style UIs use (plan → webview → user edits → apply).
+
+```typescript
+import { composePlan, applyComposePlan } from '@gitkraken/compose-tools';
+
+const planResult = await composePlan({
+    git,
+    model,
+    source: { type: 'workdir' },
+});
+
+// Show planResult.plan + planResult.source.hunks to the user. They may
+// reassign hunks between commits, reorder, edit messages, etc.
+
+const userEditedPlan = /* user-edited version of planResult.plan */;
+
+const applied = await applyComposePlan({
+    git,
+    applyPlan: {
+        plan: userEditedPlan,
+        source: planResult.source,     // the library's collected hunks
+        snapshot: planResult.snapshot, // safety hash — verified at apply time
+    },
+});
+```
+
+`applyComposePlan` reverifies the workdir matches `snapshot` before mutating. If it drifted between plan and apply, it throws `WorkflowError('SAFETY_CHECK_FAILED')`.
+
+### `split(input)`
+
+Partitions an existing branch into a stack of smaller branches.
+
+```typescript
+import { split } from '@gitkraken/compose-tools';
+
+const result = await split({
+    git,
+    model,
+    branchName: 'feature/large-pr',
+    baseBranch: 'main',
+    onBeforeApply: async (plan) => {
+        for (const p of plan.partitioning.partitions) console.log(`${p.branchName}: ${p.title}`);
+        return true;
+    },
+});
+```
+
+Requires at least 2 commits on the branch. The original branch is replaced by the partition branches.
+
+### `undoCompose(input)`
+
+See [Undo](#undo) below.
+
+## Sources
+
+| Source | Description |
+|---|---|
+| `{ type: 'workdir', stagedOnly?, noUntracked? }` | Collects staged, unstaged, and untracked changes. `stagedOnly: true` limits to the index; `noUntracked: true` skips untracked files. |
+| `{ type: 'branch', name, mergeTarget? }` | Collects `mergeBase(mergeTarget, name) → name` as one combined diff. `mergeTarget` defaults to `'main'`. |
+| `{ type: 'commit-range', branch, from, to }` | Collects a contiguous range on `branch` with per-hunk author info. `from` is **exclusive** (parent of the first commit to include); `to` is **inclusive**. For a single-commit recompose: `from = parent(sha), to = sha`. |
+
+## Targets
+
+| Target | Description |
+|---|---|
+| `{ type: 'head' }` | Commit onto the current branch. Default for `workdir` source. |
+| `{ type: 'branch', name, preserveOriginal? }` | Create a single named branch. `preserveOriginal: true` keeps the source branch. |
+| `{ type: 'branch-replace' }` | Replace the source branch in-place. Only valid with a `branch` source. |
+| `{ type: 'auto', preserveOriginal? }` | Create one branch per concern, optionally subdividing into stacked sub-branches. Default for `branch` source. |
+| `{ type: 'rewrite-range', branch, rangeFrom, rangeTo, preserveSuffix? }` | Rewrite a contiguous range on `branch`. Commits before `rangeFrom` always stay. When `preserveSuffix: true` (default), commits after `rangeTo` are cherry-picked onto the new range tip. Intended for use with `source: 'commit-range'`. Cherry-pick conflicts surface as `GitError('CHERRY_PICK_CONFLICT')`. |
+
+## Options
+
+### `depth`
+
+Controls how many AI calls run and how deeply each reasons.
+
+| Depth | Phases | Best for |
+|---|---|---|
+| `'quick'` | Single `compose-group` call (lightweight prompt) | Small changes, fast feedback |
+| `'balanced'` (default) | `compose-group` + optional `order` | Most use cases |
+| `'deep'` | `analyze` + `group` + `order` + optional `partition` per branch | Large, complex changesets |
+
+### `strategy`
+
+Controls AI aggressiveness at grouping and partitioning time. All settings default to `'balanced'`.
+
+```typescript
+strategy: {
+    grouping: {
+        branchSplitting: 'conservative' | 'balanced' | 'aggressive',
+        commitGranularity: 'consolidated' | 'balanced' | 'granular',
+    },
+    partition: {
+        splitting: 'conservative' | 'balanced' | 'aggressive',
+    },
+}
+```
+
+- `branchSplitting` — how aggressively to separate changes into distinct branches
+- `commitGranularity` — how fine-grained individual commits should be
+- `partition.splitting` — how aggressively to subdivide branches into stacked sub-branches
+
+### `onBeforeApply`
+
+Inspect the plan before any git mutations. Return `false` to abort — the workflow returns the plan without applying it.
+
+```typescript
+onBeforeApply: async (plan) => {
+    console.log(`${plan.branches.length} branches, ${plan.allOrderedCommits.length} commits`);
+    return true;
+}
+```
+
+Equivalent to calling `composePlan` — useful when you want the sugar `compose` path but need a chance to intervene.
+
+### `onBeforeModelCall` / `onAfterModelCall`
+
+Per-call observability hooks. Informational only — the library doesn't interpret the return.
+
+```typescript
+onBeforeModelCall: ({ phase, attempt, maxAttempts, callId }) => {
+    // phase: 'analyze' | 'group' | 'order' | 'partition' | 'compose-group' | 'quick-compose'
+    // callId: stable UUID — correlates with onAfterModelCall and with result.feedbackTargetCallId
+},
+
+onAfterModelCall: ({ phase, attempt, callId, success, durationMs, usage, error, promptVersion }) => {
+    // Fires on both success and error
+},
+```
+
+Consumers build their own per-call telemetry from these. No built-in telemetry is emitted by the library.
+
+### `onBeforePrompt`
+
+Gating hook — run immediately before each `model.generate`. Returning `false` aborts the workflow with `WorkflowError('CANCELLED')`. Use for large-prompt confirmations, cost warnings, org policy checks.
+
+```typescript
+onBeforePrompt: async ({ phase, attempt, tokenEstimate, charCount, messageCount }) => {
+    if (tokenEstimate > 20_000) {
+        return await showUserConfirmation(`Large prompt (${tokenEstimate} tokens). Continue?`);
+    }
+    return true;
+}
+```
+
+### `hunkFilter`
+
+Runs after source collection and before the AI pipeline. Drops hunks the consumer doesn't want the AI to see. Used for AIIgnore globs, org policy filters, etc.
+
+```typescript
+hunkFilter: async (hunks) => hunks.filter(h => !isAiIgnored(h.fileName)),
+```
+
+The filter must preserve the original `index` values on remaining hunks (only drop entries, never renumber). The library rebuilds the safety snapshot to reflect just the filtered subset, so `verifyResultingDiff` still has a correct expectation. `result.hunksFilteredCount` tells the consumer how many were dropped.
+
+### `signing`
+
+GPG signing for produced commits. Typically derived from `git config commit.gpgsign` + `user.signingkey`.
+
+```typescript
+signing: {
+    enabled: true,
+    signingKey: 'ABCD1234',     // optional — passed to commit-tree as -S<key>
+    gpgProgram: '/usr/bin/gpg', // optional — sets GIT_GPG_PROGRAM env
+}
+```
+
+### `authorAttribution`
+
+How the primary author is picked when a commit's hunks come from multiple original authors (recompose / commit-range sources). Ignored when no hunks carry author info (e.g. workdir source).
+
+| Value | Behavior |
+|---|---|
+| `'plurality'` (default) | The author who owns the most hunks wins; all other distinct authors become `Co-authored-by:` trailers |
+| `'first-hunk'` | Use the first hunk's author; other distinct authors become `Co-authored-by:` trailers |
+| function | Fully custom — inspect the hunks and return the primary identity (or `undefined` to use the commit creator's identity). Co-authors are still derived from the union of remaining authors |
+
+### `signal`
+
+Standard `AbortSignal`. Threaded through every AI call, every git operation, and every hook. On abort, the workflow throws `WorkflowError('CANCELLED')`.
+
+### `session` (resumable workflows)
+
+Pass a `ComposeSession` from a prior run to skip already-completed AI phases. Each task checks its own entry in `completedSteps`; if present, the task returns the cached result instead of invoking the model.
+
+Useful when a user ToS-rejected between phases, when a CLI wants to build plans incrementally, or when recovering from a transient failure without redoing the whole pipeline.
+
+```typescript
+// First attempt — aborted between analyze and group
+const first = await composePlan({ git, model, depth: 'deep', ... });
+
+// Retry with the session — analyze is skipped, group/order/partition run fresh
+const second = await composePlan({ git, model, depth: 'deep', session: first.session, ... });
+```
+
+A resumed task contributes no usage and no callIds — telemetry for that phase reflects the original run.
+
+### `promptOverrides`
+
+Per-task prompt overrides for consumers with their own prompt template services (server-driven templates, provider-specific templates, org-tuned wording).
+
+```typescript
+import type { ComposeTaskName, PromptOverride } from '@gitkraken/compose-tools';
+
+promptOverrides: {
+    group: {
+        system: myCustomGroupSystemPrompt,      // replaces the built-in system prompt entirely
+        userPrefix: 'Additional context:\n...', // prepended to the user prompt
+        userSuffix: '\nReminder: prefer short subjects.', // appended
+    },
+    order: {
+        userSuffix: myOrderingHints,
+    },
+}
+```
+
+Task names: `'analyze' | 'group' | 'compose-group' | 'order' | 'partition' | 'quick-compose'`.
+
+The library still runs the same validators against the model response, so a replacement `system` prompt must preserve the output contract the task expects (JSON shape inside `<output>` tags, hunk index constraints, etc.).
+
+### `context`
+
+Optional issue / PR URLs surfaced in commit messages.
+
+```typescript
+context: { issueUrl: 'https://github.com/org/repo/issues/42', pullRequestUrl: '...' }
+```
+
+### `instructions`
+
+Free-form natural-language guidance passed to the AI.
+
+```typescript
+instructions: 'Separate the refactoring from the feature work. Put all test changes in their own commit.'
+```
+
+### `maxRetries`
+
+Per-task retry count when the AI output fails validation. Default `3`.
+
+### `conventions` / `conventionAuthor`
+
+Override auto-detected commit message conventions. By default the library samples recent commits from the repo. Set `conventionAuthor` to sample commits from a specific author only (handy when the current user's style should drive it).
+
+## Result metadata
+
+Every top-level entry point returns an object with these common fields:
+
+| Field | Set on | Meaning |
+|---|---|---|
+| `plan` | all paths | The AI's full analysis / grouping / ordering / branches |
+| `snapshot` | all paths | Safety hash fingerprint of the collection — carry it to apply time |
+| `source` | all paths | `{ type, hunks, commitMessages?, branchName?, baseBranch? }` — the hunks the AI operated on |
+| `session` | all paths | Pass to a subsequent call to resume |
+| `phases` | all paths | `PhaseDetail[]` with `{ name, durationMs, attempts, usage?, modelId?, promptVersion?, callIds? }` per phase |
+| `usage` | all paths | Aggregated `{ inputTokens, outputTokens, ... }` across all AI calls |
+| `diffStats` | sugar / plan | `{ fileCount, hunkCount, addedLines, removedLines }` |
+| `feedbackTargetCallId` | when AI ran | callId of the last validated model response — stamp this on thumbs up/down feedback events |
+| `hunksFilteredCount` | when `hunkFilter` ran | Number of hunks the filter dropped |
+| `commitShas` | apply paths | `{ commitId: sha }` mapping for every commit written |
+| `undoId` | apply paths | Pass to `undoCompose()` to reverse |
+| `partitions` / `partitionGroups` | apply paths with partitioning | Applied partition info |
+
+## Undo
+
+Every operation that mutates the repository returns an `undoId`. The undo system is **surgical** — it reverses only the git mutations that were recorded, rather than restoring a full repository snapshot.
+
+### Undo an operation
+
+```typescript
+import { undoCompose } from '@gitkraken/compose-tools';
+
+const undoResult = await undoCompose({
+    git,
+    undoId: result.undoId,
+    onProgress: (step) => console.log(step),
+});
+
+// undoResult.deletedBranches   — branches removed (reversed a creation)
+// undoResult.recreatedBranches — branches restored (reversed a deletion)
+// undoResult.restoredBranches  — branches moved back to their pre-operation SHA
+// undoResult.restoredHead      — whether HEAD was restored
+// undoResult.restoredWorkdir   — whether the working directory was restored
+// undoResult.warnings          — non-fatal issues encountered
+```
+
+### Safety checks
+
+The undo system validates safety before executing. It refuses to proceed when:
+
+- **Dirty working directory** — uncommitted changes would be at risk. Never force-able.
+- **Branch has new commits** — a branch created by the operation has been modified since. Force-able with `force: true`.
+- **HEAD SHA unreachable** — the pre-operation HEAD commit is no longer reachable (e.g. after garbage collection).
+- **Manifest not found** — the undo ID doesn't correspond to a stored manifest.
+
+### Dry-run validation
+
+```typescript
+import { validateUndoCompose } from '@gitkraken/compose-tools';
+
+const validation = await validateUndoCompose({ git, undoId: result.undoId });
+
+if (!validation.safe) {
+    for (const blocker of validation.blockers) console.error(`Blocked: ${blocker.type} — ${blocker.message}`);
+}
+for (const warning of validation.warnings) console.warn(`Warning: ${warning.type} — ${warning.message}`);
+```
+
+### Force undo
+
+```typescript
+await undoCompose({ git, undoId, force: true });
+```
+
+Downgrades the "branch has new commits" blocker to a warning. The `dirty_workdir` blocker is never force-able.
+
+### List all undo IDs
+
+```typescript
+import { listUndoIds } from '@gitkraken/compose-tools';
+
+const ids = await listUndoIds(git);
+```
+
+Manifests are persisted as git objects under `refs/undo/<id>` — they survive branch operations and are cleaned up automatically when an undo is executed.
+
+## Individual task functions
+
+The AI pipeline is built from composable task functions. Call them individually for custom workflows.
+
+| Function | Purpose |
+|---|---|
+| `analyze(input)` | Identify logical concerns, dependencies, and ordering constraints in a set of hunks |
+| `group(input)` | Group hunks into branches and commits |
+| `order(input)` | Determine optimal commit ordering within each branch |
+| `partition(input)` | Subdivide a branch into stacked sub-branches |
+| `composeGroup(input)` | Combined analyze + group in a single AI call (used by `balanced` / `quick` depths) |
+| `quickCompose(input)` | Full pipeline (analyze + group + order + optional partition) in a single AI call |
+
+Each task accepts an optional `session` to maintain AI conversation context (or to resume from cached `completedSteps`), and returns an updated session in its output. Each task also accepts `promptOverride`, `onBeforeModelCall`, `onAfterModelCall`, `onBeforePrompt`, and `signal` for the same behaviors as the top-level entry points.
+
+## Error handling
+
+| Error | Codes |
+|---|---|
+| `GitError` | `NO_CHANGES`, `BRANCH_NOT_FOUND`, `OPERATION_FAILED`, `SAFETY_CHECK_FAILED`, `CHERRY_PICK_CONFLICT` |
+| `WorkflowError` | `SAFETY_CHECK_FAILED` (workdir changed between plan and apply), `INTERNAL`, `CANCELLED` |
+| `WorkflowInputError` | Invalid workflow input (missing `model`, incompatible source/target combination, etc.) |
+| `TaskInputError` | Invalid task input |
+| `AIError` | AI output failed schema validation after all retries. Code: `VALIDATION_EXHAUSTED` |
+| `ComposeGitPortMissingOpError` | A flow needs a `ComposeGitOps` method the consumer didn't provide and `exec` isn't available either. Has `.op` (missing op name) and `.hint`. |
+
+```typescript
+import { compose, GitError, WorkflowError, AIError } from '@gitkraken/compose-tools';
+
+try {
+    await compose({ git, model });
+} catch (error) {
+    if (error instanceof GitError && error.code === 'NO_CHANGES') {
+        console.log('Nothing to compose');
+    } else if (error instanceof GitError && error.code === 'CHERRY_PICK_CONFLICT') {
+        console.error(`Conflict cherry-picking ${error.detail?.sha}`);
+    } else if (error instanceof AIError) {
+        console.error('AI could not produce valid output after retries');
+    } else if (error instanceof WorkflowError && error.code === 'CANCELLED') {
+        console.log('Operation cancelled');
+    } else if (error instanceof WorkflowError) {
+        console.error(`Workflow failed: ${error.code} — ${error.message}`);
+    }
+}
+```
+
+## Progress tracking
+
+Every top-level entry point accepts an `onProgress` callback that receives a discriminated `ComposeProgressEvent`. Each event carries a default `message`, a relative `weight` (for progress bar math), and a phase-specific payload.
+
+```typescript
+import { compose, defaultPhaseMessages } from '@gitkraken/compose-tools';
+
+const result = await compose({
+    git,
+    model,
+    onProgress: (event) => {
+        // event.phase:   'collecting' | 'compose-grouping' | 'analyzing' | 'grouping' |
+        //                'ordering' | 'partitioning' | 'verifying' | 'applying'
+        // event.message: default English label — use directly or map to localized copy
+        // event.weight:  approximate relative duration for progress math
+        // event.event:   ProgressEvent with { type, attempt, maxAttempts, errors? } (AI phases)
+        // event.detail:  phase-specific string (non-AI phases)
+        // event.branch:  only for 'partitioning', names the branch being subdivided
+    },
+});
+
+// defaultPhaseMessages is exported for consumers who want to remap phase labels
+// for localization without losing the weights.
+```
+
+After completion, `result.phases` has timing and usage per phase:
+
+```typescript
+for (const phase of result.phases) {
+    console.log(`${phase.name}: ${phase.durationMs}ms, ${phase.attempts} attempts`);
+    if (phase.usage) console.log(`  ${phase.usage.inputTokens} in, ${phase.usage.outputTokens} out`);
+    if (phase.callIds) console.log(`  call IDs: ${phase.callIds.join(', ')}`);
+}
+
+console.log(`Total tokens: ${result.usage.inputTokens} in, ${result.usage.outputTokens} out`);
+```
+
+## Contributing
+
+This package follows the monorepo's standard tooling — see the root [CONTRIBUTING.md](../../CONTRIBUTING.md). Local commands:
+
+```bash
+pnpm --filter @gitkraken/compose-tools build
+pnpm --filter @gitkraken/compose-tools typecheck
+pnpm --filter @gitkraken/compose-tools test
+```

package/dist/ai/session.d.ts

@@ -0,0 +1,12 @@
+import { AiMessage } from "@gitkraken/shared-tools";
+
+//#region src/ai/session.d.ts
+interface AiSession {
+  messages: AiMessage[];
+  systemPrompt: string;
+}
+declare function createAiSession(systemPrompt: string): AiSession;
+declare function appendUserMessage<S extends AiSession>(session: S, content: string): S;
+declare function appendAssistantMessage<S extends AiSession>(session: S, content: string): S;
+//#endregion
+export { AiSession, appendAssistantMessage, appendUserMessage, createAiSession };

package/dist/ai/session.js

@@ -0,0 +1 @@
+function e(e){return{messages:[],systemPrompt:e}}function t(e,t){return{...e,messages:[...e.messages,{role:`user`,content:t}]}}function n(e,t){return{...e,messages:[...e.messages,{role:`assistant`,content:t}]}}export{n as appendAssistantMessage,t as appendUserMessage,e as createAiSession};

package/dist/ai/types.d.ts

@@ -0,0 +1,31 @@
+//#region src/ai/types.d.ts
+interface TokenUsage {
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens?: number;
+  cacheWriteTokens?: number;
+  reasoningTokens?: number;
+  cost?: number;
+}
+declare function addUsage(total: TokenUsage, part: TokenUsage): void;
+declare function emptyUsage(): TokenUsage;
+interface PhaseDetail {
+  name: string;
+  durationMs: number;
+  attempts: number;
+  usage?: TokenUsage;
+  /** Which model ran this phase. Set for AI phases, undefined otherwise. */
+  modelId?: string;
+  /** Identifier of the prompt template used for this phase, when a consumer override supplied one. */
+  promptVersion?: string;
+  /** Stable call IDs for each model.generate invocation in this phase (one per attempt). */
+  callIds?: string[];
+}
+interface ProgressEvent {
+  type: 'attempt_start' | 'validation_failed';
+  attempt: number;
+  maxAttempts: number;
+  errors?: string[];
+}
+//#endregion
+export { PhaseDetail, ProgressEvent, TokenUsage, addUsage, emptyUsage };

package/dist/ai/types.js

@@ -0,0 +1 @@
+function e(e,t){e.inputTokens+=t.inputTokens,e.outputTokens+=t.outputTokens,t.cacheReadTokens!=null&&(e.cacheReadTokens=(e.cacheReadTokens??0)+t.cacheReadTokens),t.cacheWriteTokens!=null&&(e.cacheWriteTokens=(e.cacheWriteTokens??0)+t.cacheWriteTokens),t.reasoningTokens!=null&&(e.reasoningTokens=(e.reasoningTokens??0)+t.reasoningTokens),t.cost!=null&&(e.cost=(e.cost??0)+t.cost)}function t(){return{inputTokens:0,outputTokens:0}}export{e as addUsage,t as emptyUsage};

package/dist/cancellation.d.ts

@@ -0,0 +1,20 @@
+//#region src/cancellation.d.ts
+/**
+ * Throws a `WorkflowError('CANCELLED')` if the signal has been aborted.
+ *
+ * Call at workflow phase boundaries so cancellation is observable even when
+ * a consumer's adapter doesn't fully respect the signal on every operation.
+ * Individual `git.exec` and `model.generate` calls should also receive the
+ * signal via their options; this helper is the coarse-grained backstop.
+ */
+declare function throwIfCancelled(signal?: AbortSignal): void;
+/**
+ * Wraps a native `AbortError` (thrown by a signal-aware adapter) in a
+ * `WorkflowError('CANCELLED')`. Rethrows non-cancellation errors unchanged.
+ *
+ * Use to normalize exceptions from `git.exec` or `model.generate` so consumers
+ * only have to check for `WorkflowError` with code `'CANCELLED'`.
+ */
+declare function wrapCancellation<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T>;
+//#endregion
+export { throwIfCancelled, wrapCancellation };

package/dist/cancellation.js

@@ -0,0 +1 @@
+import{WorkflowError as e}from"./errors/workflow.js";function t(t){if(t?.aborted)throw new e(`CANCELLED`,t.reason instanceof Error?t.reason.message:`Operation cancelled`)}function n(t,n){return t.catch(t=>{throw r(t)||n?.aborted?new e(`CANCELLED`,t instanceof Error?t.message:`Operation cancelled`,{cause:t}):t})}function r(e){return e instanceof Error&&(e.name===`AbortError`||e.name===`DOMException`)}export{t as throwIfCancelled,n as wrapCancellation};