@simplium/hive 4.0.0

package/CHANGELOG.md

@@ -0,0 +1,225 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+Remaining work: npm publish (`@simplium/hive` — org verification + `npm publish`, package is pack-tested); OpenCode adapter (Q4 access pending); GDPR/DPA with Anthropic (R7, external action); Phase 3 public docs.
+
+---
+
+## [4.0.0] - 2026-07-02
+
+HIVE becomes a **pure agent governance layer**: the Layer 2 runtime is gone, traceability is automatic, the capability pack is distributable via npm, and definitions are empirically evaluable. All claims verified by command.
+
+### BREAKING — Removed
+- **Layer 2 NestJS runtime removed** (`apps/hive-runtime`, `packages/hive-core`, Turborepo). Preserved intact in the [`legacy/layer2-runtime`](https://github.com/marcablanca/hive-framework/tree/legacy/layer2-runtime) branch. The `hive` CLI (`run`/`stats`/`learn`) no longer exists; per ADR-000 the host runtime executes agents
+- With it goes its entire dependency surface: **`npm audit` now reports 0 vulnerabilities** (was 8 moderate, all in the NestJS/express chain)
+
+### Added
+- **Automatic traceability hook** (`hooks/hive-log.mjs`) — zero-dep PostToolUse hook: every HIVE agent invoked via the Task tool is logged to `HIVE-LOG.md` (ISO 42001 A.9) and `.claude/hive-events.jsonl` (machine-readable stream for external observability, e.g. Argos). Replaces the honor-system self-logging footer; never blocks tool flow; ignores non-HIVE subagents. Installed by `init-project` in consumers and dogfooded in this repo
+- **npm package** — `@simplium/hive` with `npx hive-init <dir>` zero-dep installer; `prepack` renders the consumer payload into `dist/claude` (aborts unless 18+18). Pack-tested end to end (tarball → install → bin). `private: true` kept as publish guard until the npm org is verified
+- **Layer 1 evals** (`npm run eval`) — 5 golden tasks against the live API using the real adapter body + assigned model per agent; structural checks, cost from API usage fields, `HIVE_EVAL_BUDGET_USD` cap, stale model IDs surface as findings; honest SKIP without `ANTHROPIC_API_KEY`
+- **`scripts/lib/adapter-render.ts`** — single source of truth for permission translation and adapter rendering (was duplicated across both generators)
+- **Typecheck gate** (`npm run typecheck`) in CI, replacing the removed build step
+- 7 new tests (6 hook + 1 eval skip-path); suite total 15, now 100% aimed at the live surface
+
+### Changed
+- README rewritten around the **agent governance layer / capability pack** positioning (explicitly not an AgentOS)
+- `@hive/core` types/schemas inlined into `scripts/lib/` (runtime-only types dropped)
+- CI actions bumped to v5 (Node 24 runners); repo is flat — no workspaces, no turbo
+- `.env.example` reduced to eval configuration
+- `audit_prompt.md` moved to `docs/auditorias/`
+
+---
+
+## [3.2.0] - 2026-07-02
+
+Post-audit remediation (forensic audit 2026-07-02 verified the declared state as reliable; this release closes the P2/P3/P4 findings). All claims verified by command.
+
+### Added
+- **Root test suite for Layer 1 generator/ops scripts** (`scripts/scripts.spec.ts`, 8 tests): validate, reindex determinism, adapter contract (18+18 files, `human_approval` ⇒ `disallowedTools: Bash`, version stamp), init-project install + dry-run, log-session append/reject, cost-report. Closes the coverage gap where all 161 tests lived in the ADR-000-superseded runtime layer. Total suite: 169
+- **`log-session --file <path>`** — target log override (testability; default unchanged)
+- **CI gate: generated files in sync** — `reindex` + `adapters` + `git diff --exit-code` fails the build if `AGENT_INDEX.yaml` or `.claude/` adapters drift from sources
+
+### Changed
+- **Package manager: pnpm → npm** per the ecosystem mandate (npm in all environments): npm workspaces replace `pnpm-workspace.yaml`, `package-lock.json` tracked (3.0.3 lockfile lesson applied), CI runs `npm ci` and npm-form gates, live docs / agent sources / Golden Path B / generated adapters use npm command forms (`npm run X -- <args>`). Historical audit records under `audit/` kept verbatim
+- **`reindex` is deterministic** — keeps the existing `AGENT_INDEX.yaml` untouched when only generation dates would change (no more date churn)
+- **Quickstart restructured** — Layer 1 `init-project` is the primary path; the Layer 2 runtime is explicitly marked as reference (ADR-000) and its live-API/DB end-to-end flow declared out of release verification
+- `--max-warnings 0` enforced inside each workspace `lint` script (was a fragile CI passthrough arg)
+- `hive.config.ts` monorepo root detection now keys on `turbo.json` (was `pnpm-workspace.yaml`, removed in this release)
+
+### Fixed
+- README version badge said 3.0.3 while package.json was 3.1.0
+- Last live v2 model reference (`GEMINI` in documentation-writer footer) removed; agent history table kept as record
+- RISK-REGISTER R6 stamp wording made version-agnostic (was frozen at v3.0.3)
+
+---
+
+## [3.1.0] - 2026-06-22
+
+Post-audit implementation. All claims in this entry are verified; no aspirational items. Tests: 161/161.
+
+### Added
+- **Claude Code Layer 1 discovery** — `.claude/agents/` (18 agents) and `.claude/skills/` (18 skills) generated from HIVE source definitions; agents carry native `disallowedTools` translated from the HIVE abstract permission model
+- **`pnpm adapters`** (`scripts/generate-adapters.ts`) — regenerates Claude Code adapters for this repo; idempotent; includes HIVE version stamp per file
+- **`pnpm init-project <dir>`** (`scripts/init-project.ts`) — installs Layer 1 adapters in any consumer project without forking; run again after `git pull` to update
+- **`pnpm log-session`** (`scripts/log-session.ts`) — appends an agent invocation row to `HIVE-LOG.md`; covers ISO 42001 A.9 traceability for Layer 1 usage
+- **`pnpm cost-report`** (`scripts/cost-report.ts`) — reads `HIVE-LOG.md`, infers model from adapters, calculates estimated cost (75%/25% in/out ratio) per agent; alerts when average session cost exceeds `max_cost_per_task`
+- **`HIVE-LOG.md`** — append-only session log tracked in git; `git log` of the file is the audit trail
+- **ESLint flat config** (`eslint.config.mjs`) — `typescript-eslint` + `eslint-config-prettier`; 0 errors, 0 warnings; `pnpm lint` now executes (was phantom since 3.0.0)
+- **CI: lint gate** — `pnpm lint -- --max-warnings 0` added before build
+- **CI: security audit gate** — `pnpm audit --audit-level=high` (0 current high vulns; gate catches regressions)
+- **Prompt injection guard** — `[Security — Prompt Injection Guard]` block inserted into all 36 agent/skill definitions (LLM01/OWASP)
+
+### Fixed
+- **Pricing** (`hive.config.ts`): opus input 15→5, output 75→25; haiku input 0.25→1, output 1.25→5 — all prior cost trail in USD was wrong
+- **JIT savings** (README): "~85%" corrected to "over 90% (measured: 93–98%, see `scripts/measure-jit.ts`)"
+- **Test count** (README, docs): 153→161 (was wrong since 3.0.0)
+- **Human approval enforcement**: `human_approval: true` now maps to `disallowedTools: [Bash]` in Claude Code adapters; 7 blocking agents cannot execute shell commands without the host session surfacing them for approval — replaces the phantom gate that was never implemented in the harness
+- Removed `REDIS_URL` from `.env.example` (Redis never used in runtime)
+- Removed unused `fileURLToPath` import (`hive.config.ts`) and `loadAgent` import (`agent-loader.service.ts`)
+- Gemini v2 fields (`fallback_to_gemini_when`, `gemini-3-pro` entries) removed from 7 definition bodies — HIVE v3 is Anthropic-only
+- `claude-3-5-sonnet-20241022` → `claude-sonnet-4-6` in ai-ml-engineer code examples
+- Antigravity runtime commands labeled `[Runtime: Antigravity — v2 legacy]` in web-performance, seo-aeo-geo, documentation-writer skills
+
+### Changed
+- **vitest** 2.1.0 → 3.2.6 (eliminates critical vulnerability; 161/161 tests pass on v3)
+- **@nestjs/config** 3.x → 4.x (drops lodash dependency, eliminates high vulnerability)
+- **pnpm overrides**: `multer ≥2.1.1`, `form-data ≥4.0.6`, `vite ≥6.4.2` — force patched versions of transitive deps not directly upgradable
+- **ADR-000** status: direction decided (A2) and implemented for Claude Code; OpenCode pending
+- **IMPLEMENTATION-PLAN**: D1.2 BullMQ/Redis, D1.6 WebSocket, D3.1-D3.4 MCP marked with honest status (not shipped / partial)
+- **`[Unreleased]`**: Phase 2 scope superseded by ADR-000 A2 decision
+
+### Security
+- Vulnerabilities: 17 (1 critical dev-only, 4 high) → 10 (0 critical, 0 high) via dep updates and pnpm overrides
+- Prompt injection: 0/36 → 36/36 definitions with explicit injection guard
+
+---
+
+## [3.0.3] - 2026-04-21
+
+### Fixed
+- CI was failing because `pnpm-lock.yaml` was excluded by `.gitignore`; lockfile now tracked so `pnpm install --frozen-lockfile` resolves on the runner
+- Prisma client was never generated during build, breaking typecheck for `PrismaService`; `build` script now runs `prisma generate && tsc`, and a `postinstall` hook keeps local dev in sync
+- `learn.command.ts` typed `entries` parameters with `ReturnType<ErrorCaptureService["parseJournal"]>`, but `parseJournal` is async; wrapped with `Awaited<...>` to unwrap the Promise
+
+### Added
+- `db:migrate` and `db:generate` scripts in `@hive/runtime` for local Prisma workflows
+
+---
+
+## [3.0.2] - 2026-04-20
+
+### Added
+- `README.md` rewritten in English: reflects the v3 runtime, CLI, validation pipeline, MCP bridge; removes stale v2.x content
+- `CHANGELOG.md` (this file) following Keep a Changelog + SemVer
+- `package.json` metadata: `description`, `license`, `author`, `repository`, `homepage`, `bugs`, `keywords`, `engines`
+
+---
+
+## [3.0.1] - 2026-04-05
+
+### Fixed
+- Corrected Anthropic model IDs used by the executor
+- Made ErrorCapture I/O async to avoid blocking the event loop
+- Downgraded missing-MCP warning to nominal severity when a server is optional
+
+---
+
+## [3.0.0] - 2026-04-05
+
+Phase 0 + Phase 1 complete. Full rewrite introducing the NestJS runtime, Turborepo monorepo, and the v3 agent/skill format.
+
+### Added
+- **v3 agent/skill format** — YAML frontmatter + Markdown body; all 36 entries live in per-directory `AGENT.md` / `SKILL.md` files
+- **36 agents/skills migrated** — all entries from v2.x converted to v3 format with required frontmatter fields (`type`, `tier`, `known_failure_modes`, `stacks`, `mcp_required`)
+- **Turborepo monorepo** — `hive-framework` root with `apps/hive-runtime` and `packages/hive-core` workspaces; managed with pnpm
+- **`hive-core` package** — shared types, validation schemas, and utilities
+- **`hive-runtime` NestJS application** — bootstraps as both HTTP gateway and CLI context; no global HTTP server needed for CLI use
+- **Agent loader** — reads `AGENT_INDEX.yaml` at runtime for JIT agent resolution
+- **Agent selector** — keyword + tier + stack matching to pick the best agent for a task
+- **Executor** — calls Claude API with the resolved agent prompt and task description
+- **Prisma + PostgreSQL persistence** — task records, token usage, cost, and event log stored via Prisma ORM
+- **Task queue + TaskRouter** — priority-aware routing with dependency resolution
+- **MCP bridge with fallback** — health-check nominal; no active MCP connections in this release *(corrected 3.1.0)*
+- **Validation pipeline** — four stages: structural validation → evidence checking → confidence scoring → escalation routing
+- **Confidence scoring** — per-output score; low-confidence results escalate or request human approval
+- **Human approval gate** — `human_approval` field validated by schema; runtime enforcement was not implemented in this release *(corrected 3.1.0: enforcement added via `disallowedTools` in Claude Code adapters)*
+- **Event system** — typed event bus for task lifecycle events
+- **Cost tracking** — per-task token count and estimated cost persisted and queryable; pricing had errors corrected in 3.1.0
+- **Structured logging** — Pino installed; used in one code path in this release *(corrected 3.1.0)*
+- **CLI (`hive run` / `hive stats` / `hive learn`)** — thin CLI wrapper over the NestJS app context
+- **Gateway API** — REST endpoints (3 endpoints); WebSocket not implemented in this release *(corrected 3.1.0)*
+- **Evals + golden tests** — regression suite covering golden-path scenarios for both stacks
+- **CI workflow** — GitHub Actions pipeline running build and test; lint gate was not functional in this release *(corrected 3.1.0)*
+- **Error capture hook** — structured error recording with full task context
+- **`hive learn` command** — processes recent outcomes to update confidence baselines
+- **161 tests** — unit and integration tests (Vitest) *(was documented as 153; actual count verified 3.1.0)*
+- **Apache 2.0 license**
+
+### Changed
+- `AGENT_INDEX.yaml` is now auto-generated by `pnpm reindex` from frontmatter; do not edit manually
+- Replaced flat agent directory with tiered structure (`00-orchestrator` through `07-support`)
+- Modularized large agents exceeding the 25K token limit; extracted reference material to per-agent `references/` directories (45 module files relocated)
+
+---
+
+## [2.3.0] - 2026-01-XX
+
+### Added
+- Golden Paths for Stack A (Laravel) and Stack B (Next.js) with clear directory architecture
+- MCP documentation: global vs project-level MCP configuration
+- Improved `CLAUDE.md` templates with explicit stack declarations
+
+### Changed
+- Security rules updated to define production boundaries more precisely
+- MCPs categorized and documented in `docs/protocols/mcp-registry.md`
+
+---
+
+## [2.2.0] - 2026-01-XX
+
+### Added
+- PRP (Product Requirements Prompt) system integrated into the Orchestrator
+- `PRPValidator` — validates PRP completeness before task decomposition
+- `PRPToTasksConverter` — converts a PRP into routable sub-tasks
+- Full PRP template with annotated example
+
+---
+
+## [2.1.0] - 2026-01-XX
+
+### Added
+- **JIT Mapping** — `AGENT_INDEX.yaml` for agent discovery; only the selected agent's definition is loaded per task (~85% token context reduction)
+- `pnpm reindex` script to regenerate the index from agent frontmatter
+
+---
+
+## [2.0.0] - 2026-01-XX
+
+### Added
+- 36th agent: `brand-design-system`
+- Multi-model assignment per agent: Opus for blocking tiers, Sonnet for critical, Gemini for content/support
+- Tier system with three levels: Blocking / Critical / Support
+- `human_approval: true` flag on 7 critical agents
+- `upgrade_to_opus_when` field for Sonnet agents that may need escalation
+- `known_failure_modes` field required for Tier 0 and Tier 1 agents
+
+### Changed
+- All agent definitions updated with tier, model, and escalation metadata
+
+---
+
+## [1.0.0] - 2026-01-XX
+
+### Added
+- Initial release: 35 specialized agents covering orchestration, development, quality, infrastructure, intelligence, growth, and support
+- Central Orchestrator agent with task routing logic
+- Anti-fabrication system: `[AF-v2]` footer requirement and evidence checks
+- Initial `CLAUDE.md` with framework conventions

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2024-2026 Jose de Vivar / Simplium
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,148 @@
+# HIVE Framework
+
+**Agent governance layer — 36 curated agent & skill definitions with a portable permission model, traceability, and evidence-based discipline. Installs into any Claude Code project.**
+
+[![CI](https://github.com/marcablanca/hive-framework/actions/workflows/ci.yml/badge.svg)](https://github.com/marcablanca/hive-framework/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
+[![Version](https://img.shields.io/badge/version-4.0.0-brightgreen.svg)](CHANGELOG.md)
+[![Node](https://img.shields.io/badge/node-%3E%3D22-green.svg)](package.json)
+[![npm](https://img.shields.io/badge/npm-11-CB3837.svg)](package.json)
+
+---
+
+## What is HIVE
+
+HIVE is an **agent governance layer**, not an AgentOS: the operating system is provided by the host runtime (Claude Code today; others via adapter generators). HIVE supplies the workforce and the policy — a **capability pack** of 36 definitions (18 agents + 18 skills) covering the full software development lifecycle, each with:
+
+- an **abstract permission model** (`file_system` / `network` / `database` / `human_approval`) translated to each runtime's native enforcement (Claude Code: `disallowedTools`)
+- **tiers and `known_failure_modes`** — criticality-aware routing metadata
+- **anti-fabrication discipline** — evidence requirements and prompt-injection guards baked into every definition
+- **traceability** — automatic invocation logging to `HIVE-LOG.md` (ISO 42001 A.9) plus a JSONL event stream for external observability
+
+Definitions target two stacks: **Stack A** (PHP 8.3 / Laravel / MySQL / Plesk) and **Stack B** (Next.js 15 / NestJS / Prisma / PostgreSQL).
+
+> The former Layer 2 NestJS runtime was retired per [ADR-000](audit/ADR-000-rearchitecture-options.md) and removed in v4. It is preserved in the [`legacy/layer2-runtime`](https://github.com/marcablanca/hive-framework/tree/legacy/layer2-runtime) branch.
+
+---
+
+## Quickstart
+
+```bash
+git clone https://github.com/marcablanca/hive-framework.git
+cd hive-framework
+npm install
+npm run init-project -- /path/to/your-project
+```
+
+This installs 18 agents + 18 skills into the target project's `.claude/` (with native permission translation and version stamps) plus the auto-logging hook. Open the project in Claude Code — everything is discovered natively. Re-run after pulling a new HIVE version to update.
+
+---
+
+## Architecture
+
+```
+0*-*/AGENT.md · SKILL.md          36 source definitions (frontmatter + body)
+        │
+        ├── npm run validate      schema gate (Zod) — 0 errors required
+        ├── npm run reindex       AGENT_INDEX.yaml (JIT index, deterministic)
+        │
+        ├── npm run adapters      .claude/agents + .claude/skills (this repo)
+        └── npm run init-project  same, into any consumer project
+                │
+                ▼
+        Host runtime (Claude Code)
+        native discovery · disallowedTools enforcement · hooks
+                │
+                ├── HIVE-LOG.md            automatic invocation log (ISO 42001 A.9)
+                └── hive-events.jsonl      event stream for external observability
+```
+
+### Tier System
+
+Agents and skills are organized into 8 tiers (00–07), from highest criticality to support roles:
+
+| Tier | Name | Description |
+|------|------|-------------|
+| 00 | Orchestrator | Central coordinator; routes and manages all tasks |
+| 01 | Foundation | Architecture, product, legal/compliance, brand |
+| 02 | Core Development | Backend, frontend, API, database |
+| 03 | Quality & Security | Testing, security auditing, performance, accessibility |
+| 04 | Infrastructure | DevOps, cloud, billing, incident response, search |
+| 05 | Intelligence | AI/ML, data analysis, analytics, observability, voice |
+| 06 | Growth | SEO, marketing, CRO, email, mobile |
+| 07 | Support | Docs, releases, i18n, UX research, competitive intel |
+
+7 agents in blocking tiers carry `human_approval: true`, translated to `disallowedTools: [Bash]` in Claude Code so shell actions surface through the host approval flow.
+
+---
+
+## Agents & Skills Catalog
+
+36 total = 18 agents + 18 skills. Sourced from `AGENT_INDEX.yaml`.
+
+| Tier | Focus | Agents | Skills |
+|------|-------|--------|--------|
+| 00 — Orchestrator | Task routing, coordination | orchestrator | — |
+| 01 — Foundation | Architecture, product, legal | architecture-planner, legal-compliance, product-manager | brand-design-system |
+| 02 — Core Development | Backend, frontend, API, DB | backend-developer, frontend-developer, api-designer, database-engineer | — |
+| 03 — Quality & Security | Tests, security, perf, a11y | test-engineer, security-auditor | web-performance, accessibility |
+| 04 — Infrastructure | DevOps, cloud, billing, search | billing-payments, incident-response | cloud-infrastructure, devops-engineer, search |
+| 05 — Intelligence | AI/ML, data, analytics, voice | ai-ml-engineer, data-analyst | analytics-implementation, observability, voice-ai |
+| 06 — Growth | SEO, marketing, CRO, email, mobile | — | email-deliverability, growth-analytics, landing-page-cro, marketing-communications, mobile-development, seo-aeo-geo |
+| 07 — Support | Docs, releases, i18n, UX, research | competitive-intelligence, cost-optimization, customer-success, ux-research | documentation-writer, release-manager, translator-i18n |
+
+Model distribution: 7 opus / 28 sonnet / 1 haiku. JIT index reduces per-task context by 93–98% vs loading all definitions (`npx tsx scripts/measure-jit.ts`).
+
+---
+
+## Scripts Reference
+
+| Command | Description |
+|---------|-------------|
+| `npm run init-project -- <dir>` | Install/update Layer 1 (adapters + hook) in a consumer project |
+| `npm run adapters` | Regenerate this repo's `.claude/` adapters from sources |
+| `npm run validate` | Validate all 36 definitions against the frontmatter schema |
+| `npm run reindex` | Regenerate `AGENT_INDEX.yaml` (deterministic — no date churn) |
+| `npm run log-session -- --agent <n> --task "..." --outcome <O>` | Manually append an invocation to `HIVE-LOG.md` |
+| `npm run cost-report` | Estimated cost per agent from `HIVE-LOG.md`, with budget alerts |
+| `npm run secrets-audit` | Scan definitions for hardcoded secrets |
+| `npm run eval` | Layer 1 evals against the live API (needs `ANTHROPIC_API_KEY`; skips honestly without it) |
+| `npm test` / `npm run lint` / `npm run typecheck` | Offline quality gates (also in CI) |
+
+---
+
+## Golden Paths
+
+Step-by-step walkthroughs for common workflows on each stack:
+
+- [Golden Path — Stack A (Laravel)](docs/GOLDEN-PATH-STACK-A.md) — PHP / Laravel / Filament / MySQL
+- [Golden Path — Stack B (Next.js)](docs/GOLDEN-PATH-STACK-B.md) — Next.js / NestJS / Prisma / PostgreSQL
+
+---
+
+## Roadmap
+
+| Phase | Status | Scope |
+|-------|--------|-------|
+| Phase 0 — Agent migration | Complete | 36 definitions in v3 YAML frontmatter format |
+| Phase 1 — Core runtime | Retired | NestJS runtime built, then superseded by ADR-000; preserved in `legacy/layer2-runtime` |
+| Phase 2 — Governance layer | Complete | Adapter generators, permission translation, traceability hook, Layer 1 evals, distribution without fork |
+| Phase 3 — Ecosystem | In progress | npm publish (`npx @simplium/hive`, package ready — org verification pending), OpenCode adapter, public docs |
+
+---
+
+## Documentation
+
+- [HIVE Rules & Conventions](docs/HIVE-RULES.md)
+- [Changelog](CHANGELOG.md)
+- [Audit trail (2026)](audit/AUDIT-REPORT.md)
+
+---
+
+## License
+
+Licensed under [Apache 2.0](LICENSE).
+
+## Author
+
+Built by José at [Simplium.io](https://simplium.io).

package/bin/hive-init.mjs

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+/**
+ * HIVE Layer 1 installer (npm package bin).
+ *
+ * Usage:
+ *   npx @simplium/hive <target-dir>        # install/update into a project
+ *   npx @simplium/hive .                   # install into current dir
+ *
+ * Copies the pre-rendered adapters shipped in the package (dist/claude/)
+ * into <target>/.claude/ and wires the traceability hook into settings.json.
+ * Zero runtime dependencies. Idempotent: re-run after upgrading the package.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, copyFileSync, readdirSync, existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const PAYLOAD = join(PKG_ROOT, "dist", "claude");
+const HOOK_COMMAND = 'node "$CLAUDE_PROJECT_DIR/.claude/hooks/hive-log.mjs"';
+
+function fail(msg) {
+  console.error(`✖ ${msg}`);
+  process.exit(1);
+}
+
+const rawTarget = process.argv[2];
+if (!rawTarget) {
+  console.error("Usage: npx @simplium/hive <target-directory>");
+  process.exit(1);
+}
+const target = resolve(process.cwd(), rawTarget);
+if (!existsSync(target)) fail(`Target directory does not exist: ${target}`);
+if (!existsSync(PAYLOAD)) fail("Package payload missing (dist/claude) — was the package built with prepack?");
+
+const version = JSON.parse(readFileSync(join(PKG_ROOT, "package.json"), "utf-8")).version;
+
+function copyDir(fromDir, toDir) {
+  mkdirSync(toDir, { recursive: true });
+  let n = 0;
+  for (const f of readdirSync(fromDir)) {
+    copyFileSync(join(fromDir, f), join(toDir, f));
+    n++;
+  }
+  return n;
+}
+
+const agents = copyDir(join(PAYLOAD, "agents"), join(target, ".claude", "agents"));
+const skills = copyDir(join(PAYLOAD, "skills"), join(target, ".claude", "skills"));
+copyDir(join(PAYLOAD, "hooks"), join(target, ".claude", "hooks"));
+
+// Wire the hook into settings.json (merge; never clobber unrelated config)
+const settingsPath = join(target, ".claude", "settings.json");
+let hookNote = "settings.json wired (PostToolUse → Task)";
+let settings = {};
+if (existsSync(settingsPath)) {
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+  } catch {
+    settings = null;
+    hookNote = `settings.json is not valid JSON — add the PostToolUse hook manually (command: ${HOOK_COMMAND})`;
+  }
+}
+if (settings !== null) {
+  const hooks = settings.hooks ?? {};
+  const post = hooks.PostToolUse ?? [];
+  const wired = post.some(m => (m.hooks ?? []).some(h => (h.command ?? "").includes("hive-log.mjs")));
+  if (wired) {
+    hookNote = "settings.json already wired";
+  } else {
+    post.push({ matcher: "Task", hooks: [{ type: "command", command: HOOK_COMMAND }] });
+    hooks.PostToolUse = post;
+    settings.hooks = hooks;
+    writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+  }
+}
+
+console.log(`\nHIVE Framework v${version}`);
+console.log(`✅ Installed: ${agents} agents + ${skills} skills + hook → ${target}/.claude/`);
+console.log(`   ${hookNote}`);
+console.log(`\n   Next: open ${target} in Claude Code — agents and skills are discovered natively.`);
+console.log(`   Update: npx @simplium/hive@latest ${rawTarget} after a new HIVE release.\n`);