Critical Gate 2.8.0: Task Contracts and Realistic Diff Integrity

Critical Gate 2.8.0 is not a release about adding a bigger pile of detectors.

That is the important part.

The easy path for an AI-code-review tool is to keep expanding the checklist: more rules, more warnings, more pattern matching, more things that look impressive in a demo. That can make a report longer without making it more useful.

Critical Gate is trying to solve a narrower problem:

Did this diff satisfy the task contract without unsafe side effects?

Version 2.8.0 matters because it makes that word, contract, more explicit. A task is no longer only a sentence passed through --task. It can now include structured constraints about paths, artifacts, invariants, and validation evidence.

That moves Critical Gate closer to the way serious AI-agent work actually happens.

An agent is not just asked to “improve the app.” A good agent task usually has boundaries:

• these files are in scope;
• these files are out of scope;
• this artifact must exist after the change;
• these properties must not change;
• these checks must be run before handoff.

Critical Gate 2.8.0 gives those boundaries a machine-readable shape through --task-contract.

What Changed In 2.8.0

The new core feature is a structured task contract:

critical-gate check \
  --task-contract task-contract.json \
  --check-ran "bun run build"

The contract can declare:

• allowed_paths: the file patterns the task is allowed to change.
• forbidden_paths: file patterns that should not change for this task.
• expected_artifacts: files, reports, generated outputs, or other artifacts reviewers should verify.
• invariants: deterministic rules the diff must preserve.
• required_checks: validation commands expected before handoff.

The CLI also adds two ways to tell Critical Gate which validation actually happened:

critical-gate check \
  --task-contract task-contract.json \
  --check-ran "bun run build"

or:

critical-gate check \
  --task-contract task-contract.json \
  --checks-report checks.json

--check-ran is simple and useful for local work. --checks-report is better when automation has structured check results with command names, pass/fail status, and optional exit codes.

The important design choice is that 2.8.0 does not pretend every declared contract field should immediately become a hard blocker in every repository. Some parts enforce deterministically today. Some start in observation-first mode.

That is the correct rollout posture.

The Task Contract Shape

A practical contract can be small:

{
  "goal": "Publish a Critical Gate 2.8.0 release post and update related synapses.",
  "allowed_paths": [
    "src/content/posts/**",
    "docs/critical-gate-dogfood.md",
    "docs/critical-gate-evidence/**"
  ],
  "forbidden_paths": [
    "package.json",
    "bun.lock",
    "astro.config.*",
    "Dockerfile",
    "src/styles/**"
  ],
  "expected_artifacts": [
    "src/content/posts/2026-07-10-critical-gate-2-8-task-contracts-realistic-diff-integrity.md"
  ],
  "invariants": [
    "no_new_dependencies",
    "no_config_changes"
  ],
  "required_checks": [
    "bun run build"
  ]
}

This is not a replacement for the task prompt. It is the part of the task prompt that should be checked mechanically.

The goal explains intent. The allowed and forbidden paths define scope. The expected artifact says what must exist after the task. The invariants define properties the diff should preserve. The required checks connect the final diff to validation evidence.

That structure is valuable because it separates two things that often get blurred in AI-agent workflows:

Instruction: what the agent should do.
Contract: what the final diff must prove.

Prompts guide behavior. Contracts verify artifacts.

Scope Is Now More Explicit

The most immediately enforceable part of 2.8.0 is path scope.

When a task contract declares allowed_paths, Critical Gate can flag changed files outside those patterns as scope findings. When it declares forbidden_paths, Critical Gate can flag matching files as forbidden-path changes.

That is deliberately boring, and that is why it is useful.

If a content task says only Markdown posts, dogfood evidence, and synapse metadata are in scope, then a package manifest change should not slip through as “probably fine.” If a UI copy task says styles are forbidden, then a stylesheet edit should be visible. If a small bug fix forbids runtime config, then a Dockerfile change deserves immediate attention.

This matters for AI agents because scope drift is one of their most common failure modes. The model may produce a coherent patch while also changing files the task never asked it to touch.

In 2.8.0, scope can be judged against explicit task boundaries instead of only inferred task text and repository history.

