critical-gate 2.2.0 → 2.3.0

package/README.md

@@ -36,6 +36,27 @@ Current detectors focus on TypeScript and JavaScript repositories:
 Every finding includes severity, confidence, evidence, tags, and a repair hint that another agent or
 developer can act on.
 
+## Supported Scope
+
+Current support is strongest for TypeScript and JavaScript repositories with Git history and
+package-manager metadata available. The best-covered ecosystems are Node-based projects using
+common TS/JS source, test, package manifest, lockfile, config, and CI patterns.
+
+Experimental support includes framework-aware heuristics for patterns seen in dogfooding, such as
+Astro-style content contracts and repository-specific history or utility reuse signals. These checks
+start conservatively and should stay in observation mode until a repository has enough clean runs.
+
+Out of scope for the current release stage:
+
+- Deep semantic analysis for non-TS/JS languages.
+- Whole-repository LLM scanning.
+- Broad vulnerability scanning beyond lightweight diff-only secret and path checks.
+- Treating current internal dogfood metrics as a broad external benchmark.
+
+Critical Gate is useful today as a pre-review integrity gate for agent-produced TS/JS diffs, but it
+is still pre-stable. Roll it out progressively before making it a hard organization-wide merge
+requirement.
+
 ## Concrete Examples
 
 Critical Gate is most useful when an AI-generated diff looks plausible at a glance but breaks the
@@ -196,12 +217,37 @@ Critical Gate has one analysis core and multiple surfaces:
 - **Codex hook**: repair-oriented stop hook for agent workflows.
 - **VS Code extension**: Activity Bar dashboard, status bar state, Problems diagnostics, full report
   output, evidence navigation, and repair-copy actions.
+- **Agent onboarding**: `critical-gate init-agent` and the VS Code initialization command add a
+  managed Critical Gate section to `AGENTS.md` while preserving existing repository instructions.
 
 The CLI remains the source of truth. The editor and CI surfaces consume CLI output rather than
 reimplementing detector logic.
 
+## Recommended Team Rollout
+
+Start with report-only local runs and default thresholds. Treat medium, low, info, and
+observation-mode findings as calibration data until the repository has enough clean runs.
+
+Recommended sequence:
+
+1. Run the CLI locally on AI-generated diffs with specific task text.
+2. Add the VS Code extension for developer feedback where useful.
+3. Add GitHub Action SARIF upload with default blocking behavior for eligible blocker and high
+   findings.
+4. Review noisy findings and tune task text, repository docs, or `.critical-gate.json` policy.
+5. Add Codex hook enforcement only where compact repair loops are useful.
+6. Promote observation-friendly detector families only after dogfooding shows acceptable precision.
+
+See [docs/usage-guide.md](docs/usage-guide.md) for local rollout advice and
+[docs/github-integration.md](docs/github-integration.md) for CI thresholds.
+
 ## Quick Start From Source
 
+Critical Gate's current CLI distribution path is source-based: clone, install, build, and run
+`node dist/cli.js`. Package-registry publishing and prebuilt action releases are intentionally held
+until repository metadata, external dogfooding, and release artifacts are stable enough for broader
+public use.
+
 Requirements:
 
 - Node.js 22.13 or newer.
@@ -354,6 +400,13 @@ the VS Code surface. Configure `criticalGate.cliPath` only when testing a custom
 For a fuller walkthrough with examples, rollout advice, report interpretation, and troubleshooting,
 read [docs/usage-guide.md](docs/usage-guide.md).
 
+## Quality Evidence
+
+The CI workflow publishes coverage and deterministic evaluation reports as GitHub Actions artifacts:
+`critical-gate-coverage` and `critical-gate-evaluation`. See
+[docs/evaluation-strategy.md](docs/evaluation-strategy.md) for artifact paths, thresholds, and the
+current limits of the internal evaluation corpus.
+
 ## Development
 
 Useful commands:
@@ -382,10 +435,14 @@ Branch and commit conventions for this repository:
 - [docs/project-brief.md](docs/project-brief.md): product thesis, users, positioning, and scope.
 - [docs/architecture.md](docs/architecture.md): core architecture and data flow.
 - [docs/detectors.md](docs/detectors.md): detector catalog, severities, evidence, and implementation notes.
