docs(oss): record owner decisions as ADRs and the starting baseline

ADR-0001..0006 capture the scope decisions: no monetization, memory
through a contract backed by local mem0 (knowledge graph deferred), team
mode postponed, cost tracking open and self-learning out, whatsapp-web.js
for WhatsApp, opt-in analytics. baseline.md records build, typecheck,
lint and unit test results on macOS before scope work starts.
This commit is contained in:
shumeiko.it
2026-10-15 18:35:58 +02:00
parent 2346cf3ca4
commit ea21721d2a
8 changed files with 263 additions and 0 deletions

View File

@@ -0,0 +1,31 @@
# ADR-0001: The community edition has no monetization
- Status: Accepted
- Date: 2026-10-14
- Source: Waggle OSS Agreed Scope Annex
## Context
The commercial product sells tiers (Trial, Solo, Teams, Enterprise) through Stripe. The
server gates routes with `requireTier`, caps sessions per tier and blocks some embedding
providers; the web UI keeps its own copy of the tier model and shows plan cards, trial
banners, upgrade modals and KVARK and Team calls to action.
## Decision
The community edition is free and has no monetization. We remove the tier model, trial
logic, the Stripe integration, license checks, KVARK tools and nudges, and upgrade or Team
calls to action. Everything a tier used to gate becomes available. The per-tier session cap
becomes a fixed constant.
## Consequences
- P0.1 removes `packages/shared/src/tiers.ts`, the `assert-tier` middleware and the routes
that call `requireTier`, `/api/tier` and `/api/tier/start-trial`, and the trial auto-start
after onboarding.
- P1.1 removes `packages/server/src/stripe/` and `packages/server/src/kvark/`; P1.4 removes
`packages/agent/src/kvark-tools.ts`; P1.3a removes the billing UI.
- On startup the sidecar drops the `tier`, `trialStartedAt` and `stripe_customer_id` keys from
`config.json`.
- UserTier (UI complexity), ModelTier, persona tiers, CLI levels and memory health levels are
unrelated to billing and stay.

View File

@@ -0,0 +1,38 @@
# ADR-0002: Memory goes through a contract backed by local mem0
- Status: Accepted
- Date: 2026-10-14, amended 2026-10-15 (knowledge graph deferred)
## Context
Memory today is the hive-mind substrate in `packages/hive-mind-core` (FrameStore,
HybridSearch, KnowledgeGraph, identity and awareness layers). About 250 imports across agent,
server, weaver and cli depend on it, and around 20 files query the memory database with SQL.
The agreed scope takes the memory packages out of the community edition.
## Decision
- Waggle reaches memory only through a memory contract package (P0.3): remember, search, get,
update, delete and history, plus a capability map that the UI uses to hide unsupported
features.
- The backend is the open-source mem0 library (`mem0ai`, Apache-2.0) running inside the
sidecar. Data stays in a SQLite file in the Waggle data directory. The hosted Mem0 Platform
is not used.
- Fact extraction and embeddings use the Waggle-managed Ollama runtime or the user's own
provider key.
- Memory features in v1: facts, search and the user profile. Hidden in v1: history import,
wiki, Claude Code and Codex hooks, Waggle Room and the memory MCP server.
- The knowledge graph is deferred to a later release, because open-source mem0 has no graph
memory since version 3. The capability map marks it unavailable, so it can be added later
without changing the contract.
- No code outside the adapter queries the memory store with SQL.
## Consequences
- Tables that belong to Waggle rather than to memory (cron, notifications, pending actions,
skill hashes, file index, cost tracking) move to a separate `waggle.db` (P1.5).
- Non-memory code in `hive-mind-core` (WorkspaceManager, logger, injection scanner, ingress
guard) moves to `@waggle/core` (P1.5).
- Search quality is compared with the current engine on a reference question set, with a
local model and with a provider key, before release.
- `hive-mind-*`, `memory-mcp` and `wiki-compiler` are removed once nothing imports them (P2.2).

View File

@@ -0,0 +1,23 @@
# ADR-0003: Team mode stays in the repository but is not built or shipped
- Status: Accepted
- Date: 2026-10-14
## Context
Team mode spans the team server runtime (`packages/server/src/index.ts` with its routes,
services, database, scheduler and WebSocket layer), WaggleDance, the worker and the team
screens in the web UI. The local sidecar loads the team server dynamically, which pulls Clerk,
BullMQ, ioredis, postgres and drizzle into every build.
## Decision
Team mode code stays in the repository as a separate package. It is not built, bundled or
shipped in v1, and the team screens are removed from the UI.
## Consequences
- P1.1 separates the team runtime from the local sidecar and removes the dynamic team server
start, so the sidecar bundle no longer carries Clerk, BullMQ, ioredis, postgres or drizzle.
- P1.3a removes the team screens.
- Team code receives no new features until a later decision.

