# Release Readiness

## Current status — 26 September 2026

The package is at **3.0.0-alpha.15**, the release being cut now. npm still serves
**3.0.0-alpha.13**: `3.0.0-alpha.14` was cut in `CHANGELOG.md` and `package.json` on 18
September but was **never published and never tagged**, and an earlier version of this page
wrongly called it published. alpha.15 carries everything since alpha.13; its publish record
(tarball, checksum, dist-tags, smoke) is added below once it is live.

The Node suite was measured green on
23 September at the branch head merged as `3cafa920`: **5,542 tests, 5,542
passed, zero failed, zero skipped** — three independent full runs that day
agreed (the `seedance-modelark` fps branch before and after merging `main`,
and the mograph branch). That is `npm test`, not the full
`check:release-readiness-lite` gate, so it is a test-count measurement rather
than a release-gate pass; run the gate before cutting alpha.15.

Certified live since the last status: **`seedance-modelark`** (BytePlus
ModelArk, Seedance 2.5) on 2026-09-21 and again 2026-09-22 — 87,300 tokens =
USD 0.934 for 4 s at 720p, with extend mode certified at USD 1.106 and both
open reference-video rules settled on 2026-09-23 (a 1080p reference and
23.976 fps are accepted); evidence in `docs/audits/2026-09-21-live-acceptance.md`,
`2026-09-22-live-acceptance.md` and `2026-09-23-live-acceptance.md`.
**`reapi-seedance`** is certified on BOTH credential paths (treg 2026-09-21,
direct 2026-09-22): each a 480p 4 s job billed 475 credits = USD 0.475, the
charge equal to the wallet delta.

### Previous status — 15 September 2026

