@ikon85/agent-workflow-kit 0.34.0 → 0.34.3

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.34.0",
+  "kitVersion": "0.34.3",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -137,7 +137,7 @@
       "ownerSkill": "diagnose",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "38ae64634933b42a6fea8b480c1962fc494a2dc08d7b07b0ab9a114eaeaa631e",
+      "sha256": "8a6b1036968146beff15a03e03c7b0f7d71ab65a666201ee8e1588c484f32ce6",
       "mode": 420,
       "origin": "kit"
     },
@@ -267,7 +267,7 @@
       "ownerSkill": "implement",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "5b55552c4a0d90fe15c9ee44abce4498faa03b73e332024e30ab69c2b7065770",
+      "sha256": "dff8c4bd4a1cfd376bc5fdd9d97641301d61055fd9155bde50c1e9634a6015d2",
       "mode": 420,
       "origin": "kit"
     },
@@ -367,7 +367,7 @@
       "ownerSkill": "kit-release",
       "surface": "codex",
       "installRole": "maintainer",
-      "sha256": "d05a4059a19816ff302c119f797f1ea2b71554ecffac7a8f0b919cfe5517d940",
+      "sha256": "7e08d5115d34f36da08491fa3bb8d5f4ca45e2908560e8f8c924cf3fd619d7f9",
       "mode": 420,
       "origin": "kit"
     },
@@ -447,7 +447,7 @@
       "ownerSkill": "orchestrate-wave",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "3a281805aee83a771675f8f80b9bd9dee3c1b2f2b2ca58001b37d8565a7d9d7d",
+      "sha256": "4c40d95e773649ba87e5010740180b66682a18cdf98ba7d8b7907397ea212ed0",
       "mode": 420,
       "origin": "kit"
     },
@@ -627,7 +627,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "5f5ceed4ec89d8eae8f1199d08b4948e9627eef7ce128e1858b208511c726e52",
+      "sha256": "6c896543b1a1a50ca3f591d63e364a3f0d624b8ae02ef93183e3665a27248d3c",
       "mode": 420,
       "origin": "kit"
     },
@@ -637,7 +637,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "7a72f72bc4c42401e6bfefb1253d87a2970b633d5f9e9bf975c5d486813cacd2",
+      "sha256": "be08d8e86f4573049c9cd809cde9417a334d364f3e823548bcd54136b1da4b01",
       "mode": 420,
       "origin": "kit"
     },
@@ -647,7 +647,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "codex",
       "installRole": "consumer",
-      "sha256": "e0dd9835e3658909132058e9a5fdd851e972220bbadaf78a57e3c6220d470922",
+      "sha256": "b4bf369b9c7791b9b9c76438aaa4cd9a07a0860fcc6bb9b52eebe12c6427ccbb",
       "mode": 420,
       "origin": "kit"
     },
@@ -1359,7 +1359,7 @@
       "ownerSkill": "diagnose",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "2cdcb0ff5699dfeda8f8f9f487a8290d97d44176ddb6942638f4a9a32ecbaaad",
+      "sha256": "44edd6a5af6429fd711ddbb3a4123b51a9c497573c147c2fc7b874e6e2a1336c",
       "mode": 420,
       "origin": "kit"
     },
@@ -1579,7 +1579,7 @@
       "ownerSkill": "implement",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "5b55552c4a0d90fe15c9ee44abce4498faa03b73e332024e30ab69c2b7065770",
+      "sha256": "dff8c4bd4a1cfd376bc5fdd9d97641301d61055fd9155bde50c1e9634a6015d2",
       "mode": 420,
       "origin": "kit"
     },
@@ -1679,7 +1679,7 @@
       "ownerSkill": "kit-release",
       "surface": "claude",
       "installRole": "maintainer",
-      "sha256": "d05a4059a19816ff302c119f797f1ea2b71554ecffac7a8f0b919cfe5517d940",
+      "sha256": "7e08d5115d34f36da08491fa3bb8d5f4ca45e2908560e8f8c924cf3fd619d7f9",
       "mode": 420,
       "origin": "kit"
     },
