Critical Gate 2.4: Complete Installation and Usage Guide for AI-Generated Diffs

Critical Gate 2.4 is the first version where the usage story feels like a real developer tool instead of a source-only dogfood project.

That matters.

The earlier versions proved the product idea: a repository-aware diff integrity gate for AI-generated code changes. Critical Gate could inspect an agent-produced diff, compare it against the task intent, and flag evidence-backed risks like unrelated file edits, unnecessary rewrites, unjustified dependencies, weakened tests, silent public API changes, config drift, and repository convention drift.

But a tool can have a good idea and still be awkward to adopt.

Critical Gate 2.4 changes the adoption path:

• The npm CLI package is now the primary public install path.
• Users can run it directly with npx critical-gate.
• Teams can install it as a dev dependency with npm install -D critical-gate.
• The GitHub Action uses the versioned npm CLI by default.
• The VS Code extension is documented as a Marketplace install.
• Agent onboarding can write Critical Gate instructions into AGENTS.md.
• Codex hooks can call the installable CLI instead of building from source.
• Release governance now checks that npm, GitHub Action, VS Code Marketplace metadata, docs, runtime version output, and SARIF tool metadata stay aligned.

This post is a practical guide to using Critical Gate 2.4 properly.

It is not just a release announcement. It is meant to answer:

How do I install this, run it locally, wire it into CI, configure policy, teach repo conventions, use it with Codex, understand reports, and roll it out without creating noise?

What Critical Gate Is For

Critical Gate is not a generic AI code reviewer.

That distinction matters because it keeps the product focused.

A generic AI reviewer tries to answer:

What comments might be useful on this pull request?

Critical Gate asks a narrower question:

Does this diff satisfy the task without taking unsafe or unjustified liberties?

It is an enforcement layer for the final diff. It checks whether an agent-produced patch is acceptable for this repository, given:

• the task intent
• changed files
• local conventions
• public API surface
• tests
• dependencies
• configuration
• expected blast radius
• repository history
• learned support-file relationships

The value is not prettier review comments. The value is catching high-risk agent failure patterns before merge.

Examples:

• A small task touches unrelated files.
• A simple feature becomes a large rewrite.
• A dependency is added without justification.
• Tests are weakened while staying green.
• A public export changes silently.
• A runtime config file changes during a UI task.
• A local path, token, or internal URL appears in the diff.
• An agent creates a helper that already exists nearby.

Critical Gate is deterministic-first. Static analysis, git diff parsing, AST-style symbol checks, manifests, heuristics, and repository history run before any model help. LLMs are optional interpreters, not the primary detector.

What Changed in 2.4

The headline in 2.4 is distribution and maintainability.

Before 2.4, the tool was mainly source-based: clone the repository, install dependencies, build the CLI, and run node dist/cli.js.

That path still exists for contributors and maintainers, but it is no longer the main public user flow.

Critical Gate 2.4 adds:

• npm CLI as the primary public install path
• package validation for the built executable
• GitHub Action backed by the versioned npm CLI
• local source mode preserved for dogfooding and release verification
• Marketplace installation as the primary VS Code path
• installable CLI guidance for Codex hooks and agent onboarding
• release governance checks across npm, GitHub Action, VS Code, docs, version output, and SARIF metadata
• a split CLI entrypoint with focused modules for parsing, command implementations, result construction, IO defaults, help text, hook rendering, and compatibility exports
• Node 20 support as a real checked runtime
• a bundled VS Code analyzer to avoid Marketplace packaging warnings

The practical result is simple:

You can now use Critical Gate without cloning the Critical Gate repository.

Requirements

For normal users:

• Node.js 20 or newer
• Git history for baseline comparisons
• A TypeScript or JavaScript repository where package metadata and diffs are available

For source development:

• Node.js 20 or newer
• pnpm 10.34.4

The package is strongest today on TypeScript and JavaScript repositories. It is especially useful in Node-based projects with common source, test, package manifest, lockfile, config, and CI patterns.