View File

@@ -0,0 +1,26 @@
# ADR-0004: Cost tracking is open; self-learning and optimizer are excluded
- Status: Accepted
- Date: 2026-10-14, amended 2026-10-15 (`optimizer` classified as self-learning)
## Context
Waggle tracks model costs and budget limits (execution traces, cost reservation, the
`CostTracker` in the agent). It also has a self-learning subsystem: behaviour evolution,
improvement signals, learning from user corrections, judge and eval loops, and the
`packages/optimizer` package for GEPA prompt optimization, called from the chat route through
`packages/server/src/local/services/optimizer-service.ts`.
## Decision
- Cost tracking and budget limits are part of the community edition, under MIT.
- Self-learning is excluded, including `packages/optimizer`. The project owner reworks it
separately.
## Consequences
- P1.2 and P1.5 move cost tracking to `waggle.db`.
- P1.4 removes the self-learning modules, `packages/optimizer` and the optimizer service. The
tables `evolution_runs` and `improvement_signals` are not carried into `waggle.db`.
- P1.4 decides whether the optimization log (`optimization_log`) is still needed without
`optimizer`.

View File

@@ -0,0 +1,34 @@
# ADR-0005: The WhatsApp channel uses whatsapp-web.js
- Status: Accepted, one open item (browser source)
- Date: 2026-10-14
## Context
The WhatsApp channel (`packages/server/src/local/channels/whatsapp-adapter.ts`) uses Baileys.
Baileys itself is MIT, but it depends on `libsignal`, which is GPL-3.0. The sidecar build
bundles both, which would put GPL code into the shipped community edition.
## Decision
Replace Baileys with `whatsapp-web.js` (Apache-2.0) and remove Baileys from the dependencies
of `server` and `launcher`.
## Consequences
- `whatsapp-web.js` drives a Chrome browser through Puppeteer. The installer does not bundle a
browser, and installing dependencies does not download one.
- Open item, proposed and awaiting the owner: use an installed Edge or Chrome, and download a
browser (about 170 MB) only if none is found when the user enables WhatsApp.
- Voice and video messages go through ffmpeg, which is not bundled because ffmpeg builds carry
their own LGPL or GPL terms. Use an installed ffmpeg or download it on demand.
- The client is unofficial. The UI warns that WhatsApp may block the account.
## Alternatives considered
- whatsmeow (Go, MPL-2.0): no browser, but needs a separate Go binary per platform.
- WPPConnect (LGPL-3.0): also browser-based, stricter license.
- venom-bot: no npm release since November 2024.
- open-wa: Hippocratic license, not an open-source license in the OSI sense.
- WhatsApp Business Cloud API: needs a business account and a public webhook, so it does not
fit a local app.

View File

@@ -0,0 +1,25 @@
# ADR-0006: Analytics are opt-in
- Status: Accepted, one open item (PostHog project)
- Date: 2026-10-14
## Context
The web UI initializes PostHog on startup when a project key was present at build time, and
only an opt-out marker in local storage stops it. Local telemetry
(`packages/core/src/telemetry.ts`) stays on the machine.
## Decision
- Analytics are opt-in. On first launch a dialog asks for consent. Until the user chooses
"Allow", PostHog is not initialized and nothing is sent.
- Settings have a toggle to change the choice later.
- The PostHog project key is injected at build time (`VITE_POSTHOG_KEY`) from the build
environment and is never committed. Builds from source without the key send nothing.
## Consequences
- P1.3a adds the consent dialog and the settings toggle and moves PostHog initialization
behind consent.
- Open item, proposed and awaiting the owner: a separate PostHog project for the community
edition, so its events never mix with the commercial product.

30
docs/oss/adr/README.md Normal file
View File

