diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index d9d2f17..7086a7e 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,4 +1,4 @@ -## Agentic Git Evidence +## Evident Evidence - [ ] Evidence envelope generated - [ ] Evidence envelope validated @@ -11,7 +11,7 @@ Evidence summary: ```json { - "schemaVersion": "agentic-git-evidence/v0.1", + "schemaVersion": "evident-evidence/v0.1", "runId": "", "baseRef": "", "headRef": "", diff --git a/.github/workflows/agentic-evidence.yml b/.github/workflows/evident-evidence.yml similarity index 61% rename from .github/workflows/agentic-evidence.yml rename to .github/workflows/evident-evidence.yml index b3299ee..c983728 100644 --- a/.github/workflows/agentic-evidence.yml +++ b/.github/workflows/evident-evidence.yml @@ -1,4 +1,4 @@ -name: Agentic Git Evidence +name: Evident Evidence on: pull_request: @@ -8,7 +8,7 @@ on: evidence_path: description: Path to the evidence envelope. required: false - default: agentic-pr-evidence.json + default: evident-pr-evidence.json type: string validation_command: description: Command to run before writing evidence. @@ -21,18 +21,18 @@ permissions: jobs: evidence: - name: Agentic evidence + name: Evident evidence runs-on: ubuntu-latest steps: - name: Checkout - uses: actions/checkout@v4 + uses: actions/checkout@v5 with: fetch-depth: 0 - name: Setup Node uses: actions/setup-node@v4 with: - node-version: "24" + node-version: "20" - name: Optional validation command id: validation @@ -41,27 +41,27 @@ jobs: - name: Write evidence envelope if: always() - run: node scripts/write-agentic-evidence-envelope.mjs --out "${EVIDENCE_PATH}" + run: node scripts/write-evident-evidence-envelope.mjs --out "${EVIDENCE_PATH}" env: - EVIDENCE_PATH: ${{ inputs.evidence_path || 'agentic-pr-evidence.json' }} - AGENTIC_VALIDATION_COMMAND: ${{ inputs.validation_command || '' }} - AGENTIC_VALIDATION_STATUS: ${{ steps.validation.outcome || 'skipped' }} + EVIDENCE_PATH: ${{ inputs.evidence_path || 'evident-pr-evidence.json' }} + EVIDENT_VALIDATION_COMMAND: ${{ inputs.validation_command || '' }} + EVIDENT_VALIDATION_STATUS: ${{ steps.validation.outcome || 'skipped' }} - name: Validate evidence envelope if: always() - run: node scripts/check-agentic-evidence-envelope.mjs --evidence "${EVIDENCE_PATH}" + run: node scripts/check-evident-evidence-envelope.mjs --evidence "${EVIDENCE_PATH}" env: - EVIDENCE_PATH: ${{ inputs.evidence_path || 'agentic-pr-evidence.json' }} + EVIDENCE_PATH: ${{ inputs.evidence_path || 'evident-pr-evidence.json' }} - name: Check external action policy if: always() - run: node scripts/check-agentic-external-actions.mjs --evidence "${EVIDENCE_PATH}" + run: node scripts/check-evident-external-actions.mjs --evidence "${EVIDENCE_PATH}" env: - EVIDENCE_PATH: ${{ inputs.evidence_path || 'agentic-pr-evidence.json' }} + EVIDENCE_PATH: ${{ inputs.evidence_path || 'evident-pr-evidence.json' }} - name: Upload evidence artifact if: always() uses: actions/upload-artifact@v4 with: - name: agentic-pr-evidence - path: ${{ inputs.evidence_path || 'agentic-pr-evidence.json' }} + name: evident-pr-evidence + path: ${{ inputs.evidence_path || 'evident-pr-evidence.json' }} diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2c6fcc3..aabf9be 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,6 +1,6 @@ # Contributing -## Development Principles +## Principles Keep the workflow: @@ -9,38 +9,41 @@ Keep the workflow: - dependency-light - deterministic before AI-assisted - default-deny for external side effects -- clear about what is evidence and what is only a claim +- clear about evidence versus claims ## Local Checks -Run: +Run the full local check: ```bash -node scripts/check-agentic-evidence-envelope.mjs --evidence examples/agentic-evidence/minimal-evidence.json -node scripts/check-agentic-external-actions.mjs --evidence examples/agentic-evidence/minimal-evidence.json -node scripts/write-agentic-evidence-envelope.mjs --out /tmp/agentic-pr-evidence.json -node scripts/check-agentic-evidence-envelope.mjs --evidence /tmp/agentic-pr-evidence.json -node scripts/check-agentic-external-actions.mjs --evidence /tmp/agentic-pr-evidence.json +npm run check ``` -When package scripts are available: +Generate and validate a fresh evidence packet: ```bash -bun run agentic:evidence:example:check -bun run agentic:evidence:write -bun run agentic:evidence:check -bun run agentic:external-actions:check +node scripts/write-evident-evidence-envelope.mjs --out /tmp/evident-pr-evidence.json +node scripts/check-evident-evidence-envelope.mjs --evidence /tmp/evident-pr-evidence.json +node scripts/check-evident-external-actions.mjs --evidence /tmp/evident-pr-evidence.json ``` -## Pull Request Expectations +Check script syntax: + +```bash +node --check scripts/check-evident-evidence-envelope.mjs +node --check scripts/check-evident-external-actions.mjs +node --check scripts/write-evident-evidence-envelope.mjs +``` + +## Pull Requests Each PR should include: -- evidence envelope path +- evidence envelope path or artifact - commands run - check result summary - external-action policy summary -- explicit note for any skipped checks +- skipped-check notes, if any Do not include: @@ -50,25 +53,28 @@ Do not include: - provider account data - unredacted credentials -## External Action Changes - -Changes that weaken approval requirements need extra review. +## Sensitive Changes -Examples: +Ask for extra review when changing: -- marking an external action as approved by default -- removing a required action class -- allowing attempted action without approval -- hiding failed checks -- making evidence optional for agentic PRs +- required evidence fields +- required action classes +- default-deny behavior +- approval handling +- CI workflow permissions +- SARIF or security reporting ## Documentation Style -Use direct wording. Separate: +Prefer: + +- short sections +- tables for comparisons +- code blocks for commands +- direct current-state wording -- current behavior -- planned behavior -- non-goals -- security boundary +Avoid: -Avoid compliance claims unless the implementation directly satisfies the referenced standard. +- compliance claims not implemented by code +- long roadmap text in the README +- burying security boundaries in prose diff --git a/NOTICE b/NOTICE index 4235803..914d98d 100644 --- a/NOTICE +++ b/NOTICE @@ -1,4 +1,4 @@ -Agentic Git Workflow +Evident Copyright 2026 IntelIP -This product includes software developed for the Agentic Git Workflow project. +This product includes software developed for the Evident project. diff --git a/README.md b/README.md index 4dbd883..c1538bf 100644 --- a/README.md +++ b/README.md @@ -1,97 +1,115 @@ -# Agentic Git Workflow +# Evident + +![Evident product overview](docs/assets/evident-hero.png) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/IntelIP/agentic-git-workflow/badge)](https://scorecard.dev/viewer/?uri=github.com/IntelIP/agentic-git-workflow) +![Node.js](https://img.shields.io/badge/Node.js-%3E%3D20-339933?logo=node.js&logoColor=white) +![GitHub Actions](https://img.shields.io/badge/GitHub%20Actions-CI-2088FF?logo=githubactions&logoColor=white) +![JSON Schema](https://img.shields.io/badge/JSON%20Schema-evidence%20contract-0B6BFF) +![SARIF](https://img.shields.io/badge/SARIF-code%20scanning-2563EB) +![License](https://img.shields.io/badge/license-Apache--2.0-green) + +Evidence-backed pull request governance for agentic development. Copyright 2026 IntelIP. Licensed under Apache-2.0. -Evidence-backed pull request workflow for agentic development. +## 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 | -Agentic Git Workflow is not a coding agent. It is a Git governance layer around coding agents, human developers, and CI. It makes agent-assisted changes easier to review by requiring structured evidence, deterministic checks, default-deny external action gates, and merge-queue-compatible pull request discipline. +## Why Teams Use It -## Why +AI-assisted pull requests should not depend on reviewer trust alone. -AI-assisted code changes need more than a generated diff. Reviewers need to know: +Evident gives reviewers a repeatable answer to: -- what task produced the change -- what files changed -- which commands ran -- which checks passed or failed -- whether deployment, migration, infrastructure, billing, live-money, credentialed provider, secret, or destructive actions were attempted -- what evidence artifact can be inspected later +- 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? -This project packages that evidence contract as reusable docs, schemas, scripts, templates, and GitHub Actions workflow. +## Stack Tags -## What It Provides +| 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 | +| Governance model | Default-deny external action policy | +| Prior-art alignment | SLSA-inspired, in-toto-inspired | -- evidence envelope schema -- external action policy schema -- dependency-free evidence validator -- dependency-free external action checker -- dependency-free evidence writer -- reusable GitHub Actions workflow -- pull request template -- minimal fixture for local testing -- research grounding and OSS readiness docs +## 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 -Validate the bundled example: +Validate the bundled fixture: ```bash -node scripts/check-agentic-evidence-envelope.mjs --evidence examples/agentic-evidence/minimal-evidence.json -node scripts/check-agentic-external-actions.mjs --evidence examples/agentic-evidence/minimal-evidence.json +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: ```bash -node scripts/write-agentic-evidence-envelope.mjs --out agentic-pr-evidence.json -node scripts/check-agentic-evidence-envelope.mjs --evidence agentic-pr-evidence.json -node scripts/check-agentic-external-actions.mjs --evidence agentic-pr-evidence.json +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 ``` -Use package scripts when available: +Package scripts: ```bash -bun run agentic:evidence:example:check -bun run agentic:evidence:write -bun run agentic:evidence:check -bun run agentic:external-actions:check -``` - -## Core Model - -Every agentic pull request should produce one evidence envelope: - -```json -{ - "schemaVersion": "agentic-git-evidence/v0.1", - "runId": "local-example-001", - "repo": "example/agentic-git-workflow", - "git": { - "baseRef": "main", - "headRef": "agentic/example-evidence", - "sha": "0000000000000000000000000000000000000000" - }, - "changedFiles": ["README.md"], - "commandsRun": [], - "checks": [], - "externalActionPolicy": { - "defaultMode": "deny", - "actionClasses": [] - } -} +npm run check +npm run evident:evidence:write +npm run evident:evidence:check +npm run evident:external-actions:check ``` -The full contract lives in: +## Repository Layout -- `schemas/evidence-envelope.schema.json` -- `schemas/external-action-policy.schema.json` -- `docs/evidence-schema.md` +| 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/` | Workflow model, schema reference, and research grounding | -## Default-Deny External Actions +## Protected Action Classes -These action classes require explicit approval before attempted execution: +These actions require explicit approval before attempted execution: - deployment - database migration @@ -102,44 +120,43 @@ These action classes require explicit approval before attempted execution: - secret-value read - destructive workspace action -The checker fails when an action is marked `attempted: true` without `approved: true`. +The external-action checker fails when an action is marked `attempted: true` without `approved: true`. ## GitHub Actions -The reusable workflow lives at: +Run directly on pull requests: -```text -.github/workflows/agentic-evidence.yml -``` +```yaml +name: Evident Evidence -It can be run directly on pull requests or called from another workflow through `workflow_call`. +on: + pull_request: -## Prior Art +jobs: + evidence: + uses: IntelIP/agentic-git-workflow/.github/workflows/evident-evidence.yml@main +``` -This project is inspired by: +The workflow writes `evident-pr-evidence.json`, validates the envelope, checks the external-action policy, and uploads the evidence artifact. -- SLSA provenance -- in-toto supply-chain step metadata -- GitHub merge queues -- Graphite stacked pull requests -- Google Tricorder-style review-time static analysis -- OpenSSF Scorecard -- Inspect AI and other repeatable eval frameworks -- OpenTelemetry-style observable runtime events +## Docs -See `docs/research-grounding.md`. +- [Workflow model](docs/workflow-model.md) +- [Evidence schema](docs/evidence-schema.md) +- [Research grounding](docs/research-grounding.md) +- [Security policy](SECURITY.md) +- [Contributing](CONTRIBUTING.md) ## Non-Goals - no autonomous deployment - no replacement for human review -- no claim of SLSA compliance -- no claim of in-toto verification - no secret access -- no provider-specific production workflow in core v0 +- no provider-specific production workflow in core +- no SLSA or in-toto compliance claim yet ## Status -Current state: v0.1.0 public initial release. +Current release: v0.1.0 public initial release. -This package is intentionally small: schemas, scripts, workflow templates, docs, and examples. Product-specific app code and provider workflows are outside the core. +Evident is intentionally small: schemas, scripts, reusable workflows, examples, templates, and docs. diff --git a/SECURITY.md b/SECURITY.md index a4cb22b..2eed6bd 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,9 +2,9 @@ ## Supported Versions -This project is currently pre-release. Security reports should target the latest `main` branch until versioned releases exist. +Security reports should target the latest `main` branch until versioned maintenance branches exist. -## Reporting a Vulnerability +## Reporting Report security issues privately to the project maintainer before public disclosure. @@ -19,37 +19,38 @@ Do not include live secrets, credentials, private keys, tokens, or account data ## Security Model -Agentic Git Workflow assumes generated code and agent claims are untrusted until validated by deterministic checks. +Evident assumes generated code and agent claims are untrusted until deterministic checks validate the evidence packet. -The default security posture: +Default posture: -- evidence is explicit and machine-readable -- external action classes are default-deny -- deployment, migration, infrastructure, DNS, hosting, billing, live-money, credentialed provider reads, secret-value reads, and destructive workspace actions require explicit approval -- evidence checks should run in CI before review and merge -- merge queues or branch protection should keep main protected +| Area | Policy | +| --- | --- | +| Evidence | Machine-readable and reviewable | +| External actions | Default-deny | +| Secret values | Must not be read or logged | +| Provider access | Credentialed reads require explicit approval | +| Dangerous operations | Deploy, migration, infra, DNS, billing, live-money, and destructive actions require explicit approval | +| CI | Evidence checks run before merge review decisions | -## Out of Scope for v0 +## Out Of Scope -The v0 workflow does not claim: +v0.1.0 does not claim: - SLSA compliance - in-toto verification -- cryptographic signing of evidence +- cryptographic evidence signing - complete supply-chain protection - autonomous production safety -These can be added later, but v0 should describe itself as SLSA- and in-toto-inspired. +Current claim: SLSA- and in-toto-inspired evidence for AI-assisted pull requests. ## Maintainer Checklist -Before publishing a release: +Before release: - run private-name scan - run secret scan -- confirm no local absolute paths remain -- confirm no private session ids remain -- confirm no provider account context remains - validate example evidence - validate generated evidence -- verify external action checker blocks attempted unapproved actions +- verify unapproved attempted external actions fail +- verify Scorecard workflow passes diff --git a/docs/assets/evident-hero.png b/docs/assets/evident-hero.png new file mode 100644 index 0000000..156f71b Binary files /dev/null and b/docs/assets/evident-hero.png differ diff --git a/docs/evidence-schema.md b/docs/evidence-schema.md index cd76828..a73e477 100644 --- a/docs/evidence-schema.md +++ b/docs/evidence-schema.md @@ -1,112 +1,50 @@ # Evidence Schema -The evidence envelope is the core public contract for Agentic Git Workflow. +The evidence envelope is the core Evident contract. -Schema file: +Schema files: -```text -schemas/evidence-envelope.schema.json -``` - -External action policy schema: +- `schemas/evidence-envelope.schema.json` +- `schemas/external-action-policy.schema.json` -```text -schemas/external-action-policy.schema.json -``` - -## Required Fields +## Required Envelope Fields | Field | Purpose | | --- | --- | -| `schemaVersion` | Versioned evidence contract. Current value: `agentic-git-evidence/v0.1`. | -| `runId` | Unique id for the evidence-producing run. | -| `repo` | Repository name. | -| `git` | Base ref, head ref, commit SHA, and optional PR metadata. | -| `actor` | Human, agent, CI, or system identity that produced evidence. | -| `agentRuntime` | Runtime/tooling metadata. | -| `taskSource` | Why work started. | -| `changedFiles` | Files changed by the PR or local run. | -| `commandsRun` | Commands executed and their statuses. | -| `checks` | Higher-level validation results. | -| `approvals` | Approval status by action class. | -| `externalActionPolicy` | Default-deny side-effect policy. | -| `artifacts` | Evidence artifacts produced by the run. | -| `createdAt` | Creation timestamp. | - -## Minimal Example - -```json -{ - "schemaVersion": "agentic-git-evidence/v0.1", - "runId": "local-example-001", - "repo": "example/agentic-git-workflow", - "git": { - "baseRef": "main", - "headRef": "agentic/example-evidence", - "sha": "0000000000000000000000000000000000000000" - }, - "actor": { - "type": "agent", - "id": "codex-local" - }, - "agentRuntime": { - "name": "codex" - }, - "taskSource": { - "type": "chat", - "summary": "Create a minimal evidence fixture." - }, - "changedFiles": ["README.md"], - "commandsRun": [], - "checks": [], - "approvals": [], - "externalActionPolicy": { - "defaultMode": "deny", - "actionClasses": [] - }, - "artifacts": [], - "createdAt": "2026-07-02T00:00:00.000Z" -} -``` - -## Command Status - -`commandsRun[].status` values: - -- `passed` -- `failed` -- `skipped` - -Skipped commands should include enough context for reviewers to decide whether the PR can proceed. - -## Check Status - -`checks[].status` values: - -- `passed` -- `failed` -- `skipped` -- `pending` - -`pending` is acceptable while a workflow runs. It should not be treated as merge-ready. - -## Approval Status - -`approvals[].status` values: - -- `not_required` -- `required` -- `approved` -- `denied` +| `schemaVersion` | Contract version. Current value: `evident-evidence/v0.1` | +| `runId` | Unique evidence run id | +| `repo` | Repository name | +| `git` | Base ref, head ref, SHA, optional PR metadata | +| `actor` | Human, agent, CI, or system identity | +| `agentRuntime` | Runtime/tooling metadata | +| `taskSource` | Why work started | +| `changedFiles` | Files changed by the PR or local run | +| `commandsRun` | Commands executed and their statuses | +| `checks` | Higher-level validation results | +| `approvals` | Approval status by action class | +| `externalActionPolicy` | Default-deny side-effect policy | +| `artifacts` | Evidence artifacts produced by the run | +| `createdAt` | Creation timestamp | + +## Minimal Valid Fixture + +The smallest maintained valid fixture lives at `examples/evident-evidence/minimal-evidence.json`. + +Use that fixture instead of copying a shortened shape: the validators require at least one command, one check, and the complete default-deny action-class set. + +## Status Values + +| Field | Allowed Values | +| --- | --- | +| `commandsRun[].status` | `passed`, `failed`, `skipped` | +| `checks[].status` | `passed`, `failed`, `skipped`, `pending` | +| `approvals[].status` | `not_required`, `required`, `approved`, `denied` | -Protected external actions should be `required` until explicit approval exists. +Failed and skipped checks should stay visible. A failing evidence packet is better than a missing one. ## External Action Policy -`externalActionPolicy.defaultMode` must be: - -- `deny` -- `default-deny` +`externalActionPolicy.defaultMode` must be `deny` or `default-deny`. Required action classes: @@ -121,32 +59,32 @@ Required action classes: Each action class requires: -- `requiresExplicitApproval: true` -- `approved` -- `attempted` -- `expectedSideEffects` -- `forbiddenSideEffects` -- `verificationCommand` +| Field | Rule | +| --- | --- | +| `requiresExplicitApproval` | Must be `true` | +| `approved` | Boolean approval state | +| `attempted` | Boolean execution-attempt state | +| `expectedSideEffects` | Array | +| `forbiddenSideEffects` | Non-empty array | +| `verificationCommand` | Non-empty string | The checker fails when `attempted: true` and `approved !== true`. -## Validation - -Validate an existing file: +## Validation Commands ```bash -node scripts/check-agentic-evidence-envelope.mjs --evidence agentic-pr-evidence.json -node scripts/check-agentic-external-actions.mjs --evidence agentic-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 ``` Generate and validate: ```bash -node scripts/write-agentic-evidence-envelope.mjs --out agentic-pr-evidence.json -node scripts/check-agentic-evidence-envelope.mjs --evidence agentic-pr-evidence.json -node scripts/check-agentic-external-actions.mjs --evidence agentic-pr-evidence.json +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 ``` ## Boundary -This schema is intentionally simpler than SLSA provenance or in-toto link metadata. It can later export to those formats, but v0 should not claim compliance. +This schema is simpler than SLSA provenance or in-toto link metadata. Future versions can export to those formats, but v0.1.0 does not claim compliance. diff --git a/docs/research-grounding.md b/docs/research-grounding.md index 761f0ba..7618ad3 100644 --- a/docs/research-grounding.md +++ b/docs/research-grounding.md @@ -1,216 +1,75 @@ -# Agentic Git Research Grounding +# Evident Research Grounding -Purpose: ground the agentic Git workflow in proven software-delivery patterns before extracting it as an open-source project. +Evident combines proven software-delivery patterns for AI-assisted pull requests. -This workflow should not be positioned as "AI writes code and we trust it." The stronger position is: agent-assisted changes become reviewable, auditable, replayable, and merge-safe through existing Git, CI, provenance, eval, and observability practices. +It does not introduce a new security standard. It applies existing ideas from provenance, code review, merge queues, static analysis, evals, and observability. ## Thesis -Agentic Git is a control plane for AI-assisted software changes: +Agentic development should stay Git-native: -1. Break work into small stacked pull requests. -2. Attach machine-readable evidence to every pull request. -3. Run deterministic checks before human review. -4. Require explicit approval before deploys, migrations, live-provider actions, billing changes, or other external side effects. -5. Merge only through protected queues after evidence is current. -6. Evaluate agent behavior over time, not only single PR output. -7. Keep a readable ledger for humans and a structured ledger for tools. +1. Keep changes small. +2. Record machine-readable evidence. +3. Run deterministic checks. +4. Default-deny external side effects. +5. Review through normal pull requests. +6. Merge only after current checks pass. -The public project should package this as a workflow layer around GitHub, Graphite or merge queues, and local/CI validation. The agent is optional. The evidence contract is the product. +The agent is optional. The evidence contract is the product. -## Prior Art +## Prior Art Map -| Prior art | Source | Relevant lesson | Agentic Git implication | -| --- | --- | --- | --- | -| Supply-chain provenance | [SLSA Build provenance](https://slsa.dev/spec/draft/build-provenance), [SLSA levels](https://slsa.dev/spec/v1.0/levels) | Provenance records where, when, how, and from what inputs an artifact was produced. Higher levels add stronger integrity guarantees. | A PR needs evidence about prompt/task source, model/tool runner, touched files, validation commands, approvals, and merge state. | -| Step-level supply-chain metadata | [in-toto](https://in-toto.io/), [in-toto getting started](https://in-toto.io/docs/getting-started/) | Supply chains can be described as signed steps with materials and products. | Agentic changes should emit step records: plan, edit, test, review, approval, merge. | -| Merge queues | [GitHub merge queue docs](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue) | Queues protect busy branches by validating the merge result before landing. | Agentic PRs should land only after queue-time evidence is fresh. | -| Reusable CI workflows | [GitHub reusable workflows](https://docs.github.com/en/actions/how-tos/reuse-automations/reuse-workflows) | Shared workflow files can be called from many repositories through `workflow_call`. | Open-source package should ship a reusable `agentic-evidence.yml` workflow. | -| Stacked review | [Graphite stacked PR guidance](https://graphite.com/docs/best-practices-for-reviewing-stacks) | Stacks keep large work reviewable by splitting it into dependent PRs. | Agent output should be shaped into a stack, not one giant diff. | -| Automated analysis in review | [Google Tricorder paper](https://research.google.com/pubs/archive/43322.pdf), [Google SWE book static analysis chapter](https://abseil.io/resources/swe-book/html/ch20.html) | Static analysis works best when integrated into the review workflow and tuned for developer acceptance. | Agentic evidence should prioritize actionable, deterministic findings and avoid noisy claims. | -| Open-source security posture | [OpenSSF Scorecard](https://github.com/ossf/scorecard), [Scorecard site](https://scorecard.dev/) | Open-source projects need automated checks across code, build, dependencies, tests, and maintenance practices. | Public launch needs Scorecard, branch protection guidance, security policy, pinned actions, and dependency posture checks. | -| LLM and agent evals | [OpenAI Evals](https://github.com/openai/evals), [Inspect AI](https://inspect.aisi.org.uk/) | LLM systems need repeatable evals for task behavior, tool use, and safety properties. | Agentic Git should include evals for review-quality, retry-classification, refusal around external actions, and evidence completeness. | -| Coding agents | [SWE-agent](https://github.com/swe-agent/swe-agent), [SWE-agent docs](https://swe-agent.com/latest/) | Coding agents can operate on real GitHub repositories and issue-like tasks. | The differentiator is not another coding agent; it is the Git governance and evidence layer around any coding agent. | -| Observability | [OpenTelemetry docs](https://opentelemetry.io/docs/), [What is OpenTelemetry?](https://opentelemetry.io/docs/what-is-opentelemetry/) | Observable systems emit traces, metrics, and logs so operators can understand internal state from outputs. | Agent workflows need run traces, decision logs, check results, and reviewer-facing summaries. | - -## Current Pilot Mapping - -| Pilot primitive | Research anchor | Public OSS primitive | +| Pattern | Example Sources | What Evident Borrows | +| --- | --- | --- | +| Provenance | [SLSA](https://slsa.dev/spec/v1.0/levels), [SLSA build provenance](https://slsa.dev/spec/draft/build-provenance) | Record where work came from, what inputs existed, and which process produced the artifact | +| Supply-chain steps | [in-toto](https://in-toto.io/), [in-toto docs](https://in-toto.io/docs/getting-started/) | Treat plan, edit, test, review, and merge as auditable steps | +| Merge safety | [GitHub merge queues](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-a-merge-queue) | Validate the final merge state, not just stale local state | +| Stacked review | [Graphite stacked PRs](https://graphite.com/docs/best-practices-for-reviewing-stacks) | Split large agent work into reviewable PRs | +| Review-time analysis | [Google Tricorder](https://research.google.com/pubs/archive/43322.pdf), [Google SWE book: static analysis](https://abseil.io/resources/swe-book/html/ch20.html) | Put actionable automated checks in the review path | +| OSS health | [OpenSSF Scorecard](https://github.com/ossf/scorecard), [Scorecard](https://scorecard.dev/) | Track public repo hygiene without making it a deployment gate | +| Agent evals | [Inspect AI](https://inspect.aisi.org.uk/), [OpenAI Evals](https://github.com/openai/evals) | Test agent behavior over repeated tasks, not one-off claims | +| Coding agents | [SWE-agent](https://github.com/swe-agent/swe-agent) | Support real repository workflows while staying agent-agnostic | +| Observability | [OpenTelemetry](https://opentelemetry.io/docs/what-is-opentelemetry/) | Make runs inspectable through structured traces, logs, and artifacts | + +## Mapping To This Repo + +| Repo Primitive | Grounded By | Purpose | | --- | --- | --- | -| Agentic ledger substrate | SLSA, in-toto, OpenTelemetry | `evidence-ledger` schema and JSON examples | -| PR evidence layer | SLSA provenance, GitHub checks | `agentic-evidence.yml` reusable workflow plus PR template | -| Multi-repo rollout verifier | in-toto step metadata, merge queues | `rollout-verifier` script that checks repo, PR, and stack state | -| Deploy safety gate | Protected branches, merge queues, external-action approval | `external-action-gates` manifest and check script | -| Prediction research safety evals | OpenAI Evals, Inspect AI | `evals/` suite for agent workflow behavior | -| Chat history ledger surface | OpenTelemetry, review UX | human-readable run ledger and PR summary view | -| Graphite stack merge | Graphite stacked PRs, GitHub merge queue | stack-first workflow docs, queue-time check refresh | - -## Public Contract - -An open-source v0 should define four contracts. - -### 1. Evidence Envelope - -Minimum fields: - -- `schemaVersion` -- `runId` -- `repo` -- `baseRef` -- `headRef` -- `actor` -- `agentRuntime` -- `taskSource` -- `changedFiles` -- `commandsRun` -- `checks` -- `approvals` -- `externalActionPolicy` -- `artifacts` -- `createdAt` - -This is intentionally smaller than full SLSA or in-toto. It borrows their provenance mindset without claiming equivalent supply-chain assurance. - -### 2. External Action Policy - -Default-deny classes: - -- deployment -- database migration -- infrastructure change -- DNS or hosting change -- billing or live-money action -- credentialed provider read -- secret-value read -- destructive workspace action - -Each class needs explicit operator approval, expected side effects, forbidden side effects, and a verification command. - -### 3. PR Evidence Check - -Required outputs: - -- evidence file exists -- evidence schema validates -- changed files match evidence -- required commands ran -- external action policy present -- forbidden side effects absent -- PR body includes evidence summary - -### 4. Agent Eval Set - -Initial evals: - -- refuses deploy without approval -- refuses migration without approval -- does not read secret values -- classifies auth/credit failures as non-retryable -- produces evidence for changed files -- keeps stack PRs small -- summarizes validation failures without hiding them - -## Open-Source Repo Shape - -```text -agentic-git-workflow/ - README.md - LICENSE - SECURITY.md - docs/ - research-grounding.md - workflow-model.md - evidence-schema.md - external-action-policy.md - stacked-prs.md - oss-readiness.md - schemas/ - evidence-envelope.schema.json - external-action-policy.schema.json - scripts/ - check-evidence.mjs - check-external-actions.mjs - check-rollout-stack.mjs - .github/ - workflows/ - agentic-evidence.yml - templates/ - pull_request_template.md - approval-packet.md - evals/ - approval-boundaries/ - evidence-completeness/ - retry-classification/ - examples/ - github-actions-minimal/ - graphite-stack/ - vercel-eve-pilot-sanitized/ -``` - -## Extraction Rules - -Keep public: - -- generic evidence schema -- generic CI checks -- Graphite/GitHub workflow docs -- approval-gate model -- sanitized Eve/Vercel example -- failure-mode examples with no private context - -Keep private unless deliberately branded: - -- private business context -- domain-specific provider account details -- live trading workflow details -- local machine paths -- private session IDs and logs -- secret names that reveal private infra -- private workflow-tool internals unless deliberately branded - -## Positioning - -Avoid: - -- "Autonomous AI engineer" -- "Trust agent output" -- "One-click deploy from AI" -- "Replaces code review" - -Use: - -- "Evidence-backed PR workflow for agentic development" -- "SLSA-inspired provenance for AI-assisted code changes" -- "Stacked PR discipline for coding agents" -- "Default-deny external action gates" -- "Agent-agnostic Git governance" - -## Launch Criteria - -Before public release: - -1. Fresh repo or clean extraction branch exists. -2. Secret scan passes. -3. Private names and paths are removed or intentionally branded. -4. License chosen. -5. `SECURITY.md` explains responsible reporting and supported versions. -6. Reusable workflow works in a toy repo. -7. One Graphite or GitHub merge-queue demo PR shows evidence refresh at merge time. -8. Evals include at least one passing and one failing fixture. -9. README explains non-goals and approval boundaries. -10. OpenSSF Scorecard action is configured after repo is public. - -## First Implementation Sequence - -1. Create `docs/oss-readiness.md` and classify files as public, sanitize, or private. -2. Add `schemas/evidence-envelope.schema.json`. -3. Extract `scripts/check-evidence.mjs` from the pilot evidence check. -4. Add reusable GitHub workflow with `workflow_call`. -5. Add minimal example repo fixture. -6. Run local checks against fixture. -7. Create sanitized `examples/vercel-eve-pilot/`. -8. Open first public-prep PR with this document as evidence. +| Evidence envelope | SLSA, in-toto | Structured audit packet for PRs | +| External action policy | Security review, deployment controls | Prevent hidden deploys, migrations, secret reads, provider reads, and destructive actions | +| Evidence workflow | GitHub Actions, reusable workflows | Run evidence checks in CI | +| PR template | Code review practice | Put evidence summary in front of reviewers | +| Scorecard workflow | OpenSSF Scorecard | Track public repo health | + +## Claims We Can Make + +- Evidence-backed PR workflow for agentic development +- SLSA-inspired provenance for AI-assisted changes +- in-toto-inspired step records +- Agent-agnostic Git governance +- Default-deny external action policy +- CI-validated evidence envelope + +## Claims We Should Avoid + +- SLSA compliant +- in-toto verified +- Autonomous deployment safety +- Replacement for human review +- Guaranteed secure agent output +- Formal supply-chain security + +## Next Research-Backed Extensions + +| Extension | Why It Matters | +| --- | --- | +| Signed evidence | Improves tamper resistance | +| SLSA export | Bridges to existing supply-chain tooling | +| in-toto link export | Models each workflow step explicitly | +| OpenTelemetry spans | Makes agent runs easier to debug | +| Agent eval suite | Tests approval-boundary behavior | +| Stack metadata | Makes multi-PR agent work easier to inspect | ## Boundary -This project should not claim SLSA compliance, in-toto verification, or formal supply-chain security until it implements those specifications directly. The correct claim for v0 is "SLSA- and in-toto-inspired evidence for AI-assisted pull requests." +Current v0.1.0 is intentionally modest. It is a structured evidence and review workflow, not a formal supply-chain security implementation. diff --git a/docs/workflow-model.md b/docs/workflow-model.md index 4222ae1..59311f1 100644 --- a/docs/workflow-model.md +++ b/docs/workflow-model.md @@ -1,97 +1,93 @@ -# Workflow Model +# Evident Workflow Model -Agentic Git Workflow turns a coding-agent run into a reviewable pull request packet. +Evident turns an agentic coding run into a reviewable pull request packet. -## Objects +## Core Objects -| Object | Meaning | +| Object | Role | | --- | --- | -| Task source | Issue, chat request, ticket, manual prompt, or other source that explains why work started. | -| Agent runtime | Tooling that made or coordinated the change. This can be Codex, another coding agent, CI, or a human-operated script. | -| Evidence envelope | JSON artifact that records changed files, commands, checks, approvals, action policy, and artifacts. | -| External action policy | Default-deny list of side-effect classes that require explicit approval. | -| Pull request | Human review unit containing code plus evidence summary. | -| Stack | Ordered set of dependent PRs for larger work. | -| Merge queue | Final validation point before main changes. | - -## Flow - -1. Receive task. -2. Create a branch. -3. Make a small change. -4. Run deterministic commands. -5. Write evidence envelope. -6. Validate evidence envelope. -7. Check external action policy. -8. Open pull request with evidence summary. -9. Review as a human-readable diff plus machine-readable evidence. -10. Merge through protected queue after checks are current. +| Task source | Why the work started: issue, chat request, ticket, prompt, or manual request | +| Runtime | Human, CI process, coding agent, or mixed toolchain that produced the change | +| Evidence envelope | JSON record of Git state, changed files, commands, checks, approvals, side-effect policy, and artifacts | +| External action policy | Default-deny policy for deploys, migrations, infra, DNS, billing, secrets, provider reads, and destructive actions | +| Pull request | Human review surface for the diff plus evidence summary | +| Stack | Ordered PR chain for larger changes | +| Merge queue | Optional final validation point before main | + +## Standard Flow + +```text +task + -> branch + -> small change + -> deterministic checks + -> evidence envelope + -> evidence validation + -> external-action check + -> pull request + -> review + -> merge +``` + +## Review Packet + +Each PR should expose: + +- task source +- changed files +- commands run +- checks passed, failed, skipped, or pending +- required approvals +- external actions attempted or blocked +- evidence artifact path + +Evidence is not a claim that the work is correct. Evidence is the record reviewers inspect before trusting the work. ## Stack Discipline -Prefer stacked PRs when a task contains separate concepts: +Use stacked PRs when a task contains separate concepts: -- substrate or schema -- validation script +- schema or substrate +- validator script - workflow wiring - UI or docs - eval coverage -Each PR should be independently understandable. The evidence envelope should describe that PR, not the whole roadmap. - -## Evidence Discipline - -Evidence is not a claim that the agent did good work. Evidence is a record that reviewers can inspect: - -- files changed -- commands run -- check statuses -- approvals required -- approvals granted or denied -- side effects attempted -- artifacts produced - -Failed checks belong in evidence. A failing artifact is better than an omitted failure. +Each PR should explain only its own change. Avoid one evidence envelope that tries to justify a whole roadmap. ## External Action Discipline Default posture: no external side effects without explicit approval. -Protected action classes: - -- deployment -- database migration -- infrastructure change -- DNS or hosting change -- billing or live-money action -- credentialed provider read -- secret-value read -- destructive workspace action +Protected classes: -The workflow can document proposed side effects before approval, but it should not execute them. +| Class | Examples | +| --- | --- | +| deployment | Production deploy, hosting mutation | +| database migration | Schema or data mutation | +| infrastructure change | Cloud resource mutation | +| DNS or hosting change | DNS update, host config update | +| billing or live-money | Paid resource change, transaction | +| credentialed provider read | API call using private credentials | +| secret-value read | Reading or logging secret values | +| destructive workspace action | File deletion, force push, history rewrite | -## Review Discipline +The workflow can document planned side effects before approval. It should not execute them. -Reviewer questions: +## Reviewer Checklist - Does the task source match the diff? - Are changed files listed? - Did required commands run? - Are skipped commands explained? -- Does the external action policy still default to deny? +- Does the policy still default to deny? - Did any protected action happen without approval? - Is the PR small enough to review? -- Is the evidence current after queue-time checks? - -## Merge Discipline - -Use branch protection or merge queues. The evidence workflow should pass on the final PR state before merge. - -Do not treat stale local evidence as final merge evidence. +- Is evidence current for the final PR state? ## Extension Points -The v0 workflow stays agent-agnostic. Future integrations can add: +Future versions can add: - signed evidence - SLSA provenance export diff --git a/examples/agentic-evidence/minimal-evidence.json b/examples/evident-evidence/minimal-evidence.json similarity index 89% rename from examples/agentic-evidence/minimal-evidence.json rename to examples/evident-evidence/minimal-evidence.json index add660f..ce758ad 100644 --- a/examples/agentic-evidence/minimal-evidence.json +++ b/examples/evident-evidence/minimal-evidence.json @@ -1,10 +1,10 @@ { - "schemaVersion": "agentic-git-evidence/v0.1", + "schemaVersion": "evident-evidence/v0.1", "runId": "local-example-001", "repo": "example/agentic-git-workflow", "git": { "baseRef": "main", - "headRef": "agentic/example-evidence", + "headRef": "evident/example-evidence", "sha": "0000000000000000000000000000000000000000", "pullRequest": "1", "pullRequestUrl": "https://github.com/example/agentic-git-workflow/pull/1" @@ -20,23 +20,23 @@ }, "taskSource": { "type": "chat", - "summary": "Create a minimal evidence fixture for the Agentic Git workflow." + "summary": "Create a minimal evidence fixture for the Evident workflow." }, "changedFiles": [ "docs/research-grounding.md", "schemas/evidence-envelope.schema.json", - "scripts/check-agentic-evidence-envelope.mjs" + "scripts/check-evident-evidence-envelope.mjs" ], "commandsRun": [ { - "command": "node scripts/check-agentic-evidence-envelope.mjs --evidence examples/agentic-evidence/minimal-evidence.json", + "command": "node scripts/check-evident-evidence-envelope.mjs --evidence examples/evident-evidence/minimal-evidence.json", "status": "passed", "exitCode": 0 } ], "checks": [ { - "name": "agentic-evidence-envelope", + "name": "evident-evidence-envelope", "status": "passed", "summary": "Minimal fixture validates against v0.1 required fields and default-deny policy." } @@ -127,7 +127,7 @@ "artifacts": [ { "name": "minimal evidence fixture", - "path": "examples/agentic-evidence/minimal-evidence.json" + "path": "examples/evident-evidence/minimal-evidence.json" } ], "createdAt": "2026-07-02T00:00:00.000Z" diff --git a/package.json b/package.json index b646c2e..4c32dfe 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "agentic-git-workflow", "version": "0.1.0", - "description": "Evidence-backed pull request workflow for agentic development.", + "description": "Evident: evidence-backed pull request governance for agentic development.", "type": "module", "license": "Apache-2.0", "author": "IntelIP", @@ -15,11 +15,11 @@ }, "private": false, "scripts": { - "agentic:evidence:example:check": "node scripts/check-agentic-evidence-envelope.mjs --evidence examples/agentic-evidence/minimal-evidence.json", - "agentic:evidence:write": "node scripts/write-agentic-evidence-envelope.mjs --out agentic-pr-evidence.json", - "agentic:evidence:check": "node scripts/check-agentic-evidence-envelope.mjs --evidence agentic-pr-evidence.json", - "agentic:external-actions:check": "node scripts/check-agentic-external-actions.mjs --evidence agentic-pr-evidence.json", - "check": "npm run agentic:evidence:example:check && node scripts/check-agentic-external-actions.mjs --evidence examples/agentic-evidence/minimal-evidence.json" + "evident:evidence:example:check": "node scripts/check-evident-evidence-envelope.mjs --evidence examples/evident-evidence/minimal-evidence.json", + "evident:evidence:write": "node scripts/write-evident-evidence-envelope.mjs --out evident-pr-evidence.json", + "evident:evidence:check": "node scripts/check-evident-evidence-envelope.mjs --evidence evident-pr-evidence.json", + "evident:external-actions:check": "node scripts/check-evident-external-actions.mjs --evidence evident-pr-evidence.json", + "check": "npm run evident:evidence:example:check && node scripts/check-evident-external-actions.mjs --evidence examples/evident-evidence/minimal-evidence.json" }, "engines": { "node": ">=20" @@ -31,6 +31,11 @@ "evidence", "provenance", "ci", - "workflow" + "workflow", + "evident", + "json-schema", + "sarif", + "openssf-scorecard", + "github-actions" ] } diff --git a/schemas/evidence-envelope.schema.json b/schemas/evidence-envelope.schema.json index a515d41..11eb96a 100644 --- a/schemas/evidence-envelope.schema.json +++ b/schemas/evidence-envelope.schema.json @@ -1,7 +1,7 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://agentic-git.dev/schemas/evidence-envelope.schema.json", - "title": "Agentic Git Evidence Envelope", + "$id": "https://raw.githubusercontent.com/IntelIP/agentic-git-workflow/main/schemas/evidence-envelope.schema.json", + "title": "Evident Evidence Envelope", "type": "object", "required": [ "schemaVersion", @@ -23,7 +23,7 @@ "properties": { "schemaVersion": { "type": "string", - "const": "agentic-git-evidence/v0.1" + "const": "evident-evidence/v0.1" }, "runId": { "type": "string", diff --git a/schemas/external-action-policy.schema.json b/schemas/external-action-policy.schema.json index 8769429..fd7e90a 100644 --- a/schemas/external-action-policy.schema.json +++ b/schemas/external-action-policy.schema.json @@ -1,7 +1,7 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://agentic-git.dev/schemas/external-action-policy.schema.json", - "title": "Agentic Git External Action Policy", + "$id": "https://raw.githubusercontent.com/IntelIP/agentic-git-workflow/main/schemas/external-action-policy.schema.json", + "title": "Evident External Action Policy", "type": "object", "required": ["defaultMode", "actionClasses"], "additionalProperties": true, diff --git a/scripts/check-agentic-evidence-envelope.mjs b/scripts/check-evident-evidence-envelope.mjs similarity index 97% rename from scripts/check-agentic-evidence-envelope.mjs rename to scripts/check-evident-evidence-envelope.mjs index b6335f5..a41a397 100644 --- a/scripts/check-agentic-evidence-envelope.mjs +++ b/scripts/check-evident-evidence-envelope.mjs @@ -2,7 +2,7 @@ import { existsSync, readFileSync } from "node:fs"; import { isAbsolute, join } from "node:path"; const args = parseArgs(process.argv.slice(2)); -const evidencePath = args.evidence ?? "agentic-pr-evidence.json"; +const evidencePath = args.evidence ?? "evident-pr-evidence.json"; const root = process.cwd(); const requiredActionClasses = [ "deployment", @@ -28,7 +28,7 @@ try { const result = { ok: blockers.length === 0, - status: blockers.length === 0 ? "agentic_evidence_envelope_ready" : "blocked", + status: blockers.length === 0 ? "evident_evidence_envelope_ready" : "blocked", checkedAt: new Date().toISOString(), evidencePath, schemaPath: "schemas/evidence-envelope.schema.json", @@ -57,7 +57,7 @@ function validateEvidence(value, localBlockers, localWarnings) { return; } - stringEquals(value.schemaVersion, "agentic-git-evidence/v0.1", "schemaVersion", localBlockers); + stringEquals(value.schemaVersion, "evident-evidence/v0.1", "schemaVersion", localBlockers); requiredString(value.runId, "runId", localBlockers); requiredString(value.repo, "repo", localBlockers); requiredString(value.createdAt, "createdAt", localBlockers); diff --git a/scripts/check-agentic-external-actions.mjs b/scripts/check-evident-external-actions.mjs similarity index 98% rename from scripts/check-agentic-external-actions.mjs rename to scripts/check-evident-external-actions.mjs index 5e8c20b..0ada9aa 100644 --- a/scripts/check-agentic-external-actions.mjs +++ b/scripts/check-evident-external-actions.mjs @@ -2,7 +2,7 @@ import { existsSync, readFileSync } from "node:fs"; import { isAbsolute, join } from "node:path"; const args = parseArgs(process.argv.slice(2)); -const evidencePath = args.evidence ?? "agentic-pr-evidence.json"; +const evidencePath = args.evidence ?? "evident-pr-evidence.json"; const requiredActionClasses = [ "deployment", "database-migration", diff --git a/scripts/write-agentic-evidence-envelope.mjs b/scripts/write-evident-evidence-envelope.mjs similarity index 88% rename from scripts/write-agentic-evidence-envelope.mjs rename to scripts/write-evident-evidence-envelope.mjs index 15082cf..31f5357 100644 --- a/scripts/write-agentic-evidence-envelope.mjs +++ b/scripts/write-evident-evidence-envelope.mjs @@ -4,11 +4,11 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; import { dirname } from "node:path"; const args = parseArgs(process.argv.slice(2)); -const outPath = args.out ?? "agentic-pr-evidence.json"; +const outPath = args.out ?? "evident-pr-evidence.json"; const now = new Date().toISOString(); const changedFiles = getChangedFiles(); -const validationCommand = process.env.AGENTIC_VALIDATION_COMMAND ?? ""; -const validationStatus = normalizeStatus(process.env.AGENTIC_VALIDATION_STATUS ?? "skipped"); +const validationCommand = env("EVIDENT_VALIDATION_COMMAND"); +const validationStatus = normalizeStatus(env("EVIDENT_VALIDATION_STATUS") || "skipped"); const sha = env("GITHUB_SHA") || git(["rev-parse", "HEAD"]) || "unknown"; const baseRef = env("GITHUB_BASE_REF") || git(["rev-parse", "--abbrev-ref", "HEAD"]) || "main"; const headRef = env("GITHUB_HEAD_REF") || git(["rev-parse", "--abbrev-ref", "HEAD"]) || "HEAD"; @@ -16,7 +16,7 @@ const repo = env("GITHUB_REPOSITORY") || basename(git(["rev-parse", "--show-topl const runId = env("GITHUB_RUN_ID") || `local-${sha.slice(0, 12)}-${Date.now()}`; const evidence = { - schemaVersion: "agentic-git-evidence/v0.1", + schemaVersion: "evident-evidence/v0.1", runId, repo, git: { @@ -31,14 +31,14 @@ const evidence = { id: env("GITHUB_ACTOR") || env("USER") || "local-agent", }, agentRuntime: { - name: env("AGENTIC_RUNTIME_NAME") || "unspecified", - model: env("AGENTIC_RUNTIME_MODEL") || "", - tooling: splitCsv(env("AGENTIC_RUNTIME_TOOLING") || "git,github-actions,node"), + name: env("EVIDENT_RUNTIME_NAME") || "unspecified", + model: env("EVIDENT_RUNTIME_MODEL") || "", + tooling: splitCsv(env("EVIDENT_RUNTIME_TOOLING") || "git,github-actions,node"), }, taskSource: { - type: env("AGENTIC_TASK_SOURCE_TYPE") || "manual", - summary: env("AGENTIC_TASK_SUMMARY") || "Agentic Git evidence envelope generated from repository state.", - url: env("AGENTIC_TASK_URL") || "", + type: env("EVIDENT_TASK_SOURCE_TYPE") || "manual", + summary: env("EVIDENT_TASK_SUMMARY") || "Evident evidence envelope generated from repository state.", + url: env("EVIDENT_TASK_URL") || "", }, changedFiles, commandsRun: validationCommand @@ -52,7 +52,7 @@ const evidence = { ] : [ { - command: "node scripts/write-agentic-evidence-envelope.mjs", + command: "node scripts/write-evident-evidence-envelope.mjs", status: "passed", exitCode: 0, completedAt: now, @@ -83,7 +83,7 @@ const evidence = { }, artifacts: [ { - name: "agentic evidence envelope", + name: "Evident evidence envelope", path: outPath, }, ], @@ -97,7 +97,7 @@ writeFileSync(outPath, `${JSON.stringify(evidence, null, 2)}\n`); console.log(JSON.stringify(evidence, null, 2)); function getChangedFiles() { - const explicit = env("AGENTIC_CHANGED_FILES"); + const explicit = env("EVIDENT_CHANGED_FILES"); if (explicit) return splitCsv(explicit); const base = env("GITHUB_BASE_REF"); diff --git a/templates/pull_request_template.md b/templates/pull_request_template.md index d9d2f17..7086a7e 100644 --- a/templates/pull_request_template.md +++ b/templates/pull_request_template.md @@ -1,4 +1,4 @@ -## Agentic Git Evidence +## Evident Evidence - [ ] Evidence envelope generated - [ ] Evidence envelope validated @@ -11,7 +11,7 @@ Evidence summary: ```json { - "schemaVersion": "agentic-git-evidence/v0.1", + "schemaVersion": "evident-evidence/v0.1", "runId": "", "baseRef": "", "headRef": "",