It is not a full multi-language semantic analyzer. It is not a broad vulnerability scanner. It is not a whole-repository LLM review tool.

That is intentional.

Quick Start With npx

The fastest way to run Critical Gate is:

npx critical-gate check \
  --task "Add signup validation" \
  --base main \
  --format markdown

With pnpm:

pnpm dlx critical-gate check \
  --task "Add signup validation" \
  --base main \
  --format markdown

That command checks the current repository diff against main.

The task text is important. It tells the gate what the diff was supposed to accomplish. Critical Gate then asks whether the changed files, churn, tests, dependencies, config, API surface, and repository context fit that task.

Check the installed version:

npx critical-gate --version

In 2.4, this should report:

critical-gate 2.4.0

Install as a Dev Dependency

For repeated use in a repository, install Critical Gate locally:

npm install -D critical-gate

With pnpm:

pnpm add -D critical-gate

After that, package scripts and local hooks can call critical-gate directly.

For example, in package.json:

{
  "scripts": {
    "gate": "critical-gate check",
    "gate:markdown": "critical-gate check --format markdown",
    "gate:repair": "critical-gate check --format repair"
  }
}

Then run:

npm run gate -- --task "Add email validation to signup form" --base main

That style is useful when teams want a stable local command that agents, humans, and hooks can all call.

The Core Command

The main command is:

critical-gate check --task <text>

Common options:

--base <ref>        Git baseline reference
--format <format>   json, markdown, sarif, repair, or pr-comment
--fail-on <level>   blocker, high, or medium
--staged            Analyze staged changes with git diff --cached
--strict            Compatibility flag for stricter future thresholds
--output <path>     Write report to a file

The most common local command is:

npx critical-gate check \
  --task "Add email validation to signup form without changing authentication flow" \
  --base main \
  --format markdown

Use --base origin/main when your local branch tracks a remote target:

npx critical-gate check \
  --task "Fix the profile heading font weight" \
  --base origin/main \
  --format markdown

Analyze only staged changes:

npx critical-gate check \
  --task "Prepare signup validation patch" \
  --staged \
  --format markdown

Lower the failure threshold to blockers only:

npx critical-gate check \
  --task "Add signup validation" \
  --base main \
  --fail-on blocker

Raise the threshold to fail on medium findings after dogfooding:

npx critical-gate check \
  --task "Add signup validation" \
  --base main \
  --fail-on medium

Start with the default. Do not rush into stricter thresholds until your repository has enough clean runs.

Choosing Task Text

Task intent is part of the input contract.

Good task text is specific:

Add email validation to signup form without changing authentication flow.

Fix the VS Code Activity Bar icon so it renders visibly in dark themes.

Document CLI, GitHub Action, Codex hook, and VS Code installation.

Weak task text is vague:

Update code.

Fix stuff.

Improve project.

Vague task text makes scope analysis harder. Critical Gate reports task intent quality warnings, but those warnings do not fail the gate by themselves. They explain why the diff may be harder to judge and suggest adding a feature, module, file family, user flow, or public API target.

In CI, use PR titles plus relevant PR body context when possible. If a PR intentionally changes configuration, dependencies, or public API, say that in the task text.

For example:

Add CSV export using existing file writer utilities; do not add new runtime dependencies.

or:

Expose parseReport options, update API snapshot, and document the migration.

That gives the gate enough signal to distinguish intended blast radius from agent drift.

Output Formats

Critical Gate supports several output formats.

Use Markdown for humans:

npx critical-gate check \
  --task "Add email validation to signup form" \
  --base main \
  --format markdown

Use JSON for automation:

npx critical-gate check \
  --task "Add email validation to signup form" \
  --base main \
  --format json \
  --output critical-gate.json

Use SARIF for code scanning tools:

npx critical-gate check \
  --task "Add email validation to signup form" \
  --base main \
  --format sarif \
  --output critical-gate.sarif

Use repair output for agents:

