@nerviq/cli 1.11.0 → 1.12.0

package/README.md

@@ -4,7 +4,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@nerviq/cli)](https://www.npmjs.com/package/@nerviq/cli)
 [![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)
-[![Checks: 2438](https://img.shields.io/badge/checks-2438-brightgreen)](https://github.com/nerviq/nerviq)
+[![Checks: 2441](https://img.shields.io/badge/checks-2441-brightgreen)](https://github.com/nerviq/nerviq)
 
 ---
 
@@ -71,6 +71,7 @@ npx @nerviq/cli --beginner         # Show only the 5 starter commands
 npx @nerviq/cli audit              # Quick scan: score + top 3 actions
 npx @nerviq/cli audit --full       # Full audit with all checks + badge
 npx @nerviq/cli audit --snapshot --tag "pre-refactor"  # Save a named snapshot for history/compare/trend
+npx @nerviq/cli audit --diff-only  # PR/working-tree audit: changed files + linked governance/config surfaces only
 npx @nerviq/cli compare            # Detailed per-check diff between latest 2 audit snapshots
 npx @nerviq/cli audit --webhook https://hooks.slack.com/services/...  # Push audit results to Slack/Discord/generic HTTP
 npx @nerviq/cli audit --workspace packages/*  # Monorepo: root governance + stack-specific workspace profiles
@@ -98,7 +99,7 @@ npx @nerviq/cli --beginner
 | **Team lead / DevEx** | `nerviq governance` → `nerviq audit --json` | CI threshold + `nerviq watch` |
 | **Enterprise / Platform** | `nerviq harmony-audit` → `nerviq harmony-drift` | Policy packs + `nerviq certify` |
 
-## 2,438 Checks Across 96 Categories (8 Platforms × ~300 Governance Rules)
+## 2,441 Checks Across 96 Categories (8 Platforms × ~300 Governance Rules)
 
 | Category Group | Checks | Examples |
 |----------------|--------|---------|
@@ -171,6 +172,28 @@ Stable SDK surfaces: `audit`, `harmonyAudit`, `detectPlatforms`, `getCatalog`
 Experimental SDK surfaces: `synergyReport`, `routeTask`
 
 See [sdk/README.md](sdk/README.md) for full JavaScript examples, error handling guidance, and TypeScript usage.
+
+## Integration Contract Pack
+
+Nerviq publishes a compact integration pack so external systems do not need to scrape CLI text:
+
+- OpenAPI 3.1 contract from `nerviq serve` via `GET /api/openapi.json`
+- Generic audit webhook schema at [`contracts/audit-webhook-event.schema.json`](contracts/audit-webhook-event.schema.json)
+- CI reference patterns in [`docs/ci-integration.md`](docs/ci-integration.md)
+- SDK usage guide in [`sdk/README.md`](sdk/README.md)
+- First-tier release gate in [`docs/first-tier-integration-gate.md`](docs/first-tier-integration-gate.md)
+
+See [`docs/integration-contracts.md`](docs/integration-contracts.md) for the full pack.
+
+## Category Definition Kit
+
+Nerviq is positioned as the control plane for AI-enabled development:
+
+- a repo-native governance layer for AI coding agents
+- a cross-platform drift detector and operating model
+- not a full SAST scanner, prompt library, or single-vendor IDE plugin
+
+See [`docs/category-definition-kit.md`](docs/category-definition-kit.md) for the category language, comparison matrix, operating model, and adoption playbook.
 
 ## MCP Server — `nerviq serve`
 
@@ -193,7 +216,7 @@ All successful operational responses are wrapped in a JSON envelope:
 {
   "data": {},
   "meta": {
-    "version": "1.11.0",
+    "version": "1.12.0",
     "timestamp": "2026-04-09T12:00:00.000Z"
   }
 }
@@ -270,21 +293,23 @@ Levels:
 
 | Command | What it does |
 |---------|-------------|
-| `nerviq audit` | Score 0-100 — quick scan with top 3 actions (default) |
-| `nerviq audit --full` | Full audit with all checks, weakest areas, confidence labels |
-| `nerviq fix <key>` | Auto-fix a specific check (shows score impact) |
-| `nerviq fix --all-critical` | Fix all critical issues at once |
+| `nerviq audit` | Score 0-100 — quick scan with top 3 actions and milestone coaching (default) |
+| `nerviq audit --full` | Full audit with all checks, weakest areas, confidence labels, and milestone coaching |
+| `nerviq audit --diff-only` | Analyze only changed files plus linked governance/config surfaces from git diff / working tree |
+| `nerviq fix <key>` | Auto-fix a specific check (shows score impact) |
+| `nerviq fix --all-critical` | Fix all critical issues at once |
 | `nerviq rollback` | Undo the most recent apply (delete created files) |
 | `nerviq rollback --list` | Show available rollback points |
-| `nerviq setup` | Generate starter-safe CLAUDE.md + hooks + commands |
-| `nerviq augment` | Repo-aware improvement plan (no writes) |
-| `nerviq suggest-only` | Structured report for sharing |
+| `nerviq setup` | Generate starter-safe CLAUDE.md + hooks + commands |
+| `nerviq augment` | Repo-aware improvement plan with archetype profiling, operating profile, and adopt/defer/ignore guidance (no writes) |
+| `nerviq suggest-only` | Structured report for sharing, including repo archetype, operating profile, and adopt/defer/ignore guidance |
 | `nerviq plan` | Export proposal bundles with previews |
 | `nerviq apply` | Apply proposals with rollback |
 | `nerviq governance` | Permission profiles, hooks, policy packs |
 | `nerviq benchmark` | Baseline vs projected score in isolated temp copy |
 | `nerviq check-health` | Detect regressions between audit snapshots |
-| `nerviq deep-review` | AI-powered config review (opt-in) |
+| `nerviq deep-review` | AI-powered config review (opt-in) |
+| `nerviq deep-review --behavioral` | Local behavioral drift review with outcome-layer heuristics |
 | `nerviq interactive` | Step-by-step guided wizard |
 | `nerviq watch` | Live monitoring with score delta |
 | `nerviq history` | Audit snapshot history from saved snapshots |
@@ -294,10 +319,11 @@ Levels:
 | `nerviq anti-patterns` | Detect anti-patterns in current project |
 | `nerviq freshness` | Show verification freshness for all checks |
 | `nerviq rules-export` | Export recommendation rules (human summary or --json) |
-| `nerviq badge` | shields.io badge for README |
-| `nerviq certify` | Certification level + badge |
-| `nerviq scan dir1 dir2` | Compare multiple repos |
-| `nerviq org scan dir1 dir2` | Aggregate multiple repos into one score table |
+| `nerviq badge` | shields.io badge for README |
+| `nerviq certify` | Certification level + badge |
+| `nerviq scan dir1 dir2` | Compare multiple repos |
+| `nerviq org scan dir1 dir2` | Aggregate multiple repos into one score table |
+| `nerviq org policy` | Inspect resolved org/team/repo policy layers |
 | `nerviq harmony-audit` | Cross-platform DX audit |
 | `nerviq harmony-sync` | Sync config across platforms |
 | `nerviq harmony-drift` | Detect platform drift |
@@ -306,7 +332,7 @@ Levels:
 | `nerviq harmony-governance` | Unified platform governance |
 | `nerviq synergy-report` | Multi-agent synergy analysis |
 | `nerviq catalog` | Show check catalog for all 8 platforms |
-| `nerviq doctor` | Self-diagnostics |
+| `nerviq doctor` | Self-diagnostics for install health, freshness, platform detection, declared MCP servers, and hook runtime |
 | `nerviq convert` | Convert config between platforms |
 | `nerviq migrate` | Migrate platform config versions |
 | `nerviq serve` | Start local MCP-compatible HTTP API |
@@ -315,7 +341,7 @@ Levels:
 
 | Flag | Effect |
 |------|--------|
-| `--full` | Full audit output (all checks, weakest areas, confidence labels) |
+| `--full` | Full audit output (all checks, weakest areas, confidence labels, milestone coaching) |
 | `--verbose` | Full audit + medium-priority recommendations |
 | `--threshold N` | Exit 1 if score < N (for CI) |
 | `--json` | Machine-readable JSON output |
@@ -324,6 +350,13 @@ Levels:
 | `--webhook-header NAME:VALUE` | Add a custom webhook header; repeat the flag for multiple headers |
 | `--webhook-retries N` | Retry transient webhook failures (`429`, `5xx`, timeouts) up to `N` extra times |
 | `--snapshot` | Save audit snapshot for trending |
+| `--tag LABEL` | Label a saved snapshot (repeat the flag for multiple tags) |
+| `--behavioral` | Run the opt-in local behavioral drift review via `deep-review` |
+| `--history` | With `deep-review --behavioral`, show behavioral snapshot history |
+| `--compare` | With `deep-review --behavioral`, compare the latest two behavioral snapshots |
+| `--diff-only` | Run a changed-file audit instead of a full repo audit |
+| `--diff-base SHA` | Base SHA for `--diff-only` PR comparisons (defaults to CI env vars when present) |
+| `--diff-head SHA` | Head SHA for `--diff-only` PR comparisons (defaults to `GITHUB_SHA` or `HEAD`) |
 | `--dry-run` | Preview changes without writing files |
 | `--config-only` | Only write config files, never source code |
 | `--auto` | Apply without prompts |
@@ -342,6 +375,51 @@ npx @nerviq/cli audit \
   --webhook-header "X-Nerviq-Environment: production" \
   --webhook-retries 4
 ```
+
+Generic webhook endpoints now receive a stable `nerviq.audit.completed` event envelope with:
+
+- backward-compatible top-level `platform`, `score`, `passed`, `failed`, and `results`
+- nested `data` and `meta` blocks for new consumers
+- schema versioning through `schemaVersion`
+
+For PR-focused audits, you can scope Nerviq to the working tree or an explicit base/head range:
+
+```bash
+npx @nerviq/cli audit --diff-only
+npx @nerviq/cli audit --diff-only --diff-base origin/main --diff-head HEAD
+```
+
+`--diff-only` is intentionally a scoped review surface. It reports a `diff-only changed-file audit` score, lists the changed files it considered, and reminds you to run a full `nerviq audit` for the complete repo posture. Because diff-only scores are not directly comparable to full audit history, Nerviq blocks `--diff-only --snapshot`.
+
+For multi-repo governance, Nerviq also supports inherited policy layers:
+
+- `.nerviq/org-policy.json` in an ancestor directory for org defaults
+- `.nerviq/team-policy.json` in the repo for team overrides
+- `.nerviq/repo-policy.json` in the repo for repo-specific overrides
+
+Inspect the resolved contract with:
+
+```bash
+npx @nerviq/cli org policy
+npx @nerviq/cli org scan ./app ./api ./infra --json
+```
+
+For opt-in outcome-layer inspection, Nerviq can also run a local behavioral drift review:
+
+```bash
+npx @nerviq/cli deep-review --behavioral
+npx @nerviq/cli deep-review --behavioral --snapshot --milestone baseline --tag "behavioral-baseline"
+npx @nerviq/cli deep-review --behavioral --history
+npx @nerviq/cli deep-review --behavioral --compare
+```
+
+Behavioral drift mode is intentionally guarded:
+
+- It analyzes repository structure and instruction-vs-outcome mismatch heuristics
+- It does not claim agent attribution without explicit evidence
+- It is not marketed as SAST, semantic code review, or runtime analysis
+
+`nerviq setup` now seeds a trust-boundary section in `CLAUDE.md` and an `injection-defense` starter hook for `WebFetch`, `WebSearch`, `Read`, `Grep`, `Glob`, and MCP-backed external-content flows. `nerviq doctor` validates that the declared starter hook still runs and logs suspicious prompt-injection patterns correctly.
 
 ## Backed by Research
 
@@ -349,7 +427,7 @@ Nerviq is built on the NERVIQ knowledge engine — the largest verified catalog
 
 - **448+ research documents** covering all 8 platforms
 - **332+ experiments** with tested, rated results
-- **2,438 checks** across 8 platforms (~300 unique governance rules × 8 platform adaptations), each with `sourceUrl` and `confidence` level (0.0-1.0)
+- **2,441 checks** across 8 platforms (~300 unique governance rules × 8 platform adaptations), each with `sourceUrl` and `confidence` level (0.0-1.0)
 - Every check is traceable to primary documentation or verified experiment
 - 90-day freshness cycle: stale findings are re-verified or pruned
 
@@ -372,7 +450,7 @@ Every write command supports `--snapshot` for automatic backup before changes.
 
 - **Zero dependencies** — nothing to audit
 - **Runs locally** — audit, setup, plan, apply, governance, benchmark all run on your machine
-- **Deep review is opt-in** — only `deep-review` sends selected config for AI analysis
+- **Deep review is opt-in** — `deep-review` sends selected config for AI analysis, while `deep-review --behavioral` stays local and uses heuristic outcome-layer analysis only
 - **AGPL-3.0 Licensed** — open source
 
 ## Links