@nerviq/cli 1.26.0 → 1.27.1

package/README.md

@@ -77,9 +77,9 @@ Every Nerviq check is tagged with one of four explicit layers so you know exactl
 - **governance** — agent configuration posture: presence, content, and quality of agent-instruction files and platform settings.
 - **drift** — cross-platform consistency: do your configured platforms agree, and does declared state match repo reality?
 - **hygiene** — repo-level cleanliness adjacent to agents (gitignore, CHANGELOG, SECURITY.md, LICENSE, Node version pinning, etc.).
-- **shallow-risk** — reserved for obvious agent-config ↔ codebase boundary issues (CTO-06, not yet populated).
+- **shallow-risk** — obvious agent-config ↔ codebase boundary issues emitted through the experimental `--shallow-risk` lane.
 
-There is deliberately no "deep-review" or general-security-scanning layer — Nerviq is an agent-configuration audit tool, not a code-review tool. The full taxonomy and disambiguation rules live in `docs/integration-contracts.md §8`, and the `layer` field is surfaced in every output format (JSON, CSV, JUnit, Markdown, text).
+There is deliberately no "deep-review" or general-security-scanning layer — Nerviq is an agent-configuration audit tool, not a code-review tool. The experimental `nerviq audit --shallow-risk` pass now adds an opt-in, non-scoring boundary scan on top of the four-layer model. The full taxonomy and disambiguation rules live in `docs/integration-contracts.md §8`, and the `layer` field is surfaced in every output format (JSON, CSV, JUnit, Markdown, text).
 
 ## Quick Start
 
@@ -234,8 +234,8 @@ All successful operational responses are wrapped in a JSON envelope:
 {
   "data": {},
   "meta": {
-    "version": "1.26.0",
-    "timestamp": "2026-04-15T14:00:00.000Z"
+    "version": "1.27.1",
+    "timestamp": "2026-04-15T22:00:00.000Z"
   }
 }
 ```

package/SECURITY.md

@@ -0,0 +1,82 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in Nerviq, please report it responsibly.
+
+**Email:** [business@nerviq.net](mailto:business@nerviq.net) (subject: SECURITY)
+
+Please include:
+
+- Description of the vulnerability
+- Steps to reproduce
+- Affected version(s)
+- Impact assessment (if known)
+
+**Do not** open a public GitHub issue for security vulnerabilities.
+
+## Response SLA
+
+| Severity | Response Time | Fix Timeline |
+|----------|--------------|--------------|
+| **Critical** (RCE, data exfiltration) | < 24 hours | < 48 hours |
+| **High** (privilege escalation, auth bypass) | < 48 hours | < 7 days |
+| **Medium** (information disclosure, DoS) | < 7 days | < 30 days |
+| **Low** (minor issues, hardening) | < 14 days | Next release |
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 1.27.x | Yes |
+| 1.26.x | Yes |
+| 1.25.x | Yes |
+| 1.24.x | Yes |
+| < 1.24 | No |
+| < 1.27 | No |
+
+Only the latest patch release of each supported major.minor line receives security updates.
+
+## Dependency Policy
+
+- **Zero runtime dependencies.** Nerviq ships with no production `node_modules` — only Node.js (>=18) is required.
+- **devDependencies audited monthly** using `npm audit` and reviewed for known CVEs.
+- **SBOM published** with every release (`sbom.cdx.json`) in CycloneDX format for full dependency transparency.
+- **Lockfile integrity** checked in CI to prevent supply-chain tampering.
+- **npm provenance attestation** — every release published via the GitHub Actions release workflow is signed with an npm provenance attestation (`npm publish --provenance`). This cryptographically links the published package to a specific GitHub Actions run, repository, and commit. Consumers can verify the attestation with `npm audit signatures @nerviq/cli`.
+
+## Security Architecture
+
+- All operations run **locally** — no data is sent to external servers by default.
+- The `nerviq serve` command binds to **localhost only** (127.0.0.1), never to 0.0.0.0.
+- `deep-review` (opt-in) redacts secrets and credentials before sending config snippets to any AI provider.
+- No secrets, tokens, or API keys are stored by Nerviq.
+
+## Reporting False Positives in Checks
+
+If a Nerviq audit check produces a false positive (flags something that is not actually a problem):
+
+1. Run `nerviq audit --verbose` to identify the exact check key (e.g., `permissionDeny`).
+2. Open a GitHub issue with:
+   - The check key
+   - Your project structure (relevant files only)
+   - Why you believe it is a false positive
+3. Alternatively, use `nerviq feedback --key <checkKey> --status rejected --effect neutral --notes "false positive: <reason>"` to record it locally.
+
+False positive reports help us improve check accuracy for all users.
+
+## Acknowledgments
+
+We gratefully acknowledge security researchers who responsibly disclose vulnerabilities. With your permission, we will list you in our security acknowledgments.
+
+## Internal Response Process
+
+When a vulnerability report arrives:
+
+1. **Acknowledge** — Reply within the SLA above confirming receipt
+2. **Triage** — Classify severity (Critical/High/Medium/Low), assign to founder
+3. **Reproduce** — Verify the vulnerability exists in the latest supported version
+4. **Fix** — Develop fix on a private branch, add regression test
+5. **Release** — Publish patched version to npm, tag in GitHub
+6. **Disclose** — Notify reporter, update CHANGELOG.md with security tag, credit reporter if permitted
+7. **Post-mortem** — For Critical/High: document root cause and prevention measures in `research/`

package/bin/cli.js

@@ -579,6 +579,8 @@ const HELP = `
 
   DISCOVER
     nerviq audit                  Quick scan: score + top 3 gaps (Harmony-first when 2+ platforms detected)
