@nerviq/cli 1.27.0 → 1.29.0

package/docs/integration-contracts.md

@@ -0,0 +1,287 @@
+# Integration Contract Pack
+
+This document centralizes Nerviq's integration surfaces so external systems can adopt one stable package instead of scraping CLI text output.
+
+## Included contract surfaces
+
+- `nerviq serve` live OpenAPI contract via `GET /api/openapi.json`
+- `nerviq-mcp` stdio JSON-RPC 2.0 transport for MCP hosts
+- Generic audit webhook event contract via `contracts/audit-webhook-event.schema.json`
+- CI reference patterns for GitHub Actions, GitLab, Bitbucket, and generic shell runners
+- SDK usage examples through `sdk/README.md`
+
+## 1. Local REST contract
+
+Start the local API server:
+
+```bash
+npx @nerviq/cli serve --port 3000
+curl http://127.0.0.1:3000/api/openapi.json > nerviq-openapi.json
+```
+
+Current GET endpoints:
+
+- `/api/openapi.json`
+- `/api/health`
+- `/api/audit`
+- `/api/harmony`
+- `/api/catalog`
+
+The live OpenAPI document is the canonical machine-readable contract for local HTTP consumers.
+
+## 2. MCP transport (stdio JSON-RPC 2.0)
+
+Nerviq also ships a separate MCP server binary for hosts that speak Model Context Protocol over stdio.
+
+Use `nerviq serve` for local HTTP/OpenAPI consumers.
+Use `nerviq-mcp` when the host expects MCP over stdio.
+
+Example host registration:
+
+```json
+{
+  "mcpServers": {
+    "nerviq": {
+      "command": "npx",
+      "args": ["-y", "-p", "@nerviq/cli", "nerviq-mcp"]
+    }
+  }
+}
+```
+
+The runtime implementation lives in `src/mcp-server.js` and speaks JSON-RPC 2.0 over stdin/stdout.
+
+## 3. Generic webhook event contract
+
+When `audit` is called with `--webhook` and the URL is not a Slack or Discord webhook, Nerviq now emits a stable generic JSON event contract.
+
+Schema:
+
+- `contracts/audit-webhook-event.schema.json`
+
+Example:
+
+```json
+{
+  "event": "nerviq.audit.completed",
+  "schemaVersion": "1.0",
+  "generatedAt": "2026-04-09T12:00:00.000Z",
+  "platform": "claude",
+  "score": 84,
+  "passed": 196,
+  "failed": 34,
+  "results": [],
+  "data": {
+    "platform": "claude",
+    "platformLabel": "Claude",
+    "score": 84,
+    "scoreType": "live-audit-score",
+    "organicScore": 68,
+    "passed": 196,
+    "failed": 34,
+    "skipped": 28,
+    "checkCount": 258,
+    "topNextActions": [],
+    "quickWins": [],
+    "scoreCoaching": {
+      "currentScore": 84,
+      "nextMilestone": 90,
+      "pointsNeeded": 6,
+      "fixesNeeded": 2
+    },
+    "suggestedNextCommand": "npx nerviq fix verificationLoop"
+  },
+  "meta": {
+    "cliVersion": "1.29.0",
+    "source": "nerviq-cli",
+    "webhookFormat": "generic-audit-event"
+  }
+}
+```
+
+Compatibility note:
+
+- Top-level `platform`, `score`, `passed`, `failed`, and `results` remain present for older consumers
+- New consumers should prefer the nested `data` + `meta` contract
+
+## 4. CI reference patterns
+
+See:
+
+- `docs/ci-integration.md`
+- `action/README.md`
+- `docs/gitlab-ci-template.yml`
+- `docs/bitbucket-pipe.yml`
+
+Recommended patterns:
+
+### Score gate
+
+```bash
+npx @nerviq/cli audit --threshold 60
+```
+
+### PR drift gate
+
+```bash
+npx @nerviq/cli audit --diff-only --drift-mode ci --threshold 60
+```
+
+### Fleet rollup artifact
+
+```bash
+npx @nerviq/cli org scan ./app ./api ./infra --json --out nerviq-fleet.json
+```
+
+## 5. SDK reference
+
+See:
+
+- `sdk/README.md`
+- `docs/api-reference.md`
+
+Recommended SDK surfaces:
+
+- Stable: `audit`, `harmonyAudit`, `detectPlatforms`, `getCatalog`
+- Experimental: `synergyReport`, `routeTask`
+
+## Why this pack exists
+
+- External dashboards can bind to explicit contracts instead of scraping CLI text
+- CI systems can use repeatable patterns for threshold gates, drift gates, and fleet rollups
+- SDK users and HTTP users now share one public integration story instead of separate ad-hoc examples
+
+## 6. First-tier integration gate
+
+Nerviq does not treat every external surface as equally ready on day one.
+
+Before broader distribution surfaces such as GitHub Marketplace listings, JetBrains plugins, or similar first-tier integrations are unblocked, the release bar must be green across:
+
+- contract stability
+- public proof density
+- operational reliability
+- clear ownership and support posture
+- category fit
+
+See `docs/first-tier-integration-gate.md` for the explicit gate and current posture.
+
+## 7. CI output format contracts
+
+`nerviq audit --format=<name>` emits machine-readable output shapes for standard
+CI surfaces. All six formats share the same underlying audit result object; they
+differ only in rendering.
+
+### markdown (`--format=markdown`)
+
+GitHub-flavoured markdown suitable for a PR comment. Contract:
+
+- first line is an `## Score: N/100` heading followed by a shields.io badge
+- second block lists `**Platform:**` and `**Checks:**` summary
+- `### Top next actions` section with up to 5 items rendered as a GitHub
+  task-list checklist: `- [ ] **[SEVERITY] Title** (` + backtick key + `)`
+  optionally suffixed with ` — ` + backtick file:line
+- when `auditResult.shallowRiskHints` is present, a `### Shallow Risk (experimental, opt-in)`
+  section appears immediately after `### Top next actions`, with the
+  shallow-risk banner rendered as a blockquote and each hint listed with
+  severity, key, and file:line
+- `<details><summary>All failed checks (N)</summary>` collapsible block
+  containing a GitHub pipe-table with columns
+  `key | name | category | rating | file | line`. Pipe characters inside cells
+  are backslash-escaped.
+- footer line `Generated by [Nerviq](https://nerviq.net) vX.Y.Z · TIMESTAMP`
+- no raw HTML other than `<details>` / `<summary>`
+
+### junit (`--format=junit`)
+
+JUnit XML, Jenkins-compatible. Contract:
+
+- first line is `<?xml version="1.0" encoding="UTF-8"?>`
+- root element `<testsuites name="nerviq" tests="N" failures="F" skipped="S" time="0">`
+- one `<testsuite>` per check category, with attributes
+  `name=category`, `tests`, `failures`, `skipped`, `time`, `timestamp`,
+  `package="nerviq.PLATFORM"`
+- when `auditResult.shallowRiskHints` is present, a separate
+  `<testsuite name="shallow-risk">` is emitted so CI consumers can
+  filter it independently from governance scoring suites
+- one `<testcase>` per check, with `classname=category` and `name=key`
+- failed checks emit `<failure message="..." type="SEVERITY">BODY</failure>`
+  where message = `fix || name`, type = severity/impact, body contains
+  `name [at file:line] [(sourceUrl)]`
+- skipped checks emit `<skipped/>`
+- all attribute values and text nodes XML-escape `& < > " '`
+
+### csv (`--format=csv`)
+
+RFC 4180 CSV. Contract:
+
+- first row = header `key,id,name,category,layer,rating,severity,passed,file,line,sourceUrl,fix,projectedScoreDelta,projectedScoreAfter`
+- `layer` is one of `governance`, `drift`, `hygiene`, or `shallow-risk` (see §8)
+- one row per check result in `auditResult.results`
+- when `auditResult.shallowRiskHints` is present, those hints are
+  appended as additional rows tagged with `layer=shallow-risk`
+- `projectedScoreDelta` / `projectedScoreAfter` are populated only for rows whose
+  `key` appears in `auditResult.topNextActions` (the projection is computed per
+  top action, not per every check). Other rows leave both columns empty.
+- fields containing comma, double-quote, CR, or LF are wrapped in double-quotes
+- internal double-quotes are escaped by doubling (`""`)
+- no UTF-8 BOM
+- line separator = LF
+
+These contracts are the stable consumer API for `--format=markdown|junit|csv`.
+Downstream wrappers (GitHub Actions, Jenkins plugins, GitLab reporters,
+dashboards) should bind to these shapes rather than scraping the text output.
+
+## 8. Audit layers (scope taxonomy)
+
+Every check in the NERVIQ audit is tagged with exactly one `layer`. The
+layer answers the question "what kind of problem does this check look
+for?" and gives evaluators an explicit, stable map of what NERVIQ covers
+and what it deliberately does not.
+
+| Layer          | Short definition                                                                                                                      | Example checks                                                                                     |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `governance`   | Agent configuration posture: presence, content, and quality of agent-instruction files and platform settings. "Does my agent know X?" | `claudeMdExists`, `codexAgentsMdSubstantive`, `geminiSettingsExists`, MCP servers, hook presence   |
+| `drift`        | Cross-platform consistency and declared-vs-actual alignment. "Do two places agree on X?"                                              | Harmony drift, Gemini propagation completeness, "rules consistent across surfaces", pack agreement |
+| `hygiene`      | Repo-level cleanliness adjacent to agents — the engineering baseline that makes an agent's job easier.                                | `.gitignore`, `CHANGELOG`, `SECURITY.md`, `LICENSE`, `.editorconfig`, Node version pinning         |
+| `shallow-risk` | Opt-in boundary checks that sit at the agent-config <-> codebase edge and are emitted in parallel to the governance audit.                 | `agent-config-missing-file`, `mcp-server-no-allowlist`, `agent-config-dangerous-autoapprove`      |
+
+**Disambiguation rules** (apply when a check could plausibly fit more than one layer):
+
+- If the check asks "does my agent know X?" → `governance`.
+- If the check asks "do two places agree on X?" → `drift`.
+- If the check asks "does the repo have standard engineering hygiene that makes the agent's job easier?" → `hygiene`.
+- When in doubt, default to `hygiene`. A mild misclassification is recoverable; a missing tag breaks the coverage contract.
+
+**No deep-review lane.** There is intentionally no `deep-review`,
+`security`, or `code-review` layer. NERVIQ audits agent configuration and
+the cleanliness of the repo boundary an agent operates inside. It does
+not perform dataflow analysis, SAST, or general code review — those are
+out of scope and left to dedicated tools. This is the contract that
+lets evaluators know where our claim to ground-truth starts and stops.
+
+### 8.1 Shallow-risk as a parallel lane
+
+`shallow-risk` is the one layer that does **not** roll into the governance
+score. When enabled via `nerviq audit --shallow-risk`, findings are emitted
+through `auditResult.shallowRiskHints[]` and rendered separately in text,
+Markdown, JUnit, and CSV. They are intentionally excluded from:
+
+- `auditResult.score`
+- `auditResult.organicScore`
+- `auditResult.passed` / `failed` / `skipped`
+- `auditResult.topNextActions`
+- `auditResult.layerSummary.*.failed`
+
+This keeps the governance pipeline stable while still surfacing the
+agent-config <-> codebase red flags documented in [docs/shallow-risk.md](shallow-risk.md).
+
+**Surfaces.** The `layer` field appears in:
+
+- `auditResult.results[].layer` (JSON)
+- `auditResult.topNextActions[].layer` (JSON)
+- `auditResult.layerSummary` (JSON) — per-layer `{ total, passed, failed, skipped }`
+- CSV output — column between `category` and `rating`
+- JUnit output — attribute on each `<testcase layer="…">`
+- Markdown output — column in the failed-checks table plus a `_layer: X_` suffix on each top-action checklist item
+- Text output — "Coverage by layer:" summary block and a small `[layer]` prefix on failed-check names
+

