🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
docs(adr): record stable leaf semver (ADR-403); update ADR-100 and ADR-378 after 3.48.0 (#3533)
rUvdf74e536e549
diff --git a/v3/docs/adr/ADR-100-cli-core-split-lazy-load.md b/v3/docs/adr/ADR-100-cli-core-split-lazy-load.mdindex 5c051ddb26..56280a5eda 100644--- a/v3/docs/adr/ADR-100-cli-core-split-lazy-load.md+++ b/v3/docs/adr/ADR-100-cli-core-split-lazy-load.md@@ -1,8 +1,8 @@# ADR-100: Split `@claude-flow/cli` into `cli-core` + lazy-loaded extras-**Status**: Accepted — Partially Implemented (foundation + backend abstraction + MCP tool defs shipped as alpha.0–alpha.5; full memory/hooks handler split and `latest` promotion deferred)-**Date**: 2026-05-05 · **Updated**: 2026-05-09-**Version**: `@claude-flow/[email protected]` published; `@claude-flow/[email protected]` metapackage released+**Status**: Accepted — Partially Implemented (foundation + backend abstraction + MCP tool defs shipped as alpha.0–alpha.5; full memory/hooks handler split deferred). `cli-core` left the alpha line on 2026-09-28 (see §4).+**Date**: 2026-05-05 · **Updated**: 2026-09-28+**Version**: `@claude-flow/[email protected]` (stable, `latest`), pinned exactly by `@claude-flow/[email protected]`**Supersedes**: nothing**Related**: ADR-098 (plugin capability sync and optimization), issue [#1748](https://github.com/ruvnet/ruflo/issues/1748) Issue 3 (cold-cache 30s MCP-startup race), [#1747](https://github.com/ruvnet/ruflo/issues/1747) (hooks shell injection — fixed in 3.6.28; orthogonal to this ADR)@@ -97,6 +97,13 @@ Alpha promotion to `latest` requires:2. At least one external integrator (the #1748 reporter is a candidate) confirms MCP startup succeeds within 30s on a cold cache3. No regression in the existing 21 Tier 1 / 7 adversarial cost-tracker bench corpus+**2026-09-28 update.** `cli-core` moved to **3.7.0** on `latest` / `alpha` / `v3alpha` as part of+ADR-403, which puts every internal leaf package on stable semver. That was a+versioning-policy change, not the promotion gate above: criteria 1 and 2 were **not**+re-measured for it. What was checked is regression parity. The published tarball's API matches `main`, every+consumer resolves one copy, and `[email protected]` passes the full CI matrix. The cold-cache+performance claim of this ADR therefore remains unverified by an external integrator.+## Consequences**Positive:**@@ -243,3 +250,4 @@ This is more work than fire 1 anticipated — likely 4-6 additional fires to lan- **2026-05-05**: Proposed (this commit)- **TBD**: Accepted after cold-cache benchmark proves <5s on typical connection- **TBD**: Promoted alpha → latest after external validator (Liberation of Bajor team or equivalent) confirms MCP startup succeeds on cold cache+- **2026-09-28**: `[email protected]` published as stable under ADR-403's leaf versioning policy. The external cold-cache validation above is still outstanding.diff --git a/v3/docs/adr/ADR-378-npm-trusted-publishing-cicd.md b/v3/docs/adr/ADR-378-npm-trusted-publishing-cicd.mdindex 5f8375ccf6..15b2097146 100644--- a/v3/docs/adr/ADR-378-npm-trusted-publishing-cicd.md+++ b/v3/docs/adr/ADR-378-npm-trusted-publishing-cicd.md@@ -3,7 +3,31 @@- **Status**: Proposed- **Date**: 2026-07-30- **Related**: root `CLAUDE.md` → "Publishing to npm" (existing manual runbook), 2026-07-14 helpers-signing-key leak incident (same section), Cognitum Platform deployment table (existing WIF precedent for `meta-llm`'s CD)-- **Supersedes**: nothing — this repo has no existing publish/release GitHub Actions workflow (`.github/workflows/` has 24 workflows; none named `*publish*` or `*release*`). This is net-new automation, not a migration.+- **Supersedes**: nothing. When this ADR was written, the repo had no publish/release GitHub Actions workflow (24 workflows in `.github/workflows/`, none named `*publish*` or `*release*`). A token-based `stable-npm-release.yml` has since been added; see "Update 2026-09-28".+- **Updated**: 2026-09-28 (ADR-403 leaf versioning; state of `stable-npm-release.yml`)++## Update 2026-09-28 — what changed since this ADR was written++- **A token-based workflow now exists.** `.github/workflows/stable-npm-release.yml`+ (`workflow_dispatch` with an existing `v*` tag, `NPM_TOKEN`, not OIDC) publishes the three+ train packages from the immutable tag. None of its five runs (2026-09-21, 09-27, 09-28) has succeeded. Four failed and one was cancelled.+ - The 09-28 run for `v3.47.1` **did publish** all three packages, then failed on its own+ post-publish check (`@claude-flow/[email protected] does not match the verified archive+ integrity`).+ - The registry lags after `npm publish`: `3.48.0` took about 6.5 minutes to resolve. That lag+ is a plausible cause of the failed check, but it has not been confirmed. The check should poll+ before comparing.+ - The 09-27 run failed input validation (a non-tag ref).+ - `3.48.0` was published with the manual runbook.+- **The train is no longer always three packages.** Under ADR-403, the internal+ `@claude-flow/*` leaves are on stable semver, and the CLI pins the non-bundled ones+ (`cli-core`, `memory`, `neural`, `shared`) exactly. A release that changes one of them must+ publish that leaf *before* the train, and wait until the registry resolves it.+ Any automation built from this ADR has to cover that leaf step. Otherwise it ships a CLI+ pinned to a version that does not exist yet, or the old copy of the leaf.+- **Tarball contents are now constrained.** Each leaf has a `files` allowlist and no+ `publishConfig.tag`. A CI publish should assert both, because a missing allowlist leaked+ local runtime files into three published alpha tarballs, which are now deprecated.## Contextdiff --git a/v3/docs/adr/ADR-403-stable-semver-internal-leaf-packages.md b/v3/docs/adr/ADR-403-stable-semver-internal-leaf-packages.mdnew file mode 100644index 0000000000..e96bab8fa6--- /dev/null+++ b/v3/docs/adr/ADR-403-stable-semver-internal-leaf-packages.md@@ -0,0 +1,68 @@+# ADR 403: Stable Semver for Internal `@claude-flow/*` Leaf Packages++Status: Accepted — Implemented++Date: 2026 09 28++Related: #3530 (implementation and 3.48.0 release), #3414 (exact CLI pins), #3390 / #3335 (unpublished-leaf incidents), #3411 (leaked standalone `mcp` tarball), #3510 (superseded), #3531 (follow-up), ADR-100 (`cli-core`), ADR-378 (release automation)++## Context++The public train (`@claude-flow/cli`, `claude-flow`, `ruflo`) moved to stable semver at 3.7.0. The 18 internal leaf packages it depends on stayed on alpha pre-releases (`3.0.0-alpha.N`, `[email protected]`, `plugin-*@1.0.0-alpha.N`). That split caused four concrete problems:++1. **`latest` was not a stable version.** Some leaves set `publishConfig.tag: "v3alpha"`, so a publish never moved `latest`. Direct consumers who ran `npm install @claude-flow/memory` got whatever `latest` last pointed at, which was an alpha.+2. **Tarballs leaked local state.** Seven leaves had no `files` allowlist, so npm packed the package directory as it was. Published alphas of `shared`, `plugins` and `mcp` contained `.claude-flow/` daemon logs and pids, `settings.json` and headless-worker logs. A scan found no credentials, only local paths.+3. **The workspace graph was not publishable.** `plugin-agent-federation` depended on `file:../security` and `plugin-iot-cognitum` on `workspace:*`. Neither resolves for a registry consumer.+4. **Unpublished leaves shipped silently.** The CLI does not bundle `cli-core`, `memory`, `neural` or `shared`, so a merged fix in one of them reaches users only if that leaf is published too (#3335, #3390). Exact pins (#3414) stopped a stale cached copy from satisfying the spec. But `[email protected]` then sat unpublished behind a merged pin.++## Decision++1. **Leaves follow the train's semver policy.** Published 2026-09-28:++ | Version | Packages |+ |---|---|+ | 3.0.0 | browser, claims, deployment, guidance, hooks, mcp, memory, neural, performance, plugins, providers, security, shared, swarm, testing |+ | 3.7.0 | cli-core (continues its existing line) |+ | 1.0.0 | plugin-agent-federation, plugin-iot-cognitum |++ After this, bumps are PATCH, MINOR or MAJOR by the same rules as the train. `latest`, `alpha` and `v3alpha` all point at the stable version. No pre-release is published unless someone explicitly asks for one.++2. **`@claude-flow/embeddings` is excluded.** Its registry `latest` (`3.0.0-alpha.45`) was built from a branch that is not on `main`. Publishing from `main` would drop 139 exported names. It stays on alpha until that branch is reconciled.++3. **Every publishable leaf has a `files` allowlist** (`["dist", "README.md"]` at minimum) and **no `publishConfig.tag`**. `exports` may point only at shipped files. Entries for unshipped `examples/` and `benchmarks/`, and a `.d.js` typo, were removed.++4. **Intra-leaf dependencies use registry ranges** (`^<stable>`), never `file:` or `workspace:`.++5. **Publish order is topological, and leaves go before the train.** A release that changes a non-bundled leaf publishes the leaf first. Then it waits until `npm view <leaf>@<ver>` resolves (registry lag was about 6.5 minutes for 3.48.0), and only then pins it in the CLI. `scripts/audit-leaf-package-publish.mjs` fails if a pin does not cover the workspace version, or if changed leaf source comes without a version bump.++6. **The v3 pnpm workspace links every `@claude-flow/*` package** (`v3/.npmrc`: `prefer-workspace-packages=true`). Without that setting, pnpm replaced `link:../cli` with a newer registry `[email protected]` and pulled its alpha dependencies into the lockfile. That registry cli was published from a branch not on `main`. As a result, `pnpm-lock.yaml` cannot show whether a leaf was published. Only `npm view` can.++7. **`main` must contain everything that was published.** 3.47.0 was published from a branch that never merged. A 3.48.0 cut from `main` would therefore have removed guarded federation registration for every `npx` user. 3.48.0 cherry-picked #3510 onto `main` so the release is a superset. Before any release, check `git cherry origin/main v<last-published>` and bring every unmerged commit onto `main` first.++## Enforcement++- `scripts/audit-leaf-package-publish.mjs`: pin-covers-source check and changed-source-needs-bump check (diff mode in PR CI). The `shared` waiver was removed.+- `scripts/audit-umbrella-version-lockstep.mjs`: the three train packages share one version.+- The `pnpm install --frozen-lockfile` gate in CI.+- The witness manifest (#1825) asserts that the CLI's `memory` dependency is a registry version (`"@claude-flow/memory": "3.`), not a `workspace:` leak.++## Alternatives considered++- **Keep leaves on alpha and pin exactly.** Rejected. Direct consumers still get an alpha from `latest`, and nothing makes a publish land on `latest`.+- **Bundle every leaf into the CLI tarball.** Rejected for now. It would remove the ship-the-leaf step, but it duplicates code for direct consumers and grows the CLI tarball. The four bundled packages (`security`, `codex`, `mcp`, `plugin-agent-federation`) remain the exception and are also published standalone.+- **Bump through `3.0.0-rc.N`.** Rejected. It adds a release cycle without adding verification the per-package tests and full CI matrix do not already provide.++## Consequences++- `npx [email protected]` resolves exactly one copy of each `@claude-flow/*` dependency, all stable (checked with `npm ls` on a clean install).+- Leaf publishes are now semver-visible. A breaking change in a leaf requires a MAJOR bump, which the CLI's exact pins will surface.+- The three leaky alpha tarballs are deprecated (`[email protected]`, `[email protected]`, `[email protected]`).+- Workspace CI now tests `guidance`, `hooks`, `neural`, `plugins` and `testing` against workspace `memory` source rather than a registry alpha. That is more faithful to what ships, but it means these packages need a full recursive build before their tests.+- Pre-existing, not introduced here: `[email protected]` pins `@metaharness/[email protected]`, while the CLI's optional peer asks for `^0.4.0`. `npm ls` reports this as invalid on both 3.47.1 and 3.48.0.++## Verification (3.48.0)++- The full PR CI matrix passed: 125 checks, including macOS and Windows.+- `witness verify --strict` passes 117/117 on each OS.+- All 9 train dist-tags point at 3.48.0.+- Compared with 3.47.1 on a clean install: `doctor` has no failures, `hooks route` works, and memory store/search/retrieve behave identically on the native driver. The sql.js fallback behaves identically on both versions, and it is known not to persist between processes (#2968).