@ikon85/agent-workflow-kit 0.20.0 → 0.21.0

package/.agents/skills/project-release/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: project-release
+description: "Preview and prepare one coherent version change across a consumer's profiled packages without duplicating release logic or creating commits, tags, pushes, publishes, or merges."
+---
+
+# Project Release
+
+Prepare a consumer-owned multi-package release through the kit's shared
+SemVer, preview, and transactional apply engine. This skill changes only the
+profiled version files. It does not commit, tag, push, publish, or merge.
+
+## Profile contract
+
+Read `docs/agents/workflow-capabilities.json`. The consumer owns this file and
+its unknown keys. Project Release requires this versioned section:
+
+```json
+{
+  "schemaVersion": 1,
+  "projectRelease": {
+    "versionFiles": [
+      "package.json",
+      "packages/example/package.json"
+    ],
+    "tagPrefix": "v"
+  }
+}
+```
+
+Every `versionFiles` path is repository-relative and must name a JSON file with
+the same current SemVer. Never infer or silently add package files.
+
+## Workflow
+
+1. Run a byte-neutral preview for exactly one Patch, Minor, Major, or explicit
+   SemVer target:
+
+   ```sh
+   node scripts/project-release.mjs preview <patch|minor|major|version>
+   ```
+
+2. Report the structured result: exact current and target version, package
+   count, synchronized files, planned commit/tag actions, confirmation token,
+   and every blocker. Invalid or divergent versions, dirty profiled targets,
+   and an existing target tag block before the first write.
+
+3. Ask the user to confirm the exact target and preview confirmation token.
+   Do not treat a bump recommendation or a prior preview as confirmation.
+
+4. Apply only that still-current preview:
+
+   ```sh
+   node scripts/project-release.mjs apply <patch|minor|major|version> \
+     --confirm <confirmation-token>
+   ```
+
+   Apply re-reads repository facts and every target byte. A stale token,
+   changed target, blocked preview, partial write, or repeated apply fails
+   without a double bump. Partial writes roll back to the original bytes.
+
+5. Inspect the resulting version-file diff, then hand commit, tag, push,
+   publish, and merge to the repository's normal release/landing workflow.
+   Project Release does not commit, tag, push, publish, or merge.
+
+## Safety contract
+
+- Preview is repeatable and byte-neutral.
+- Apply writes only `projectRelease.versionFiles`.
+- Commit and tag entries in preview output are plans, never side effects.
+- Existing tags are never overwritten.
+- No runtime dependency is required beyond Node.js and Git.

package/.agents/skills/setup-workflow/workflow-overview.md

@@ -21,6 +21,7 @@ Use this section as the entry-point map for agent-assisted work. The individual
 - **Preview or restore consumer-owned memories:** use `memory-lifecycle` to classify every configured path without writing, then apply an explicitly approved collision-safe restore with a content-free receipt.
 - **Finished slice:** use `wrapup` to prepare the branch, PR, and cleanup steps your repo expects.
 - **Kit release:** use `kit-release` to derive the shipped delta, confirm Semver, regenerate the manifest, run all gates, and then hand landing to `wrapup`.
+- **Consumer project release:** use `project-release` to preview and transactionally prepare one coherent version across the package files named by the consumer-owned capability profile.
 - **Kit update:** use `kit-update` to preview and transactionally apply a parity-verified scoped release without overwriting local modifications.
 - **A huge, foggy effort, too big for one session:** use `wayfinder` — it charts it as a shared map of investigation tickets, resolving one per session.
 

