@njeybe/nativ 2.0.0

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# Changelog
+
+## 2.0.0
+
+nativ is now role-based and Claude-first. The roles (architect, project manager, worker, verifier) are fixed; the model behind each one is configurable, and Claude Code is the default host for all of them. Antigravity and Gemini still work as an optional architect.
+
+### Added
+
+- **Provider chain for Tier 1 triage.** Claude Code under your own login first (no API key needed), then the Anthropic API, then Gemini, then the offline rules engine. A provider that hits a usage limit is remembered and skipped until it resets, so a limit no longer stalls triage.
+- **Role enforcement.** `nativ hook check` runs before every file write from Claude Code. It flags or blocks writes outside the active task's `targetFiles`, writes under `.ai/` from anyone but the architect, and writes to secret files. Modes are `warn` (default), `block` and `off`, set in `.nativ/config.json`. `nativ task unlock <id>` lifts scope for one task and is deliberately not available to agents. `nativ hook status` shows what applies.
+- **`nativ setup` and `nativ doctor`.** Setup writes and merges `.mcp.json`, `.claude/settings.json`, `.claude/agents/`, `AGENTS.md` and `.nativ/config.json` without overwriting your own settings. Doctor checks the integration, asks Claude Code whether the MCP server connects, and `nativ doctor --fix` repairs drift. `nativ init` now runs setup.
+- **Claude Code plugin and marketplace** (`njeybe/nativ`), generated from the same sources as setup.
+- **Agent defaults for a Claude subscription.** Architect on Opus, worker on Sonnet, verifier on Haiku, with turn caps; triage on Haiku.
+- **`nativ_doctor`** MCP tool (read-only).
+- **`AGENTS.md`** as the one canonical directive. `CLAUDE.md` and `GEMINI.md` point at it.
+
+### Changed
+
+- **The npm package is now `@njeybe/nativ`** (it was `nativ-cli`). The command is still `nativ`. `nativ-cli` stays on npm and is deprecated in favour of the new name.
+- **`nativ update` no longer overwrites files you edited.** It refreshes only files nativ wrote and you have not touched, keeps the rest and reports them, and `--force` replaces them. It also restores `AGENTS.md`, the agents and the hooks. It never touches your contracts.
+- **Dispatched agents no longer run with `--dangerously-skip-permissions`.** The runner and Studio use `acceptEdits` plus a per-task allowlist, so the deny and ask rules and the enforcement hook apply. A task that needs another command is denied instead of run; widen the list with `NATIV_RUNNER_ALLOW`.
+- Claude is the default architect and triage provider. Wording across the CLI, templates and docs names roles instead of one vendor.
+- `nativ --version` and the MCP server report the version from `package.json`.
+
+### Removed
+
+- **The `agentj_*` MCP tools and the `agentj://` resources.** Only `nativ_*` and `nativ://` remain. The `.agentj/*.local.json` secret patterns and the `AGENTJ_DEV_DATABASE_URL` / `AGENTJ_PROD_DATABASE_URL` variables are still recognised.
+
+### Migrating from 1.x
+
+1. Switch to the new package: `npm uninstall -g nativ-cli`, then `npm install -g @njeybe/nativ`. If your own MCP configs or `nativ setup --command` use `npx -y nativ-cli`, change that to `npx -y @njeybe/nativ`.
+2. Rename any `agentj_*` tool or `agentj://` resource in your own configs to `nativ_*` and `nativ://`.
+3. In each project run `nativ update`, then `nativ doctor` (add `--fix` if it reports drift).
+4. Open Claude Code in the project once and accept the trust dialog; until then it ignores the project's permission rules.
+5. If `nativ doctor` warns that a `nativ` MCP server in your user or local scope shadows the project's, remove it: `claude mcp remove nativ -s local`.
+6. Optional: `nativ setup --enforcement block` once you trust the scope rules.
+
+## 1.0.0
+
+Initial release.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JB Natividad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,334 @@
+# nativ
+
+A role-based multi-agent workflow for AI coding agents. **Claude Code is the default**; other agents plug in. `nativ` keeps the design contracts, the task plan and the guardrails in your repository, so the same rules hold whichever tool or model does the work.
+
+> **Package:** `@njeybe/nativ` | **Command:** `nativ`
+
+---
+
+## The idea
+
+Four roles, fixed. The model or vendor behind each role is configurable.
+
+```
+   Architect            designs contracts (database, API, UI); the human approves each step
+       |
+       v   .ai/ contracts + master_plan.json
+   Project Manager      runs the task loop, delegates, reports (the main Claude Code session)
+       |
+       v   one task, one role guide, its own worktree if you like
+   Workers              backend, frontend, database, QA, Flutter, DevOps, security, migration
+       |
+       v
+   Verifier             independent checks; cannot edit files
+```
+
+Why it works:
+
+- **Contracts, not chat.** `.ai/db_schema.json`, `.ai/api_contracts.json` and `.ai/ui_specs.md` are the source of truth. Workers implement against them and escalate gaps instead of improvising.
+- **Boundaries enforced by code.** A Claude Code hook checks every file write against the active task, the protected contracts and your secret files. It does not rely on the model remembering a rule.
+- **Independent verification.** Each task has a `verificationCommand` that a gatekeeper re-runs before the task can complete, and a separate verifier agent reviews the result.
+- **Zero-credential air-gap.** Agents see database structure, never passwords, connection strings or rows.
+
+---
+
+## Quick start
+
+### 1. Install
+
+You need Node.js 20 or newer and Git. You do **not** need a clone of this repository.
+
+```bash
+# From npm
+npm install -g @njeybe/nativ
+
+# Or straight from GitHub (builds on install, about a minute)
+npm install -g github:njeybe/nativ
+```
+
+Check it with `nativ --version`. Developing nativ itself? See [docs/installation.md](docs/installation.md) for the clone and `npm link` route.
+
+### 2. Set up a project
+
+```bash
+cd your-project
+nativ init
+```
+
+`nativ init` scaffolds the `.ai/` workflow and then runs `nativ setup`, which writes the Claude Code configuration:
+
+| File | What it does |
+| :--- | :--- |
+| `.mcp.json` | Registers the `nativ` MCP server |
+| `.claude/settings.json` | Permission rules, the enforcement hook, the session-start orientation hook |
+| `.claude/agents/` | The `architect`, `worker` and `verifier` agents |
+| `AGENTS.md` | The one directive every agent follows. `CLAUDE.md` and `GEMINI.md` point at it |
+| `.nativ/config.json` | Enforcement mode and provider choices |
+
+Setup **merges**: it never overwrites your own settings, hooks, MCP servers or edited files. It is safe to run any number of times, and `nativ setup --dry-run` shows what it would change.
+
+Open Claude Code in the folder once and accept the workspace trust dialog. Until you do, Claude Code ignores the project's `permissions.allow` entries.
+
+### 3. Or install it as a Claude Code plugin
+
+```text
+/plugin marketplace add njeybe/nativ
+/plugin install nativ@nativ
+```
+
+The plugin brings the agents, the enforcement hooks, the MCP server and a skill that teaches the task loop. It calls the `nativ` command, so install the CLI first. **A plugin cannot ship permission rules**, so also run `nativ setup` in the project to add the rules that deny `nativ task unlock` and `nativ db sync`, block reading `.env*` files, and make Claude Code ask before any write under `.ai/`.
+
+### 4. Work
+
+1. Ask Claude to use the **architect** agent to design your contracts. It stops for your approval after the database schema, then the API, then the UI. Claude Code asks you to confirm every write under `.ai/`.
+2. Ask Claude to run `nativ task next` and delegate each task to a **worker** agent. It works only inside the task's `targetFiles`, verifies, and completes.
+3. Ask for a **verifier** pass before you call a milestone done.
+
+### 5. Keep it healthy
+
+```bash
+nativ doctor          # checks the MCP server, hooks, permissions, agents, providers
+nativ doctor --fix    # repairs what it can, idempotently
+```
+
+Run it after updating Claude Code or nativ. It also asks Claude Code itself whether the `nativ` server connects, and warns when a `nativ` server registered in your user or local scope is shadowing the project's.
+
+### 6. Update
+
+```bash
+npm install -g @njeybe/nativ@latest   # or: npm install -g github:njeybe/nativ
+nativ update                      # in each project
+nativ doctor
+```
+
+`nativ update` refreshes the directives, role guides, agents and hooks that nativ wrote and you have not edited. Anything you edited is kept and reported; `nativ update --force` replaces it. It never touches your contracts (`.ai/db_schema.json`, `.ai/api_contracts.json`, `.ai/ui_specs.md`, `.ai/master_plan.json`, `.ai/context.md`). See [CHANGELOG.md](CHANGELOG.md) before upgrading across a major version.
+
+---
+
+## Role enforcement
+
+`nativ hook check` runs before every `Write`, `Edit`, `MultiEdit` and `NotebookEdit`. It looks at three things:
+
+| Rule | Applies to | Meaning |
+| :--- | :--- | :--- |
+| `out_of_scope` | Workers and the project manager | The file is not in the active task's `targetFiles` (exact files, directories with a trailing `/`, and `*`/`**` globs) |
+| `protected_path` | Everyone but the architect | Anything under `.ai/` |
+| `secret_path` | Everyone, architect included | `.env`, `.env.*` (not `.env.example`), `.nativ/*.local.json`, `*.pem`, `*.key` |
+
+Who is the architect? Inside a subagent, Claude Code reports the agent's name, so the `architect` agent (or the plugin's `nativ:architect`) is recognised. For a whole session, start it with `NATIV_ROLE=architect`.
+
+**Modes** (`"enforcement"` in `.nativ/config.json`, or `nativ setup --enforcement <mode>`):
+
+| Mode | Behaviour |
+| :--- | :--- |
+| `warn` (default) | The write goes through, the agent is told why it is out of scope, and the violation is logged to `.ai/telemetry.json` |
+| `block` | The write is denied with the reason |
+| `off` | No checks |
+
+Start in `warn`, look at the log, then switch to `block`. If a task genuinely needs to leave its scope, `nativ task unlock <taskId>` lifts the scope rule for that task (contracts and secrets stay protected) and `--revoke` restores it. Unlock is a CLI command on purpose: it is not an MCP tool, so an agent cannot remove its own guardrail.
+
+`nativ hook status` shows the mode, the role and the active task's scope. Two limits to know: the hook watches the file-editing tools, not shell commands (`sed -i` or a redirect can still write a file), and it fails open, so a broken payload never stops your work. The permission rules that `nativ setup` writes add a second layer.
+
+---
+
+## Providers
+
+nativ's own model calls (currently triage of escalations) go through one adapter, so no single vendor is on the critical path.
+
+Default order: `claude-cli`, `claude-api`, `gemini`, then a deterministic rules engine.
+
+| Provider | Needs | Notes |
+| :--- | :--- | :--- |
+| `claude-cli` | Claude Code signed in | Runs `claude -p` with your subscription login. No API key. Uses Haiku by default, with all tools disabled, from an empty working directory |
+| `claude-api` | `ANTHROPIC_API_KEY` | Anthropic SDK |
+| `gemini` | `GEMINI_API_KEY` or `GOOGLE_API_KEY` | The key is sent in a header, never the URL |
+
+If a provider reports a rate or usage limit, nativ remembers it in `.nativ/provider-state.json` and skips that provider until the limit resets, so a limit costs seconds, not a long wait. If nothing is available, triage still answers from the offline rules engine. Prompts pass through secret redaction before leaving the machine.
+
+Choose providers and models per role in `.nativ/config.json`:
+
+```json
+{
+  "enforcement": "warn",
+  "providers": { "triage": ["claude-cli", "gemini"] },
+  "models": { "claude-cli": "haiku", "gemini": "gemini-3.8-flash" }
+}
+```
+
+Roles are `architect`, `pm`, `worker`, `verifier` and `triage`. Adding a vendor means adding one file under `src/providers/`.
+
+---
+
+## CLI reference
+
+### Setup and health
+
+```bash
+nativ init                       # scaffold .ai/ and run setup
+nativ setup [--dry-run] [--enforcement warn|block|off] [--command "npx -y @njeybe/nativ"] [--force]
+nativ doctor [--fix] [--no-deep] [--json]
+nativ hook status [--json]       # enforcement mode, role, active task scope
+```
+
+### Task management and JIT context slicing
+
+```bash
+nativ task next                  # next executable task and its contract slice
+nativ task list --available
+nativ task list --milestone m1 --status pending
+nativ task add "Implement OAuth2 callback" -a backend -v "npm test" -f "src/auth.ts"
+nativ task start task-01
+nativ task complete task-01                # runs the verification command
+nativ task complete task-01 --timeout 600000   # for slow suites
+nativ task block task-01 --reason "Missing Stripe API key"
+nativ task escalate task-01 --type schema_flaw --details "Missing foreign key on orders table"
+nativ task propose-patch task-01 --target db_schema --op ADD --path users.columns.bio --reason "..."
+nativ task unlock task-01 --reason "refactor touches a shared file"   # emergency; --revoke to re-lock
+nativ triage                     # evaluate pending escalations; decision cards for the human
+```
+
+### Verification
+
+```bash
+nativ verify task-01
+nativ verify --all
+nativ verify --milestone m1 --timeout 60000 --json
+```
+
+### Status and telemetry
+
+```bash
+nativ status
+nativ status --telemetry         # durations, token estimates, cost estimates, pass rates, role violations
+nativ status --json
+```
+
+### Benchmarks
+
+```bash
+nativ bench
+nativ bench --scenario concurrency --concurrency 8
+nativ bench --json
+```
+
+### Database studio and schema telemetry (masked, structure only)
+
+```bash
+nativ db status
+nativ db inspect --env dev
+nativ db diff --target contract --exit-code
+nativ studio                     # local dashboard at http://localhost:4983
+```
+
+### Git worktree sandboxing
+
+```bash
+nativ worktree create task-01
+nativ worktree list
+nativ worktree merge task-01     # Safe Merge Gatekeeper enforced
+nativ worktree remove task-01
+```
+
+---
+
+## Contract Governor
+
+A deterministic firewall between agents and the contracts (`.ai/db_schema.json`, `.ai/api_contracts.json`):
+
+```
+            An agent proposes a contract change
+                          |
+                          v
+                 [ Contract Governor ]
+                          |
+        +-----------------+------------------+
+        v                                    v
+ LOW_ADDITIVE                          HIGH_DESTRUCTIVE
+ new nullable columns, new tables,     dropping tables or columns,
+ optional params, new response fields  changing column types, dropping
+                                       routes, new required params
+        |                                    |
+        v                                    v
+ auto-approved and patched             rejected with a structured
+ atomically                            violation; three strikes trip the
+                                       circuit breaker and log an escalation
+```
+
+---
+
+## Concurrency
+
+`.ai/master_plan.json` and `.ai/telemetry.json` are protected by OS-level advisory file locks (`proper-lockfile`) with atomic read-modify-write and retry backoff for Windows `EBUSY`/`EPERM`. Several agents in separate terminals can start, complete and add tasks without lost updates. Long verification commands run outside the lock.
+
+Parallel agents share your Claude usage limit. Two or three at a time is a sensible default on a subscription.
+
+---
+
+## Telemetry
+
+Task transitions and role violations are recorded in `.ai/telemetry.json`: durations, token estimates priced with the model table in `src/core/telemetry.ts`, verification pass rates, circuit-breaker trips, and (capped at the latest 200) enforcement violations with the rule, mode, tool, project-relative path and task. File contents are never logged.
+
+---
+
+## MCP server
+
+`nativ mcp` speaks the Model Context Protocol over stdio. `nativ setup` registers it for Claude Code; the same server works with Cursor, Claude Desktop and Antigravity.
+
+| Tool / resource | Description |
+| :--- | :--- |
+| `nativ_task_next`, `nativ_task_list`, `nativ_task_add` | Find and add work |
+| `nativ_task_start`, `nativ_task_complete`, `nativ_task_block` | Move a task through its lifecycle (complete runs the gatekeeper) |
+| `nativ_task_escalate`, `nativ_task_propose_patch` | Escalate a contract gap, or propose a governed patch |
+| `nativ_verify`, `nativ_bench`, `nativ_status` | Verification, benchmarks, progress |
+| `nativ_worktree_*` | Create, list, merge and remove task worktrees |
+| `nativ_db_status`, `nativ_db_inspect`, `nativ_db_diff` | Masked, structure-only database telemetry |
+| `nativ_doctor` | Read-only health report. Repairs are `nativ doctor --fix` in a terminal |
+| `nativ://context`, `nativ://master-plan`, `nativ://db-schema`, `nativ://api-contracts`, `nativ://escalation`, `nativ://telemetry` | Read-only resources |
+
+There is deliberately no MCP tool to unlock a task, write a contract, sync a database schema or run setup.
+
+Manual registration, if you prefer:
+
+```bash
+claude mcp add nativ -- nativ mcp
+```
+
+```json
+{
+  "mcpServers": {
+    "nativ": { "command": "npx", "args": ["-y", "@njeybe/nativ", "mcp", "/absolute/path/to/project"] }
+  }
+}
+```
+
+---
+
+## Repository structure
+
+```
+nativ/
+  bin/cli.js               entry point (a fast path serves the hook commands without loading the whole CLI)
+  src/
+    index.ts               command registry
+    commands/              init, setup, doctor, hook, task, verify, worktree, db, triage, ...
+    core/                  enforcement, setup-assets, tier1-liaison, telemetry, lock-manager, verifier, ...
+    providers/             claude-cli, claude-api, gemini, registry (fallback chain and cooldown)
+    governor/              contract evaluator, circuit breaker, rules
+    mcp/server.ts          MCP server
+    db/                    masked env parser, introspection, schema diff
+    server/                Studio web dashboard
+    runner/                agent supervisor
+  templates/               AGENTS.md, CLAUDE.md, GEMINI.md, claude-agents/, dot-ai/
+  plugin/                  Claude Code plugin (generated by `npm run sync-plugin`)
+  .claude-plugin/          marketplace entry for the plugin
+  scripts/sync-plugin.mjs  renders plugin/ from the same sources as `nativ setup`
+  tests/                   regression suites (`npm test`)
+```
+
+Changed a template or the setup generator? Run `npm run sync-plugin`; a test fails if `plugin/` is out of date.
+
+---
+
+## License
+
+MIT (c) JB Natividad. See [LICENSE](LICENSE).