@@ -0,0 +1,30 @@
# Decision records: Waggle community edition
Each record captures one decision that shapes the community edition: the context, what was
decided and what follows from it. Records are numbered and never renumbered. To change a
decision, add a new record that supersedes the old one.
| ADR | Decision | Status |
|---|---|---|
| [0001](0001-no-monetization.md) | The community edition has no monetization | Accepted |
| [0002](0002-memory-contract-local-mem0.md) | Memory goes through a contract backed by local mem0 | Accepted |
| [0003](0003-team-mode-postponed.md) | Team mode stays in the repository but is not built or shipped | Accepted |
| [0004](0004-cost-tracking-in-self-learning-out.md) | Cost tracking is open; self-learning and `optimizer` are excluded | Accepted |
| [0005](0005-whatsapp-web-js.md) | The WhatsApp channel uses `whatsapp-web.js` | Accepted, one open item |
| [0006](0006-opt-in-analytics.md) | Analytics are opt-in | Accepted, one open item |
## Pending decisions
These are open with the project owner. Work continues on temporary choices and the affected
work packages wait for the answer.
| Topic | Temporary choice | Blocks |
|---|---|---|
| Licensing review | Technical license checks continue | P2.3, P2.6 |
| Product name and system identifiers | Temporary names | P1.3d, P2.6 |
| Location of the public repository | Manual builds on each OS | P1.3d, P2.6 |
| Supported platforms for v1 | Windows x64, macOS arm64 and x64, Linux x64 (glibc) | P1.3b, P1.3d |
| Installer signing | First release may ship unsigned with launch instructions | P2.5 |
| Separate data directory from the commercial edition | Not separated yet | P1.3c |
| Browser source for WhatsApp | See ADR-0005 | P1.7 |
| PostHog project for the community edition | See ADR-0006 | P1.3a |

56
docs/oss/baseline.md Normal file
View File

@@ -0,0 +1,56 @@
# Baseline at the start of the conversion
The state of build, typecheck, lint and tests before any scope work. Every later change is
compared against this record: a check that passes here must not start failing.
- Date: 2026-10-15
- Commit: `2346cf3` on `oss/community-edition` (the commercial code at `b20b138` plus the fixes
UF-001, UF-007, UF-008, UF-021 and UF-022)
- Machine: macOS 26.6.2, Apple silicon (arm64), Node 22.23.2, npm 10.9.8
- CI: not set up yet. The location of the public repository is still open, so this record
stands in for a CI baseline until the pipeline exists (work package 0.2).
## Results
| Check | Command | Result |
|---|---|---|
| Package build | `npm run build:packages` | Pass |
| Typecheck, agent | `npx tsc --noEmit --project packages/agent/tsconfig.json` | Pass |
| Typecheck, server | `npx tsc --noEmit --project packages/server/tsconfig.json` | Pass |
| Typecheck, app tooling | `npx tsc --noEmit --project app/tsconfig.json` | Pass |
| Typecheck, web | `cd apps/web && npx tsc --noEmit -p tsconfig.app.json` | Pass |
| Web build | `cd apps/web && npx vite build --outDir <temp dir>` | Pass |
| Lint | `npx eslint .` | 1,516 files, 0 errors, 0 warnings |
| Unit tests, root | `npm run test` | 719 files, 12,012 tests: 11,915 passed, 41 failed, 56 skipped (8.6 min) |
| Unit tests, web | `cd apps/web && npx vitest run` | 221 files, 1,979 tests, all passed (2.4 min) |
| E2E | `npm run test:e2e` | Not run, see below |
| Visual regression | `npm run test:visual` | Not run, see below |
The web build went to a temporary directory instead of the root `dist/`, because a running
sidecar serves that directory.
In the full root run `packages/hive-mind-cli/tests/cli-help.test.ts` also failed once: the
isolated home made npm print an update notice into the CLI output. The setup now turns that
notice off and the file passes (3 of 3), so the totals above count it as passing.
## Known failures (macOS)
All 41 failing root tests are in four files and fail the same way when run alone. They are
logged as UF-023.
| File | Failing | Symptom |
|---|---|---|
| `packages/server/tests/local/managed-ollama-runtime.test.ts` | 38 of 45 | "Official runtime archive did not contain ollama.exe" |
| `packages/hive-mind-hooks-openclaw/tests/handler.test.ts` | 1 of 16 | Expects `/var/folders/...`, receives `/private/var/folders/...` |
| `packages/server/tests/local/files.test.ts` | 1 of 48 | "escapes workspace root through symlink" in a move test |
| `packages/server/tests/local/external-tool-runs.test.ts` | 1 of 17 | "OpenClaw run did not settle" (timeout, not investigated) |
## Not run yet
- **E2E and visual regression.** By default the Playwright web server reuses any sidecar on
`:3333` with its data directory, and it rebuilds the root `dist/`. A baseline run needs a
free port and an isolated data directory (`WAGGLE_E2E_REUSE_EXISTING_SERVER=0`,
`WAGGLE_E2E_PORT`) at a time when restarting the local sidecar is acceptable.
- **Infrastructure suites** (`npm run test:infra`) need Postgres and Redis and cover team
mode, which is not part of the community edition.
- **Windows and Linux.** This record covers macOS only.