critical-gate 2.0.1 → 2.1.1

package/README.md

@@ -36,6 +36,157 @@ 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.
 
+## Concrete Examples
+
+Critical Gate is most useful when an AI-generated diff looks plausible at a glance but breaks the
+shape of the task.
+
+### Dependency Drift
+
+Task:
+
+```text
+Add CSV export using the existing file writer utilities.
+```
+
+Risky diff:
+
+- Adds `papaparse` or another production dependency.
+- Changes `package.json` and the lockfile.
+- Does not document why the existing repository utilities are insufficient.
+
+What Critical Gate reports:
+
+- The manifest changed.
+- A dependency was added.
+- The task did not ask for a dependency.
+- Repair guidance asks the agent to remove the package, use existing utilities, or add explicit
+  justification.
+
+### Test Weakening
+
+Task:
+
+```text
+Refactor signup validation internals without changing behavior.
+```
+
+Risky diff:
+
+```diff
+- expect(result.error.message).toContain("email is required");
++ expect(result.error).toBeDefined();
+```
+
+What Critical Gate reports:
+
+- A behavioral assertion became a generic existence assertion.
+- The replacement is less specific even though the test still passes.
+- Repair guidance asks for an equally specific behavioral assertion.
+
+### Unrelated Edits
+
+Task:
+
+```text
+Fix font weight in the profile heading.
+```
+
+Risky diff:
+
+- Changes the intended stylesheet.
+- Also rewrites unrelated layout files.
+- Touches CI config or package metadata.
+
+What Critical Gate reports:
+
+- The changed files do not fit the small task boundary.
+- Diff Cost Score and Scope Expansion Score increase.
+- Repair guidance asks to split unrelated edits or expand the task explicitly.
+
+### Utility Reinvention
+
+Task:
+
+```text
+Add signup date formatting.
+```
+
+Risky diff:
+
+```ts
+export function formatDateForSignup(value: Date): string {
+  return value.toISOString();
+}
+```
+
+when the repository already has:
+
+```ts
+export function formatDate(value: Date): string;
+```
+
+What Critical Gate reports:
+
+- A similar exported helper already exists.
+- Evidence includes existing export name, signature shape, folder role, path, and import count.
+- Repair guidance points the agent toward reuse instead of another local abstraction.
+
+### Public API Changes
+
+Task:
+
+```text
+Improve internal validation.
+```
+
+Risky diff:
+
+```diff
+- export interface SignupOptions {}
++ interface SignupOptions {}
+```
+
+What Critical Gate reports:
+
+- A public export was removed without task or release evidence.
+- If `.critical-gate/api-surface.json` exists, the finding cites the snapshotted public contract.
+- Repair guidance asks for restore, migration notes, changelog/changeset evidence, or an updated API
+  snapshot.
+
+### Clean Diff Certification
+
+When the gate passes, the Markdown report still explains what was checked:
+
+- Changed file count and churn.
+- Diff Coherence Score.
+- Dependency discipline.
+- Test integrity.
+- Public API surface.
+- Secret/path checks.
+
+This makes clean runs useful in PRs and agent handoffs instead of just saying “no findings.”
+
+## Positioning
+
+Critical Gate is adjacent to linters, test suites, security scanners, and AI code review tools, but
+it is not trying to replace them.
+
+- **Linters and formatters** enforce code style and static rules. Critical Gate checks whether the
+  diff stayed inside the task and repository contract.
+- **Test suites** prove selected behavior still passes. Critical Gate looks for tests that were
+  weakened, skipped, or changed to assert less meaningful behavior.
+- **Security scanners** look for known vulnerabilities or secrets. Critical Gate includes lightweight
+  diff-only secret/path checks but focuses on agent failure patterns beyond security.
+- **AI code reviewers** often produce broad suggestions. Critical Gate is deterministic-first and
+  evidence-first; optional model help is for explanation, not primary detection.
+- **CI checks** usually answer whether the project builds. Critical Gate answers whether the diff is
+  acceptable for the task before it is merged.
+
+The category is a **diff integrity gate for AI-assisted development**: a cheap, local, repository-
+aware enforcement layer that catches high-risk agent behavior before humans have to infer it from a
+large patch.
+
 ## Surfaces
 
 Critical Gate has one analysis core and multiple surfaces:
@@ -78,6 +229,17 @@ node dist/cli.js check --task "Add signup validation" --format sarif --output cr
 node dist/cli.js check --task "Add signup validation" --format repair
 ```
 
+Create a public API contract snapshot for repositories that expose TS/JS entrypoints:
+
+```bash
+node dist/cli.js snapshot-api
+git add .critical-gate/api-surface.json
+```
+
+After the snapshot is committed, normal `check` runs compare export removals, additions, and
+signature changes against it. Public contract changes should include snapshot, changelog, changeset,
+or migration evidence.
+
 Exit codes:
 
 - `0`: gate passed.
@@ -226,6 +388,7 @@ Branch and commit conventions for this repository:
 - [docs/github-integration.md](docs/github-integration.md): GitHub Action, SARIF, and threshold guidance.
 - [docs/codex-integration.md](docs/codex-integration.md): Codex hook and repair-loop guidance.
 - [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.
 - [CHANGELOG.md](CHANGELOG.md): project-level release notes.
 
 ## Project Status

package/dist/cli.d.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { type GitDiffResult } from "./index.js";
-export declare const CLI_VERSION = "2.0.1";
+export declare const CLI_VERSION = "2.1.1";
 export declare const ExitCode: {
     readonly Pass: 0;
     readonly FindingsFailed: 1;
@@ -12,9 +12,15 @@ interface CliIo {
     stdout: (message: string) => void;
     stderr: (message: string) => void;
     writeFile: (path: string, content: string) => void;
+    chmodFile?: (path: string, mode: number) => void;
     now: () => Date;
-    readDiff: (baseRef?: string) => GitDiffResult;
+    readDiff: (baseRef?: string, options?: {
+        staged?: boolean;
+    }) => GitDiffResult;
+    exists?: (path: string) => boolean;
+    readFile?: (path: string) => string;
 }
 export declare function main(argv?: string[], io?: CliIo): ExitCode;
+export declare function isCliEntrypoint(importMetaUrl: string, argvPath?: string): boolean;
 export {};
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAMA,OAAO,EASL,KAAK,aAAa,EAEnB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,WAAW,UAAU,CAAC;AAEnC,eAAO,MAAM,QAAQ;;;;;CAKX,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,OAAO,QAAQ,CAAC,CAAC;AAUhE,UAAU,KAAK;IACb,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,GAAG,EAAE,MAAM,IAAI,CAAC;IAChB,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,KAAK,aAAa,CAAC;CAC/C;AAYD,wBAAgB,IAAI,CAAC,IAAI,WAAwB,EAAE,EAAE,QAAY,GAAG,QAAQ,CAQ3E"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAaA,OAAO,EAyBL,KAAK,aAAa,EAEnB,MAAM,YAAY,CAAC;AAEpB,eAAO,MAAM,WAAW,UAAU,CAAC;AAEnC,eAAO,MAAM,QAAQ;;;;;CAKX,CAAC;AAEX,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,QAAQ,CAAC,CAAC,MAAM,OAAO,QAAQ,CAAC,CAAC;AAYhE,UAAU,KAAK;IACb,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACnD,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACjD,GAAG,EAAE,MAAM,IAAI,CAAC;IAChB,QAAQ,EAAE,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,aAAa,CAAC;IAC9E,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACnC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CACrC;AAyBD,wBAAgB,IAAI,CAAC,IAAI,WAAwB,EAAE,EAAE,QAAY,GAAG,QAAQ,CAQ3E;AAs0BD,wBAAgB,eAAe,CAAC,aAAa,EAAE,MAAM,EAAE,QAAQ,SAAkB,GAAG,OAAO,CAK1F"}