@@ -1759,7 +1759,7 @@
       "ownerSkill": "orchestrate-wave",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "fb244997866b4ad01db7c7de8a22467d4c8399f030d236a517b6b9cc958d9177",
+      "sha256": "24c90d6048f04df29c0031cd6b643ab433536c8a176dd4983111c6be6e0fcb19",
       "mode": 420,
       "origin": "kit"
     },
@@ -1959,7 +1959,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "5f5ceed4ec89d8eae8f1199d08b4948e9627eef7ce128e1858b208511c726e52",
+      "sha256": "6c896543b1a1a50ca3f591d63e364a3f0d624b8ae02ef93183e3665a27248d3c",
       "mode": 420,
       "origin": "kit"
     },
@@ -1969,7 +1969,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "7a72f72bc4c42401e6bfefb1253d87a2970b633d5f9e9bf975c5d486813cacd2",
+      "sha256": "be08d8e86f4573049c9cd809cde9417a334d364f3e823548bcd54136b1da4b01",
       "mode": 420,
       "origin": "kit"
     },
@@ -1979,7 +1979,7 @@
       "ownerSkill": "setup-workflow",
       "surface": "claude",
       "installRole": "consumer",
-      "sha256": "e0dd9835e3658909132058e9a5fdd851e972220bbadaf78a57e3c6220d470922",
+      "sha256": "b4bf369b9c7791b9b9c76438aaa4cd9a07a0860fcc6bb9b52eebe12c6427ccbb",
       "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,51 @@
+# Release intent is an explicit version tag
+
+Status: accepted (2026-07-22, issue #204)
+
+Clarified 2026-07-25 by issue #239: an explicit AFK end-to-end mandate may
+authorize deterministic reversible release preparation, but never the
+publication tag itself.
+
+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 explicit AFK Wave/Program mandate may cover the deterministic reversible
+  metadata preparation and landing that it names. It never by itself authorizes
+  creating or pushing the publication tag; that irreversible action requires a
+  separate explicit confirmation.
+- A single-Wave mandate does not authorize the next Program Wave. A later
+  explicit whole-Program mandate does authorize all planned Waves and remains in
+  force across their boundaries.
+- Reruns reconcile the same tag and never infer that a red workflow means
+  nothing was published.

package/docs/agents/issue-tracker.md

@@ -10,3 +10,14 @@ Issues and PRDs for this repo live in `iKon85/agent-workflow-kit` as GitHub issu
 - Route board writes, status/wave/cluster field edits, dependencies, and sub-issue links through `scripts/board-sync.py`, not bare `gh project` commands.
 - Board state is authoritative for workflow status; GitHub issues remain the durable content source.
 
+## Pickup claim
+
+Used by `/implement`, `/diagnose`, and `/orchestrate-wave` before the first
+edit. Board status `In Progress` is the human-facing signal; the claim below is
+the machine-readable one, and it is the only one that names the branch and
+worktree a colliding session would have to find.
+
+- **Check**: `gh issue view <n> --json assignees,comments --jq '{assignees: [.assignees[].login], claims: [.comments[].body | select(contains("<!-- agent-claim:"))]}'` — a foreign assignee or a marker this session did not plant is a foreign claim: stop, report the claimed branch/worktree, and leave it alone.
+- **Claim**: `gh issue edit <n> --add-assignee @me`, then `gh issue comment <n> --body '<!-- agent-claim: branch=<branch>; worktree=<absolute-path>; date=<YYYY-MM-DD> -->'`. Board status stays a `scripts/board-sync.py` write, never a bare `gh project` call.
+- **Release**: the slice PR (`closes #<n>` / `Part of #<anchor>`) supersedes the claim, so `/wrapup` needs no extra step. On abandon: `gh issue edit <n> --remove-assignee @me` plus a `claim released` comment.
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.34.0",
+  "version": "0.34.3",
   "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,43 @@ 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('an explicit AFK scope can authorize reversible preparation but never publication', 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, /explicit AFK end-to-end mandate/i);
+    assert.match(body, /deterministic recommendation/i);
+    assert.match(body, /reversible metadata preparation/i);
+    assert.match(body, /annotated `v<version>` tag[\s\S]*separate explicit confirmation/i);
+  }
+});
+
+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 });