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

This package is the canonical private-monorepo source for Waggle OS's memory
substrate and its maintainer-curated Apache-2.0 OSS distribution. Contributions
are welcome, but the private tree also contains Waggle-only material and must
never be published directly.

## Distribution and trust boundary

- Canonical source: private `marolinik/waggle-os`, under
  `packages/hive-mind-core/`.
- Public contribution surface: `github.com/marolinik/hive-mind`.
- Distribution mechanism: a reviewed, maintainer-curated forward-port that
  adapts layout/imports and removes every private exclusion.
- `scripts/oss-subtree-split.sh` produces local inspection refs only. Raw refs
  are never publication sources.

The public export excludes:

- `src/mind/evolution-runs.ts`
- `src/mind/execution-traces.ts`
- `src/mind/improvement-signals.ts`
- private vault/compliance surfaces outside this package
- interleaved `install_audit` DDL and migration logic inside
  `src/mind/{schema,db}.ts`

A file filter cannot enforce the interleaved exclusion.

## Direction of development

The private monorepo is the sole source of truth. Maintainers must not author
features only in the public mirror.

1. Author substrate changes in `waggle-os/packages/hive-mind-core/` first.
2. Reverse-port accepted public contributions into the private monorepo before
   the next curated export.
3. Run `scripts/oss-drift-check.sh` before every OSS release and after any arc
   that touched a Hive Mind checkout. The thin shell entrypoint delegates to
   the cross-platform Node 20 checker, which validates
   `scripts/oss-drift-baseline.json` without updating or accepting it. Separate
   sections identify reviewed adaptations, intentional private exclusions,
   known reviewed blockers, unreviewed differences, forbidden whole-file
   leaks, and any interleaved `install_audit` marker, including comments.
4. Treat exit `1` as release-blocking source drift and exit `2` as an
   untrustworthy setup/configuration result. Exit `0` means the mapped bytes
   exactly match the reviewed clean baseline; it is not a substitute for
   maintainer review of a new forward-port.

## Development setup

### External contributors

Use the public mirror; private Waggle OS access is neither required nor
expected.

```bash
git clone https://github.com/marolinik/hive-mind.git
cd hive-mind
npm install
npm run build
npm run test
npm run lint
```

Open branches, issues, and pull requests against `marolinik/hive-mind`.

### Maintainers with private access

```bash
git clone https://github.com/marolinik/waggle-os.git
cd waggle-os
npm install
npx tsc --build packages/hive-mind-core/tsconfig.json
npx vitest run packages/hive-mind-core/tests
```

After the canonical change lands, prepare a separate curated forward-port in a
clean public-mirror branch and review the complete export diff.

Node.js 20 or newer is required. Public contributors should use the public
mirror README and issues for current platform support. Maintainers working in
the private monorepo can additionally consult
`packages/hive-mind-cli/docs/WINDOWS-QUIRKS.md`.

## Code style

- TypeScript strict mode; avoid `any` in application code.
- ESM modules with `.js` extensions on relative imports where required by the
  emitted runtime.
- Explicit return types for exported functions and public API methods.
- Follow the repository-root ESLint configuration.

## Pull request checklist

1. Work in the repository you are authorized to access: external contributors
   use `marolinik/hive-mind`; maintainers use the private canonical monorepo.
2. Name branches `feat/<short-description>` or `fix/<short-description>`.
3. Add or extend tests for every non-trivial change.
4. Run that repository's build, tests, and lint before opening the PR.
5. In the PR body, explain the change, list verification, and state whether the
   curated OSS surface is affected.

Maintainers reverse-port accepted public changes into the canonical monorepo
before preparing the next curated export.

## Conduct, security, and license

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

Report security issues through a [private security advisory on the public Hive
Mind mirror](https://github.com/marolinik/hive-mind/security/advisories/new) or
email `hello@egzakta.com`. Do not open a public vulnerability issue.

Contributions to the public mirror are licensed under Apache-2.0. Copyright and
notice terms are defined solely by `LICENSE`.