Evident

Evidence-backed pull request governance for agentic development.

Copyright 2026 IntelIP. Licensed under Apache-2.0.

Overview

Evident is a lightweight workflow layer for AI-assisted code changes.

It does not write code. It makes code written by agents, humans, or mixed workflows easier to review by attaching a structured evidence packet to each pull request.

What Evident Captures

Area	Evidence
Task	Source request, issue, ticket, or manual prompt summary
Git	Repository, base branch, head branch, commit SHA, PR metadata
Runtime	Human, CI, or agent runtime that produced the change
Diff	Changed files
Validation	Commands run and check results
Approvals	Required, granted, denied, or skipped approvals
Side effects	Deployment, migration, infra, billing, secret, provider, and destructive-action policy
Artifacts	Evidence files generated by the run

Why Teams Use It

AI-assisted pull requests should not depend on reviewer trust alone.

Evident gives reviewers a repeatable answer to:

• What changed?
• Why did it change?
• What commands ran?
• What failed or was skipped?
• Did the workflow try to deploy, migrate, read secrets, touch billing, or mutate infrastructure?
• Where is the machine-readable audit packet?

Stack Tags

Layer	Stack
Runtime	Node.js 20+
CI	GitHub Actions
Evidence contract	JSON Schema
Security signal	OpenSSF Scorecard
Code scanning output	SARIF
Review surface	GitHub Pull Requests
Stacked review	Graphite or Graphite-like PR stacks
Checkpoint ledger	Entire or compatible Git-backed session ledger
Git substrate	GitHub today; Code Storage-compatible machine Git layer
Agent review	Codex review, when configured
Governance model	Default-deny external action policy
Prior-art alignment	SLSA-inspired, in-toto-inspired

Agentic Tooling Context

Evident is the evidence gate in a larger agentic Git stack:

• Code Storage-style substrate for machine-first Git repositories, branches, and code state
• Entire-style checkpoint ledger for agent session context and why-traceability
• Graphite-style stacked PR workflow for small dependent changes
• GitHub Pull Requests and GitHub Actions for review, checks, and artifacts
• Codex review as an optional agentic review layer

See Agentic tooling stack for the full layer map and vendor-boundary notes.

Service Modules

Module	Path	Role
Evidence writer	scripts/write-evident-evidence-envelope.mjs	Generates evident-pr-evidence.json from Git and CI context
Envelope validator	scripts/check-evident-evidence-envelope.mjs	Validates required evidence fields
External-action guard	scripts/check-evident-external-actions.mjs	Fails unapproved protected side-effect attempts
PR evidence workflow	.github/workflows/evident-evidence.yml	Runs evidence checks on pull requests
Scorecard workflow	.github/workflows/scorecard.yml	Runs non-gating OpenSSF Scorecard scans
PR template	.github/pull_request_template.md	Puts evidence summary in front of reviewers

Quick Start

Add Evident to another repository:

name: Evident Evidence

on:
  pull_request:

permissions:
  contents: read
  actions: read

jobs:
  evidence:
    uses: IntelIP/agentic-git-workflow/.github/workflows/[email protected]
    with:
      # Replace with the repository's normal validation command.
      validation_command: npm test
      toolkit_ref: v0.1.0

toolkit_ref is required when the consumer repository does not vendor the Evident scripts. In consumer repositories, setting it forces the workflow to use the pinned Evident toolkit instead of PR-controlled local scripts. Pin it to the same release tag or SHA as the reusable workflow. Before the first release tag exists, use main instead of v0.1.0.

Validate the bundled fixture:

node scripts/check-evident-evidence-envelope.mjs --evidence examples/evident-evidence/minimal-evidence.json
node scripts/check-evident-external-actions.mjs --evidence examples/evident-evidence/minimal-evidence.json

Generate evidence from the current Git state:

node scripts/write-evident-evidence-envelope.mjs --out evident-pr-evidence.json
node scripts/check-evident-evidence-envelope.mjs --evidence evident-pr-evidence.json
node scripts/check-evident-external-actions.mjs --evidence evident-pr-evidence.json

Package scripts:

npm run check
npm run evident:evidence:write
npm run evident:evidence:check
npm run evident:external-actions:check

Repository Layout

Path	Purpose
.github/workflows/evident-evidence.yml	Reusable evidence workflow for PRs
.github/workflows/scorecard.yml	Non-gating OpenSSF Scorecard scan
schemas/	Evidence and external-action JSON schemas
scripts/	Dependency-free writer and validators
examples/	Minimal valid evidence fixture
templates/	PR template for evidence-backed review
docs/	Getting started, review guidance, workflow model, schema reference, and research grounding

Protected Action Classes

These actions require explicit approval before attempted execution:

• deployment
• database migration
• infrastructure change
• DNS or hosting change
• billing or live-money action
• credentialed provider read
• secret-value read
• destructive workspace action

The external-action checker fails when an action is marked attempted: true without approved: true.

GitHub Actions

Run directly on pull requests in this repository:

name: Evident Evidence

on:
  pull_request:

jobs:
  evidence:
    uses: IntelIP/agentic-git-workflow/.github/workflows/evident-evidence.yml@main
    with:
      toolkit_ref: main

For consumer repositories that use fallback toolkit checkout, pin both the workflow ref and toolkit_ref to the same release tag.

The workflow runs the repository validation command first, then writes evident-pr-evidence.json, validates the envelope, checks the external-action policy, and uploads the evidence artifact.

Docs

• Getting started
• Agentic tooling stack
• Workflow model
• Evidence schema
• Codex review
• Research grounding
• Security policy
• Contributing
• Changelog

Non-Goals

• no autonomous deployment
• no replacement for human review
• no secret access
• no provider-specific production workflow in core
• no SLSA or in-toto compliance claim yet

Status

Current package version: v0.1.0. GitHub release tag pending.

Evident is intentionally small: schemas, scripts, reusable workflows, examples, templates, and docs.