package/.claude/skills/project-release/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: project-release
+description: "Preview and prepare one coherent version change across a consumer's profiled packages without duplicating release logic or creating commits, tags, pushes, publishes, or merges."
+---
+
+# Project Release
+
+Prepare a consumer-owned multi-package release through the kit's shared
+SemVer, preview, and transactional apply engine. This skill changes only the
+profiled version files. It does not commit, tag, push, publish, or merge.
+
+## Profile contract
+
+Read `docs/agents/workflow-capabilities.json`. The consumer owns this file and
+its unknown keys. Project Release requires this versioned section:
+
+```json
+{
+  "schemaVersion": 1,
+  "projectRelease": {
+    "versionFiles": [
+      "package.json",
+      "packages/example/package.json"
+    ],
+    "tagPrefix": "v"
+  }
+}
+```
+
+Every `versionFiles` path is repository-relative and must name a JSON file with
+the same current SemVer. Never infer or silently add package files.
+
+## Workflow
+
+1. Run a byte-neutral preview for exactly one Patch, Minor, Major, or explicit
+   SemVer target:
+
+   ```sh
+   node scripts/project-release.mjs preview <patch|minor|major|version>
+   ```
+
+2. Report the structured result: exact current and target version, package
+   count, synchronized files, planned commit/tag actions, confirmation token,
+   and every blocker. Invalid or divergent versions, dirty profiled targets,
+   and an existing target tag block before the first write.
+
+3. Ask the user to confirm the exact target and preview confirmation token.
+   Do not treat a bump recommendation or a prior preview as confirmation.
+
+4. Apply only that still-current preview:
+
+   ```sh
+   node scripts/project-release.mjs apply <patch|minor|major|version> \
+     --confirm <confirmation-token>
+   ```
+
+   Apply re-reads repository facts and every target byte. A stale token,
+   changed target, blocked preview, partial write, or repeated apply fails
+   without a double bump. Partial writes roll back to the original bytes.
+
+5. Inspect the resulting version-file diff, then hand commit, tag, push,
+   publish, and merge to the repository's normal release/landing workflow.
+   Project Release does not commit, tag, push, publish, or merge.
+
+## Safety contract
+
+- Preview is repeatable and byte-neutral.
+- Apply writes only `projectRelease.versionFiles`.
+- Commit and tag entries in preview output are plans, never side effects.
+- Existing tags are never overwritten.
+- No runtime dependency is required beyond Node.js and Git.

package/.claude/skills/setup-workflow/workflow-overview.md

@@ -21,6 +21,7 @@ Use this section as the entry-point map for agent-assisted work. The individual
 - **Preview or restore consumer-owned memories:** use `memory-lifecycle` to classify every configured path without writing, then apply an explicitly approved collision-safe restore with a content-free receipt.
 - **Finished slice:** use `wrapup` to prepare the branch, PR, and cleanup steps your repo expects.
 - **Kit release:** use `kit-release` to derive the shipped delta, confirm Semver, regenerate the manifest, run all gates, and then hand landing to `wrapup`.
+- **Consumer project release:** use `project-release` to preview and transactionally prepare one coherent version across the package files named by the consumer-owned capability profile.
 - **Kit update:** use `kit-update` to preview and transactionally apply a parity-verified scoped release without overwriting local modifications.
 - **A huge, foggy effort, too big for one session:** use `wayfinder` — it charts it as a shared map of investigation tickets, resolving one per session.
 

package/.claude/skills/skill-manifest.json

@@ -395,6 +395,16 @@
       ],
       "provenance": "own"
     },