`main` at `ec5a942` (#523, the 3.0.0-alpha.13 release commit) passes the full
Node suite on the primary machine (macOS 26.6.2 / Node v22.22.3 / Bun 1.3.14 /
Python 3.14.7 with the exact pins and RAQM) from a clean worktree:
**4,869 Node tests, 4,869 passed, zero failed, zero skipped** (the release gate
`check:release-readiness-lite`, exit 0). The count grew from 4,773 on 9 September
with the surface-shrink and module-size phases (#497, #502, #511, #517–#522) and
the peer merges #512–#516. **GitHub Actions is billing-blocked as of 15 September
16:19 UTC** (jobs refused before starting: "recent account payments have failed
or your spending limit needs to be increased"); the six merges from #519 on and
the release itself were verified by that local gate and merged with the
`main: require green CI before merge` ruleset briefly disabled, then re-enabled.
On a checkout whose `.env.local` carries a real `USEAPI_API_TOKEN`, two
`veo-runtime` cases that expect the token absent fail — environment, not tree.
**From #525 (15 September) CI is checks-only by default:** the required
`build · test · smokes · guardrails` check on a PR or a main push means the
`checks` job passed and the four test shards were deliberately skipped, unless the
PR carried the `ci:full` label or the run was the nightly full suite on main. A
release candidate must therefore cite either a labelled PR run, a nightly run, or a
local `check:release-readiness-lite` from the release commit — a green PR check
alone is not full-suite evidence. From #575 (18 September) the same check also
carries a third conditional leg, the shared coordinator's own deploy gate, which
runs only on a PR that changes `services/shared-lane-coordinator/`, under
`ci:full`, on manual dispatch and nightly.

The 9 September record (`a89e890`, #504, 4,773 tests, macOS 26.6.2 / Node
v22.22.3 / Bun 1.3.14 / Python 3.14.7) stands as the previous primary-machine
baseline: #473–#505 (consumer naming, the free-engine readiness file, in-flight
execute-status, the live-acceptance harness, the shot-refs and film #3 branches,
the mascot rename and five docs-drift gates).
The 7 September second-machine reproduction (`91e0505`, #462; macOS 26.6.2 /
Node 22.22.3 / Bun 1.3.14 / Python 3.14.7, 4,632 tests) remains the last
cross-machine check; on that run the critical
coverage suite 81 passed, all local smokes and guardrails passed; Flow sidecar
typecheck clean and **876 passed, 14 live-service skips, 1 todo**; in-tree
seedance engine offline self-test 53/53.

**Live support, free lanes:** `veo-useapi` is certified at 0 credits (one 8 s
text-to-video job, balance 25,610 before and after, clip QC'd frame by frame).
`seedance-direct` is certified at $0 too, and from an INSTALLED package: the
stranger test's alpha.10 install bootstrapped its own engine profile and
rendered one 8 s scene with the wallet unchanged (500 credits before and
after, `spendDetected: false`). `runway-useapi` has no account (suspended 2026-08-10).
Details, commands and evidence paths: [live acceptance record](https://github.com/davendra/videoclaw-v3/blob/main/docs/audits/2026-09-07-live-acceptance.md).

**Live support, paid backends (2026-09-09, `npm run acceptance:live`, one
operator-approved call each):** `gemini-tts` narration (5.3 s WAV; whisper confirms
speech, though only five of ten words — the text began with a `Name:`-style
prefix that Gemini TTS most likely read as a speaker label; one sample),
`lyria3` soundtrack (27.4 s MP3 returned for a 10 s request; one sample), and the Magnific image upscaler (256²
→ 512², 90 credits read off the account before and after) are **certified**.
`dreamina-useapi` is **not pursued**: Dreamina was dropped on
2026-09-09 as too expensive to keep supporting, so it stays uncertified by
decision (the one attempt that day was refused by the provider's account flag
4013 before any charge).

**Google Flow free lane, by operation (2026-09-16, `npm run acceptance:live --
--route veo-useapi --veo-model free --operation i2v|r2v --approve`):** image-to-video
(`produce` with an image asset, sidecar actualCost 0) and reference-to-video
(`flow-r2v --model veo-3.1-lite-low-priority` against a registered Flow character,
the first proof that Flow honours character refs on the free model) are
**certified at 0 credits**, both landing 1920×1080 / 8 s with audio after the free
1080p upsample, wallet unchanged across each job; text-to-video was certified on
2026-09-09. The harness reads Google's own price table before every free row and
refuses to submit unless the operation's `_lite_low_priority` row exists and costs
0. Extension and first+last (interpolation) have no `vclaw` surface, so they stay
uncertified; the 360p omni upsampler needs a paid omni clip. Rows and the full
inventory: [2026-09-16 live acceptance](https://github.com/davendra/videoclaw-v3/blob/main/docs/audits/2026-09-16-live-acceptance.md). The
`higgsfield-cli` cinema route is **certified** (2026-09-17, `npm run
acceptance:live -- --kind cinema --sheet-dir <dir> --approve`): the harness walks
the whole evidence-gated ladder — create, character sheet, ten recognition
decisions, rights, voice, preflight, compile, exact quote, authorize, execute ONE
task, sync — against the real `higgsfield` 1.1.23 binary, and the one
`seedance_2_5` 5 s / 480p shot landed with quote == charge (15 credits; the same
row cost 12.5 on 2026-09-05 — the price moved, the contract held) and the wallet
moving by exactly that. Two facts the run surfaced: the authorization must cover
the whole five-shot quote (105 credits) even though one shot is submitted, and a
re-quote on the same project duplicates its queue tasks until `cinema-authorize`
refuses (#542), so the harness gives every cinema run a fresh project. Every
other route and backend is offline-tested only. Evidence rows:
[2026-09-09](https://github.com/davendra/videoclaw-v3/blob/main/docs/audits/2026-09-09-live-acceptance.md),
[2026-09-16](https://github.com/davendra/videoclaw-v3/blob/main/docs/audits/2026-09-16-live-acceptance.md),
[2026-09-17](https://github.com/davendra/videoclaw-v3/blob/main/docs/audits/2026-09-17-live-acceptance.md).

> **Roadmap phases.** PRs #482, #490, #492 and #494 cite "roadmap Phase 1/4/5".
> That roadmap was a session plan and was never checked in; the closest
> checked-in record is `docs/audits/production-readiness-plan.md` (the 24-item
> readiness plan, all items done) and the dated outcome next to it.

**Published:** `3.0.0-alpha.13` is the latest version on npm. (`3.0.0-alpha.14` was never published; its changes ship in alpha.15.) The alpha.13 record: `3.0.0-alpha.13` on the npm `alpha` dist-tag from `ec5a942`
(#523), tag `v3.0.0-alpha.13`, sha256
`1a00f181a0fa64c4aa9d1460e62e4fdd8f18002be576ea67800e64d09e62ec43` (local pack
of the release commit; registry shasum `83839c34d50a2b2a4d22f94fc0b60ea008d622e5`
== the pack's). `latest` moved with it the same hour (`npm dist-tag ls videoclaw`:
`alpha: 3.0.0-alpha.13`, `latest: 3.0.0-alpha.13`); `npx -p videoclaw@alpha vclaw
--version` from the registry prints 3.0.0-alpha.13. It carries the deprecation
notices (#497, #502), `produce --approve` and the plain-produce spend-flag
refusal (#511), and the five giant-module splits (#517–#522; the size guard now
has zero frozen ceilings). The pre-publish hook re-ran the full suite on the
publishing worktree (4,869 passed, 0 failed); the fresh-directory tarball smoke
is recorded on #523. The `--tag alpha` publish and the `latest` move were run by
the operator (npm two-factor). Roadmap phases 1, 5, 4, 2 and 3 are all shipped.

**Published:** `3.0.0-alpha.12` on the npm `alpha` dist-tag from `e45f393`
(#475), tag `v3.0.0-alpha.12`, sha256
`9fb5eb2768d2ea96793a26c107999e965fd375bfdcdc76247c44628082e9f190` (local pack
of the release commit == registry download). It carries the consumer-facing
route names (#473) and the engine readiness marker + `setupHint` (#474): a
fresh machine now reads Seedance 2.0 as unavailable until the Higgsfield
browser session is imported, and every unavailable route names its next
command. Prepublish suite skipped on the publishing machine (memory pressure);
the identical tree passed the full CI gate on #475/#474 (4,670 tests, 0
failed).

**Published:** `3.0.0-alpha.11` on the npm `alpha` dist-tag from `6baf01c`
(#470), tag `v3.0.0-alpha.11`, sha256
`2da0a323d471388aa8c5b8e7894f4e00fe2664e2b38dffc73408b3fc8aeb939b` (local pack
of the release commit == registry download). It carries the stranger-test
fixes (#469 code, #467 docs): a fresh install can now take a text-only project
to a render from `docs/AGENT_QUICKSTART.md` alone. The publishing machine's
local prepublish suite was killed by memory pressure; the identical tree passed
the full CI gate on #470 and #469 (4,659 tests, 0 failed). The stranger test
itself (`videoclaw@3.0.0-alpha.10`, docs only, fresh prefix) rendered one free
Flow scene at 0 credits and logged 18 gaps; issue #468 (an in-flight run marker
for `execute-status`) was the one left open and is now closed — `produce` writes a
per-run marker before submitting and `execute-status` reports `execution-in-flight`
without touching the previous report.

**Published:** `3.0.0-alpha.10` on the npm `alpha` dist-tag from `85992f5`
(#465), tag `v3.0.0-alpha.10`. Tarball `videoclaw-3.0.0-alpha.10.tgz`, 2,838
files, 15.6 MB packed, sha256
`56f36e8add16b87a359d991baf887baade812c38ff81684e686a24ebc88338a6` — identical
between the local pack of the release commit and the registry download. The
pre-publish hook re-ran lint, module-size, build and the suite (4,643 passed,
0 failed). A fresh-directory offline install and `npx -p videoclaw@alpha vclaw
video providers` from the registry both resolve the packed sidecar, engine and
skill resources. `latest` was promoted to alpha.12 on 2026-09-09 (`npm dist-tag ls videoclaw`:
`alpha: 3.0.0-alpha.12`, `latest: 3.0.0-alpha.12`) under the policy in
[Publishing](./PUBLISHING.md#choose-a-version-and-channel); the paid-lane
acceptance work continues from the remaining-work table of the
[dated outcome](https://github.com/davendra/videoclaw-v3/blob/main/docs/audits/2026-09-07-production-readiness-outcome.md#remaining-production-acceptance-and-priorities)
(the table no longer lives in this file).

The earlier 7 September record (candidate `3328e42`, 4,623/1 skip, the 51-skill
review) and its remaining-work table are in the
[dated outcome](https://github.com/davendra/videoclaw-v3/blob/main/docs/audits/2026-09-07-production-readiness-outcome.md).
The pre-remediation baseline at `9f81a02` had 4,571 passes, 39 failures and
one skip, caused by unsupported Python/shaping prerequisites.

Earlier May/August results and unversioned “latest HEAD” records are preserved
in [Historical release-readiness records](./RELEASE_READINESS_HISTORY.md).
They include retired aliases/routes and must not be copied into a current
release decision. The [documentation audit](https://github.com/davendra/videoclaw-v3/blob/main/docs/audits/2026-09-07-documentation-findings.md)
records source-reviewed gaps separately from executed checks.

## Required evidence for a release

| Gate | Acceptance criterion | Evidence to record |
|---|---|---|
| Node core | Lint, module-size, build, Node tests, critical coverage, relevant smokes and guardrails pass | Commit, environment, commands, pass/fail/skip totals; explain skips |
| Live provider support | One quoted, operator-approved job per claimed route, produced by `npm run acceptance:live -- --route <id> [--veo-model <m>] --approve` (dry without `--approve`; `--kind narrate|soundtrack|image-upscale [--backend <id>]` for the audio and Magnific backends; `--kind cinema --sheet-dir <dir>` for the official Higgsfield CLI cinema route through its evidence-gated ladder, one paid shot) | The row the harness appends to `docs/audits/<date>-live-acceptance.md`: transport, profile, job id and `.vclaw-jobs` file, `actualCost`/`costSource`, output probe, one-frame-per-second filmstrip, balance before/after where the route exposes one |
| Optional Flow sidecar | Typecheck and Bun suite pass; bridge resolves application code independently of project workspace | Bun version, sidecar dependency setup, test and bridge results; required CI gate includes this job |
| Python/media helpers | Supported Python environment passes prerequisite checks and affected local media fixtures | Python 3.12+ environment, dependencies, FFmpeg/ffprobe and required font/shaping capabilities |
| Installed package | Real tarball installs outside the checkout and resolves bundled resources | Version/channel, checksum, inventory, clean-directory schema/project/resource smoke |
| Queue and recovery | Saved quote/authorisation/receipt state prevents unintended replacement submissions; affected recovery and lease tests pass | Mocked contract results, ambiguous-submit/reconciliation checks and shared/local coordinator boundary |
| Documentation | Canonical references, independently authored guides and actual command/runtime behaviour agree | Mirror check, site build and content/link review; deployed revision if deploying docs |
| Live provider support | Explicitly authorised representative render and content QA for each provider being certified | Account/route/model, date, quote/charge, job ID, media checks and limitations; never infer from offline tests |
| Optional shared service | Deployment, authentication, lease coordination and recovery are verified when multi-machine operation is included | Service revision, configuration boundary and health/recovery evidence |

A failing required check blocks release. An unavailable external provider check
must narrow the published support claim; it must not be labelled a pass.
CI stubs for account/browser-engine presence make offline tests reproducible,
but do not demonstrate authenticated live access.

## Local verification

Use a source checkout with Node >=20.10, an active Python 3.12+ environment
prepared from `requirements-test.txt`, FFmpeg/ffprobe, and optional runtime
prerequisites appropriate to the changed code. See the installation guide.

```bash
npm run check:test-python
npm run check:release-readiness-lite
npm run check:docs-site
```

The readiness bundle builds once, runs the Node suite (unless explicitly
sharded by CI), critical coverage, local smokes, image-storyboard E2E and
repository guardrails. It is one gate, not the entire matrix above. Run the
separate Flow sidecar checks after its dependencies are installed:

```bash
(cd vclaw-cli && bun run typecheck && bun test)
```

Match additional tests to the change. Read-only project health and a documented
preview path can provide operator checks without submitting provider work.
For example, use `node dist/cli/vclaw.js video plan --project <slug>` from a
source checkout; installed-package users use `vclaw video plan --project <slug>`.
The selected sample must have the artifacts required by planning.

## Package and deployment acceptance

Follow [Publishing](./PUBLISHING.md) for channel selection and a real tarball
installation. A package inventory is necessary but not sufficient: a file may
be present yet resolved relative to the wrong directory, or require an optional
runtime that has not been installed. Package users should not have to run the
source test suite merely to discover the CLI.

Keep separate records for the npm package, git revision, documentation site and
optional Cloudflare coordinator. A merged PR or successful docs deployment does
not imply an npm release, a configured Homebrew tap, or a verified live render.
The checked-in Homebrew formula remains an unconfigured template.

## Final release record

Before marking a release ready, add a dated record with its exact source commit,
package version/channel, tested environment, gate results and remaining external
limitations. Preserve failure output and skipped checks. Review acceptance must
remain artifact-backed: `verdict: "pass"` and `metrics.publishReady: true`.
Do not replace evidence with a generic “all tests pass” statement.