@ikon85/agent-workflow-kit 0.34.0 → 0.34.1

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

@@ -1,13 +1,14 @@
 ---
 name: kit-release
-description: "Prepare a verified release PR for agent-workflow-kit, delegate landing to wrapup, then monitor the trusted post-merge publishing flow through npm/GitHub parity."
+description: "Prepare and integrate a verified agent-workflow-kit release, then record separately confirmed publication intent with an annotated version tag and monitor npm/GitHub parity."
 ---
 
 # Kit Release
 
 Prepare a release deterministically. This skill owns the shipped-delta decision,
-metadata preparation, and verification. It does not implement commit, push, PR,
-merge, registry publishing, tags, or release creation.
+metadata preparation, verification, and the separate post-merge publication
+gate. It delegates commit, branch push, PR, merge, and cleanup to wrapup. It
+never publishes to a registry or creates a GitHub release directly.
 
 ## Workflow
 
@@ -42,7 +43,20 @@ merge, registry publishing, tags, or release creation.
    `scripts/wrapup-land.py` exclusively own commit, push, PR creation, merge,
    and cleanup. Do not reproduce those operations here.
 
-5. After merge, monitor the `release.yml` workflow and inspect its externally
+5. After merge, report the exact integrated version and commit as
+   `awaiting-tag`. Merging integrates the prepared release; it cannot start
+   publication. Ask the user for a second, explicit confirmation to publish
+   that exact `v<version>`. The earlier Semver confirmation authorized metadata
+   preparation, not publication.
+
+6. After that confirmation, verify that the package version on current
+   `origin/main` is exactly `<version>`. Create a matching annotated
+   `v<version>` tag on that commit and push only that tag. A lightweight tag,
+   mismatching version, or commit outside canonical `main` is invalid release
+   intent. Never infer a tag target, move an existing tag, or tag an unmerged
+   commit.
+
+7. Monitor the tag-triggered `release.yml` workflow and inspect its externally
    reconstructable state:
 
    ```sh
@@ -56,6 +70,17 @@ merge, registry publishing, tags, or release creation.
    release asset have identical version, manifest hash, and tarball integrity.
    The release is complete only at `released`.
 
+   Manual dispatch is recovery only. It requires the explicit existing
+   annotated tag and runs the same idempotent reconciler:
+
+   ```sh
+   gh workflow run release.yml -f tag=v<version>
+   ```
+
+   Use it only after reconstructing the release state for that tag. Never use
+   dispatch as the normal publication route or substitute a new version for a
+   partial release.
+
    The registry identity is **`@ikon85/agent-workflow-kit`**. The unscoped
    `agent-workflow-kit` package is owned by another publisher and must never be
    queried, published, or treated as this repository's release.

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

@@ -1,13 +1,14 @@
 ---
 name: kit-release
-description: "Prepare a verified release PR for agent-workflow-kit, delegate landing to wrapup, then monitor the trusted post-merge publishing flow through npm/GitHub parity."
+description: "Prepare and integrate a verified agent-workflow-kit release, then record separately confirmed publication intent with an annotated version tag and monitor npm/GitHub parity."
 ---
 
 # Kit Release
 
 Prepare a release deterministically. This skill owns the shipped-delta decision,
-metadata preparation, and verification. It does not implement commit, push, PR,
-merge, registry publishing, tags, or release creation.
+metadata preparation, verification, and the separate post-merge publication
+gate. It delegates commit, branch push, PR, merge, and cleanup to wrapup. It
+never publishes to a registry or creates a GitHub release directly.
 
 ## Workflow
 
@@ -42,7 +43,20 @@ merge, registry publishing, tags, or release creation.
    `scripts/wrapup-land.py` exclusively own commit, push, PR creation, merge,
    and cleanup. Do not reproduce those operations here.
 
-5. After merge, monitor the `release.yml` workflow and inspect its externally
+5. After merge, report the exact integrated version and commit as
+   `awaiting-tag`. Merging integrates the prepared release; it cannot start
+   publication. Ask the user for a second, explicit confirmation to publish
+   that exact `v<version>`. The earlier Semver confirmation authorized metadata
+   preparation, not publication.
+
+6. After that confirmation, verify that the package version on current
+   `origin/main` is exactly `<version>`. Create a matching annotated
+   `v<version>` tag on that commit and push only that tag. A lightweight tag,
+   mismatching version, or commit outside canonical `main` is invalid release
+   intent. Never infer a tag target, move an existing tag, or tag an unmerged
+   commit.
+
+7. Monitor the tag-triggered `release.yml` workflow and inspect its externally
    reconstructable state:
 
    ```sh
