@nerviq/cli 1.29.1 → 1.30.0

package/CHANGELOG.md

@@ -5,8 +5,244 @@ All notable changes to the **Nerviq** CLI are 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).
 
+## Evidence tiers
+
+Per **TRUTH-03** (POS-05 / continuous-governance positioning, 2026-04-29),
+every changelog entry from this release forward is tagged with an explicit
+evidence tier so a buyer / reviewer / contributor can tell at a glance how
+strongly we stand behind the claim:
+
+- `[Tested]` — verified in this codebase via `npm test` (canonical or Jest).
+  This is the strongest tier; a reproducible test guards against regression.
+- `[Measured]` — backed by a controlled before/after run with declared
+  evaluator + cross-model judge, recorded under
+  `nerviq-research/research/measurement-runs/`. Strongest external evidence.
+- `[Reported]` — surfaced by an external pilot, user-lab study, or community
+  observation; not yet independently re-measured.
+- `[Aspirational]` — directional claim, design intent, or planned behavior.
+  Honest but not yet evidence-backed; flagged so it can't masquerade as proof.
+
+Untagged historical entries pre-2026-04-29 should be treated as `[Tested]` if
+they describe shipped behavior with regression coverage; the absence of a
+tag is not an evidence-tier downgrade.
+
 ## [Unreleased]
 
