moving

docs/briefs/hive-mind-ci-npm-publish-brief-2026-04-19.md

@@ -0,0 +1,154 @@
+# Brief za Claude Code — hive-mind CI pipeline + npm publish
+
+**Datum**: 2026-04-19
+**Izvor**: H-34 closure posle 2026-04-18 late-night sesije (282/282 green, 4 packages, ~8500 LOC vendored)
+**Scope**: JEDNA sesija, jedan fokus. No new features, no scope creep.
+**Output**: Green CI badge + 4 packages live na npm registry + first-run smoke skripta
+
+---
+
+## Session goal (one sentence)
+
+Take the hive-mind repo from "locally 282/282 green" to "cloneable by a stranger, CI-validated, installable via `npm install @hive-mind/*` on any machine, with a smoke test script that proves end-to-end working MCP server in under 5 minutes."
+
+## Why now
+
+H-34 extraction is tehnički CLOSED (Waves 4–6 shipped 2026-04-18). But the repo is not "shipped" until:
+1. A fresh clone on a clean runner passes all 282 tests without manual intervention.
+2. The 4 packages are discoverable via `npm search` and installable via `npm install`.
+3. A press/analyst persona (non-developer) can run a smoke script and see the MCP server work.
+
+This session closes that gap. It is the last operational task before SOTA benchmark proof (LoCoMo 91.6% target) becomes the critical-path blocker for Waggle launch.
+
+## Current state (as of H-34 closure)
+
+- Repo: `D:\Projects\hive-mind`, Apache 2.0, 4 packages migrated.
+- Packages: `@hive-mind/core`, `@hive-mind/wiki-compiler`, `@hive-mind/mcp-server`, `@hive-mind/cli`.
+- Tests: 282/282 green across 38 test files (locally).
+- Commits: Waves 4-6 landed in 2026-04-18 session (`9f774f7`, `74f2b76`, `a30d04a`, `6c32987`).
+- Missing: GitHub Actions config, npm publish config, CHANGELOG, first-run smoke, release notes.
+
+## Non-goals (strict)
+
+- NO new features.
+- NO refactoring beyond what CI forces.
+- NO touching waggle-os monolith (companion fix `803c6f6` already landed separately).
+- NO starting v2 GEPA, LoCoMo benchmark, or H13 landing work.
+- NO npm scope changes, package renames, or version bumps beyond v0.1.0.
+- NO platform-specific CI (Windows/macOS matrix) in this pass — Linux runner only. Cross-platform is a follow-up.
+
+If any non-goal item appears tempting, STOP and write a follow-up issue instead.
+
+## Acceptance criteria
+
+### A. GitHub Actions CI pipeline
+
+Path: `.github/workflows/ci.yml` in hive-mind repo.
+
+- Triggers: push to `main`, PR to `main`.
+- Runner: `ubuntu-latest`, Node 22 LTS, pnpm (use repo's pnpm version from `package.json` `packageManager` field or `.nvmrc` / `.tool-versions`).
+- Steps (in order):
+  1. Checkout
+  2. Setup Node + pnpm + cache
+  3. `pnpm install --frozen-lockfile`
+  4. `pnpm -r run lint` (if lint scripts exist; skip gracefully if not)
+  5. `pnpm -r run typecheck` (if typecheck scripts exist)
+  6. `pnpm -r run test` — MUST pass with 282/282 on clean runner
+  7. `pnpm -r run build`
+  8. Artifact upload: dist folders of all 4 packages (for inspection)
+- Required status check to be enabled on `main` branch protection.
+- Green badge in README.md.
+
+### B. npm publish readiness (dry-run first, then publish)
+
+For each of the 4 packages:
+
+- `package.json` has: `name`, `version: "0.1.0"`, `description`, `license: "Apache-2.0"`, `repository` (pointing to GitHub repo), `homepage`, `bugs`, `keywords`, `author`, `main`, `types` (if TS), `files` (explicit allowlist, not `.npmignore`), `publishConfig.access: "public"` (for scoped packages).
+- `README.md` at package root (can be short, links to monorepo root README).
+- LICENSE file at package root (Apache 2.0 text).
+- `pnpm -r publish --dry-run` MUST succeed without warnings beyond informational.
+- After dry-run clean: actual `npm publish` for all 4 packages.
+- Verify via `npm view @hive-mind/core` etc. that all 4 are live.
+
+Note on npm org scope: if `@hive-mind` org does not exist on npm yet, Claude Code stops and asks Marko to create it with his npm login (requires 2FA + organization creation flow). Alternative: unscoped names `hive-mind-core` etc. — but preferred is scoped.
+
+### C. Root README normalization
+
+Path: `README.md` at hive-mind repo root.
+
+- CI badge (green)
+- npm version badges for all 4 packages
+- Quickstart: 5 lines max to go from `npm install` to first MCP tool call
+- License: Apache 2.0
+- Link to EXTRACTION.md (methodology doc)
+- Link to first-run smoke (see D)
+- Cross-repo link to `waggle-os` as consuming application
+
+### D. First-run smoke script
+
+Path: `scripts/first-run-smoke.sh` (+ Windows counterpart `scripts/first-run-smoke.ps1` if trivial; skip if not).
+
+- Goal: A non-developer (press/analyst persona) runs one command and sees the MCP server respond.
+- Steps automated:
+  1. Check Node 22+ available
+  2. `npm install -g @hive-mind/cli` (or temp-dir install)
+  3. `hive-mind init --tmp` (creates sample workspace in a temp dir)
+  4. `hive-mind mcp start &` (starts MCP server)
+  5. `hive-mind mcp call list_tools` (prints 21 tools)
+  6. `hive-mind harvest demo` (runs one small harvest from a public URL)
+  7. `hive-mind mcp call search "demo"` (returns results)
+  8. Print green checkmark + "smoke passed in Nms"
+
+If any command does not exist in the current CLI surface, STOP — do not add it. Note the gap and return to Marko for decision (this is persona-facing; we do not invent commands).
+
+### E. CHANGELOG.md
+
+Path: `CHANGELOG.md` at root. Keep-a-Changelog format.
+
+```
+## [0.1.0] - 2026-04-19
+
+### Added
+- Initial public release extracted from waggle-os monolith
+- @hive-mind/core: bitemporal KG, MPEG-4 I/P/B frame model, workspace, mind-cache
+- @hive-mind/wiki-compiler: markdown compile pipeline with versioned output
+- @hive-mind/mcp-server: 21 MCP tools + 4 resources
+- @hive-mind/cli: 6 commands (init, harvest, mcp, wiki, search, status — verify exact names)
+- 282 tests across 38 files
+- Apache 2.0 license
+```
+
+### F. Release notes + GitHub Release
+
+- Tag `v0.1.0` on the commit that passes CI green.
+- GitHub Release from the tag, body = CHANGELOG entry + "installed via `npm install @hive-mind/core`".
+- Marked as "latest release" and NOT pre-release (first stable public).
+
+## Order of operations (recommended)
+
+1. CI pipeline first (A). Do not touch anything else until CI runs green on a commit in `main` (or a feature branch). CI will expose any hidden local-only assumptions fast.
+2. Package metadata hardening (B, up to dry-run). Dry-run surfaces missing fields without committing to npm.
+3. Root README + CHANGELOG (C, E). Easy wins that unblock D.
+4. First-run smoke (D). This is the riskiest item — it exercises the full surface from outside. Expect to find 1-2 small gaps in CLI surface area. Flag them to Marko via follow-up issue, do NOT patch inline.
+5. npm org creation + real publish (B final step). Requires Marko.
+6. Tag + GitHub Release (F).
+
+## Definition of done
+
+- CI green on `main` for the commit that ships v0.1.0.
+- `npm view @hive-mind/core` returns `0.1.0`.
+- `scripts/first-run-smoke.sh` on a clean Ubuntu runner exits 0 in under 5 minutes.
+- CHANGELOG.md has v0.1.0 entry.
+- GitHub Release `v0.1.0` exists with installation instructions.
+- Root README has green CI badge + npm badges + 5-line quickstart.
+
+## Escalation triggers (when to stop and ask Marko)
+
+- npm `@hive-mind` org does not exist → needs Marko's npm login.
+- CI fails on a test that passed locally → likely environment assumption; worth 30 min to diagnose, then stop.
+- `pnpm publish --dry-run` warns about something non-trivial → confirm with Marko before proceeding.
+- CLI surface gap in first-run smoke → do not invent commands; report and ask.
+
+## Reporting at session end
+
+Brief commit log (files touched, tests added if any), npm package URLs (once live), first-run smoke timing, and one-paragraph "what was surprising" note. Surface any technical debt discovered during CI surfacing — these go to follow-up issues, not patched in this session.