@@ -56,6 +70,17 @@ merge, registry publishing, tags, or release creation.
    release asset have identical version, manifest hash, and tarball integrity.
    The release is complete only at `released`.
 
+   Manual dispatch is recovery only. It requires the explicit existing
+   annotated tag and runs the same idempotent reconciler:
+
+   ```sh
+   gh workflow run release.yml -f tag=v<version>
+   ```
+
+   Use it only after reconstructing the release state for that tag. Never use
+   dispatch as the normal publication route or substitute a new version for a
+   partial release.
+
    The registry identity is **`@ikon85/agent-workflow-kit`**. The unscoped
    `agent-workflow-kit` package is owned by another publisher and must never be
    queried, published, or treated as this repository's release.

package/README.md

@@ -24,8 +24,10 @@ changes.
 Maintainers prepare releases with `/kit-release`. It derives the shipped delta
 from a fresh manifest, recommends Semver, applies only the confirmed target,
 regenerates the checked-in manifest, and runs the full test and pack gates.
-Landing remains owned by `/wrapup`; publishing the matching npm package and
-GitHub release happens only through the configured post-merge release flow.
+Landing remains owned by `/wrapup` and only integrates the prepared version.
+After a separate publication confirmation, a matching annotated `v<version>`
+tag on canonical `main` starts the trusted publish flow. Manual dispatch
+requires an explicit existing tag and only reconciles an incomplete release.
 
 These are the skills, helper scripts, and conventions one team actually uses to
 take work from a vague idea to a merged, verified PR with [Claude Code] and
@@ -385,6 +387,12 @@ the old way. Decision record:
 
 ## Release notes
 
+### 0.34.1
+
+- changed: `.agents/skills/kit-release/SKILL.md`
+- changed: `.claude/skills/kit-release/SKILL.md`
+- changed: `scripts/release-state.mjs`
+
 ### 0.34.0
 
 - added: `src/commands/routing-policy-update.mjs`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.34.0",
+  "kitVersion": "0.34.1",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -367,7 +367,7 @@
       "ownerSkill": "kit-release",
       "surface": "codex",
       "installRole": "maintainer",
-      "sha256": "d05a4059a19816ff302c119f797f1ea2b71554ecffac7a8f0b919cfe5517d940",
+      "sha256": "168879858199f19f124e8bc3722f430f65b44b1fb6409d9c2112e6ec02d9b561",
       "mode": 420,
       "origin": "kit"
     },
@@ -1679,7 +1679,7 @@
       "ownerSkill": "kit-release",
       "surface": "claude",
       "installRole": "maintainer",
-      "sha256": "d05a4059a19816ff302c119f797f1ea2b71554ecffac7a8f0b919cfe5517d940",
+      "sha256": "168879858199f19f124e8bc3722f430f65b44b1fb6409d9c2112e6ec02d9b561",
       "mode": 420,
       "origin": "kit"
     },
@@ -2671,7 +2671,7 @@
       "path": "scripts/release-state.mjs",
       "kind": "script",
       "installRole": "consumer",
-      "sha256": "2aae056a8e0e945dbf68298236719c78e22f13dbd8f0c3466b969355d3809058",
+      "sha256": "23b4ffc77e9b499587fa563d067b1df9ae81b87a654d636281c7d139e5842687",
       "mode": 420,
       "origin": "kit"
     },