+(no unreleased changes)
+
+## [1.30.0] - 2026-04-29
+
+### Summary
+
+Agent-facing surfaces ship: SDK bundled into the CLI tarball (MEMO-03 = B
+decision), GitHub Action wired with full marketplace metadata (MR-06),
+`nerviq certify --agent-ready` hardening gate (AI-13), and a postinstall
+quick-start hint (AI-10). Continuous-governance UX polish carries over
+from the round-5/6 closure waves: `pr-check` composite command (LOOP-02),
+named watch alerts (LOOP-01), stale-reference headline before "Top 3 fixes"
+(PROD-03), Windows mojibake fix (MEMO-16), and OWASP cross-walk on
+shallow-risk findings (POS-01a). Performance: ~17% cut in the
+checkAllTechniques hot loop (AI-12a). All 7 user-lab BUG fixes from the
+2026-04-28 12-persona study landed (BUG-01..07). Tooling: `publish.js`
+no longer swallows errors (EXP-08).
+
+### Added — Agent-facing surfaces (round-8/9 closures)
+
+- `[Tested]` **SDK bundled into the CLI tarball (MEMO-03 a..e).** New
+  `package.json` `exports` map exposes `@nerviq/cli`, `@nerviq/cli/sdk`
+  (programmatic API), `@nerviq/cli/sdk/types` (TypeScript declarations),
+  and `@nerviq/cli/package.json`. The `files` whitelist now includes
+  `sdk/`, so `npm pack --dry-run` ships
+  `sdk/{index.js,index.d.ts,package.json,README.md}` (266 files,
+  883.1kB). README + `sdk/README.md` rewritten to point at the bundled
+  install path; the never-published `@nerviq/sdk` package name is now
+  documented as historical only. **Closes the public install-path
+  contradiction flagged by the Codex CTO/CEO Market Memo (2026-04-13).**
+- `[Tested]` **`nerviq certify --agent-ready` (AI-13).** New mode under
+  the existing `certify` command runs 6 pass/fail criteria
+  (`agent-context-present`, `gitignore-blocks-env`,
+  `deny-rules-configured`, `no-critical-shallow-risk`,
+  `no-stale-references`, `governance-score-floor ≥ 50`). 3 are critical;
+  failing any drops the verdict from `agent-ready-full` to
+  `agent-ready-with-caveats` or `not-agent-ready`. Distinct shields.io
+  badges per verdict. Exit 0 on no-critical-fail, exit 1 otherwise
+  (CI-friendly).
+- `[Tested]` **GitHub Action marketplace metadata (MR-06).**
+  `action/action.yml` adds the `branding` block (icon: `shield`, color:
+  `green`) required for Marketplace listing, expands inputs
+  (`threshold` / `platform` / `dir` / `diff-only` / `diff-base`), and
+  expands outputs (`score` / `organic-score` / `passed` / `failed` /
+  `total` / `stale-references` / `gate`). Invocation now passes
+  `--no-harmony-first` so machine output stays parser-safe regardless
+  of the harmony-first default. `GITHUB_STEP_SUMMARY` includes
+  stale-reference count + gate verdict.
+- `[Tested]` **Postinstall quick-start hint (AI-10).**
+  `tools/postinstall.js` runs once after `npm install @nerviq/cli`,
+  printing a 4-line "next steps" block (`audit` / `setup --auto` /
+  `harmony-audit`). Suppressed in CI / non-TTY / transitive-dep installs
+  / when `NERVIQ_POSTINSTALL_QUIET=1` is set. Wired via
+  `package.json:postinstall` with a `|| true` failsafe so it never
+  breaks an install.
+- `[Tested]` **AI-07 self-governing agent example.**
+  `sdk/examples/self-governing-agent.js` is the reference implementation
+  of the 5-step pattern documented at `/docs/for-agents`: pre-task
+  audit (surface stale references) → harmony check (multi-platform
+  only) → actual task → post-task diff audit → outcome record.
+  Resolves SDK via `require('@nerviq/cli/sdk')` with an in-repo
+  fallback so the example is testable from a checkout.
+- `[Tested]` **AI-08 Nerviq references in generated CLAUDE.md.**
+  `src/setup.js` claude-md template now includes a "Governance check
+  (Nerviq)" section telling the agent to run `nerviq audit` before
+  substantive changes, re-run after editing
+  CLAUDE/AGENTS/.cursor/rules/.mcp.json/hooks, use `nerviq watch` for
+  continuous-mode workflows, and `nerviq pr-check --threshold 70`
+  before opening PRs.
+- `[Tested]` **AI-09 orchestrator integration patterns.**
+  `sdk/examples/langchain-integration.md` ships LangChain (Node +
+  Python), CrewAI, and generic-orchestrator patterns plus a decision
+  matrix for "which tool to call when". Documentation-only; SDK code
+  unchanged.
+- `[Tested]` **REL-01 release announcement automation.**
+  `tools/announce-release.js` extracts the CHANGELOG entry for a given
+  version, counts TRUTH-03 evidence tiers
+  (`[Tested]` / `[Measured]` / `[Reported]` / `[Aspirational]`), and
+  emits a markdown body for `gh release create --notes`. Wired as
+  `npm run announce:release [version]`.
+
+### Performance
+
+- `[Tested]` **`checkAllTechniques` partition-before-loop (AI-12a).**
+  `src/audit.js` partitions the techniques map into applicable /
+  not-applicable arrays in a single pre-pass, then iterates only the
+  applicable list in the hot loop. Not-applicable entries get
+  fast-pushed to results without per-check work. Bench: **494ms vs
+  ~600ms baseline** on a 120-file site repo (~17% cut). Per AI-12
+  governance-budget tracking — moves real-repo overhead from ~1.17%
+  toward the revised <2% cumulative / <1% per-call envelope.
+
+### Round 6 — Continuous-governance polish (2026-04-29)
+
+- `[Tested]` `bin/cli.js` adds the `nerviq pr-check` composite command —
+  audit + diff-only + threshold gate + markdown PR-comment + JSON envelope,
+  with explicit gate ✅/❌ and exit code 1 on fail. **LOOP-02 closed.**
+- `[Tested]` `src/audit.js` runs the BUG-04 stale-reference patterns
+  default-on as a mini-scan. CLI text output prints the
+  `📌 Stale references in agent docs: N` block before "Top 3 things to fix"
+  so it is the literal first user-visible value. **PROD-03 closed.**
+- `[Tested]` `src/watch.js` emits named `🔔 NEW: …` / `✓ CLEARED: …`
+  alerts per change diff (sourced from staleReferences + critical
+  shallow-risk hits). `--no-alerts` opt-out flag. **LOOP-01 closed.**
+- `[Tested]` `src/shallow-risk/patterns/*` — every pattern now declares
+  an `owaspTags: [...]` array machine-readable cross-walk to OWASP Agentic
+  / MCP / Agentic-Skills Top 10 categories. Surfaced through `buildFinding`
+  so JSON consumers (`audit --json`, `pr-check --json`) get the tags on
+  every shallow-risk finding. **POS-01a closed.**
+- `[Tested]` `src/safe-glyph.js` (new) — Windows mojibake fix. Auto-
+  detects modern terminals (Windows Terminal, VS Code, WSL, Git Bash) and
+  falls back to ASCII glyphs (`[OK]`, `[X]`, `[!]`) on legacy cmd.exe / PS.
+  Override via `NERVIQ_GLYPH=ascii|unicode`. `colorize()` routes all CLI
+  output through the helper. **MEMO-16 closed.**
+- `[Reported]` `src/auto-suggest.js` empty-state message now lists explicit
+  `missingSignals` + thresholds so users know exactly what's missing if
+  the suggest-rules loop is data-starved. Reported by user-lab BUG-07.
+- `[Reported]` `nerviq audit --fix --json` now emits valid JSON with the
+  full outcome envelope (mode, exitCode, plan, advisoryOnly, patchArtifact,
+  rollbackArtifact, reAudit, unresolvedKeys, branchName, warnings).
+  Reported by user-lab BUG-01.
+- `[Reported]` Machine formats (sarif/junit/csv/markdown) no longer get
+  contaminated by the Harmony-first banner. Default is parser-safe.
+  Reported by user-lab BUG-02.
+- `[Reported]` `deep-review --behavioral` returns `score: null,
+  status: "insufficient-signal"` on repos with <5 source files instead of
+  the misleading 100/100. Reported by user-lab BUG-05.
+- `[Reported]` `exception list/add --json` emits stable
+  `{records, count, generatedAt}` envelope. Reported by user-lab BUG-06.
+
+
+
+### Research — published evidence surfaces (no CLI code change, 2026-04-17)
+
+No product behavior change in this entry. Recording for coherence so
+operators can cite the CLI from the research artifacts that now
+reference it.
+
+- **"State of AI Agent Governance 2026-Q2" report** — 20-repo public
+  dataset audited with this CLI (v1.29.1). CC0. Published in
+  `DnaFin/nerviq-research`.
+- **Harmony value quantified** on 7 archetypes via `nerviq harmony-sync
+  --fix` before/after. Lift is bounded above by starting drift
+  (low-harmony repos: avg +20.5; high-harmony: avg 0).
+- **Self-dogfood audit** — `nerviq audit` run on the research repo +
+  this CLI repo, all numbers published honestly including harmony
+  33/100 on the research repo.
+- **First tier-4 measurements** — catalog items #63 (Meta-prompting)
+  and #11 (Chain-of-thought) earned the `📏 Measured` badge via
+  cross-model-judge before/after runs.
+- Three CI workflows now live in `DnaFin/nerviq-research`:
+  `tier1-runner.yml` (Fri 08:00 UTC), `tier2-runner.yml` (Sat 09:00
+  UTC), `tier25-runner.yml` (Sat 10:00 UTC). This CLI is what the
+  tier-2.5 workflow drives via subprocess — unchanged here.
+
+Public artifacts: https://github.com/DnaFin/nerviq-research
+
+### Documentation & positioning
+
+- `[Tested]` **AGENTS.md rewritten as flagship instruction file (DOG-01).**
+  The previous placeholder boilerplate is replaced with a real,
+  Nerviq-validated agent instruction surface for this CLI repo:
+  governance entry-point, single-source-of-truth pointers
+  (`package.json`, `release-metadata.json`, `nerviq-state.json`),
+  trust-boundary policy on instruction surfaces, and the canonical
+  release-prep checklist linked from the repo-boundary policy doc.
+  Closes the dogfood trust-break flagged by the 2026-04-28 cross-repo
+  project-domain audit.
+- `[Tested]` **README continuous-governance positioning (POS-03 / POS-05).**
+  Lede aligned with the COMPLEMENTARY positioning frame (Nerviq sits
+  alongside ASTs / linters / SAST, not in place of them). README v2
+  qualifies the value claim with the explicit "continuous" qualifier
+  so a one-shot reader doesn't mistake the audit-only surface for the
+  full product.
+- `[Tested]` **TRUTH-03 evidence-tier convention added to changelog.**
+  Every entry from this release forward is tagged with one of
+  `[Tested]` / `[Measured]` / `[Reported]` / `[Aspirational]` so a
+  buyer / reviewer / contributor can tell at a glance how strongly
+  we stand behind the claim. Documented in the file header.
+- `[Tested]` **Freshness watchlist hardening (Claude/Codex/Copilot/Gemini
+  provider model pages).** Provider model docs added to each platform's
+  freshness module so the daily watch surfaces upstream model-release
+  changes instead of going quiet between major doc-site refactors.
+  Also: Gemini IDE-integration URL fixed; non-existent "hooks" page
+  removed from the Gemini watchlist.
+- `[Tested]` **SECURITY.md internal contradiction fixed.** The supported
+  versions table now shows the `1.29.x` line as the active line of
+  support, replacing the stale `1.0.x` reference that survived from
+  the early-2026-Q2 cleanup pass.
+
+### Infrastructure
+
+- `[Tested]` **OIDC trusted publisher migration (`fc6ead3`).**
+  `.github/workflows/publish.yml` switched to `npm publish --provenance
+  --access public` running under GitHub Actions OIDC against the npmjs
+  Trusted Publisher (org `nerviq`, repo `nerviq`, workflow
+  `publish.yml`, environment `npm-publish`). No `NPM_TOKEN` in CI;
+  local `npm publish` is no longer a valid escape hatch. Provenance
+  attestations are generated for every release from this point
+  forward.
+
+### Verified
+
+- `[Tested]` jest: **475/475** passing (no test count delta from the
+  v1.29.0 / v1.29.1 baseline — round-6/8/9 features ship with their
+  own regression coverage that landed in the same suite).
+- `[Tested]` canonical CLI tests: **162/162** passing.
+- `[Tested]` `npm pack --dry-run`: clean. Tarball ships
+  `bin`, `src`, `sdk`, `docs`, `contracts`, `README.md`,
+  `CHANGELOG.md`, `SECURITY.md`, `package.json`.
+- `[Tested]` `node tools/pre-publish.js --ci --expected-version 1.30.0`:
+  passes (config + version surfaces aligned).
+- `[Tested]` `node tools/validate-release-metadata.js`: passes against
+  `package.json` + `CHANGELOG.md` + research-side `nerviq-state.json`.
+
 ## [1.29.1] - 2026-04-16
 
 ### Fixed — UX polish from external pilot feedback