package/docs/license-faq.md

@@ -0,0 +1,53 @@
+# Nerviq License FAQ
+
+Nerviq is licensed under **AGPL-3.0** (GNU Affero General Public License v3.0).
+
+This FAQ answers common questions about what you can and can't do.
+
+---
+
+## What can I do freely?
+
+**Use the CLI locally** — Run `nerviq audit`, `setup`, `fix`, `benchmark`, etc. on your own machine or CI pipeline. No restrictions.
+
+**Use it in CI/CD** — Add the GitHub Action or run `npx @nerviq/cli` in your pipeline. The output (scores, reports) is yours.
+
+**Fork and modify** — You can fork the repo, modify it, and use your fork internally.
+
+**Use the npm package** — Install `@nerviq/cli` globally or as a dev dependency. Normal usage is fine.
+
+## What triggers AGPL obligations?
+
+**Running Nerviq as a network service for others.** If you modify Nerviq and offer it as a hosted service (e.g., a SaaS dashboard that runs Nerviq audits for external users over a network), you must make your modified source code available to those users under AGPL-3.0.
+
+This is the key difference from regular GPL: AGPL extends the source-sharing requirement to users who interact with the software over a network, not just those who receive a copy.
+
+## Common scenarios
+
+| Scenario | AGPL obligation? |
+|----------|-----------------|
+| Developer runs `nerviq audit` locally | **No** |
+| CI pipeline runs `nerviq audit --threshold 60` | **No** |
+| Team uses nerviq internally on their repos | **No** |
+| Company wraps nerviq in an internal tool for their own devs | **No** |
+| Company offers "nerviq-as-a-service" to external customers | **Yes** — must share modified source |
+| Embedding nerviq checks in a paid SaaS product | **Yes** — must share modified source |
+| Using nerviq output (scores, reports) in your own product | **No** — output is data, not software |
+
+## What about the SDK (`@nerviq/sdk`)?
+
+The SDK is also AGPL-3.0. If you import it into your application and serve that application to users over a network, the AGPL obligation applies to the combined work.
+
+## What if I need a commercial license?
+
+Contact us at **hello@nerviq.net** to discuss commercial licensing options. We offer:
+- **Enterprise license** — use Nerviq without AGPL obligations
+- **OEM license** — embed Nerviq in your own product
+
+## Key points
+
+- **Local CLI usage is always fine** — no obligations
+- **CI usage is always fine** — no obligations
+- **Internal tools are fine** — no obligations
+- **Hosting for others triggers AGPL** — share your source
+- **Output data is yours** — scores, reports, JSON are not covered by AGPL