package/docs/adr/0004-release-intent-is-a-version-tag.md

@@ -0,0 +1,42 @@
+# Release intent is an explicit version tag
+
+Status: accepted (2026-07-22, issue #204)
+
+The release workflow currently publishes whenever a merge to `main` changes
+`package.json`. That keeps the canonical branch and npm close together, but it
+also makes an ordinary merge an irreversible public action whose consequence is
+not visible in the merge affordance. A failed post-publish readback can further
+make the run red after npm has already accepted the version.
+
+We decided that integration and publication are separate transitions:
+
+1. Merging a prepared version into `main` integrates it but does not publish it.
+2. A matching annotated `v<version>` tag on that `main` commit records Release
+   intent and starts the normal publish workflow.
+3. The workflow validates tag, package version, canonical-branch ancestry,
+   artifact integrity, and tests before publishing.
+4. A manual dispatch is a recovery/reconciliation route for one explicit tag,
+   never the ordinary release trigger.
+5. Publication completes only when npm and the GitHub release are both visible
+   and match the local version, manifest, and tarball. Eventual-consistency
+   readbacks use bounded retry and preserve an externally reconstructable state.
+
+## Considered options
+
+- **Merge-triggered publishing:** rejected because merge acceptance and
+  irreversible publication remain one implicit action.
+- **Manual dispatch as the normal route:** rejected because the release identity
+  is easier to forget and less durable than a version tag.
+- **PR label or commit marker:** rejected because it introduces hidden release
+  semantics without giving the publication a first-class Git identity.
+- **Environment approval on the merge-triggered workflow:** rejected as the
+  primary contract because it adds a UI gate but still does not represent the
+  approved version as a durable release object.
+
+## Consequences
+
+- A prepared version may temporarily exist on `main` in an `awaiting-tag` state.
+- An AFK wave may create its own tag after all pre-authorized landing gates pass;
+  the next program wave still requires separate authorization.
+- Reruns reconcile the same tag and never infer that a red workflow means
+  nothing was published.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.34.0",
+  "version": "0.34.1",
   "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.test.mjs

@@ -1,12 +1,170 @@
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
 import { mkdtemp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
 import { nextVersion, prepareRelease } from './kit-release.mjs';
 
 const REPO = join(dirname(fileURLToPath(import.meta.url)), '..');
+const exec = promisify(execFile);
+
+async function releaseWorkflow() {
+  return readFile(join(REPO, '.github/workflows/release.yml'), 'utf8');
+}
+
+function workflowRunScript(workflow, stepName) {
+  const lines = workflow.split('\n');
+  const nameIndex = lines.findIndex((line) => line.trim() === `- name: ${stepName}`);
+  assert.notEqual(nameIndex, -1, `workflow step not found: ${stepName}`);
+  const runIndex = lines.findIndex(
+    (line, index) => index > nameIndex && line.trim() === 'run: |',
+  );
+  assert.notEqual(runIndex, -1, `run block not found for workflow step: ${stepName}`);
+  const indent = lines[runIndex].match(/^\s*/)[0].length + 2;
+  const body = [];
+  for (const line of lines.slice(runIndex + 1)) {
+    if (line.trim() && line.match(/^\s*/)[0].length < indent) break;
+    body.push(line.slice(indent));
+  }
+  return body.join('\n');
+}
+
+async function git(runCwd, args, options = {}) {
+  return exec('git', args, { cwd: runCwd, ...options });
+}
+
+async function releaseIntentFixture({
+  packageVersion = '1.2.3',
+  annotated = true,
+  onMain = true,
+  mainAhead = false,
+} = {}) {
+  const root = await mkdtemp(join(tmpdir(), 'kit-release-intent-'));
+  const origin = join(root, 'origin.git');
+  const repo = join(root, 'repo');
+  await git(root, ['init', '--bare', origin]);
+  await git(root, ['init', '--initial-branch=main', repo]);
+  await git(repo, ['config', 'user.name', 'Release Test']);
+  await git(repo, ['config', 'user.email', 'release-test@example.invalid']);
+  await writeFile(join(repo, 'package.json'), `${JSON.stringify({
+    name: '@ikon85/agent-workflow-kit',
+    version: packageVersion,
+  }, null, 2)}\n`);
+  await git(repo, ['add', 'package.json']);
+  await git(repo, ['commit', '-m', 'release fixture']);
+  await git(repo, ['remote', 'add', 'origin', origin]);
+  await git(repo, ['push', '-u', 'origin', 'main']);
+  if (!onMain) {
+    await git(repo, ['checkout', '-b', 'not-main']);
+    await writeFile(join(repo, 'outside-main.txt'), 'not canonical\n');
+    await git(repo, ['add', 'outside-main.txt']);
+    await git(repo, ['commit', '-m', 'outside main']);
+  }
+  const tag = 'v1.2.3';
+  await git(repo, annotated
+    ? ['tag', '-a', tag, '-m', `Release ${tag}`]
+    : ['tag', tag]);
+  if (mainAhead) {
+    await writeFile(join(repo, 'after-release.txt'), 'main moved\n');
+    await git(repo, ['add', 'after-release.txt']);
+    await git(repo, ['commit', '-m', 'move canonical main']);
+    await git(repo, ['push', 'origin', 'main']);
+  }
+  return { root, repo, tag };
+}
+
+async function validateReleaseIntent(fixture, releaseTag = fixture.tag) {
+  const workflow = await releaseWorkflow();
+  const script = workflowRunScript(workflow, 'Validate release intent');
+  const output = join(fixture.root, 'github-output');
+  try {
+    const result = await exec('bash', ['-euo', 'pipefail', '-c', script], {
+      cwd: fixture.repo,
+      env: {
+        ...process.env,
+        GITHUB_OUTPUT: output,
+        RELEASE_TAG: releaseTag,
+      },
+    });
+    return { ...result, output: await readFile(output, 'utf8') };
+  } catch (error) {
+    return { error, stderr: error.stderr ?? '', stdout: error.stdout ?? '' };
+  }
+}
+
+test('release workflow treats an annotated version tag as normal intent and merge as integration only', async () => {
+  const workflow = await releaseWorkflow();
+  assert.match(workflow, /push:\s*\n\s+tags:\s*\n\s+- ['"]v\*\.\*\.\*['"]/);
+  assert.doesNotMatch(workflow, /push:\s*\n\s+branches:\s*\[main\]/);
+  assert.match(workflow, /workflow_dispatch:\s*\n\s+inputs:\s*\n\s+tag:/);
+  assert.match(workflow, /tag:[\s\S]*?required:\s*true/);
+  assert.match(
+    workflow,
+    /group:\s*release-\$\{\{ github\.event_name == 'workflow_dispatch' && inputs\.tag \|\| github\.ref_name \}\}/,
+  );
+  assert.doesNotMatch(workflow, /git diff --name-only[\s\S]*package\.json/);
+  assert.ok(
+    workflow.indexOf('- name: Validate release intent')
+      < workflow.indexOf('node scripts/release-state.mjs'),
+    'release intent must be validated before the reconciler can publish',
+  );
+  assert.equal(workflow.match(/node scripts\/release-state\.mjs/g)?.length, 1);
+});
+
+test('the same pre-publish validator accepts a matching annotated tag', async () => {
+  const fixture = await releaseIntentFixture();
+  try {
+    const result = await validateReleaseIntent(fixture);
+    assert.equal(result.error, undefined, result.stderr);
+    assert.match(result.output, /^tag=v1\.2\.3$/m);
+    assert.match(result.output, /^commit=[0-9a-f]{40}$/m);
+  } finally {
+    await rm(fixture.root, { recursive: true, force: true });
+  }
+});
+
+for (const scenario of [
+  {
+    name: 'missing manual recovery tag',
+    options: {},
+    tag: 'v9.9.9',
+    error: /does not exist/,
+  },
+  {
+    name: 'tag/package version mismatch',
+    options: { packageVersion: '1.2.4' },
+    error: /does not match package version/,
+  },
+  {
+    name: 'lightweight tag',
+    options: { annotated: false },
+    error: /must be annotated/,
+  },
+  {
+    name: 'tag outside canonical main ancestry',
+    options: { onMain: false },
+    error: /not an ancestor of origin\/main/,
+  },
+  {
+    name: 'stale canonical main commit with the same package version',
+    options: { mainAhead: true },
+    error: /does not identify the current origin\/main commit/,
+  },
+]) {
+  test(`the pre-publish validator rejects a ${scenario.name}`, async () => {
+    const fixture = await releaseIntentFixture(scenario.options);
+    try {
+      const result = await validateReleaseIntent(fixture, scenario.tag);
+      assert.ok(result.error, 'validation unexpectedly succeeded');
+      assert.match(`${result.stderr}\n${result.stdout}`, scenario.error);
+    } finally {
+      await rm(fixture.root, { recursive: true, force: true });
+    }
+  });
+}
 
 test('the install manifest ships both release primitives named by the skill', async () => {
   const manifest = JSON.parse(await readFile(join(REPO, 'agent-workflow-kit.package.json')));
@@ -20,11 +178,31 @@ test('the install manifest ships both release primitives named by the skill', as
 test('both release skill surfaces name only the owned scoped npm package', async () => {
   const claude = await readFile(join(REPO, '.claude/skills/kit-release/SKILL.md'), 'utf8');
   const codex = await readFile(join(REPO, '.agents/skills/kit-release/SKILL.md'), 'utf8');
+  assert.equal(codex, claude);
   for (const body of [claude, codex]) {
     assert.match(body, /`@ikon85\/agent-workflow-kit`/);
   }
 });
 
+test('maintainer docs and the accepted ADR agree that merge integrates and an annotated tag publishes', async () => {
+  const paths = [
+    'CLAUDE.md',
+    'AGENTS.md',
+    'README.md',
+    '.claude/skills/kit-release/SKILL.md',
+    '.agents/skills/kit-release/SKILL.md',
+    'docs/adr/0004-release-intent-is-a-version-tag.md',
+  ];
+  const bodies = await Promise.all(
+    paths.map((path) => readFile(join(REPO, path), 'utf8')),
+  );
+  for (const [index, body] of bodies.entries()) {
+    assert.match(body, /annotated\s+[`*]?v<version>[`*]?\s+tag/i, paths[index]);
+    assert.match(body, /integrat/i, paths[index]);
+  }
+  assert.match(bodies.at(-1), /Status: accepted \(2026-07-22, issue #204\)/);
+});
+
 test('patch, minor, and major confirmations select exactly one target version', () => {
   assert.equal(nextVersion('1.2.3', 'patch'), '1.2.4');
   assert.equal(nextVersion('1.2.3', 'minor'), '1.3.0');

package/scripts/release-state.mjs

@@ -2,11 +2,18 @@ import { execFile } from 'node:child_process';
 import { mkdtemp, rm } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
 import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
 import { assertReleaseParity, releaseIdentityFromTarball } from './release-parity.mjs';
 
 const exec = promisify(execFile);
+const DEFAULT_VISIBILITY = {
+  attempts: 6,
+  initialDelayMs: 1_000,
+  backoffFactor: 2,
+  sleep,
+};
 
 const assertMatches = (local, remote, label) => assertReleaseParity({
   local,
@@ -28,7 +35,24 @@ export async function inspectRelease(adapter) {
   return { status: 'released', identity };
 }
 
-export async function reconcileRelease(adapter) {
+async function awaitVisibility(read, phase, options = {}) {
+  const policy = { ...DEFAULT_VISIBILITY, ...options };
+  let delay = policy.initialDelayMs;
+  for (let attempt = 1; attempt <= policy.attempts; attempt += 1) {
+    const visible = await read();
+    if (visible) return visible;
+    if (attempt < policy.attempts) {
+      await policy.sleep(delay);
+      delay *= policy.backoffFactor;
+    }
+  }
+  throw new Error(
+    `${phase.operation} succeeded but ${phase.subject} was not visible `
+    + `after ${policy.attempts} ${phase.service} read attempts`,
+  );
+}
+
+export async function reconcileRelease(adapter, { visibility } = {}) {
   const { identity, tarball } = await adapter.local();
   let npm = await adapter.npm(identity);
   let github = await adapter.github(identity);
@@ -36,15 +60,21 @@ export async function reconcileRelease(adapter) {
   if (!npm) {
     if (github) throw new Error('GitHub release exists before npm package');
     await adapter.publishNpm({ identity, tarball });
-    npm = await adapter.npm(identity);
-    if (!npm) throw new Error('npm package missing after publish');
+    npm = await awaitVisibility(() => adapter.npm(identity), {
+      service: 'npm',
+      operation: 'npm publish',
+      subject: 'package',
+    }, visibility);
   }
   assertMatches(identity, npm, 'npm');
 
   if (!github) {
     await adapter.createGithub({ identity, tarball });
-    github = await adapter.github(identity);
-    if (!github) throw new Error('GitHub release missing after create');
+    github = await awaitVisibility(() => adapter.github(identity), {
+      service: 'GitHub',
+      operation: 'GitHub release creation',
+      subject: 'release',
+    }, visibility);
   }
   assertReleaseParity({ local: identity, npm, github });
   return { status: 'released', identity };

package/scripts/release-state.test.mjs

@@ -18,17 +18,62 @@ const identity = {
   tarballIntegrity: 'sha512-example', manifestSha256: 'abc123',
 };
 
-function adapter({ npmPublished = false, githubReleased = false, npmIdentity = identity } = {}) {
+function adapter({
+  npmPublished = false,
+  githubReleased = false,
+  npmIdentity = identity,
+  npmInvisibleReads = 0,
+  githubInvisibleReads = 0,
+  publishNpmError,
+  createGithubError,
+} = {}) {
   const events = [];
   let npmExists = npmPublished;
   let githubExists = githubReleased;
+  let npmReadsUntilVisible = npmInvisibleReads;
+  let githubReadsUntilVisible = githubInvisibleReads;
   return {
     events,
     local: async () => ({ identity, tarball: '/tmp/kit.tgz' }),
-    npm: async () => { events.push('read npm'); return npmExists ? npmIdentity : null; },
-    github: async () => { events.push('read github'); return githubExists ? identity : null; },
-    publishNpm: async () => { events.push('publish npm'); npmExists = true; },
-    createGithub: async () => { events.push('create github'); githubExists = true; },
+    npm: async () => {
+      events.push('read npm');
+      if (!npmExists) return null;
+      if (npmReadsUntilVisible > 0) {
+        npmReadsUntilVisible -= 1;
+        return null;
+      }
+      return npmIdentity;
+    },
+    github: async () => {
+      events.push('read github');
+      if (!githubExists) return null;
+      if (githubReadsUntilVisible > 0) {
+        githubReadsUntilVisible -= 1;
+        return null;
+      }
+      return identity;
+    },
+    publishNpm: async () => {
+      events.push('publish npm');
+      if (publishNpmError) throw publishNpmError;
+      npmExists = true;
+    },
+    createGithub: async () => {
+      events.push('create github');
+      if (createGithubError) throw createGithubError;
+      githubExists = true;
+    },
+  };
+}
+
+function visibilityOptions(attempts, delays = []) {
+  return {
+    visibility: {
+      attempts,
+      initialDelayMs: 10,
+      backoffFactor: 2,
+      sleep: async (delay) => delays.push(delay),
+    },
   };
 }
 
@@ -40,6 +85,72 @@ test('a fresh release publishes npm, verifies registry readback, then creates Gi
   ]);
 });
 
+test('npm visibility is retried with bounded backoff after a successful publish', async () => {
+  const fixture = adapter({ npmInvisibleReads: 2 });
+  const delays = [];
+  assert.deepEqual(
+    await reconcileRelease(fixture, visibilityOptions(4, delays)),
+    { status: 'released', identity },
+  );
+  assert.deepEqual(fixture.events, [
+    'read npm', 'read github', 'publish npm',
+    'read npm', 'read npm', 'read npm',
+    'create github', 'read github',
+  ]);
+  assert.deepEqual(delays, [10, 20]);
+});
+
+test('GitHub visibility is retried with bounded backoff after a successful create', async () => {
+  const fixture = adapter({ npmPublished: true, githubInvisibleReads: 2 });
+  const delays = [];
+  assert.deepEqual(
+    await reconcileRelease(fixture, visibilityOptions(4, delays)),
+    { status: 'released', identity },
+  );
+  assert.deepEqual(fixture.events, [
+    'read npm', 'read github', 'create github', 'read github', 'read github', 'read github',
+  ]);
+  assert.deepEqual(delays, [10, 20]);
+});
+
+test('permanent npm absence fails at the bound with post-publish phase evidence', async () => {
+  const fixture = adapter({ npmInvisibleReads: 4 });
+  const delays = [];
+  await assert.rejects(
+    reconcileRelease(fixture, visibilityOptions(3, delays)),
+    /npm publish succeeded but package was not visible after 3 npm read attempts/,
+  );
+  assert.deepEqual(delays, [10, 20]);
+  assert.equal(fixture.events.filter((event) => event === 'read npm').length, 4);
+  assert.ok(!fixture.events.includes('create github'));
+});
+
+test('permanent GitHub absence fails at the bound with post-create phase evidence', async () => {
+  const fixture = adapter({ npmPublished: true, githubInvisibleReads: 4 });
+  const delays = [];
+  await assert.rejects(
+    reconcileRelease(fixture, visibilityOptions(3, delays)),
+    /GitHub release creation succeeded but release was not visible after 3 GitHub read attempts/,
+  );
+  assert.deepEqual(delays, [10, 20]);
+  assert.equal(fixture.events.filter((event) => event === 'read github').length, 4);
+  assert.ok(!fixture.events.includes('publish npm'));
+});
+
+test('a rejected publish is not reported as a post-publish visibility timeout', async () => {
+  const rejected = new Error('registry rejected publish');
+  const fixture = adapter({ publishNpmError: rejected });
+  await assert.rejects(reconcileRelease(fixture, visibilityOptions(3)), (error) => error === rejected);
+  assert.deepEqual(fixture.events, ['read npm', 'read github', 'publish npm']);
+});
+
+test('a rejected GitHub create is not reported as a post-create visibility timeout', async () => {
+  const rejected = new Error('GitHub rejected release create');
+  const fixture = adapter({ npmPublished: true, createGithubError: rejected });
+  await assert.rejects(reconcileRelease(fixture, visibilityOptions(3)), (error) => error === rejected);
+  assert.deepEqual(fixture.events, ['read npm', 'read github', 'create github']);
+});
+
 test('an npm-published release resumes at GitHub without a second npm publish', async () => {
   const fixture = adapter({ npmPublished: true });
   await reconcileRelease(fixture);
@@ -47,6 +158,12 @@ test('an npm-published release resumes at GitHub without a second npm publish',
   assert.ok(!fixture.events.includes('publish npm'));
 });
 
+test('an already-published release at parity is a read-only no-op', async () => {
+  const fixture = adapter({ npmPublished: true, githubReleased: true });
+  assert.deepEqual(await reconcileRelease(fixture), { status: 'released', identity });
+  assert.deepEqual(fixture.events, ['read npm', 'read github']);
+});
+
 test('post-merge status inspection is read-only and reports the reconstructable phase', async () => {
   const fixture = adapter({ npmPublished: true });
   assert.deepEqual(await inspectRelease(fixture), { status: 'awaiting-github', identity });