That is a stronger contract.

Required Checks Become Evidence, Not Ritual

Many handoffs say:

Tests passed.

That sentence is useful only if it says which tests, when, and whether the required checks for this task were actually run.

Critical Gate 2.8.0 starts connecting required checks to reported validation evidence. If the task contract says required_checks includes bun run build, the check can compare that requirement against --check-ran "bun run build" or an equivalent checks report.

This closes a small but important gap in agent handoffs.

The final report can now distinguish:

• the contract required a build, and the build was reported as run;
• the contract required a build, but no check evidence was provided;
• the contract required a check, but a structured report marked it as failed;
• the task did not declare required checks, so there is nothing to compare.

That does not make Critical Gate a test runner. It should not become one.

The better design is to let the normal project tools run validation, then let Critical Gate compare the declared validation contract against the evidence supplied to the gate.

Observation-First Is The Right Rollout

2.8.0 intentionally keeps required checks, expected artifacts, and invariant coverage in an observation-first posture where appropriate.

That may sound conservative, but it is the only responsible way to roll out a gate that will be used in real repositories.

Expected artifacts are not always easy to verify deterministically. A contract can say “publish the generated report,” but whether that report is semantically complete may still require human review. So Critical Gate can surface the declared artifact as a finding for reviewers instead of pretending every artifact has been fully proven.

Required checks are also tricky during rollout. A local CLI invocation may know only what the user passed with --check-ran; CI may have richer metadata; some teams may want missing check evidence to block immediately; others may want it to educate first.

Invariant coverage is similar. It is useful to say which invariants the contract requested and which detector families can enforce them. But not every invariant should be treated as perfectly covered on day one.

Observation-first rollout keeps the tool honest:

Show the contract.
Show what was checked.
Show what is only declared.
Promote blocking behavior only where evidence is deterministic enough.

That is much better than turning every new contract field into a noisy blocker.

Deterministic Invariants Matter More Than Detector Count

The most important invariants in 2.8.0 are enforced through existing deterministic detectors.

For example:

• no_new_dependencies maps to dependency discipline.
• no_config_changes maps to config-change detection.
• no_public_api_change maps to public API and framework contract checks.
• no_test_weakening maps to skipped tests, removed assertions, and weaker assertions.
• no_secret_leaks and no_environment_leaks map to secret, path, and environment-specific value detection.

This is the right architecture.

The contract should not create a parallel detector universe. It should sharpen existing detectors by giving them a clearer task boundary.

Without a contract, a config change might be suspicious if the task did not mention configuration. With a contract that explicitly says no_config_changes, the same change is no longer just suspicious. It violates a declared invariant.

Without a contract, adding a dependency can be flagged when the task does not justify it. With no_new_dependencies, dependency addition is a direct contract violation unless the contract itself is revised with reviewer approval.

That is how 2.8.0 improves precision without simply adding more warning types.

Why “More Detectors” Is Not Enough

More detectors can be useful, but detector count is not the product.

A gate becomes valuable when its findings answer practical review questions:

• Was this file allowed to change?
• Was this file explicitly forbidden?
• Did the task require an artifact that reviewers should verify?
• Did the diff preserve the invariants the task cared about?
• Did the agent run the required validation?
• If not, what exact repair should happen?

Adding detector after detector can create a wall of loosely related warnings. A task contract creates a smaller, sharper review surface.

This is especially important for AI-agent workflows. Agents do not fail only by writing bad code. They fail by doing too much, doing too little, skipping validation, changing operational files, weakening tests, or quietly modifying public contracts.

Those are task-aware failures.

A detector that ignores the task boundary can only say:

This pattern may be risky.

A detector grounded in a task contract can say:

This change violates what the task explicitly allowed.

That is a different level of usefulness.

How This Helps Agent Repair Loops

Critical Gate has always been most interesting as part of an agent repair loop.

The loop is simple:

1. A human or orchestrator gives an agent a task.
2. The agent edits the repository.
3. Normal validation runs.
4. Critical Gate checks the final diff against the task.
5. If the diff violates the contract, the agent receives scoped repair guidance.
6. The agent repairs only the relevant files.
7. The gate runs again.

