Evaluate Your First Change

The fastest first value is a verdict on a real change. You do not need an account, an API key, or a seeded graph to get one — run the gate in --offline mode against the embedded best-practice packs and read the decision it returns.

Evaluate a diff offline

From inside a repository with an uncommitted or staged change, run:

forgecroft-gate --diff <(git diff) --offline --json

The diff never leaves your machine — --offline makes no network call and needs no key. The gate matches your changed paths against the embedded packs and returns a verdict.

Read the verdict

A completed evaluation returns one of four deterministic decisions:

• go — no Control was violated; the change is clear to merge.
• conditional_go — the change is allowed but a finding needs attention or an approval.
• no_go — a Control blocks the change. The right response is to produce a different change, not to override.
• insufficient_context — the gate could not resolve enough of your graph to judge confidently. It returns empty plus a coverage note rather than a false go.

Each finding carries a severity, a human-readable message, and a fix_hint you can act on. There is no model on this path — the same diff always returns the same verdict.

An offline go is not a hosted go. Offline checks the generic packs only; it does not consult your organization’s Controls, Exceptions, or blast radius. A change that is go offline can still be blocked by a Control in hosted mode.

Wire it into CI

Once you have seen a verdict locally, drop the gate into your pull-request flow so every change is evaluated before it merges. Copy the starter workflow from examples/forgecroft-gate.yml into your repository at .github/workflows/forgecroft-gate.yml and add a FORGECROFT_API_KEY repository secret.

See CI Gate for the full workflow, fail-open semantics, and offline mode.

Next steps

• Connect your repository — wire the gate into CI with a hosted API key so verdicts reflect your org’s Controls.
• Drive it from a coding agent — have Claude Code, Codex, or Cursor call forgecroft_evaluate mid-loop and self-correct on each fix_hint.
• Seed your system map — derive your import graph so blast-radius reflects your real code structure.
• Core Concepts — the Systems / Components / Controls model behind every verdict.