package/bin/cli.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+
+// Claude Code runs `nativ hook check` before every file write, so those two commands skip loading the whole CLI
+// (every command and database driver, roughly half a second) and import only what they need. Everything else
+// goes through the full program exactly as before.
+const [, , group, subcommand, ...rest] = process.argv;
+
+if (group === 'hook' && (subcommand === 'check' || subcommand === 'context')) {
+  // The optional targetDir is the first argument that is not a flag.
+  const targetDir = rest.find((arg) => !arg.startsWith('-'));
+  try {
+    if (subcommand === 'check') {
+      const { runHookCheck } = await import('../dist/commands/hook.js');
+      await runHookCheck(targetDir);
+    } else {
+      const { runSessionContext } = await import('../dist/core/setup-assets.js');
+      runSessionContext(targetDir);
+    }
+  } catch (err) {
+    // A hook must never fail the tool call it guards.
+    process.stderr.write(`nativ hook ${subcommand}: ${err instanceof Error ? err.message : String(err)}; allowing.\n`);
+  }
+  // No process.exit(): on Windows a pipe write is asynchronous and exiting here could cut the decision short.
+  process.exitCode = 0;
+} else {
+  const { run } = await import('../dist/index.js');
+  run().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/dist/commands/bench.d.ts

@@ -0,0 +1,8 @@
+import { BenchmarkOptions, BenchmarkReport } from '../core/benchmark.js';
+export interface BenchCommandOptions extends BenchmarkOptions {
+    output?: string;
+    json?: boolean;
+    scenario?: string;
+    concurrency?: number;
+}
+export declare function runBench(targetDirArg?: string, options?: BenchCommandOptions): Promise<BenchmarkReport | undefined>;

package/dist/commands/bench.js

@@ -0,0 +1,52 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import pc from 'picocolors';
+import { runBenchmarks, formatBenchmarkReport } from '../core/benchmark.js';
+export async function runBench(targetDirArg, options = {}) {
+    const targetDir = path.resolve(targetDirArg || process.cwd());
+    try {
+        if (!options.json) {
+            console.log(pc.bold(pc.cyan('\n🚀 Initiating Nativ Synthetic Benchmark Matrix...')));
+            if (options.scenario) {
+                console.log(pc.dim(`  Target Scenario: `) + pc.yellow(options.scenario));
+            }
+            if (options.concurrency) {
+                console.log(pc.dim(`  Simulated Workers: `) + pc.yellow(String(options.concurrency)));
+            }
+        }
+        const report = await runBenchmarks(options);
+        if (options.json) {
+            console.log(JSON.stringify(report, null, 2));
+        }
+        else {
+            console.log(formatBenchmarkReport(report));
+        }
+        // Write to output file if requested or if inside an existing .ai project
+        let outputPath = options.output;
+        if (!outputPath) {
+            const aiDir = path.join(targetDir, '.ai');
+            if (fs.existsSync(aiDir)) {
+                outputPath = path.join(aiDir, 'benchmark_report.json');
+            }
+        }
+        if (outputPath) {
+            const resolvedOutput = path.resolve(outputPath);
+            const outDir = path.dirname(resolvedOutput);
+            if (!fs.existsSync(outDir)) {
+                fs.mkdirSync(outDir, { recursive: true });
+            }
+            fs.writeFileSync(resolvedOutput, JSON.stringify(report, null, 2) + '\n', 'utf8');
+            if (!options.json) {
+                console.log(pc.dim(`📁 Benchmark report saved to: `) + pc.white(resolvedOutput) + '\n');
+            }
+        }
+        if (report.summary.failedScenarios > 0) {
+            process.exitCode = 1;
+        }
+        return report;
+    }
+    catch (err) {
+        console.error(pc.red(`\n✖ Benchmark suite failed: ${err.message}`));
+        process.exitCode = 1;
+    }
+}

package/dist/commands/db.d.ts

@@ -0,0 +1,22 @@
+export declare function runDbStatus(targetDirArg?: string, options?: {
+    json?: boolean;
+}): Promise<void>;
+export declare function runDbInspect(targetDirArg?: string, options?: {
+    env?: string;
+    table?: string;
+    json?: boolean;
+}): Promise<void>;
+export declare function runDbDiff(targetDirArg?: string, options?: {
+    target?: string;
+    json?: boolean;
+    exitCode?: boolean;
+}): Promise<void>;
+/** Exports a live schema into .ai/db_schema.json. Previews unless --yes is passed. */
+export declare function runDbSync(targetDirArg?: string, options?: {
+    source?: string;
+    yes?: boolean;
+}): Promise<void>;
+export declare function runDbUi(targetDirArg?: string, options?: {
+    port?: string;
+    open?: boolean;
+}): Promise<void>;