npx critical-gate check \
  --task "Add email validation to signup form" \
  --base main \
  --format repair

Use PR-comment output for GitHub discussions:

npx critical-gate check \
  --task "Add email validation to signup form" \
  --base main \
  --format pr-comment \
  --output critical-gate-pr-comment.md

The PR comment format groups the same evidence-backed data into blocking findings, observations, expected support changes, and strongest scope drivers.

Understanding Reports

A report includes:

• decision: pass or fail
• changed files
• file roles
• additions and deletions
• findings
• severity
• confidence
• evidence
• repair guidance
• Diff Cost Score
• Diff Coherence Score
• task intent quality
• reviewer checklist
• policy applied section when policy exists

Diff Cost Score is a rough blast-radius and churn signal. It helps answer:

Was this amount of change reasonable for the task?

Diff Coherence Score is a positive 0 to 100 signal. It summarizes whether the changed files, support files, churn, and findings appear to fit the task intent.

Scope Expansion Score appears in editor and dashboard contexts to show how much the diff spread beyond the expected task boundary.

JSON output also includes confidence calibration counts:

• blockingEligibleCount
• observationModeCount
• confidenceSuppressedCount

Those counts explain whether high-risk findings were eligible to block, kept in observation mode, or suppressed because confidence was below threshold.

What Findings Look Like

Every finding is meant to be actionable.

A useful finding points to:

• file path
• line range when available
• symbol or manifest key when relevant
• detector name
• severity
• confidence
• evidence message
• repair guidance

For example, a dependency finding should not say:

Dependency changed.

It should explain:

package.json added production dependency papaparse, but the task asked for CSV export using existing file writer utilities.
Repair: remove the dependency, use existing utilities, or document why the package is required.

That is repair-oriented. A human can act on it. Codex can act on it. CI can fail on it.

Severity and Confidence

Critical Gate uses severity and confidence together.

Severity levels:

• blocker: should fail by default
• high: should fail by default when confidence and policy allow
• medium: should warn and appear in summaries
• low: informational unless combined with other risk
• info: context for humans and dashboards

Confidence bands:

• very-high: 0.90 and above
• high: 0.80 to 0.89
• medium: 0.60 to 0.79
• low: below 0.60

By default, only blocker and high findings can fail the gate, and they still need enough confidence.

This prevents a useful but uncertain observation from becoming a noisy merge blocker.

Blocking-Capable Detectors

The strongest detectors are the ones with concrete evidence.

Dependency Addition

Flags added dependencies when the task does not justify them.

Signals:

• added entries in dependencies or devDependencies
• lockfile companion changes
• task wording
• visible justification

Use case:

npx critical-gate check \
  --task "Add CSV export using existing file writer utilities" \
  --base main

If the diff adds a CSV library without explanation, Critical Gate should flag it.

Test Weakening

Flags removed assertions, skipped tests, .only, todo, and specificity drops.

Example risky change:

- expect(result.error.message).toContain("email is required");
+ expect(result.error).toBeDefined();

The second assertion may still pass, but it proves less.

Secret and Path

Flags suspicious added strings:

• provider-token-looking values
• absolute local paths
• internal hosts
• risky environment values

This is a lightweight diff-only scanner, not a full security scanner. It should sit beside mature security tooling.

Public API Surface

Flags silent public contract changes.

Signals:

• exported symbol additions
• export removals
• signature changes
• .critical-gate/api-surface.json
• public entrypoints from package metadata
• bin fields
• policy entrypoints
• framework contract fallbacks
• release evidence

This matters for libraries, CLIs, SDKs, and shared packages.

Config Change

Flags operational config drift.

Signals:

• CI config
• runtime pins
• TypeScript config
• package-manager config
• Docker or build config
• missing docs or task acknowledgement

Runtime files like .node-version, .nvmrc, .tool-versions, .npmrc, and .pnpmrc are treated as configuration.

Scope and Rewrite