package/docs/maintenance.md

@@ -0,0 +1,155 @@
+# Knowledge Maintenance Process
+
+How to keep Nerviq's knowledge base accurate, current, and trustworthy.
+
+## Maintenance Cadences
+
+### Daily: Freshness Daemon
+
+The freshness system runs automatically and flags checks whose source documentation may have changed.
+
+**Canonical source of truth:**
+- `src/platform-change-manifest.js` centralizes tracked sources, review cadence, workflow details, and update triggers for all 8 platforms.
+- `.github/workflows/freshness-check.yml` is the live automation path that runs the daily freshness review and opens stale-source issues.
+
+**What to do:**
+- Review `nerviq doctor` output for freshness warnings
+- Review `nerviq doctor` output for broken MCP declarations (missing commands, unreachable URLs, missing env vars)
+- Review `nerviq doctor` output for broken hook runtime health (missing scripts, missing runtimes, or starter hook regressions)
+- Review `.claude/logs/prompt-injection-alerts.log` if the starter `injection-defense` hook reports suspicious external-content patterns during normal development
+- If a check's `sourceUrl` returns 404 or has changed significantly, mark for review
+- Update `confidence` values for any checks with degraded sources
+
+**Automation:**
+```bash
+npx @nerviq/cli doctor --verbose    # Shows freshness gates + MCP + hook runtime validation
+```
+
+**Programmatic manifest:**
+```js
+const { getPlatformChangeManifest, summarizePlatformChangeManifest } = require('@nerviq/cli');
+
+console.log(summarizePlatformChangeManifest());
+console.log(getPlatformChangeManifest()[0].trackedSources);
+```
+
+### Weekly: Platform Changelog Review
+
+Each supported platform publishes updates that may affect Nerviq's checks.
+
+**Process:**
+1. Check official changelogs/release notes for all 8 platforms:
+   - Claude Code: Anthropic changelog
+   - Codex: OpenAI platform updates
+   - Gemini CLI: Google AI Studio releases
+   - GitHub Copilot: GitHub blog/changelog
+   - Cursor: Cursor changelog
+   - Windsurf: Codeium/Windsurf releases
+   - Aider: GitHub releases
+   - OpenCode: GitHub releases
+
+2. For each relevant change:
+   - Does it add a new config option? → Candidate for new check
+   - Does it deprecate a feature? → Update or retire affected checks
+   - Does it change file formats? → Update config-parser.js
+
+3. Log findings in `research/` with date stamp
+4. If the change affects rollout posture or config semantics, update `src/platform-change-manifest.js` so cadence + triggers stay aligned with reality
+
+### Monthly: Cross-Reference Audit
+
+Verify internal consistency across the knowledge base.
+
+**Process:**
+1. Run the cross-reference audit:
+   ```bash
+   # From the NERVIQ research repo
+   python tools/check-trust-drift.py
+   ```
+
+2. Check for:
+   - Duplicate check IDs across platforms
+   - Checks with confidence below 0.7 (candidates for re-verification)
+   - Techniques referenced in research but missing from code
+   - Techniques in code with no corresponding research doc
+
+3. Reconcile any mismatches:
+   - Update source URLs that have moved
+   - Re-verify claims that have contradicting evidence
+   - Remove techniques that are no longer applicable
+
+### Quarterly: Pruning
+
+Remove or archive knowledge that is no longer relevant.
+
+**Process:**
+1. Query all checks by `lastVerified` date
+2. Identify checks not verified in 90+ days
+3. For each stale check:
+   - **Re-verify**: Visit sourceUrl, test the check, update confidence
+   - **Archive**: If the feature no longer exists, move to `_archived/`
+   - **Retire**: If the platform deprecated the feature, remove the check and note in CHANGELOG
+
+4. Review research documents older than 90 days:
+   - Still accurate? → Update `lastVerified` date
+   - Outdated? → Mark as `status: archived` in frontmatter
+   - Contradicted by newer findings? → Create superseding document
+
+5. Audit experiment results:
+   - Re-run 5 random experiments to confirm results still hold
+   - Update ratings if behavior has changed
+
+## The 90-Day Rule
+
+Every piece of knowledge in Nerviq has a maximum freshness window of 90 days.
+
+**What this means:**
+- After 90 days without re-verification, a check's confidence is automatically degraded
+- Research documents older than 90 days without updates are flagged in `nerviq doctor`
+- Stale checks are not removed automatically but are surfaced in audit output with warnings
+
+**How to handle stale checks:**
+
+1. **Check still valid, source unchanged:**
+   Update `lastVerified` timestamp. No code change needed.
+
+2. **Check valid but source URL changed:**
+   Update `sourceUrl` in the technique definition. Update `lastVerified`.
+
+3. **Check partially valid — behavior changed:**
+   Update the check function, fix text, confidence level. Create a research note documenting the change.
+
+4. **Check no longer valid — feature removed:**
+   Remove from `techniques.js`. Add entry to CHANGELOG. If other checks depend on it, update those too.
+
+5. **Check cannot be verified — source unavailable:**
+   Lower confidence to 0.5. Add a `TODO` comment. Flag for next weekly review.
+
+## Freshness Tracking Fields
+
+Each technique in Nerviq supports these freshness-related fields:
+
+| Field | Type | Purpose |
+|-------|------|---------|
+| `sourceUrl` | string | Primary documentation URL |
+| `confidence` | number (0.0-1.0) | How confident we are the check is correct |
+| `lastVerified` | ISO date string | When the check was last manually verified |
+| `addedVersion` | string | Nerviq version when the check was added |
+
+## Emergency Updates
+
+When a platform ships a breaking change:
+
+1. Create a research doc immediately: `research/{platform}-breaking-change-YYYY-MM-DD.md`
+2. Update affected techniques in the same session
+3. Run full check matrix: `node test/{platform}-check-matrix.js`
+4. Run golden matrix to detect output changes: `node test/{platform}-golden-matrix.js`
+5. Publish patch release if checks produce incorrect results
+
+## Metrics to Track
+
+- **Freshness coverage**: % of checks verified within 90 days
+- **Confidence distribution**: histogram of confidence values across all checks
+- **Stale check count**: number of checks past 90-day window
+- **Source availability**: % of sourceUrls returning 200
+- **Platform coverage**: checks per platform (target: balanced distribution)