# Contributing to `@waggle/hive-mind-core`

This package is the substrate of the Waggle OS memory layer + the Apache 2.0 OSS subtree-split target. Contributions are welcome from anyone — the substrate is built to be a standalone OSS library, not a Waggle-only artifact.

## How the package is distributed

`@waggle/hive-mind-core` lives in the `marolinik/waggle-os` monorepo at `packages/hive-mind-core/`. From there, `git subtree split` periodically emits the contents to a public OSS repo at `github.com/marolinik/hive-mind`.

If you're reading this on **github.com/marolinik/hive-mind** (the OSS mirror): file issues + PRs against THAT repo. The maintainer (Egzakta Group) periodically merges accepted upstream changes back into `marolinik/waggle-os` via the inverse subtree-pull.

If you're reading this on **github.com/marolinik/waggle-os** (the canonical monorepo): file issues + PRs directly here. Changes ship to OSS via the next `subtree split` cycle.

The OSS-export filter excludes Waggle-proprietary files documented in `EXTRACTION.md` (when present) — currently `vault.ts`, `evolution-runs.ts`, `execution-traces.ts`, `improvement-signals.ts`, and `compliance/**` stay in `@waggle/core`, not `@waggle/hive-mind-core`. PRs touching those files belong on the waggle-os monorepo only.

## Direction of development (maintainers — ratified 2026-06-11)

**The monorepo is the sole source of truth. Maintainers must not author features directly on the OSS mirror.** This invariant broke once: the cross-encoder reranker was written directly on `marolinik/hive-mind` during a benchmark arc and existed only there until a recon pass found it and reverse-ported it (waggle-os `f47ee8f`). The rules that prevent a repeat:

1. Substrate changes are authored in `waggle-os/packages/hive-mind-core/` first; the mirror is regenerated via `scripts/oss-subtree-split.sh` afterward.
2. Work done in a scratch `hive-mind` checkout (benchmarks, experiments) must be reverse-ported into the monorepo in the same work arc — never left to accumulate on the mirror.
3. Run `scripts/oss-drift-check.sh` before every OSS release push and after any arc that touched a hive-mind checkout. It file-diffs the mapped source trees and flags ONLY-IN-OSS files (the reverse-port failure mode), ONLY-IN-MONO files (pending export), and divergent edits.
4. External contributor PRs against the OSS repo are welcome (see above) — the maintainer merges accepted changes back into the monorepo via subtree-pull, then re-splits.

## Setting up the dev environment

```bash
# Clone the monorepo
git clone https://github.com/marolinik/waggle-os.git
cd waggle-os

# Install workspace deps (registers all packages including hive-mind-core)
npm install

# Build the substrate
cd packages/hive-mind-core
npx tsc --build

# Run hive-mind-core's tests in isolation
npx vitest run

# Run the full repo test suite
cd ../..
npm run test
```

Node.js >= 20 required. macOS and Linux work natively. Windows works with the postinstall override that `@waggle/hive-mind-cli` provides — see `packages/hive-mind-cli/docs/WINDOWS-QUIRKS.md`.

## Code style

- TypeScript strict mode (the monorepo `tsconfig.base.json` enables `strict: true`, `noImplicitAny`, `noUnusedLocals`, `noUnusedParameters`)
- ESM modules — `.js` extensions on all relative imports for runtime resolution after tsc emit
- No `any` in application code — use `unknown` + narrowing
- Public API methods + exported functions get explicit return types
- Internal class methods can rely on type inference

The repository uses ESLint at the workspace root — run `npm run lint` from the repo root.

## Pull request guidelines

1. **Fork** the canonical waggle-os repo (or work on a branch in your local clone if you have direct push access).
2. **Create a branch** named `feat/<short-description>` or `fix/<short-description>`.
3. **Test first** — for any non-trivial change, add or extend a test in `packages/hive-mind-core/tests/`. Existing tests are organized by substrate area (`tests/mind/`, `tests/harvest/`).
4. **Run the full suite** — `npm run test` from the repo root. Failing tests block the PR. (Some env-dependent tests are expected to fail without local Postgres + Redis — they're marked in the `marketplace` + `server` packages, not in `hive-mind-core`.)
5. **tsc must compile clean** — `npx tsc --build` from the package root.
6. **Open the PR** against `main` of waggle-os. Include in the PR body:
   - What changed + why
   - Test plan (which test files added/modified)
   - Whether the change affects the OSS subtree-split surface (i.e., introduces new public exports, changes existing public types, deprecates surface)

Maintainer review aim: 2 business days for triage, additional time for substantial changes.

## Code of Conduct

This project follows the [Contributor Covenant Code of Conduct](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). Be excellent to each other.

Report issues to `hello@egzakta.com` or by opening a private security advisory on the canonical repo.

## License

By contributing, you agree your contributions are licensed under Apache 2.0 (see `LICENSE`). Egzakta Group d.o.o. acts as steward for the OSS distribution.

## Quick links

- Canonical monorepo: https://github.com/marolinik/waggle-os
- OSS mirror: https://github.com/marolinik/hive-mind
- Issues: https://github.com/marolinik/waggle-os/issues
- Maintainer: Egzakta Group d.o.o. — `hello@egzakta.com`