+    "project-release": {
+      "class": "generic",
+      "publish": true,
+      "entryPoint": true,
+      "surfaces": [
+        "claude",
+        "codex"
+      ],
+      "provenance": "own"
+    },
     "kit-update": {
       "class": "generic",
       "publish": true,

package/PROVENANCE.md

@@ -33,7 +33,7 @@ carries Chase's `THIRD-PARTY-NOTICES.md`.
 
 retro, wrapup, spec-self-critique, board-to-waves, verify-spike, decision-gate,
 codex-adapter-sync, setup-pre-commit, code-review, orchestrate-wave,
-census-update, memory-lifecycle — covered by the root LICENSE.
+census-update, memory-lifecycle, project-release — covered by the root LICENSE.
 `setup-pre-commit` was rewritten from Matt Pocock's husky-based skill to a
 zero-dep native git `core.hooksPath` scaffold; nothing of the original
 mechanic remains (courtesy attribution).

package/README.md

@@ -332,6 +332,16 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.21.0
+
+- added: `.agents/skills/project-release/SKILL.md`
+- added: `.claude/skills/project-release/SKILL.md`
+- added: `scripts/project-release.mjs`
+- added: `src/lib/release-apply.mjs`
+- changed: `.agents/skills/setup-workflow/workflow-overview.md`
+- changed: `.claude/skills/setup-workflow/workflow-overview.md`
+- changed: `scripts/kit-release.mjs`
+
 ### 0.20.0
 
 - added: `.claude/hooks/branch-context.py`
@@ -652,12 +662,13 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## What's in the box
 
-**41 skills** (Router: ask-matt — "which skill/flow fits?" · Plan: grill-me,
+**42 skills** (Router: ask-matt — "which skill/flow fits?" · Plan: grill-me,
 grill-with-docs, to-prd, to-issues, board-to-waves, triage, spec-self-critique,
 verify-spike, decision-gate, scale-check, to-waves, wayfinder, research · Execute: tdd, prototype, implement, orchestrate-wave ·
 Design/diagnose/refactor streams: diagnose, zoom-out,
 improve-codebase-architecture, codebase-design, domain-modeling, security-audit · Land: wrapup,
-resolving-merge-conflicts, code-review, local-ci, git-worktree-recover, kit-release · Learn: retro, audit-skills, write-a-skill · Setup:
+resolving-merge-conflicts, code-review, local-ci, git-worktree-recover, kit-release,
+project-release · Learn: retro, audit-skills, write-a-skill · Setup:
 setup-workflow, git-guardrails, setup-pre-commit · Codex cross-model: grill-me-codex,
 grill-with-docs-codex, codex-review, codex-build),
 installed for both surfaces — `.claude/skills`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.20.0",
+  "kitVersion": "0.21.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -379,6 +379,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".agents/skills/project-release/SKILL.md",
+      "kind": "skill",
+      "ownerSkill": "project-release",
+      "surface": "codex",
+      "sha256": "5aa0b0827e8691334c30608df8506c756455ecebcc460efa140889297cf02ed5",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".agents/skills/prototype/LOGIC.md",
       "kind": "skill",
@@ -609,7 +618,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "codex",
-      "sha256": "c522a7de1b8eaa827a72880651a94aca6d066687e8c21b789d9008e3321f7362",
+      "sha256": "bc4db6413135ad9056cc63691cb823a9b198ad47538f292b37fcbb915477a716",
       "mode": 420,
       "origin": "kit"
     },
@@ -1405,6 +1414,15 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": ".claude/skills/project-release/SKILL.md",
+      "kind": "skill",
+      "ownerSkill": "project-release",
+      "surface": "claude",
+      "sha256": "5aa0b0827e8691334c30608df8506c756455ecebcc460efa140889297cf02ed5",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": ".claude/skills/prototype/LOGIC.md",
       "kind": "skill",
@@ -1653,7 +1671,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "claude",
-      "sha256": "c522a7de1b8eaa827a72880651a94aca6d066687e8c21b789d9008e3321f7362",
+      "sha256": "bc4db6413135ad9056cc63691cb823a9b198ad47538f292b37fcbb915477a716",
       "mode": 420,
       "origin": "kit"
     },
@@ -2028,7 +2046,7 @@
     {
       "path": "scripts/kit-release.mjs",
       "kind": "script",
-      "sha256": "d3148aab63fa670c0a3407d2816d287b7cdeaa130588fb55b6075217da95d3d3",
+      "sha256": "3c86eb5fc4b2071b423d87f023ba4c3f778ffe716a2603dcecdbe4e83ec1b8df",
       "mode": 420,
       "origin": "kit"
     },
@@ -2102,6 +2120,13 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": "scripts/project-release.mjs",
+      "kind": "script",
+      "sha256": "6c08cf16f97fdbc0172041c64109e859b1f073862e9f8edc2accbafd97b33843",
+      "mode": 493,
+      "origin": "kit"
+    },
     {
       "path": "scripts/release-delta-guard.mjs",
       "kind": "script",
@@ -2165,6 +2190,13 @@
       "mode": 493,
       "origin": "kit"
     },
