@ikon85/agent-workflow-kit 0.10.0 → 0.12.0

package/.claude/skills/to-waves/SKILL.md

@@ -1,15 +1,16 @@
 ---
 name: to-waves
 disable-model-invocation: true
-description: "Unfold a Program-PRD's wave plan onto the board — parse + graph-validate it, show the complete Wellenplan as a chat preview before ANY board write, then after approval publish named wave stubs (native parent = the PRD) + slice leaves (native parent = their stub) with Wave and Phase stamped in one batch, and report a counted completion. Idempotent + crash-recoverable on re-run; adopts referenced existing issues instead of duplicating them. Use on a Program-PRD, the native anchor over several waves. NOT for a single-wave feature (to-issues) and NOT for clustering a backlog (board-to-waves)."
+description: "Turn a Program-PRD's wave plan into fully planned, execute-ready wave anchors and slice leaves after one complete chat preview. Validates the graph, publishes every wave, runs the to-prd/spec-self-critique/to-issues maturity contract for each wave, models unresolved work as explicit gates, and audits counted readiness. Idempotent and crash-recoverable. Use on a Program-PRD over several waves. NOT for a single-wave feature (to-issues) or backlog clustering (board-to-waves)."
 ---
 
 # to-waves — Unfold a Program-PRD's wave plan onto the board
 
 Takes a **Program-PRD** — the native Sub-Issue anchor over a multi-wave program
 (Programm → Phase → Welle → Slice) — and turns its `## Wellenplan` chapter into
-**named wave stubs + slice leaves** on the board. Pipeline position:
-`scale-check → grill → to-prd (program mode) → to-waves → …per wave: to-issues`.
+**fully planned wave anchors + slice leaves** on the board. Pipeline position:
+`scale-check → grill → to-prd (program mode) → to-waves`, with the per-wave
+`to-prd → spec-self-critique → to-issues` maturity pass owned inside this run.
 The **grill and to-prd sit upstream**; to-waves runs once the Program-PRD exists.
 It **never invents structure** — it only unfolds what the plan already decided.
 
@@ -70,28 +71,39 @@ Show:
 - The **publish plan**: how many stubs + leaves will be created, which referenced
   existing issues will be **adopted** (§4) rather than created, and which
   Wave/Phase stamps will be applied.
+- The complete per-wave issue contracts that will be materialized: outcome,
+  Blast-Radius, acceptance criteria, AFK/HITL bucket, native dependencies, and
+  self-contained handoff. A placeholder is not preview-complete.
 
-Then ask for approval. Only on an explicit "yes" proceed to §4/§5. On "no", stop —
-no writes happened.
+This complete Program preview is the **single user approval** for the default
+planning run. Only on an explicit "yes" proceed to §4/§5/§7; when a later
+per-wave maturity pass reproduces the approved cut, **do not ask for another per-wave approval**.
+Ask again only when new evidence changes structure or exposes
+a genuinely undecided gate. On "no", stop — no writes happened.
 
 ## 4. Publish — the fixed order
 
 After approval, publish in **exactly this order** (issue CREATES stay sequential so
 the numbering is deterministic; only the field stamps are batched):
 
-1. **Wave stubs — Stufe 1p.** One per Wellenplan row, native parent = the PRD.
+1. **Wave stubs — transient Stufe 1p.** One per Wellenplan row, native parent = the PRD.
    Title `Welle <N> — <Name>`; created with the `wave-stub` label and Status Spec.
    Body = the Stufe-1p stub template (named header, the program idempotency marker,
-   the revision marker — see §6). Not yet Wave/Phase-stamped (that is step 4).
+   the revision marker — see §6). This is a crash-recovery checkpoint inside the
+   run, never its successful terminal state. Not yet Wave/Phase-stamped (step 4).
    ```bash
    python3 scripts/board-sync.py create --title "Welle <N> — <Name>" \
      --body-file <stub.md> --wave-stub --status-role spec
    ```