@@ -1449,7 +1685,8 @@ Closes #35
 - Landing page (GitHub Pages ready)
 - Launch content and community posts
 
-[Unreleased]: https://github.com/nerviq/nerviq/compare/v1.29.1...HEAD
+[Unreleased]: https://github.com/nerviq/nerviq/compare/v1.30.0...HEAD
+[1.30.0]: https://github.com/nerviq/nerviq/compare/v1.29.1...v1.30.0
 [1.29.1]: https://github.com/nerviq/nerviq/compare/v1.29.0...v1.29.1
 [1.29.0]: https://github.com/nerviq/nerviq/compare/v1.28.0...v1.29.0
 [1.28.0]: https://github.com/nerviq/nerviq/compare/v1.27.1...v1.28.0

package/README.md

@@ -1,6 +1,6 @@
 # Nerviq
 
-> Standardize and govern your AI coding agent setup — score, fix, and align across 8 platforms.
+> **Continuous** cross-platform configuration governance for AI coding agents. Audit, score, and align agent config across 8 platforms — at config-time, before runtime, as a recurring layer (not a one-shot audit). Four lifecycle loops: local dev watch → PR/CI gate → org fleet posture → AI behavior compliance. (Pre-runtime config layer; complements runtime governance like Microsoft AGT and code-quality tools like SonarQube.)
 
 [![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)
@@ -44,6 +44,17 @@ Nerviq audits, sets up, and governs AI coding agent configurations for **8 platf
 
 Most repos use **more than one** AI coding agent — Claude and Cursor, Copilot and Codex, Gemini and Windsurf. Their configs drift silently. Nerviq is the neutral control plane that detects that drift, scores it, and helps align it.
 
+### Headline value: stale-reference detection
+
+`nerviq audit` runs a deterministic mini-scan on every invocation that catches the most common form of agent-config rot:
+
+- **Scripts that don't exist.** Your `AGENTS.md` says "run `npm test`" but `scripts.test` isn't defined in `package.json`. Flagged.
+- **Framework versions that drifted.** Your `CLAUDE.md` says "this is a Next.js 15 app" but `package.json` declares `next@^16.x`. Flagged.
+
+These checks run without a flag, with near-zero false positives, and are surfaced as a top-line section in audit output. Buyers and reviewers can verify each finding in 30 seconds — `cat package.json` against the agent doc. This is what cross-platform configuration governance looks like at the file boundary.
+
+### Cross-platform Harmony
+
 When your repo has 2+ platforms configured, `nerviq audit` leads with the Harmony Score — cross-platform alignment — before any single-platform results. Single-platform repos still get a normal per-platform audit.
 
 ```
@@ -172,12 +183,17 @@ npx @nerviq/cli synergy-report     # Multi-agent synergy analysis
 
 Synergy evaluates compound audit results, discovers compensation patterns (where one platform covers another's gaps), and ranks recommendations by cross-platform impact.
 
-## SDK — `@nerviq/sdk` `BETA`
+## SDK — `@nerviq/cli/sdk` `BETA`
+
+Programmatic access to all Nerviq capabilities. The SDK ships **inside** the `@nerviq/cli` package (no separate install) per MEMO-03 (B = BUNDLE, signed 2026-04-28).
 
-Programmatic access to all Nerviq capabilities:
+**Recommended (single install):**
 
 ```js
-const { audit, harmonyAudit, detectPlatforms } = require('@nerviq/sdk');
+// Both forms work — same code path, both exported from @nerviq/cli.
+const { audit, harmonyAudit, detectPlatforms } = require('@nerviq/cli');
+// OR for explicit SDK-shape (input validation, typed):
+const sdk = require('@nerviq/cli/sdk');
 
 async function main() {
   try {
@@ -198,6 +214,8 @@ async function main() {
 main();
 ```
 
+> **Migration note (2026-04-29):** Earlier docs referenced `require('@nerviq/sdk')` as a separate npm package. That package was never published. The SDK now ships bundled inside `@nerviq/cli` (zero additional install). Existing `require('@nerviq/sdk')` calls will fail with module-not-found; switch to `require('@nerviq/cli')` or `require('@nerviq/cli/sdk')`. See `research/memo-03-sdk-decision-2026-04-28.md` for the rationale.
+
 Stable SDK surfaces: `audit`, `harmonyAudit`, `detectPlatforms`, `getCatalog`  
 Experimental SDK surfaces: `synergyReport`, `routeTask`
 
@@ -247,8 +265,8 @@ All successful operational responses are wrapped in a JSON envelope:
 {
   "data": {},
   "meta": {
-    "version": "1.29.1",
-    "timestamp": "2026-04-16T08:00:00.000Z"
+    "version": "1.30.0",
+    "timestamp": "2026-04-29T12:00:00.000Z"
   }
 }
 ```

package/SECURITY.md

@@ -28,14 +28,10 @@ Please include:
 
 | Version | Supported |
 |---------|-----------|
-| 1.29.x | Yes |
-| 1.28.x | Yes |
-| 1.27.x | Yes |
-| 1.26.x | Yes |
-| < 1.26 | No |
-| < 1.29 | No |
-
-Only the latest patch release of each supported major.minor line receives security updates.
+| 1.30.x | Yes |
+| < 1.30 | No |
+
+Only the latest patch release of each supported major.minor line receives security updates. Older minors are out of scope — upgrade to a supported line for fixes.
 
 ## Dependency Policy