Prepare Evident v0.1.0 release

.github/workflows/evident-evidence.yml

@@ -3,6 +3,21 @@ name: Evident Evidence
 on:
   pull_request:
   workflow_dispatch:
+    inputs:
+      evidence_path:
+        description: Path to the evidence envelope.
+        required: false
+        default: evident-pr-evidence.json
+        type: string
+      validation_command:
+        description: Command to run before writing evidence.
+        required: false
+        default: ""
+        type: string
+      toolkit_ref:
+        description: Evident toolkit ref for fallback scripts. Pin to the same ref as the reusable workflow.
+        required: false
+        type: string
   workflow_call:
     inputs:
       evidence_path:
@@ -15,6 +30,10 @@ on:
         required: false
         default: ""
         type: string
+      toolkit_ref:
+        description: Evident toolkit ref for fallback scripts. Pin to the same ref as the reusable workflow.
+        required: false
+        type: string
 
 permissions:
   contents: read
@@ -39,28 +58,63 @@ jobs:
         if: ${{ inputs.validation_command }}
         run: ${{ inputs.validation_command }}
 
+      - name: Resolve Evident toolkit path
+        id: toolkit
+        if: ${{ always() }}
+        shell: bash
+        env:
+          TOOLKIT_REF: ${{ inputs.toolkit_ref || '' }}
+        run: |
+          if [ "$GITHUB_REPOSITORY" = "IntelIP/agentic-git-workflow" ]; then
+            echo "path=." >> "$GITHUB_OUTPUT"
+          elif [ -n "$TOOLKIT_REF" ]; then
+            echo "path=.evident/toolkit" >> "$GITHUB_OUTPUT"
+            echo "ref=$TOOLKIT_REF" >> "$GITHUB_OUTPUT"
+          elif [ -f scripts/write-evident-evidence-envelope.mjs ] && \
+            [ -f scripts/check-evident-evidence-envelope.mjs ] && \
+            [ -f scripts/check-evident-external-actions.mjs ]; then
+            echo "path=." >> "$GITHUB_OUTPUT"
+          else
+            echo "::error::toolkit_ref is required when Evident scripts are not vendored. Pin it to the same ref as the reusable workflow."
+            echo "path=.evident/toolkit" >> "$GITHUB_OUTPUT"
+            exit 1
+          fi
+
+      - name: Checkout Evident toolkit
+        if: ${{ always() && steps.toolkit.outputs.path == '.evident/toolkit' && steps.toolkit.outputs.ref != '' }}
+        uses: actions/checkout@v5
+        with:
+          repository: IntelIP/agentic-git-workflow
+          ref: ${{ steps.toolkit.outputs.ref }}
+          path: .evident/toolkit
+          persist-credentials: false
+
       - name: Write evidence envelope
-        if: always()
-        run: node scripts/write-evident-evidence-envelope.mjs --out "${EVIDENCE_PATH}"
+        if: ${{ always() && steps.toolkit.outcome == 'success' }}
+        run: node "${TOOLKIT_PATH}/scripts/write-evident-evidence-envelope.mjs" --out "${EVIDENCE_PATH}"
         env:
+          TOOLKIT_PATH: ${{ steps.toolkit.outputs.path }}
           EVIDENCE_PATH: ${{ inputs.evidence_path || 'evident-pr-evidence.json' }}
           EVIDENT_VALIDATION_COMMAND: ${{ inputs.validation_command || '' }}
           EVIDENT_VALIDATION_STATUS: ${{ steps.validation.outcome || 'skipped' }}
+          EVIDENT_WRITER_COMMAND: node ${{ steps.toolkit.outputs.path }}/scripts/write-evident-evidence-envelope.mjs
 
       - name: Validate evidence envelope
-        if: always()
-        run: node scripts/check-evident-evidence-envelope.mjs --evidence "${EVIDENCE_PATH}"
+        if: ${{ always() && steps.toolkit.outcome == 'success' }}
+        run: node "${TOOLKIT_PATH}/scripts/check-evident-evidence-envelope.mjs" --evidence "${EVIDENCE_PATH}"
         env:
+          TOOLKIT_PATH: ${{ steps.toolkit.outputs.path }}
           EVIDENCE_PATH: ${{ inputs.evidence_path || 'evident-pr-evidence.json' }}
 
       - name: Check external action policy
-        if: always()
-        run: node scripts/check-evident-external-actions.mjs --evidence "${EVIDENCE_PATH}"
+        if: ${{ always() && steps.toolkit.outcome == 'success' }}
+        run: node "${TOOLKIT_PATH}/scripts/check-evident-external-actions.mjs" --evidence "${EVIDENCE_PATH}"
         env:
+          TOOLKIT_PATH: ${{ steps.toolkit.outputs.path }}
           EVIDENCE_PATH: ${{ inputs.evidence_path || 'evident-pr-evidence.json' }}
 
       - name: Upload evidence artifact
-        if: always()
+        if: ${{ always() && steps.toolkit.outcome == 'success' }}
         uses: actions/upload-artifact@v4
         with:
           name: evident-pr-evidence

.gitignore

@@ -1,5 +1,6 @@
 node_modules/
 agentic-pr-evidence.json
+evident-pr-evidence.json
 .DS_Store
 .env
 .env.*

CHANGELOG.md