-2. **Slice leaves.** One per slice under each wave, native parent = its stub. Created
-   with the spec-role status and **no** `ready-for-agent` (a leaf is not buildable until its
+2. **Preliminary slice leaves for multi-slice waves.** Create one per slice under
+   each wave whose approved cut contains ≥2 slices, native parent = its stub. For
+   an exactly-one-slice wave, **do not create a preliminary child**: keep that
+   slice's metadata on the stub so step 6 can turn the stub itself into the atomic
+   executable wave leaf without a duplicate identity. Preliminary children use
+   the spec-role status and **no** `ready-for-agent` (a leaf is not buildable until its
    wave is promoted — the ordering guard stays unambiguous). Body = the slice's
    `## Slices` section carried forward per `SLICE-METADATA-FORMAT.md` (metadata block +
-   the outcome/placeholder skeleton, sharpened only at promotion). **Title carries the
+   the outcome/placeholder skeleton, finalized in step 6). **Title carries the
    navigation prefix** `Welle <N> / Slice <local-id> — <title>` — the local-id
    (`1a`, `1b`, …) encodes the build order, so the sub-issue LIST is navigable by title
    alone (same convention as `to-issues`' promoted children, `Welle N / Slice X — <outcome>`).
@@ -131,10 +143,22 @@ the numbering is deterministic; only the field stamps are batched):
    ```bash
    python3 scripts/board-sync.py program-sync <prd#>
    ```
-6. **Counted completion report + program view link.** Report `X von Y` for each part
-   (stubs created, leaves created, issues adopted, field stamps set) and link the
-   program board view. Completeness is **counted, never claimed** — the numbers come
-   from the create outputs + the `stamp-batch` response, not from memory.
+6. **Mature every wave.** For each stub in dependency order, run the approved
+   Program batch handoff: `to-prd` Mode B writes the per-wave Draft-PRD,
+   `spec-self-critique` hardens it, and `to-issues` promotes/atomizes it while
+   reusing the preliminary leaves. The pass writes complete issue bodies, final
+   AFK/HITL buckets, handoffs, native dependencies, `plan_revision`, and removes
+   `wave-stub`. It inherits the §3 approval when the cut is unchanged.
+7. **Audit every wave.** Run `execute-ready-check.py --mode audit` on every promoted
+   anchor or atomic wave leaf. Any incomplete placeholder, incoherent revision,
+   missing bucket, or child-set mismatch blocks successful completion. **Program completion gate:**
+   Although `to-issues` uses audit mode as an informational handoff check, **do not count that wave as matured** or report
+   Program success until its audit findings are clean.
+8. **Counted completion report + program view link.** Report `X von Y` for each part
+   (stubs created, leaves adopted/created, field stamps set, waves matured, waves
+   execute-ready) and link the program board view. Completeness is **counted, never
+   claimed** — the numbers come from the commands, including the exact line
+   `X von Y Wellen ausführungsreif`.
 
 ## 5. Adopt path — referenced existing issues
 
@@ -176,6 +200,10 @@ A re-run of to-waves on the same program is **delta-apply** and doubles as
   report as **orphaned** (do not auto-close — closing is the abort convention, §8).
   Cross-check the native children (`children-of <prd#>` and each stub) against the
   plan so both origins are covered.
+- **Atomic supersession exception.** A marked preliminary leaf whose local-id maps
+  to the one slice now carried by its atomic stub is not a generic orphan. Route it
+  to `to-issues` §5b cleanup whether it is still linked or was already unlinked by
+  an interrupted run. Search-by-marker is the durable recovery identity.
 - **Crash recovery.** Because create is search-before-create, `link` is idempotent,
   and `stamp-batch` field-sets are idempotent, re-running the whole publish after an
   abort resumes cleanly — already-created issues match, missing ones are created,
@@ -191,7 +219,7 @@ A re-run of to-waves on the same program is **delta-apply** and doubles as
   (the same sanctioned body-write `to-prd` Mode B uses). The mechanism that renews
   coherence is the same one the revision broke — it self-repairs.
 
-## 7. Program-grill agenda + the per-wave-start content pass
+## 7. Program completion contract
 
 to-waves also carries the **program-grill agenda** as a reference chapter — the
 checklist a program grill (upstream) should cover so the wave plan does not rest on
@@ -211,12 +239,22 @@ open switches:
   single bounded choice to `decision-gate` — not deferred into the plan as an open
   task.
 