+    nerviq audit --shallow-risk   Opt-in boundary scan for agent-config <-> codebase red flags (experimental)
+    nerviq audit --shallow-risk-only  Fast precommit shallow-risk pass without the full governance audit
     nerviq audit --fix            Audit, apply fixable critical fixes, then re-audit
     nerviq audit --fix --dry-run  Show proposed autofix diff without writing
     nerviq audit --no-harmony-first   Skip the cross-platform Harmony header
@@ -709,6 +711,8 @@ const HELP = `
     --tag LABEL       Tag the saved snapshot (use with --snapshot; repeat or comma-separate for more)
     --milestone NAME  Snapshot lifecycle milestone: baseline | post-fix | pre-upgrade | release
     --campaign A,B    Limit plan/apply to named upgrade campaigns
+    --shallow-risk    Enable experimental shallow-risk hints (parallel, not scored)
+    --shallow-risk-only Run only shallow-risk hints and skip the full governance audit
     --full            Show full audit output (all checks, weakest areas, badge)
     --lite            Short top-3 scan (default behavior since v1.5.2)
     --dry-run         Preview changes without writing files
@@ -740,6 +744,7 @@ const HELP = `
     npx nerviq --lite
     npx nerviq --platform cursor
     npx nerviq audit --workspace packages/*
+    npx nerviq audit --shallow-risk
     npx nerviq baseline init
     npx nerviq audit --diff-only --drift-mode ci
     npx nerviq --platform codex augment
@@ -819,11 +824,16 @@ async function main() {
     process.exit(0);
   }
 
+  const shallowRiskRequested = (flags.includes('--shallow-risk') || flags.includes('--shallow-risk-only')) &&
+    process.env.NERVIQ_SHALLOW_RISK !== 'off';
+  const shallowRiskOnlyRequested = flags.includes('--shallow-risk-only') &&
+    process.env.NERVIQ_SHALLOW_RISK !== 'off';
+
   const options = {
     verbose: flags.includes('--verbose'),
     json: flags.includes('--json'),
     auto: flags.includes('--auto'),
-    lite: flags.includes('--full') || flags.includes('--verbose') ? false : true,
+    lite: flags.includes('--full') || flags.includes('--verbose') || shallowRiskRequested ? false : true,
     full: flags.includes('--full'),
     showDeprecated: flags.includes('--show-deprecated'),
     snapshot: flags.includes('--snapshot'),
@@ -860,6 +870,8 @@ async function main() {
     compareView: flags.includes('--compare'),
     diffOnly: flags.includes('--diff-only'),
     noHarmonyFirst: flags.includes('--no-harmony-first'),
+    shallowRisk: shallowRiskRequested,
+    shallowRiskOnly: shallowRiskOnlyRequested,
     diffBase: parsed.diffBase || null,
     diffHead: parsed.diffHead || null,
     driftMode: parsed.driftMode || null,

package/contracts/audit-webhook-event.schema.json

@@ -0,0 +1,138 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://nerviq.net/contracts/audit-webhook-event.schema.json",
+  "title": "Nerviq Audit Webhook Event",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "event",
+    "schemaVersion",
+    "generatedAt",
+    "platform",
+    "score",
+    "passed",
+    "failed",
+    "results",
+    "data",
+    "meta"
+  ],
+  "properties": {
+    "event": {
+      "const": "nerviq.audit.completed"
+    },
+    "schemaVersion": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "platform": {
+      "type": "string"
+    },
+    "score": {
+      "type": "number"
+    },
+    "passed": {
+      "type": "integer"
+    },
+    "failed": {
+      "type": "integer"
+    },
+    "results": {
+      "type": "array"
+    },
+    "data": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "platform",
+        "score",
+        "scoreType",
+        "passed",
+        "failed",
+        "checkCount",
+        "topNextActions",
+        "quickWins",
+        "scoreCoaching"
+      ],
+      "properties": {
+        "platform": {
+          "type": "string"
+        },
+        "platformLabel": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "score": {
+          "type": "number"
+        },
+        "scoreType": {
+          "type": "string"
+        },
+        "organicScore": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "passed": {
+          "type": "integer"
+        },
+        "failed": {
+          "type": "integer"
+        },
+        "skipped": {
+          "type": [
+            "integer",
+            "null"
+          ]
+        },
+        "checkCount": {
+          "type": "integer"
+        },
+        "topNextActions": {
+          "type": "array"
+        },
+        "quickWins": {
+          "type": "array"
+        },
+        "scoreCoaching": {
+          "type": [
+            "object",
+            "null"
+          ]
+        },
+        "suggestedNextCommand": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "meta": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "cliVersion",
+        "source",
+        "webhookFormat"
+      ],
+      "properties": {
+        "cliVersion": {
+          "type": "string"
+        },
+        "source": {
+          "const": "nerviq-cli"
+        },
+        "webhookFormat": {
+          "const": "generic-audit-event"
+        }
+      }
+    }
+  }
+}

package/contracts/pack-contract.schema.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Nerviq Domain/MCP Pack",
+  "type": "object",
+  "required": ["key", "label"],
+  "properties": {
+    "key": { "type": "string", "pattern": "^[a-z][a-z0-9-]*$" },
+    "label": { "type": "string" },
+    "description": { "type": "string" },
+    "useWhen": { "type": "string" },
+    "adoption": { "type": "string" },
+    "recommendedModules": { "type": "array", "items": { "type": "string" } },
+    "benchmarkFocus": { "type": "array", "items": { "type": "string" } }
+  }
+}

package/contracts/technique-contract.schema.json

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Nerviq Technique",
+  "type": "object",
+  "required": ["id", "name", "check", "impact", "category", "fix"],
+  "properties": {
+    "id": { "type": ["string", "integer"] },
+    "name": { "type": "string", "minLength": 3 },
+    "check": { "description": "Function (ctx) => boolean|null" },
+    "impact": { "type": "string", "enum": ["critical", "high", "medium", "low"] },
+    "category": { "type": "string", "minLength": 2 },
+    "fix": { "type": "string", "minLength": 5 },
+    "rating": { "type": "integer", "minimum": 1, "maximum": 5 },
+    "confidence": { "type": "number", "minimum": 0, "maximum": 1 },
+    "sourceUrl": { "type": "string", "format": "uri" },
+    "template": {}
+  }
+}

package/docs/ARCHITECTURE.md

@@ -0,0 +1,74 @@
+# Architecture
+
+## Data Flow
+
+```mermaid
+graph LR
+    CLI[bin/cli.js] --> Audit[audit.js]
+    CLI --> Setup[setup.js]
+    CLI --> Analyze[analyze.js]
+    CLI --> Plans[plans.js]
+    CLI --> Gov[governance.js]
+    CLI --> Bench[benchmark.js]
+
+    Context[context.js] --> Audit
+    Context --> Setup
+    Context --> Analyze
+
+    Techniques[techniques.js<br/>84 checks + 30 stacks] --> Audit
+    Techniques --> Setup
+
+    DomainPacks[domain-packs.js<br/>16 domains] --> Analyze
+    DomainPacks --> Gov
+
+    McpPacks[mcp-packs.js<br/>26 MCP packs] --> Analyze
+    McpPacks --> Gov
+    McpPacks --> Plans
+
+    Audit --> Activity[activity.js<br/>snapshots + history]
+    Bench --> Activity
+    Analyze --> Activity
+```
+
+## Module Responsibilities
+
+| Module | Role | I/O |
+|--------|------|-----|
+| **context.js** | Scans project directory, caches file reads | Dir path → ProjectContext |
+| **techniques.js** | Defines 84 checks + 30 stacks. The knowledge base | ProjectContext → check results |
+| **audit.js** | Runs checks, calculates score, builds topNextActions | Options → scored result |
+| **analyze.js** | Augment/suggest-only analysis with strengths, gaps, domains | Options → analysis report |
+| **plans.js** | Generates proposal bundles, applies with rollback | Audit result → proposals |
+| **setup.js** | Generates CLAUDE.md, hooks, commands, agents, skills, rules | Stacks + context → files |
+| **governance.js** | Permission profiles, hook registry, policy packs | Config → governance summary |
+| **benchmark.js** | Isolated before/after in temp copy | Options → benchmark report |
+| **domain-packs.js** | Detects repo type from signals | Context + stacks → domain matches |
+| **mcp-packs.js** | Recommends MCP servers per domain | Domains + signals → MCP packs |
+| **activity.js** | Snapshots, history, compare, trend export | Payloads → artifact files |
+
+## Scoring
+
+```
+Score = (earned / max) * 100
+
+Weights: critical=15, high=10, medium=5, low=2
+Organic score: excludes checks that nerviq itself generated
+```
+
+Checks return `true` (pass), `false` (fail), or `null` (not applicable / skip).
+
+## Trust-First Flow
+
+```
+User runs audit → sees score + gaps
+            ↓
+User runs plan → sees file previews + rationale
+            ↓
+User reviews → approves specific bundles
+            ↓
+apply writes files → rollback manifest created
+            ↓
+User runs audit again → sees improvement
+```
+
+No step writes without the previous step's output being reviewed.