Task contracts make that loop cleaner.

Instead of telling the agent “fix the review comments,” the report can point to evidence:

• package.json changed even though the task contract forbids package files.
• src/styles/post.scss changed outside allowed_paths.
• bun run build was required but not reported as run.
• A production dependency was added despite no_new_dependencies.
• A config file changed despite no_config_changes.

That is much easier for an agent to repair safely because the repair boundary is explicit. The agent does not need to infer whether it should touch package files, config files, tests, or docs. The contract already says.

This is also useful for humans. A reviewer can quickly distinguish a real contract violation from an expected companion change that the contract failed to include. If the contract was too narrow, revise it. If the diff wandered, repair the diff.

Both outcomes are better than vague review noise.

A Practical Example From This Blog

This post is a good example because it is a content-publishing task, not a synthetic fixture.

The real task boundary is narrow:

• create one new Markdown post under src/content/posts;
• update related synapses in older posts where the new post is strongly relevant;
• run the Astro build;
• export durable Critical Gate evidence;
• label the dogfood report;
• update the dogfood journal.

It should not:

• change package dependencies;
• edit the lockfile;
• modify Astro or Docker config;
• touch global styles;
• change page routing;
• rewrite unrelated content.

That maps naturally to a task contract:

{
  "goal": "Publish a Critical Gate 2.8.0 release post and update related synapses.",
  "allowed_paths": [
    "src/content/posts/**",
    "docs/critical-gate-dogfood.md",
    "docs/critical-gate-evidence/**"
  ],
  "forbidden_paths": [
    "package.json",
    "bun.lock",
    "astro.config.*",
    "Dockerfile",
    "src/styles/**"
  ],
  "expected_artifacts": [
    "src/content/posts/2026-07-10-critical-gate-2-8-task-contracts-realistic-diff-integrity.md"
  ],
  "invariants": [
    "no_new_dependencies",
    "no_config_changes"
  ],
  "required_checks": [
    "bun run build"
  ]
}

After implementation, the local workflow is:

bun run build

bun run gate -- \
  --task-contract C:/path/to/task-contract.json \
  --check-ran "bun run build"

The contract keeps the dogfood run honest. If I accidentally edit package.json, Critical Gate should flag it as a forbidden path and as a dependency/config concern depending on the diff. If I forget to report the build, the required-check detector should say the contract asked for validation evidence that was not supplied. If I touch a global stylesheet while writing a post, the scope detector should surface that mismatch immediately.

That is the product direction I want.

Not more theatrics.

More explicit contracts over real diffs.

What 2.8.0 Does Not Claim

It is worth being precise about what this release does not prove.

2.8.0 does not mean every task contract field is fully enforceable in every possible repository. It does not replace tests. It does not replace human review. It does not make expected artifact verification magically semantic.

It also does not turn Critical Gate into a broad AI reviewer.

The best version of the tool remains deterministic-first:

• parse the diff;
• classify changed files;
• compare the diff to task intent;
• apply repository policy and history where useful;
• enforce concrete invariants;
• report observation-mode findings where rollout is still early;
• produce repair guidance that keeps agents inside the task boundary.

The model, if used at all, should interpret compact evidence. It should not be the source of truth.

Why 2.8.0 Matters

The important shift in 2.8.0 is from “does this diff look suspicious?” toward “does this diff satisfy the explicit contract for this task?”

That is a more realistic foundation for AI-agent development.

Agents need prompts, but teams need contracts. A prompt can tell the agent what to attempt. A contract can tell the gate what the final diff must prove.

Critical Gate 2.8.0 makes that contract concrete:

• structured task boundaries through --task-contract;
• explicit allowed and forbidden path enforcement through scope findings;
• expected artifacts surfaced for reviewer verification;
• required checks compared against --check-ran or --checks-report;
• deterministic invariants enforced through existing detectors;
• observation-first rollout for areas that need more evidence before blocking.

That is better than blindly increasing detector count because it improves the question being asked.

The goal is not:

How many warnings can the tool produce?

The goal is:

Did this AI-generated diff honor the task contract?

Critical Gate 2.8.0 is a meaningful step toward that version of diff integrity.