-**The per-wave-start content pass** is where slice content is sharpened — deliberately
-**just-in-time (Late Binding)**, never ex ante on spec. When a wave is promoted:
-`to-prd` (Mode B, into the wave stub) + `spec-self-critique` are **mandatory**, and
-the depth ladder is **raised for a high-stakes wave** (a design-grill or a
-`decision-gate` before slicing). This is what folds in any drift propagated since the
-plan was first written.
+**Default postcondition:** every published wave is fully planned and passes the
+shared execute-ready audit before this run reports success. Stufe 1p is an
+internal recovery state, not the result presented to the user. **Late Binding is not the default**
+for unfinished issue prose or missing buckets.
+
+Uncertainty is planned, not hidden. A bounded trade-off becomes an explicit
+**Decision Gate**, a factual unknown becomes a **Verify Spike**, and an unresolved
+structure seam becomes a HITL **Design-Grill** slice (or an explicitly named
+planning wave). Place that gate before its dependent build slice and write the
+native blocking edge. The gate issue itself still receives a complete contract and
+handoff; the dependent work is blocked, not vaguely under-planned.
+
+A mandatory human or external setup action follows the same rule: model it as a
+HITL predecessor, never bury it inside a `ready-for-agent` build leaf. If later
+drift invalidates an already planned wave, use the revision/escalation path in §8;
+do not pre-emptively leave every future wave incomplete.
 
 ## 8. Close protection, abort convention, escalation path
 
@@ -255,6 +293,7 @@ python3 scripts/board-sync.py program-sync <prd#>
 to-waves: prd=#<n> preview=<approved|rejected>
   created=<stubs X von Y, leaves X von Y>  adopted=<#a #b … | none>
   stamped=<N von M Wave/Phase>  phase=<stamped | skipped (profile lacks fields.phase)>