+- [docs/detector-quality.md](docs/detector-quality.md): detector quality boundaries, blind spots,
+  and coverage expectations.
 - [docs/usage-guide.md](docs/usage-guide.md): practical usage examples and troubleshooting.
 - [docs/installation.md](docs/installation.md): CLI, GitHub Action, Codex hook, and VSIX installation.
 - [docs/editor-surface.md](docs/editor-surface.md): VS Code dashboard and diagnostics behavior.
 - [docs/github-integration.md](docs/github-integration.md): GitHub Action, SARIF, and threshold guidance.
+- [docs/policy-file.md](docs/policy-file.md): `.critical-gate.json` policy-as-code reference and
+  validated examples.
 - [docs/codex-integration.md](docs/codex-integration.md): Codex hook and repair-loop guidance.
 - [docs/dogfood-evidence-plan.md](docs/dogfood-evidence-plan.md): real-repository dogfood automation,
   repair-loop metrics, and screenshot proof plan.
@@ -393,12 +450,15 @@ Branch and commit conventions for this repository:
   evidence, misses, fixes, and current evaluation baseline.
 - [docs/versioning-policy.md](docs/versioning-policy.md): release and versioning policy.
 - [docs/improvements-task-plan.md](docs/improvements-task-plan.md): trust and calibration roadmap.
+- [docs/tasks/pragmatic-improvement-backlog.md](docs/tasks/pragmatic-improvement-backlog.md):
+  realistic next improvements for trust, evaluation, policy, and rollout.
+- [SECURITY.md](SECURITY.md): supported security policy and private vulnerability reporting path.
 - [CHANGELOG.md](CHANGELOG.md): project-level release notes.
 
 ## Project Status
 
 The repository contains the TypeScript CLI implementation, deterministic detectors, Codex hook
-integration, GitHub Action integration, optional LLM explanation boundaries, npm package
+integration, GitHub Action integration, optional LLM explanation boundaries, source-based CLI
 distribution, and a VS Code Marketplace extension surface.
 
 ## License

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "critical-gate",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Repository-aware diff integrity gate for AI-generated code changes.",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/criticaldeveloper/critical-gate.git"
+  },
+  "homepage": "https://github.com/criticaldeveloper/critical-gate#readme",
+  "bugs": {
+    "url": "https://github.com/criticaldeveloper/critical-gate/issues"
+  },
   "bin": {
     "critical-gate": "./dist/cli.js"
   },
@@ -11,10 +19,14 @@
   ],
   "keywords": [
     "ai",
+    "ai-agents",
     "codex",
     "diff",
+    "diff-integrity",
     "quality-gate",
-    "code-review"
+    "code-review",
+    "sarif",
+    "static-analysis"
   ],
   "license": "MIT",
   "engines": {
@@ -24,6 +36,7 @@
     "@eslint/js": "^9.29.0",
     "@types/node": "^24.0.3",
     "@types/vscode": "^1.120.0",
+    "@vitest/coverage-v8": "4.1.9",
     "@vscode/test-electron": "^3.0.0",
     "@vscode/vsce": "^3.9.2",
     "ajv": "^8.20.0",
@@ -35,6 +48,8 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",
+    "package:action": "pnpm build && node scripts/prepare-action-package.mjs",
+    "smoke:action": "node scripts/smoke-action-package.mjs",
     "build:vscode": "tsc -p extensions/vscode/tsconfig.json",
     "build:vscode-tests": "tsc -p extensions/vscode/tsconfig.test.json",
     "package:vscode": "node scripts/prepare-vscode-package.mjs && pnpm build && pnpm build:vscode && node scripts/bundle-vscode-analyzer.mjs && pnpm --dir extensions/vscode exec vsce package --no-dependencies --out ../../artifacts/vscode/critical-gate-vscode.vsix",
@@ -45,6 +60,7 @@
     "format": "prettier --check .",
     "format:write": "prettier --write .",
     "test": "vitest run",
+    "coverage": "vitest run --coverage",
     "evaluate": "pnpm build && node scripts/evaluate-fixtures.mjs",
     "dogfood:plan": "node scripts/dogfood-runner.mjs plan",
     "dogfood:render": "node scripts/render-dogfood-report.mjs",