Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 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

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.md
index 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 cache
3. 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.md
index 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.
## Context
diff --git a/v3/docs/adr/ADR-403-stable-semver-internal-leaf-packages.md b/v3/docs/adr/ADR-403-stable-semver-internal-leaf-packages.md
new file mode 100644
index 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).