+  matured=<X von Y>  execute-ready=<X von Y Wellen ausführungsreif>
   revision=r<N>  renewed-markers=<count | none>  orphaned=<#… | none>
   graph=<ok | blocking: …>  program-view=<url>
 ```

package/README.md

@@ -332,6 +332,26 @@ still reference. Flags: `--force` (overwrite pre-existing files on `init`),
 
 ## Release notes
 
+### 0.12.0
+
+- added: `.agents/skills/kit-update/SKILL.md`
+- added: `.claude/skills/kit-update/SKILL.md`
+- changed: `.agents/skills/setup-workflow/workflow-overview.md`
+- changed: `.claude/skills/setup-workflow/workflow-overview.md`
+
+### 0.11.0
+
+- added: `scripts/release-parity.mjs`
+- added: `scripts/release-state.mjs`
+- changed: `.agents/skills/kit-release/SKILL.md`
+- changed: `.agents/skills/scale-check/SKILL.md`
+- changed: `.agents/skills/to-issues/SKILL.md`
+- changed: `.agents/skills/to-waves/SKILL.md`
+- changed: `.claude/skills/kit-release/SKILL.md`
+- changed: `.claude/skills/scale-check/SKILL.md`
+- changed: `.claude/skills/to-issues/SKILL.md`
+- changed: `.claude/skills/to-waves/SKILL.md`
+
 ### 0.10.0
 
 - added: `.agents/skills/kit-release/SKILL.md`

package/agent-workflow-kit.package.json

@@ -1,5 +1,5 @@
 {
-  "kitVersion": "0.10.0",
+  "kitVersion": "0.12.0",
   "files": [
     {
       "path": ".agents/skills/ask-matt/SKILL.md",
@@ -321,7 +321,16 @@
       "kind": "skill",
       "ownerSkill": "kit-release",
       "surface": "codex",
-      "sha256": "e24be892d52e29bf1add2a417afb34d17e9e5fa46ba1014ba81b4ad7069f905e",
+      "sha256": "d05a4059a19816ff302c119f797f1ea2b71554ecffac7a8f0b919cfe5517d940",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": ".agents/skills/kit-update/SKILL.md",
+      "kind": "skill",
+      "ownerSkill": "kit-update",
+      "surface": "codex",
+      "sha256": "26737ea49ac104260e56fd1604f60249ca1d59f1a2c1f22db55649833d01ebc3",
       "mode": 420,
       "origin": "kit"
     },
@@ -438,7 +447,7 @@
       "kind": "skill",
       "ownerSkill": "scale-check",
       "surface": "codex",
-      "sha256": "aa5f96503278e831c0229cdec4ba057d245c6dfa202296cbe0f236328bc67bf4",
+      "sha256": "80f8d5b4b811afd0bce4546d18170eed8a79ae2ee872b40563814374ea2ad1c2",
       "mode": 420,
       "origin": "kit"
     },
@@ -564,7 +573,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "codex",
-      "sha256": "87e5ab578f1c17905b39b9cb39b515e4661f3437d96de919f1b23a5775760c4f",
+      "sha256": "6ce3954e4f94d112801cba0d145e4d3b6f101aca5e50e6b1f9794aa0288881a9",
       "mode": 420,
       "origin": "kit"
     },
@@ -654,7 +663,7 @@
       "kind": "skill",
       "ownerSkill": "to-issues",
       "surface": "codex",
-      "sha256": "3cc1f667c0b961f3682bf71e345be9b27b96ab62edb71aa080912418b9344728",
+      "sha256": "3fdd05150f428cf8098e4dd12f67cbc7ebe17fa9ab315e456fd0df70e5c9925d",
       "mode": 420,
       "origin": "kit"
     },
@@ -699,7 +708,7 @@
       "kind": "skill",
       "ownerSkill": "to-waves",
       "surface": "codex",
-      "sha256": "1bbffd3858c9a7fb6873f448579a8d888959ff336572a25eb9780ce55b31a2d7",
+      "sha256": "5ac4fd5d26d6ea2327fc50ad4bcc8f3d8c80186afb976410d8c3e8f3c21d896e",
       "mode": 420,
       "origin": "kit"
     },
@@ -1267,7 +1276,16 @@
       "kind": "skill",
       "ownerSkill": "kit-release",
       "surface": "claude",
-      "sha256": "e24be892d52e29bf1add2a417afb34d17e9e5fa46ba1014ba81b4ad7069f905e",
+      "sha256": "d05a4059a19816ff302c119f797f1ea2b71554ecffac7a8f0b919cfe5517d940",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": ".claude/skills/kit-update/SKILL.md",
+      "kind": "skill",
+      "ownerSkill": "kit-update",
+      "surface": "claude",
+      "sha256": "26737ea49ac104260e56fd1604f60249ca1d59f1a2c1f22db55649833d01ebc3",
       "mode": 420,
       "origin": "kit"
     },
@@ -1384,7 +1402,7 @@
       "kind": "skill",
       "ownerSkill": "scale-check",
       "surface": "claude",
-      "sha256": "aa5f96503278e831c0229cdec4ba057d245c6dfa202296cbe0f236328bc67bf4",
+      "sha256": "80f8d5b4b811afd0bce4546d18170eed8a79ae2ee872b40563814374ea2ad1c2",
       "mode": 420,
       "origin": "kit"
     },
@@ -1528,7 +1546,7 @@
       "kind": "skill",
       "ownerSkill": "setup-workflow",
       "surface": "claude",
-      "sha256": "87e5ab578f1c17905b39b9cb39b515e4661f3437d96de919f1b23a5775760c4f",
+      "sha256": "6ce3954e4f94d112801cba0d145e4d3b6f101aca5e50e6b1f9794aa0288881a9",
       "mode": 420,
       "origin": "kit"
     },
@@ -1618,7 +1636,7 @@
       "kind": "skill",
       "ownerSkill": "to-issues",
       "surface": "claude",
-      "sha256": "4a8b4badb99f459d88789ba47f8378602f66be3b7ad1bd0871737e41520dfbb1",
+      "sha256": "5874d4b2d4999bd32a0a90c955467fc4e58e230295cd6ee21936fa30456bda6e",
       "mode": 420,
       "origin": "kit"
     },
@@ -1663,7 +1681,7 @@
       "kind": "skill",
       "ownerSkill": "to-waves",
       "surface": "claude",
-      "sha256": "1bbffd3858c9a7fb6873f448579a8d888959ff336572a25eb9780ce55b31a2d7",
+      "sha256": "5ac4fd5d26d6ea2327fc50ad4bcc8f3d8c80186afb976410d8c3e8f3c21d896e",
       "mode": 420,
       "origin": "kit"
     },
@@ -1928,6 +1946,20 @@
       "mode": 420,
       "origin": "kit"
     },
+    {
+      "path": "scripts/release-parity.mjs",
+      "kind": "script",
+      "sha256": "faa4a1d1116d58f69c8541a586ebd6076ebc3f7af7809e9e4a53928f49298365",
+      "mode": 420,
+      "origin": "kit"
+    },
+    {
+      "path": "scripts/release-state.mjs",
+      "kind": "script",
+      "sha256": "2aae056a8e0e945dbf68298236719c78e22f13dbd8f0c3466b969355d3809058",
+      "mode": 420,
+      "origin": "kit"
+    },
     {
       "path": "scripts/wrapup-land.py",
       "kind": "script",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikon85/agent-workflow-kit",
-  "version": "0.10.0",
+  "version": "0.12.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": {
@@ -13,7 +13,8 @@
     "kit:build": "node scripts/build-kit.mjs",
     "kit:staleness": "node scripts/check-kit-staleness.mjs",
     "release:prepare": "node scripts/kit-release.mjs",
-    "release:guard": "node scripts/release-delta-guard.mjs"
+    "release:guard": "node scripts/release-delta-guard.mjs",
+    "release:status": "node scripts/release-state.mjs --status"
   },
   "files": [
     ".claude/",

package/scripts/build-kit.test.mjs

@@ -35,6 +35,7 @@ test('current build contains post-tag public files and repository metadata', asy
     await readFile(join(dist, '.agents/skills/codex-adapter-sync/SKILL.md'));
     await readFile(join(dist, 'scripts/program_graph.py'));
     const pkg = JSON.parse(await readFile(join(dist, 'package.json'), 'utf8'));
+    assert.equal(pkg.name, '@ikon85/agent-workflow-kit');
     assert.equal(pkg.repository.url, 'git+https://github.com/iKon85/agent-workflow-kit.git');
   });
 });

package/scripts/kit-release.test.mjs

@@ -13,6 +13,16 @@ test('the install manifest ships both release primitives named by the skill', as
   const paths = manifest.files.map((entry) => entry.path);
   assert.ok(paths.includes('scripts/kit-release.mjs'));
   assert.ok(paths.includes('scripts/release-delta-guard.mjs'));
+  assert.ok(paths.includes('scripts/release-parity.mjs'));
+  assert.ok(paths.includes('scripts/release-state.mjs'));
+});
+
+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');
+  for (const body of [claude, codex]) {
+    assert.match(body, /`@ikon85\/agent-workflow-kit`/);
+  }
 });
 
 test('patch, minor, and major confirmations select exactly one target version', () => {

package/scripts/release-parity.mjs

@@ -0,0 +1,52 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+const FIELDS = ['name', 'version', 'tarballIntegrity', 'manifestSha256'];
+
+const digest = (algorithm, content, encoding = 'hex') =>
+  createHash(algorithm).update(content).digest(encoding);
+
+async function readTarEntry(tarball, entry) {
+  const { stdout } = await exec('tar', ['-xOf', tarball, entry], { encoding: 'buffer' });
+  return stdout;
+}
+
+export async function releaseIdentityFromTarball(tarball) {
+  const bytes = await readFile(tarball);
+  const packageJson = JSON.parse(await readTarEntry(tarball, 'package/package.json'));
+  const manifest = await readTarEntry(tarball, 'package/agent-workflow-kit.package.json');
+  if (packageJson.version !== JSON.parse(manifest).kitVersion) {
+    throw new Error('tarball package and manifest versions mismatch');
+  }
+  return {
+    name: packageJson.name,
+    version: packageJson.version,
+    tarballIntegrity: `sha512-${digest('sha512', bytes, 'base64')}`,
+    manifestSha256: digest('sha256', manifest),
+  };
+}
+
+function validate(label, identity) {
+  if (!identity || typeof identity !== 'object') throw new Error(`${label} release identity missing`);
+  for (const field of FIELDS) {
+    if (typeof identity[field] !== 'string' || !identity[field]) {
+      throw new Error(`${label} ${field} missing`);
+    }
+  }
+}
+
+export function assertReleaseParity(identities) {
+  validate('local', identities.local);
+  for (const label of ['npm', 'github']) {
+    validate(label, identities[label]);
+    for (const field of FIELDS) {
+      if (identities[label][field] !== identities.local[field]) {
+        throw new Error(`${label} ${field} mismatch`);
+      }
+    }
+  }
+  return identities.local;
+}

package/scripts/release-parity.test.mjs

@@ -0,0 +1,53 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFile } from 'node:child_process';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { assertReleaseParity, releaseIdentityFromTarball } from './release-parity.mjs';
+
+const exec = promisify(execFile);
+
+const identity = {
+  name: '@ikon85/agent-workflow-kit',
+  version: '1.2.3',
+  tarballIntegrity: 'sha512-example',
+  manifestSha256: 'abc123',
+};
+
+test('identical local, npm, and GitHub release identities have parity', () => {
+  assert.deepEqual(assertReleaseParity({ local: identity, npm: { ...identity }, github: { ...identity } }), identity);
+});
+
+test('a registry or GitHub content mismatch fails closed', () => {
+  assert.throws(() => assertReleaseParity({
+    local: identity,
+    npm: { ...identity, manifestSha256: 'different' },
+    github: { ...identity },
+  }), /npm manifestSha256 mismatch/);
+  assert.throws(() => assertReleaseParity({
+    local: identity,
+    npm: { ...identity },
+    github: { ...identity, tarballIntegrity: 'different' },
+  }), /github tarballIntegrity mismatch/);
+});
+
+test('a package tarball produces a deterministic content identity', async () => {
+  const root = await mkdtemp(join(tmpdir(), 'release-parity-'));
+  const packageDir = join(root, 'package');
+  const tarball = join(root, 'kit.tgz');
+  try {
+    await mkdir(packageDir);
+    await writeFile(join(packageDir, 'package.json'), '{"name":"kit","version":"2.0.0"}\n');
+    await writeFile(join(packageDir, 'agent-workflow-kit.package.json'), '{"kitVersion":"2.0.0","files":[]}\n');
+    await exec('tar', ['-czf', tarball, '-C', root, 'package']);
+    const first = await releaseIdentityFromTarball(tarball);
+    const second = await releaseIdentityFromTarball(tarball);
+    assert.equal(first.name, 'kit');
+    assert.equal(first.version, '2.0.0');
+    assert.match(first.tarballIntegrity, /^sha512-/);
+    assert.match(first.manifestSha256, /^[a-f0-9]{64}$/);
+    assert.deepEqual(first, second);
+  } finally { await rm(root, { recursive: true, force: true }); }
+});

package/scripts/release-state.mjs

@@ -0,0 +1,172 @@
+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 { promisify } from 'node:util';
+import { fileURLToPath } from 'node:url';
+import { assertReleaseParity, releaseIdentityFromTarball } from './release-parity.mjs';
+
+const exec = promisify(execFile);
+
+const assertMatches = (local, remote, label) => assertReleaseParity({
+  local,
+  npm: label === 'npm' ? remote : local,
+  github: label === 'github' ? remote : local,
+});
+
+export async function inspectRelease(adapter) {
+  const { identity } = await adapter.local();
+  const npm = await adapter.npm(identity);
+  const github = await adapter.github(identity);
+  if (!npm) {
+    if (github) throw new Error('GitHub release exists before npm package');
+    return { status: 'awaiting-npm', identity };
+  }
+  assertMatches(identity, npm, 'npm');
+  if (!github) return { status: 'awaiting-github', identity };
+  assertReleaseParity({ local: identity, npm, github });
+  return { status: 'released', identity };
+}
+
+export async function reconcileRelease(adapter) {
+  const { identity, tarball } = await adapter.local();
+  let npm = await adapter.npm(identity);
+  let github = await adapter.github(identity);
+
+  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');
+  }
+  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');
+  }
+  assertReleaseParity({ local: identity, npm, github });
+  return { status: 'released', identity };
+}
+
+export function isMissingRelease(error, service) {
+  const detail = `${error.stderr ?? ''}\n${error.message ?? ''}`;
+  return service === 'npm'
+    ? /E404|404 Not Found|ETARGET|No matching version found/i.test(detail)
+    : /release not found|HTTP 404/i.test(detail);
+}
+
+export function githubReleaseArgs({ exists, tag, tarball, target }) {
+  if (exists) return ['release', 'upload', tag, tarball, '--clobber'];
+  return [
+    'release', 'create', tag, tarball, '--target', target,
+    '--title', tag, '--generate-notes',
+  ];
+}
+
+export function npmTarballFilename(name, version) {
+  return `${name.replace(/^@/, '').replaceAll('/', '-')}-${version}.tgz`;
+}
+
+async function packedTarball(run, spec, directory, repoRoot) {
+  const { stdout } = await run(
+    'npm', ['pack', spec, '--json', '--pack-destination', directory], { cwd: repoRoot },
+  );
+  const result = JSON.parse(stdout);
+  if (!Array.isArray(result) || result.length !== 1 || !result[0].filename) {
+    throw new Error(`unexpected npm pack result for ${spec}`);
+  }
+  return join(directory, result[0].filename);
+}
+
+function releaseReaders(context) {
+  const { run, repoRoot, env, scratch, state } = context;
+  async function local() {
+    const tarball = await packedTarball(run, '.', scratch, repoRoot);
+    return { tarball, identity: await releaseIdentityFromTarball(tarball) };
+  }
+
+  async function npm(identity) {
+    try {
+      state.npmTarball = await packedTarball(
+        run, `${identity.name}@${identity.version}`, scratch, repoRoot,
+      );
+      return await releaseIdentityFromTarball(state.npmTarball);
+    } catch (error) {
+      if (isMissingRelease(error, 'npm')) return null;
+      throw error;
+    }
+  }
+
+  async function github(identity) {
+    const tag = `v${identity.version}`;
+    try {
+      await run('gh', ['release', 'view', tag, '--json', 'tagName'], { cwd: repoRoot, env });
+    } catch (error) {
+      if (isMissingRelease(error, 'github')) return null;
+      throw error;
+    }
+    try {
+      const asset = npmTarballFilename(identity.name, identity.version);
+      await run('gh', ['release', 'download', tag, '--pattern', asset, '--dir', scratch, '--clobber'], {
+        cwd: repoRoot, env,
+      });
+      return await releaseIdentityFromTarball(join(scratch, asset));
+    } catch (error) {
+      if (/no assets match|not found/i.test(`${error.stderr ?? ''}\n${error.message ?? ''}`)) return null;
+      throw error;
+    }
+  }
+
+  return { local, npm, github };
+}
+
+function releaseWriters(context) {
+  const { run, repoRoot, env, state } = context;
+  async function publishNpm({ tarball }) {
+    await run('npm', ['publish', tarball, '--access', 'public', '--provenance'], { cwd: repoRoot, env });
+  }
+
+  async function createGithub({ identity }) {
+    if (!state.npmTarball) throw new Error('verified npm tarball unavailable for GitHub release');
+    const tag = `v${identity.version}`;
+    let exists = true;
+    try {
+      await run('gh', ['release', 'view', tag, '--json', 'tagName'], { cwd: repoRoot, env });
+    } catch (error) {
+      if (!isMissingRelease(error, 'github')) throw error;
+      exists = false;
+    }
+    await run('gh', githubReleaseArgs({
+      exists, tag, tarball: state.npmTarball, target: env.GITHUB_SHA,
+    }), { cwd: repoRoot, env });
+  }
+
+  return { publishNpm, createGithub };
+}
+
+export async function createCommandAdapter({ repoRoot, run = exec, env = process.env } = {}) {
+  const scratch = await mkdtemp(join(tmpdir(), 'awkit-publish-'));
+  const context = { run, repoRoot, env, scratch, state: {} };
+  return {
+    ...releaseReaders(context),
+    ...releaseWriters(context),
+    dispose: () => rm(scratch, { recursive: true, force: true }),
+  };
+}
+
+async function main() {
+  const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+  const adapter = await createCommandAdapter({ repoRoot });
+  try {
+    const result = process.argv.includes('--status')
+      ? await inspectRelease(adapter)
+      : await reconcileRelease(adapter);
+    console.log(`release ${result.identity.version}: ${result.status}`);
+  } finally { await adapter.dispose(); }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => { console.error(`release-state: ${error.message}`); process.exitCode = 1; });
+}