Flags unrelated files, destructive edits, and large rewrites for small tasks.

This is where Critical Gate catches one of the most common agent patterns:

The task was small, but the diff wandered.

Intent Coverage

Flags underimplementation.

If the task asks to add a visible section and the diff only changes one CSS token, that is probably not enough.

This detector helps catch plausible-looking diffs that do not actually implement the requested work.

Observation-Friendly Detectors

Some detectors are useful but intentionally non-blocking by default.

These include:

• blast radius
• expected companions
• existing solution detection
• utility reinvention
• pattern violation
• repository intelligence
• framework-pack hints

They help reviewers and agents understand what looks unusual. They should become blocking only after dogfooding and policy tuning.

That is important. The goal is not to make every detector fail more often. The goal is to make findings evidence-backed and low-noise enough to trust.

Policy-as-Code

Critical Gate reads optional repository policy from .critical-gate.json.

Create a starter policy:

npx critical-gate init-policy
git add .critical-gate.json

A policy can set the default failure threshold:

{
  "policy": {
    "failOn": "high"
  }
}

It can keep a detector in observation mode:

{
  "policy": {
    "detectorOverrides": [
      {
        "detector": "expected-companions",
        "mode": "observation",
        "reason": "Useful during rollout, not blocking yet."
      }
    ]
  }
}

It can teach expected support files:

{
  "policy": {
    "expectedCompanions": [
      {
        "id": "source-test-companion",
        "whenChanged": "src/**/*.ts",
        "allow": ["tests/**/*.test.ts", "src/**/*.test.ts"],
        "reason": "Source changes commonly need behavior tests.",
        "createdAt": "2026-06-22T00:00:00.000Z"
      }
    ]
  }
}

It can allow support files for config changes:

{
  "policy": {
    "allowedSupportFiles": [
      {
        "id": "docs-for-config",
        "whenChanged": ".github/workflows/**",
        "allow": ["docs/**/*.md", "README.md", "CHANGELOG.md"],
        "reason": "Workflow changes may include visible operational docs.",
        "createdAt": "2026-06-22T00:00:00.000Z"
      }
    ]
  }
}

It can declare public API entrypoints:

{
  "policy": {
    "publicApi": {
      "entrypoints": ["src/index.ts", "src/testing.ts"]
    }
  }
}

Important limits:

• Public API entrypoints are explicit files, not globs.
• Accepted findings match exact finding ids, not broad suppressions.
• excludePatterns tune repository intelligence; they are not a security boundary.

Accept and Teach

Critical Gate can record reviewable repository knowledge.

Accept an exact finding after team review:

npx critical-gate accept \
  --finding "scope:src/generated/client.ts" \
  --reason "Generated client file is expected for API schema refreshes."

Teach a normal support-file relationship:

npx critical-gate teach \
  --id "i18n-for-ui-copy" \
  --when-changed "src/features/**/*.tsx" \
  --allow "src/i18n/**/*.json,locales/**/*.json" \
  --reason "UI copy changes require translation updates."

Use this for durable team conventions. Do not use it to hide one-off risky diffs that should be fixed, split, or documented.

Framework Packs

Critical Gate includes deterministic framework packs for:

• React
• Next.js
• Angular
• Astro
• Lit
• Nest
• Express
• Vite
• Storybook

Packs add ecosystem-specific expected companion hints such as component tests, stories, Angular templates, Nest specs, or framework docs.

They are auto-detected from package.json dependencies and common framework config files when possible.

You can force packs in .critical-gate.json:

{
  "frameworkPacks": ["react", "storybook", "vite"]
}

Framework-pack findings use the expected-companions detector. They are evidence-backed and non-blocking by default.

Public API Snapshots

Libraries and shared packages should consider committing an API snapshot.

Create one:

npx critical-gate snapshot-api
git add .critical-gate/api-surface.json

Critical Gate infers public entrypoints from:

• package.json exports
• main
• module
• types
• browser
• bin
• fallback index files

You can pin entrypoints:

npx critical-gate snapshot-api \
  --entrypoint src/index.ts \
  --entrypoint src/testing.ts

Once committed, normal checks load .critical-gate/api-surface.json.

If a diff removes a snapshotted export, changes a public signature, adds an export to a snapshotted entrypoint, or updates the API snapshot without release evidence, the gate expects visible contract evidence:

• snapshot update
• changelog
• changeset
• migration note
• explicit API release task intent

This is one of the most valuable features for libraries and shared internal packages. Agents can easily change exports while refactoring internals. API snapshots make that visible.

Local Git Hooks

Install reviewable local hooks:

npx critical-gate install-hooks

This writes:

• .git/hooks/pre-commit: checks staged changes only and fails on blocker findings
• .git/hooks/pre-push: checks the branch against ${CRITICAL_GATE_BASE:-origin/main} and fails on high or blocker findings

Install only one:

npx critical-gate install-hooks --hook pre-commit
npx critical-gate install-hooks --hook pre-push

Use --force after reviewing an existing hook:

npx critical-gate install-hooks --hook pre-push --force

If you installed Critical Gate locally and want the hook to use the local binary:

npx critical-gate install-hooks \
  --cli "npx critical-gate" \
  --force

Runtime environment variables:

CRITICAL_GATE_TASK   overrides task intent
CRITICAL_GATE_BASE   overrides the pre-push base branch

Hooks are useful, but do not turn them on for every repository blindly. Start with local runs and CI reporting, then add hooks when the team trusts the findings.

Agent Onboarding With init-agent

Initialize durable agent instructions:

npx critical-gate init-agent

This creates or updates a managed Critical Gate section in AGENTS.md.

Existing repository instructions are preserved. Repeated runs replace only the managed Critical Gate block.

Use --cli when agents should call a project-local wrapper:

npx critical-gate init-agent --cli "npm run critical-gate --"

or:

npx critical-gate init-agent --cli "npx critical-gate"

The generated section tells agents how to run:

• check
• hook
• snapshot-api
• init-policy
• install-hooks

It also tells them what Critical Gate is not:

• not a generic review assistant
• not a repo-wide LLM scanner
• not an automatic fixer
• not a reason to rewrite files without evidence

This is a small but important feature. Agents should know before they work that the final diff will be checked.

Codex Hook Mode

Critical Gate can run as a Codex Stop hook.

Consumer repositories should use the installable CLI:

npx critical-gate hook --base main

Example hook:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx critical-gate hook --base main",
            "timeout": 60,
            "statusMessage": "Running Critical Gate"
          }
        ]
      }
    ]
  }
}

Review hook commands before trusting them.

The hook should:

• run deterministic checks
• return pass when the diff is acceptable
• return compact repair guidance when blockers exist
• avoid dumping long reports into the agent loop
• avoid mutating files directly

Repair output includes an agent repair contract:

• smallest safe repair direction
• allowed files
• forbidden files
• success criteria

That lets Codex repair the diff without wandering into unrelated files.

GitHub Actions

The 2.4 GitHub Action story is much better.

Consumer repositories can use:

uses: criticaldeveloper/critical-gate@v2

The action runs the npm-published CLI by default, so workflows do not need pnpm, a Critical Gate source checkout, or a local TypeScript build.

Minimal SARIF workflow:

name: Critical Gate

on:
  pull_request:

permissions:
  actions: read
  contents: read
  pull-requests: read
  security-events: write

jobs:
  critical-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - id: critical-gate
        uses: criticaldeveloper/critical-gate@v2
        continue-on-error: true
        with:
          task: ${{ github.event.pull_request.title }}
          base: ${{ github.event.pull_request.base.sha }}
          format: sarif
          output: critical-gate.sarif

      - uses: github/codeql-action/upload-sarif@v4
        if: always() && hashFiles('critical-gate.sarif') != ''
        with:
          sarif_file: critical-gate.sarif

      - if: steps.critical-gate.outcome == 'failure'
        run: exit 1

