Documentation / Quality and governance

Gate and Governance Center

A single gate enforces the contract on every commit, push and pipeline, and the Governance Center brings the whole lifecycle together.

The quality contract states what the team requires. The gate enforces it. It is a single engine command used in exactly the same way by Git hooks, CI, the yuli-mcp gate command and agent hooks. The result doesn't depend on who invokes it.

The command

agent-engine gate --project <raíz> --stage pre-commit|commit-msg|pre-push|ci \
  [--message-file <archivo>] [--base <revisión>] [--format text|json]

If you omit --project, the current folder is used. A folder without Git always passes.

Exit code Meaning
0 Passes.
1 Blocked: some check failed.
2 Usage error.

What each stage checks

Stage What it compares Checks
pre-commit What is staged All of the ones below.
commit-msg The commit message Only AI attribution and waivers.
pre-push Against @{upstream} (or origin/HEAD) All of the ones below.
ci Against the PR or MR target branch (or HEAD~1) All of the ones below.

The checks

Check Label in Yuli Result
Secrets in added lines Secrets Blocks. The type and line are reported, never the value.
Cheating in tests Test integrity Blocks if the profile blocks cheating; otherwise, warns.
Change size Change size Blocks with strict enforcement; otherwise, warns.
Protected files touched Protected paths Blocks with strict enforcement; otherwise, warns.
AI attribution in messages AI attribution Checks that there is no Co-Authored-By from an AI.
Expired waivers Waivers Warns. Never blocks.
Existing code without tests Safety net Warns. Never blocks.

Test anti-cheating

An agent under pressure to finish may “fix” a test instead of the code. Yuli detects it.

In tests:

  • Removed assertions or deleted tests.
  • Skipped tests: @Disabled, @Ignore, .skip(, xit, #[ignore], pytest or unittest skips, t.Skip.
  • Trivial assertions, such as assertTrue(true) or expect(true).toBe(true).
  • Expected values changed so the test passes.
  • A catch-all catch inside a test.

In the build and CI:

  • Minimum coverage lowered.
  • Tests skipped in the build.
  • Ignored failures, such as npm test || true.
  • Test script replaced with an empty one.
  • Quality gate turned off or test task disabled.

Safety net

If existing code files change without characterization or unit tests, the gate warns you: the change must preserve behavior. It never blocks the commit.

Install the Git hooks

In the Governance Center, Gates tab, click Install hooks.

  1. Yuli writes .githooks/pre-commit, .githooks/commit-msg and .githooks/pre-push.
  2. It sets git config --local core.hooksPath .githooks.

Yuli installs nothing if core.hooksPath already points to another tool (for example, husky) or if there is a hook it didn't write. If the engine isn't available, the hook warns and lets the commit through: it never leaves you unable to commit.

Uninstall hooks removes the configuration and deletes only Yuli's scripts.

In CI

The pipelines generated by Create CI include the “Contract gates” step, which runs agent-engine gate --stage ci. That way CI applies the same rules as your local team.

The Governance Center

Open it from the right rail (More tools → Governance Center) or from the command palette: Open the Governance Center. It has 10 tabs.

Tab What it contains
Contract Criticality, thresholds, protected paths, waivers, layers, SLOs, license policy, independent reviewer, data classification, FinOps budgets and history.
Gates Run the gate for a stage, install or uninstall the hooks, and the CI card.
Sensitive data Values redacted when leaving your machine, classified fields in the code and secrets in Git history.
Analysis Requirements (EARS patterns, ambiguity, ISO 25010 attributes, Gherkin) and glossary.
Design Decisions (ADRs), Threats (STRIDE), APIs (OpenAPI), C4, SLOs and Legacy.
Measurement Architecture fitness functions, LCOM4, change coupling, bus factor, debt register, twelve-factor and feature flags.
Tests Flaky tests and quarantine, mutation, test types, race conditions and load.
Supply chain Dependencies and licenses, SBOM, IaC, containers, DAST, provenance (SLSA, cosign), CODEOWNERS and history.
Delivery CI, release, rollback, progressive deployment, runbook, post-mortems, DORA, SPACE, builds and FinOps.
Agents Context, Review, Telemetry, Learning, Benchmark and Injection.

Documents it generates

Document Path
ADRs (architecture decisions) docs/architecture/adr/
STRIDE threat model docs/architecture/threat-model.md
C4 diagrams docs/architecture/c4.md
SBOM docs/reports/sbom.cdx.json and docs/reports/sbom.spdx.json
Runbook docs/operations/runbook.md
Post-mortems docs/operations/postmortems/

DORA

The Delivery tab computes the four DORA metrics: deployment frequency, lead time, change failure rate and MTTR, with the Elite, High, Medium and Low bands. It uses recorded deployments or CI. Yuli doesn't see a production APM.

Independent review

A model from another family reviews the change. It never uses the same family as the model that wrote it. If none is configured, it is shown as unavailable. It is mandatory in the Regulated and Safety-critical profiles.

Context for all agents

Under Agents → Context, the “Context for all agents” section writes the same rules for each tool:

Target File
Claude Code (CLAUDE.md) .claude/CLAUDE.md
AGENTS.md (Codex and others) AGENTS.md
Kiro (.kiro/steering) .kiro/steering/yuli.md
Antigravity .agent/rules/yuli.md
Cursor (.cursor/rules) .cursor/rules/yuli.mdc
GitHub Copilot .github/copilot-instructions.md
Gemini (GEMINI.md) GEMINI.md

The content goes in a managed block; anything you write outside it is preserved. By default the files are kept out of Git; turn that on with Version them in Git. Each target shows its status: Up to date, Outdated, Does not exist or Edited by hand.

Learned rules

When the same finding appears 3 or more times across at least 2 tasks within 30 days, it becomes a rule in .ai/rules/learned.md. You can reject it under Agents → Learning; it is only proposed again if its evidence doubles.

Honest limits

  • DAST (OWASP ZAP), container scanning (Trivy or Grype) and signing (cosign) only run if they are installed, and always with confirmation. If they are missing, Yuli says so and doesn't simulate the result.
  • Preventive and IaC rules are text patterns. Each finding includes its file and line so a person can confirm it.