@@ -0,0 +1,28 @@
+# Changelog
+
+All notable changes to Evident are recorded here.
+
+## 0.1.0 - Pending Release
+
+Initial public release.
+
+### Added
+
+- Evidence envelope contract with `evident-evidence/v0.1` schema version.
+- Dependency-free Node.js writer and validators.
+- Default-deny external action policy for protected side effects.
+- Reusable GitHub Actions workflow for PR evidence checks.
+- Pull request evidence template.
+- Minimal valid evidence fixture.
+- OpenSSF Scorecard workflow.
+- Research grounding, schema reference, and workflow model docs.
+- Agentic tooling stack guide covering Code Storage, Entire, Graphite, GitHub, Codex, and Evident boundaries.
+
+### Release Gates
+
+- `npm run check`
+- script syntax checks with `node --check`
+- generated evidence validation
+- external-action policy validation
+- GitHub Actions evidence check
+- OpenSSF Scorecard run on `main`

CONTRIBUTING.md

@@ -35,6 +35,14 @@ node --check scripts/check-evident-external-actions.mjs
 node --check scripts/write-evident-evidence-envelope.mjs
 ```
 
+Check the reusable workflow syntax before release:
+
+```bash
+actionlint
+```
+
+Install `actionlint` from the official `rhysd/actionlint` release or a trusted package manager before running this command.
+
 ## Pull Requests
 
 Each PR should include:
@@ -78,3 +86,14 @@ Avoid:
 - compliance claims not implemented by code
 - long roadmap text in the README
 - burying security boundaries in prose
+
+## Release Prep
+
+Before tagging a release:
+
+- update `CHANGELOG.md`
+- confirm README examples use the intended release tag
+- run local checks
+- run workflow syntax validation
+- confirm the latest `main` Scorecard run passes
+- create the GitHub release from a clean `main` commit

README.md

@@ -7,6 +7,9 @@
 ![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)
+![Graphite](https://img.shields.io/badge/Graphite-stacked%20review-6F42C1)
+![Entire](https://img.shields.io/badge/Entire-checkpoint%20ledger-111827)
+![Code Storage](https://img.shields.io/badge/Code%20Storage-git%20substrate-0F766E)
 ![License](https://img.shields.io/badge/license-Apache--2.0-green)
 
 Evidence-backed pull request governance for agentic development.
@@ -55,9 +58,25 @@ Evident gives reviewers a repeatable answer to:
 | 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](docs/tooling-stack.md) for the full layer map and vendor-boundary notes.
+
 ## Service Modules
 
 | Module | Path | Role |
@@ -71,6 +90,29 @@ Evident gives reviewers a repeatable answer to:
 
 ## Quick Start
 
+Add Evident to another repository:
+
+```yaml
+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:
 
 ```bash
@@ -105,7 +147,7 @@ npm run evident:external-actions:check
 | `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 |
+| `docs/` | Getting started, review guidance, workflow model, schema reference, and research grounding |
 
 ## Protected Action Classes
 
@@ -124,7 +166,7 @@ The external-action checker fails when an action is marked `attempted: true` wit
 
 ## GitHub Actions
 
-Run directly on pull requests:
+Run directly on pull requests in this repository:
 
 ```yaml
 name: Evident Evidence
@@ -135,17 +177,25 @@ on:
 jobs:
   evidence:
     uses: IntelIP/agentic-git-workflow/.github/workflows/evident-evidence.yml@main
+    with:
+      toolkit_ref: main
 ```
 
-The workflow writes `evident-pr-evidence.json`, validates the envelope, checks the external-action policy, and uploads the evidence artifact.
+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](docs/getting-started.md)
+- [Agentic tooling stack](docs/tooling-stack.md)
 - [Workflow model](docs/workflow-model.md)
 - [Evidence schema](docs/evidence-schema.md)
+- [Codex review](docs/codex-review.md)
 - [Research grounding](docs/research-grounding.md)
 - [Security policy](SECURITY.md)
 - [Contributing](CONTRIBUTING.md)
+- [Changelog](CHANGELOG.md)
 
 ## Non-Goals
 
@@ -157,6 +207,6 @@ The workflow writes `evident-pr-evidence.json`, validates the envelope, checks t
 
 ## Status
 
-Current release: v0.1.0 public initial release.
+Current package version: v0.1.0. GitHub release tag pending.
 
 Evident is intentionally small: schemas, scripts, reusable workflows, examples, templates, and docs.

docs/codex-review.md

@@ -0,0 +1,46 @@
+# Codex Review
+
+Codex review is an optional review layer for Evident pull requests. It should inspect the diff and the evidence packet, not replace deterministic checks.
+
+## Local Preflight
+
+Run local review before requesting a cloud review:
+
+```bash
+CODEX_HOME=/tmp/codex-review-home codex review --base main
+```
+
+Use an isolated `CODEX_HOME` when local MCP configuration could add noise or private integrations.
+
+## Cloud Review
+
+After the PR is open and checks are current, request review in the pull request:
+
+```text
+@codex review
+```
+
+Cloud review requires the GitHub connector to be configured for the account and organization.
+
+## Review Inputs
+
+Give Codex these facts in the PR body or comments:
+
+- task source
+- intended behavior
+- evidence artifact path
+- commands run
+- known skipped checks
+- protected side effects requested or blocked
+
+## Review Boundary
+
+Codex review should flag correctness risks, missing tests, stale evidence, unsafe side effects, and unclear PR scope.
+
+Codex review should not be treated as:
+
+- branch protection
+- dependency update automation
+- deployment approval
+- substitute for human ownership
+- proof that agent output is secure