The continue-on-error: true step is deliberate. It lets the workflow upload SARIF before failing.

Pin a CLI version only when needed:

with:
  version: "2.4.0"

Use local mode only for maintainers, source checkouts, or smoke-tested artifacts:

with:
  version: local

For prebuilt action artifacts:

pnpm package:action
pnpm smoke:action

Then use:

with:
  version: local
  install: "false"
  build: "false"

Only do that with an artifact that passed the smoke check.

GitHub Job Summary Instead of SARIF

If your repository does not use code scanning, write Markdown to the job summary:

name: Critical Gate

on:
  pull_request:

permissions:
  actions: read
  contents: read
  pull-requests: read

jobs:
  critical-gate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
        with:
          fetch-depth: 0

      - id: critical-gate
        uses: criticaldeveloper/critical-gate@v2
        continue-on-error: true
        with:
          task: ${{ github.event.pull_request.title }}
          base: ${{ github.event.pull_request.base.sha }}
          format: markdown
          output: critical-gate.md

      - if: always() && hashFiles('critical-gate.md') != ''
        run: cat critical-gate.md >> "$GITHUB_STEP_SUMMARY"

      - if: steps.critical-gate.outcome == 'failure'
        run: exit 1

Use SARIF when you want code scanning annotations. Use job summary when you want a simpler report in the workflow UI.

VS Code Marketplace Extension

Install the public extension:

Critical Gate for VS Code

The extension bundles the analyzer, so users do not need to clone the repository or install a global CLI just to use the editor surface.

After installing:

1. Open a local git repository in VS Code.
2. Open Critical Gate > Gate Runs.
3. Run Critical Gate: Run Check.

The extension provides:

• Activity Bar dashboard
• Gate Runs
• Analysis
• Problems diagnostics
• output-channel report
• evidence navigation
• repair-copy actions
• status bar state
• recent run history

Useful settings:

criticalGate.task
criticalGate.base
criticalGate.cliPath
criticalGate.refreshMode
criticalGate.refreshDebounceMs

Leave criticalGate.cliPath empty unless testing a custom CLI build.

The Problems panel maps findings like this:

• blocker/high: errors
• medium: warnings
• low: information
• info: hints

Quick actions can:

• open evidence
• copy repair prompt
• open existing solution
• open expected companion
• open cluster report
• accept blast-radius expansion locally

Recommended Rollout

Do not start by making every possible finding block merges.

Start with evidence.

A good rollout:

1. Run locally with npx critical-gate check.
2. Use specific task text.
3. Install the VS Code extension for visibility.
4. Add GitHub Action SARIF upload with default thresholds.
5. Review medium and observation-mode findings for noise.
6. Add .critical-gate.json policy only when you understand local conventions.
7. Use teach for durable support-file relationships.
8. Use accept only for exact findings the team reviewed.
9. Add API snapshots for packages with stable public entrypoints.
10. Add init-agent so agents know how to use the gate.
11. Add Codex hook mode where repair loops are useful.
12. Promote observation-friendly detectors only after dogfooding.

Default thresholds focus on blocker and high findings. Medium findings should usually educate first.

Example Workflow: Local Developer

You ask Codex or another agent:

Add username length validation to signup form and cover it with tests.

After it finishes:

npx critical-gate check \
  --task "Add username length validation to signup form and cover it with tests" \
  --base main \
  --format markdown

Expected source and test files should look normal.

Suspicious findings would include:

• production dependency added
• CI config edited
• auth flow changed
• tests weakened
• broad rewrite
• unrelated admin UI touched

If it fails, run repair output:

npx critical-gate check \
  --task "Add username length validation to signup form and cover it with tests" \
  --base main \
  --format repair

Pass that back to the agent.

Example Workflow: Library Maintainer

Initialize policy:

npx critical-gate init-policy

Declare public API entrypoints if package metadata is not enough:

{
  "policy": {
    "publicApi": {
      "entrypoints": ["src/index.ts"]
    }
  }
}

Create an API snapshot:

npx critical-gate snapshot-api
git add .critical-gate.json .critical-gate/api-surface.json

Now a public export change should include visible release evidence:

• updated snapshot
• changelog
• changeset
• migration note
• explicit API-release task intent

Run:

npx critical-gate check \
  --task "Expose parser options and document the public API change" \
  --base main \
  --format markdown

That is much better than discovering a silent API break after publishing.

Example Workflow: Team CI

Install in the repo:

npm install -D critical-gate

Add policy:

npx critical-gate init-policy

Add GitHub Action SARIF:

- id: critical-gate
  uses: criticaldeveloper/critical-gate@v2
  continue-on-error: true
  with:
    task: ${{ github.event.pull_request.title }}
    base: ${{ github.event.pull_request.base.sha }}
    format: sarif
    output: critical-gate.sarif

Then upload SARIF and fail after upload.

After a few weeks, inspect noisy findings and tune policy.

Example Workflow: Agent-Heavy Repository

Initialize agent instructions:

npx critical-gate init-agent --cli "npx critical-gate"

Add a Codex hook:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npx critical-gate hook --base main",
            "timeout": 60,
            "statusMessage": "Running Critical Gate"
          }
        ]
      }
    ]
  }
}

Now the agent knows the gate exists before it works, and the hook checks the diff when it stops.

That is the healthy loop:

task intent -> agent diff -> Critical Gate -> repair guidance -> scoped repair -> rerun

Troubleshooting

If the CLI reports no changed files, check:

• Are there changes relative to --base?
• Is --base the target branch or merge base you intended?
• Are you analyzing staged changes with --staged by accident?

If GitHub Action history is too shallow:

with:
  fetch-depth: 0

If SARIF uploads but the job passes, remember the pattern:

continue-on-error: true

on the Critical Gate step, then fail later when steps.critical-gate.outcome == 'failure'.

If repository knowledge looks stale:

CRITICAL_GATE_DISABLE_CACHE=true npx critical-gate check --task "Fix signup validation"

If VS Code keeps asking for task intent, set:

criticalGate.task

in workspace settings.

What Critical Gate Does Not Replace

Critical Gate does not replace:

• tests
• linters
• type checking
• security scanners
• human review
• release notes
• dependency review
• architecture judgment

It sits beside them.

Tests answer:

Does known behavior still pass?

Linters answer:

Does the code follow static rules?

Security scanners answer:

Are there known vulnerabilities or secrets?

Human reviewers answer:

Is this the right design and product behavior?

Critical Gate answers:

Did this agent-produced diff stay inside the task and repository contract?

That is the niche. That is why it can be low-noise.

The Best Way to Start

If you want the shortest useful path, do this:

1. Run one local check:

   npx critical-gate check \
     --task "Describe the actual task the agent was asked to do" \
     --base main \
     --format markdown

2. Install the VS Code extension:

   Critical Gate for VS Code

3. Add a GitHub Action in report-first mode.

4. Add init-agent once your team likes the output:

   npx critical-gate init-agent

5. Add policy only after seeing real findings:

   npx critical-gate init-policy

That sequence keeps friction low. It lets Critical Gate prove value before it becomes an enforcement layer.

Final Thought

AI coding agents make code changes faster than humans can comfortably audit every line.

That does not mean we should stop using them.

It means the final diff needs its own integrity layer.

Critical Gate 2.4 is the first version where that layer is easy to install and use across the normal developer surfaces:

• npx for quick local checks
• npm dev dependency for teams
• GitHub Action for CI
• VS Code Marketplace extension for editor feedback
• Codex hook for repair loops
• AGENTS.md onboarding for durable agent instructions
• policy-as-code for repository-specific rules

The goal is not to slow agents down.

The goal is to let them move quickly without quietly changing the wrong things.

That is the point of Critical Gate: evidence-backed diff integrity for AI-generated code.