+    {
+      "path": "src/lib/release-apply.mjs",
+      "kind": "script",
+      "sha256": "d9b3bd07c88629c570d8a58f1d91d1cdac1457470cee973f99e186d9630efb03",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": "src/lib/release-preview.mjs",
       "kind": "script",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Portable AI-agent workflow skills (plan → execute → land → learn) for Claude Code & Codex — grilling, TDD, diagnosis, two-axis code review, cross-model Codex review, design & domain-modeling, plus a skill router (ask-matt). npx init/update/diff/uninstall.",
   "type": "module",
   "bin": {

package/scripts/kit-release.mjs

@@ -5,19 +5,15 @@ import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
+import { applyProjectRelease } from '../src/lib/release-apply.mjs';
+import { previewProjectRelease } from '../src/lib/release-preview.mjs';
+import { nextVersion } from '../src/lib/semver.mjs';
 import { buildKit } from './build-kit.mjs';
 import { checkReleaseDelta } from './release-delta-guard.mjs';
 
 const exec = promisify(execFile);
 
-export function nextVersion(version, bump) {
-  const parts = version.split('.').map(Number);
-  if (parts.length !== 3 || parts.some(Number.isNaN)) throw new Error(`invalid semver: ${version}`);
-  if (bump === 'major') return `${parts[0] + 1}.0.0`;
-  if (bump === 'minor') return `${parts[0]}.${parts[1] + 1}.0`;
-  if (bump === 'patch') return `${parts[0]}.${parts[1]}.${parts[2] + 1}`;
-  throw new Error(`invalid bump: ${bump}`);
-}
+export { nextVersion };
 
 function note(version, delta) {
   const lines = ['added', 'removed', 'changed'].flatMap((kind) =>
@@ -30,8 +26,17 @@ async function updateMetadata(repoRoot, targetVersion, delta) {
   const pkg = JSON.parse(await readFile(packagePath, 'utf8'));
   const resumed = pkg.version === targetVersion;
   if (!resumed) {
-    pkg.version = targetVersion;
-    await writeFile(packagePath, `${JSON.stringify(pkg, null, 2)}\n`);
+    const preview = await previewProjectRelease({
+      consumerRoot: repoRoot,
+      profile: { versionFiles: ['package.json'], tagPrefix: 'v' },
+      requestedVersion: targetVersion,
+      repositoryFacts: { dirtyPaths: [], existingTags: [] },
+    });
+    await applyProjectRelease({
+      consumerRoot: repoRoot,
+      preview,
+      confirmation: preview.confirmation,
+    });
   }
   const readmePath = join(repoRoot, 'README.md');
   const readme = await readFile(readmePath, 'utf8');

package/scripts/project-release.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+import { execFileSync } from 'node:child_process';
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { applyProjectRelease, assertSafeReleaseTargets } from '../src/lib/release-apply.mjs';
+import { loadProjectReleaseProfile, previewProjectRelease } from '../src/lib/release-preview.mjs';
+
+function gitOutput(consumerRoot, args) {
+  return execFileSync('git', args, { cwd: consumerRoot, encoding: 'utf8' });
+}
+
+export function readRepositoryFacts(consumerRoot, run = gitOutput) {
+  const records = run(
+    consumerRoot, ['status', '--porcelain=v1', '-z', '--untracked-files=all'],
+  ).split('\0').filter(Boolean);
+  const dirtyPaths = [];
+  for (let index = 0; index < records.length; index += 1) {
+    const record = records[index];
+    dirtyPaths.push(record.slice(3));
+    if (record[0] === 'R' || record[0] === 'C'
+        || record[1] === 'R' || record[1] === 'C') index += 1;
+  }
+  const existingTags = run(consumerRoot, ['tag', '--list'])
+    .split('\n').filter(Boolean);
+  return { dirtyPaths, existingTags };
+}
+
+function argument(args, name) {
+  const index = args.indexOf(name);
+  return index < 0 ? null : args[index + 1];
+}
+
+export async function runProjectRelease(options) {
+  const {
+    consumerRoot, args,
+    repositoryFacts = readRepositoryFacts(consumerRoot),
+    output = console.log,
+  } = options;
+  const [command, requestedVersion] = args;
+  if (!['preview', 'apply'].includes(command) || !requestedVersion) {
+    throw new Error('usage: project-release <preview|apply> <patch|minor|major|version> [--confirm <token>]');
+  }
+  const profile = await loadProjectReleaseProfile(consumerRoot);
+  await assertSafeReleaseTargets(consumerRoot, profile.versionFiles);
+  const preview = await previewProjectRelease({
+    consumerRoot, profile, requestedVersion, repositoryFacts,
+  });
+  if (command === 'preview') {
+    output(JSON.stringify(preview));
+    return preview;
+  }
+  const result = await applyProjectRelease({
+    consumerRoot,
+    preview,
+    confirmation: argument(args, '--confirm'),
+  });
+  output(JSON.stringify(result));
+  return result;
+}
+
+async function main() {
+  await runProjectRelease({ consumerRoot: process.cwd(), args: process.argv.slice(2) });
+}
+
+if (resolve(process.argv[1] ?? '') === fileURLToPath(import.meta.url)) {
+  main().catch((error) => {
+    console.error(`project-release: ${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/scripts/test_skill_publish_audit.py

@@ -15,8 +15,9 @@ Deny classes (each with a negative fixture below):
   - residual issue refs (`#NNN`) / hard-rule refs (`HRn`)
   - unresolvable provenance cross-refs (`ADR-####` / `Welle N` / `Slice N`),
     with a documented fixture/example allowlist (PROVENANCE_FIXTURE_SUFFIXES)
-  - `../` cross-skill reaches (skills/scripts/docs — NOT the CLI src, which
-    legitimately imports `../lib/…`)
+  - `../` cross-skill reaches (skills/scripts/docs — except a static top-level
+    script import into the shipped `src/lib` deep-module seam, and CLI `src`
+    imports which legitimately use `../lib/…`)
   - bare owner/maintainer names OUTSIDE the generated credit files
   - high-entropy secrets (after exempting the manifest's own sha256 file-hashes)
 
@@ -92,18 +93,27 @@ BARE_PRIVATE = [
     ("maintainer name", re.compile(r"\bNiko\b")),
 ]
 PARENT_REF = re.compile(r"\.\./")
+SHIPPED_SRC_IMPORT = re.compile(
+    r"^\s*import\b.*\bfrom\s+['\"]\.\./src/lib/[a-z0-9-]+\.mjs['\"];\s*$"
+)
 LONG_HEX = re.compile(r"\b[0-9a-f]{40,}\b")
 GH_TOKEN = re.compile(r"\b(?:ghp|gho|ghu|ghs|github_pat)_[A-Za-z0-9_]{20,}")
 
 
 def _parent_ref_scan_text(rel: str, text: str) -> str:
-    if rel != "scripts/loc_offender_core.py":
-        return text
-    # This is the portable path-traversal guard itself, not a cross-skill reach.
-    return "\n".join(
-        line for line in text.splitlines()
-        if 'p.startswith("../")' not in line and '"/../" in p' not in line
-    )
+    lines = text.splitlines()
+    if rel == "scripts/loc_offender_core.py":
+        # This is the portable path-traversal guard itself, not a cross-skill reach.
+        lines = [
+            line for line in lines
+            if 'p.startswith("../")' not in line and '"/../" in p' not in line
+        ]
+    if rel.startswith("scripts/") and rel.endswith(".mjs"):
+        # Top-level shipped scripts may consume the kit's shipped deep modules.
+        # The exact static-import shape stays inside the bundle root; every other
+        # parent reach remains visible to the deny rule below.
+        lines = [line for line in lines if not SHIPPED_SRC_IMPORT.match(line)]
+    return "\n".join(lines)
 
 
 def _known_hashes(root: Path) -> set:
@@ -230,6 +240,15 @@ class AuditCatchesEachClass(unittest.TestCase):
     def test_parent_ref(self):
         self.assertTrue(any("parent" in v for v in self._body("[x](../../other/SKILL.md)")))
 
+    def test_static_script_import_into_shipped_src_lib_is_allowed(self):
+        script = self.dir / "scripts/release.mjs"
+        script.parent.mkdir()
+        script.write_text(
+            "import { run } from '../src/lib/release-core.mjs';\nrun();\n",
+            encoding="utf-8",
+        )
+        self.assertEqual(audit_dir(self.dir), [])
+
     def test_bare_owner_in_body(self):
         self.assertTrue(any("iKon85" in v for v in self._body("authored by iKon85")))
 

package/src/lib/bundle.mjs

@@ -48,9 +48,12 @@ export const HELPER_FILES = [
   { path: 'scripts/release-parity.mjs', kind: 'script', mode: 0o644 },
   { path: 'scripts/release-state.mjs', kind: 'script', mode: 0o644 },
   // Consumer-owned project release profiles use these read-only shared
-  // primitives before any apply/commit/tag action is allowed.
+  // primitives before any apply/commit/tag action is allowed. The thin CLI
+  // owns only repository-fact collection and delegates to the same engine.
   { path: 'src/lib/semver.mjs', kind: 'script', mode: 0o644 },
   { path: 'src/lib/release-preview.mjs', kind: 'script', mode: 0o644 },
+  { path: 'src/lib/release-apply.mjs', kind: 'script', mode: 0o644 },
+  { path: 'scripts/project-release.mjs', kind: 'script', mode: 0o755 },
   // GitHub-consumer automation: invokes the existing update command, then owns
   // only the stable tested branch/pull-request upsert.
   { path: 'scripts/kit-update-pr.mjs', kind: 'script', mode: 0o755 },

package/src/lib/release-apply.mjs

@@ -0,0 +1,81 @@
+import { createHash } from 'node:crypto';
+import { lstat, readFile, realpath } from 'node:fs/promises';
+import { isAbsolute, join, relative, resolve } from 'node:path';
+import { writeAtomic } from './atomicWrite.mjs';
+
+const sha256 = (body) => createHash('sha256').update(body).digest('hex');
+
+async function readSnapshot(consumerRoot, snapshot) {
+  return Promise.all(snapshot.map(async ({ path }) => {
+    const body = await readFile(join(consumerRoot, path), 'utf8');
+    return { path, body, version: JSON.parse(body).version, sha256: sha256(body) };
+  }));
+}
+
+const escapes = (root, target) => {
+  const path = relative(root, target);
+  return path === '..' || path.startsWith(`..${process.platform === 'win32' ? '\\' : '/'}`)
+    || isAbsolute(path);
+};
+
+export async function assertSafeReleaseTargets(consumerRoot, paths) {
+  const canonicalRoot = await realpath(consumerRoot);
+  for (const path of paths) {
+    const target = resolve(consumerRoot, path);
+    if (isAbsolute(path) || escapes(resolve(consumerRoot), target)) {
+      throw new Error(`release target is outside consumer root: ${path}`);
+    }
+    if ((await lstat(target)).isSymbolicLink()) {
+      throw new Error(`symlinked release target is not allowed: ${path}`);
+    }
+    if (escapes(canonicalRoot, await realpath(target))) {
+      throw new Error(`release target resolves outside consumer root: ${path}`);
+    }
+  }
+}
+
+export async function applyProjectRelease(options) {
+  const { consumerRoot, preview, confirmation } = options;
+  const write = options.write ?? writeAtomic;
+  if (preview.status !== 'ready') throw new Error('release preview is blocked');
+  if (confirmation !== preview.confirmation) {
+    throw new Error('release confirmation does not match preview');
+  }
+  await assertSafeReleaseTargets(
+    consumerRoot, preview.snapshot.map(({ path }) => path),
+  );
+  const current = await readSnapshot(consumerRoot, preview.snapshot);
+  if (current.every(({ version }) => version === preview.summary.targetVersion)) {
+    throw new Error(`release already prepared at ${preview.summary.targetVersion}`);
+  }
+  for (const expected of preview.snapshot) {
+    const actual = current.find(({ path }) => path === expected.path);
+    if (actual.sha256 !== expected.sha256) {
+      throw new Error(`release target changed after preview: ${expected.path}`);
+    }
+  }
+  const version = preview.summary.targetVersion;
+  const candidates = current.map((file) => {
+    const body = JSON.parse(file.body);
+    body.version = version;
+    return { ...file, next: `${JSON.stringify(body, null, 2)}\n` };
+  });
+  const written = [];
+  try {
+    for (const file of candidates) {
+      await write(join(consumerRoot, file.path), file.next);
+      written.push(file);
+    }
+  } catch (error) {
+    for (const file of written.reverse()) {
+      await writeAtomic(join(consumerRoot, file.path), file.body);
+    }
+    throw error;
+  }
+  return {
+    status: 'prepared',
+    version,
+    updated: candidates.map(({ path }) => path),
+    plannedTag: preview.actions.find(({ type }) => type === 'tag').name,
+  };
+}