From 46220eb96c3c98eb304a7296ce1091190bd7968c Mon Sep 17 00:00:00 2001
From: hudsonaikins-crown <hudson.aikins@blanoire.co>
Date: Tue, 7 Jul 2026 14:42:21 -0700
Subject: [PATCH 1/9] Prepare Evident v0.1.0 release

---
 .github/workflows/evident-evidence.yml       |  49 ++++++++-
 .gitignore                                   |   1 +
 CHANGELOG.md                                 |  27 +++++
 CONTRIBUTING.md                              |  19 ++++
 README.md                                    |  34 ++++++-
 docs/codex-review.md                         |  46 +++++++++
 docs/getting-started.md                      | 101 +++++++++++++++++++
 examples/github-actions/evident-consumer.yml |  16 +++
 8 files changed, 287 insertions(+), 6 deletions(-)
 create mode 100644 CHANGELOG.md
 create mode 100644 docs/codex-review.md
 create mode 100644 docs/getting-started.md
 create mode 100644 examples/github-actions/evident-consumer.yml

diff --git a/.github/workflows/evident-evidence.yml b/.github/workflows/evident-evidence.yml
index c983728..fa290eb 100644
--- a/.github/workflows/evident-evidence.yml
+++ b/.github/workflows/evident-evidence.yml
@@ -3,6 +3,22 @@ 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 to use when scripts are not vendored in the caller repo.
+        required: false
+        default: main
+        type: string
   workflow_call:
     inputs:
       evidence_path:
@@ -15,6 +31,11 @@ on:
         required: false
         default: ""
         type: string
+      toolkit_ref:
+        description: Evident toolkit ref to use when scripts are not vendored in the caller repo.
+        required: false
+        default: main
+        type: string
 
 permissions:
   contents: read
@@ -29,11 +50,30 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Checkout Evident toolkit
+        if: ${{ hashFiles('scripts/write-evident-evidence-envelope.mjs') == '' }}
+        uses: actions/checkout@v5
+        with:
+          repository: IntelIP/agentic-git-workflow
+          ref: ${{ inputs.toolkit_ref || 'main' }}
+          path: .evident/toolkit
+          persist-credentials: false
+
       - name: Setup Node
         uses: actions/setup-node@v4
         with:
           node-version: "20"
 
+      - name: Resolve Evident toolkit path
+        id: toolkit
+        shell: bash
+        run: |
+          if [ -f scripts/write-evident-evidence-envelope.mjs ]; then
+            echo "path=." >> "$GITHUB_OUTPUT"
+          else
+            echo "path=.evident/toolkit" >> "$GITHUB_OUTPUT"
+          fi
+
       - name: Optional validation command
         id: validation
         if: ${{ inputs.validation_command }}
@@ -41,22 +81,25 @@ jobs:
 
       - name: Write evidence envelope
         if: always()
-        run: node scripts/write-evident-evidence-envelope.mjs --out "${EVIDENCE_PATH}"
+        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' }}
 
       - name: Validate evidence envelope
         if: always()
-        run: node scripts/check-evident-evidence-envelope.mjs --evidence "${EVIDENCE_PATH}"
+        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}"
+        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
diff --git a/.gitignore b/.gitignore
index c9b82cc..1ca3c38 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
 node_modules/
 agentic-pr-evidence.json
+evident-pr-evidence.json
 .DS_Store
 .env
 .env.*
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..1793802
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,27 @@
+# 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.
+
+### 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`
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index aabf9be..6d4ae3e 100644
--- a/CONTRIBUTING.md
+++ b/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
diff --git a/README.md b/README.md
index c1538bf..ef336d6 100644
--- a/README.md
+++ b/README.md
@@ -71,6 +71,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/evident-evidence.yml@v0.1.0
+    with:
+      # Replace with the repository's normal validation command.
+      validation_command: npm test
+      toolkit_ref: v0.1.0
+```
+
+Before the first release tag exists, use `main` instead of `v0.1.0`.
+
 Validate the bundled fixture:
 
 ```bash
@@ -105,7 +128,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 +147,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
@@ -137,15 +160,20 @@ jobs:
     uses: IntelIP/agentic-git-workflow/.github/workflows/evident-evidence.yml@main
 ```
 
+For consumer repositories, pin both the workflow ref and `toolkit_ref` to the same release tag.
+
 The workflow 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)
 - [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 +185,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.
diff --git a/docs/codex-review.md b/docs/codex-review.md
new file mode 100644
index 0000000..8143963
--- /dev/null
+++ b/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
diff --git a/docs/getting-started.md b/docs/getting-started.md
new file mode 100644
index 0000000..bf1574e
--- /dev/null
+++ b/docs/getting-started.md
@@ -0,0 +1,101 @@
+# Getting Started
+
+Evident adds a machine-readable evidence packet to pull requests. It is agent-agnostic: humans, CI, coding agents, and mixed workflows can all produce the same review surface.
+
+## Requirements
+
+- GitHub repository
+- GitHub Actions enabled
+- Node.js 20 or later
+- Pull request review flow
+
+## Add The Reusable Workflow
+
+Create `.github/workflows/evident.yml` in the consumer repository:
+
+```yaml
+name: Evident Evidence
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  actions: read
+
+jobs:
+  evidence:
+    uses: IntelIP/agentic-git-workflow/.github/workflows/evident-evidence.yml@v0.1.0
+    with:
+      # Replace with the repository's normal validation command.
+      validation_command: npm test
+      toolkit_ref: v0.1.0
+```
+
+Use `toolkit_ref` to keep the workflow runner on the same Evident release as the reusable workflow. Before the first release tag exists, use `main` for both refs.
+
+## What The Workflow Does
+
+1. Checks out the pull request repository.
+2. Uses local Evident scripts when the repository vendors them.
+3. Otherwise checks out the Evident toolkit at `toolkit_ref`.
+4. Runs the optional validation command.
+5. Writes `evident-pr-evidence.json`.
+6. Validates the evidence envelope.
+7. Checks the default-deny external action policy.
+8. Uploads the evidence artifact.
+
+## Local Validation
+
+From this repository:
+
+```bash
+npm run 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
+```
+
+From a consumer repository that does not vendor the scripts, use the GitHub Actions workflow as the integration point.
+
+## Pull Request Copy
+
+Add the Evident checklist to the repository PR template:
+
+```markdown
+## Evident Evidence
+
+- [ ] Evidence envelope generated
+- [ ] Evidence envelope validated
+- [ ] Required commands listed with pass/fail/skipped status
+- [ ] Changed files listed
+- [ ] External action policy present
+- [ ] No protected side effect attempted without explicit approval
+```
+
+The full template lives at `templates/pull_request_template.md`.
+
+## Protected Side Effects
+
+These action classes are default-deny:
+
+- deployment
+- database migration
+- infrastructure change
+- DNS or hosting change
+- billing or live-money action
+- credentialed provider read
+- secret-value read
+- destructive workspace action
+
+If any class is marked `attempted: true`, it must also be marked `approved: true`.
+
+## First Adoption PR
+
+Keep the first PR small:
+
+1. Add the workflow file.
+2. Add the PR template checklist.
+3. Open a test pull request.
+4. Confirm `Evident evidence` passes.
+5. Confirm the uploaded artifact contains `evident-pr-evidence.json`.
diff --git a/examples/github-actions/evident-consumer.yml b/examples/github-actions/evident-consumer.yml
new file mode 100644
index 0000000..cae4045
--- /dev/null
+++ b/examples/github-actions/evident-consumer.yml
@@ -0,0 +1,16 @@
+name: Evident Evidence
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  actions: read
+
+jobs:
+  evidence:
+    uses: IntelIP/agentic-git-workflow/.github/workflows/evident-evidence.yml@v0.1.0
+    with:
+      # Replace with the repository's normal validation command.
+      validation_command: npm test
+      toolkit_ref: v0.1.0

From 716bf5ad49d69ca8cbcfa66db2c228ee8f00b2fc Mon Sep 17 00:00:00 2001
From: hudsonaikins-crown <hudson.aikins@blanoire.co>
Date: Tue, 7 Jul 2026 16:19:02 -0700
Subject: [PATCH 2/9] Document agentic tooling stack

---
 CHANGELOG.md               |  1 +
 README.md                  | 20 ++++++++++
 docs/research-grounding.md |  3 ++
 docs/tooling-stack.md      | 81 ++++++++++++++++++++++++++++++++++++++
 docs/workflow-model.md     | 10 +++++
 package.json               |  7 +++-
 6 files changed, 121 insertions(+), 1 deletion(-)
 create mode 100644 docs/tooling-stack.md

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 1793802..01cab6e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,7 @@ Initial public release.
 - 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
 
diff --git a/README.md b/README.md
index ef336d6..960fb8d 100644
--- a/README.md
+++ b/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 |
@@ -167,6 +186,7 @@ The workflow writes `evident-pr-evidence.json`, validates the envelope, checks t
 ## 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)
diff --git a/docs/research-grounding.md b/docs/research-grounding.md
index 7618ad3..ea8b2b7 100644
--- a/docs/research-grounding.md
+++ b/docs/research-grounding.md
@@ -25,6 +25,8 @@ The agent is optional. The evidence contract is the product.
 | 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 |
+| Agentic Git substrate | [Code Storage](https://code.storage/) | Treat repositories, branches, commits, patches, and code-like artifacts as machine-addressable product data |
+| Agent session ledger | [Entire](https://entire.io/), [Entire glossary](https://docs.entire.io/glossary) | Attach checkpoint and session context to code changes without making the PR body the only audit record |
 | 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 |
@@ -40,6 +42,7 @@ The agent is optional. The evidence contract is the product.
 | 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 |
+| Tooling stack guide | Code Storage, Entire, Graphite | Tag the workflow ecosystem while keeping vendor APIs outside v0.1.0 core |
 
 ## Claims We Can Make
 
diff --git a/docs/tooling-stack.md b/docs/tooling-stack.md
new file mode 100644
index 0000000..5cdd2f7
--- /dev/null
+++ b/docs/tooling-stack.md
@@ -0,0 +1,81 @@
+# Agentic Tooling Stack
+
+Evident sits in a broader agentic Git workflow. It does not replace the forge, the code storage layer, the checkpoint ledger, or stacked PR tooling. It records the evidence packet that makes those layers reviewable.
+
+## Layer Map
+
+| Layer | Tooling | Role In The Workflow | Evident Boundary |
+| --- | --- | --- | --- |
+| Work request | Issue, ticket, chat request, or manual prompt | Defines why the change exists | Captured as `taskSource` |
+| Coding runtime | Codex or another coding agent | Produces the branch, diff, and validation attempts | Captured as `actor`, `agentRuntime`, and `commandsRun` |
+| Git substrate | GitHub today; Code Storage as machine-first Git infrastructure | Stores repositories, branches, commits, patches, and agent-created code state | Captured as `repo`, `git`, and `changedFiles` |
+| Checkpoint ledger | Entire Checkpoints | Links commits to agent sessions, prompts, transcript context, token usage, and attribution | Referenced as an artifact or runtime tool, not required by core |
+| Evidence gate | Evident | Writes and validates the PR evidence envelope and external-action policy | Core product surface |
+| Stacked review | Graphite or Graphite-like stacked PR tooling | Keeps dependent PRs small, ordered, reviewable, and resubmittable | Captured through stack metadata in future versions |
+| Forge and CI | GitHub Pull Requests and GitHub Actions | Hosts review, checks, artifacts, and merge state | Current v0.1.0 integration point |
+| Repo hygiene | OpenSSF Scorecard, SARIF, static checks | Adds public health and automated review signals | Recorded as checks or artifacts |
+
+## Startup Tool Tags
+
+| Tool | Tag | Why It Matters |
+| --- | --- | --- |
+| [Code Storage](https://code.storage/) | `code-storage` | API-first Git infrastructure for machine-created repositories, branches, commits, and code-like artifacts |
+| [Entire](https://entire.io/) | `entire` | Checkpoint and session ledger for agent-assisted work, with checkpoint metadata stored in Git |
+| [Graphite](https://graphite.com/) | `graphite` | Stacked PR and code review workflow for keeping agent-produced changes reviewable |
+| [OpenAI Codex](https://openai.com/codex/) | `codex` | Coding and review agent used to produce or inspect changes |
+
+These tags describe the workflow ecosystem. Evident v0.1.0 does not call vendor APIs for Code Storage, Entire, Graphite, or Codex.
+
+## Control-Plane Shape
+
+```text
+task source
+  -> coding agent run
+  -> Git substrate branch/change set
+  -> checkpoint ledger
+  -> evidence envelope
+  -> stacked PR review
+  -> GitHub checks
+  -> explicit merge or release gate
+```
+
+The product opportunity is the control plane tying those objects together:
+
+- `AgentRun`: who or what produced the change
+- `Checkpoint`: where the session and reasoning context live
+- `ChangeSet`: what files and commits changed
+- `PatchStack`: how dependent PRs relate
+- `EvidenceEnvelope`: what was validated
+- `ReviewThread`: what humans or agents asked to fix
+- `MergeGate`: what must pass before merge
+- `ReleaseIntent`: what protected side effects require approval
+
+## Current v0.1.0 Scope
+
+Included:
+
+- GitHub Actions evidence workflow
+- evidence JSON envelope
+- default-deny external-action policy
+- local writer and validators
+- PR template and docs
+- OpenSSF Scorecard signal
+
+Not included yet:
+
+- Code Storage API integration
+- Entire checkpoint ingestion
+- Graphite stack metadata ingestion
+- Codex review automation
+- signed evidence
+- formal SLSA or in-toto compliance
+
+## Future Integration Points
+
+| Integration | Evidence Field |
+| --- | --- |
+| Code Storage repository or branch id | `git.remote`, `artifacts`, future `gitProvider` metadata |
+| Entire checkpoint id | `artifacts[]`, future `checkpoints[]` |
+| Graphite stack id or parent PR | future `stack` metadata |
+| Codex review result | `checks[]` and `artifacts[]` |
+| Plane or ticket system item | `taskSource.url` |
diff --git a/docs/workflow-model.md b/docs/workflow-model.md
index 59311f1..bef9013 100644
--- a/docs/workflow-model.md
+++ b/docs/workflow-model.md
@@ -14,6 +14,16 @@ Evident turns an agentic coding run into a reviewable pull request packet.
 | Stack | Ordered PR chain for larger changes |
 | Merge queue | Optional final validation point before main |
 
+## Tooling Layers
+
+| Layer | Example Tooling | Role |
+| --- | --- | --- |
+| Git substrate | GitHub, Code Storage | Stores repositories, branches, commits, and patch state |
+| Session ledger | Entire | Preserves checkpoint and agent-run context for later review |
+| Evidence gate | Evident | Validates commands, checks, changed files, approvals, and side-effect policy |
+| Stacked review | Graphite | Keeps related PRs small, ordered, and reviewable |
+| Agent review | Codex review | Adds optional diff and evidence review by an agent |
+
 ## Standard Flow
 
 ```text
diff --git a/package.json b/package.json
index 4c32dfe..b0f922e 100644
--- a/package.json
+++ b/package.json
@@ -36,6 +36,11 @@
     "json-schema",
     "sarif",
     "openssf-scorecard",
-    "github-actions"
+    "github-actions",
+    "stacked-pr",
+    "graphite",
+    "entire",
+    "code-storage",
+    "codex"
   ]
 }

From 5962934c24d850e1d7ab1aa8d45def4faf07d44f Mon Sep 17 00:00:00 2001
From: hudsonaikins-crown <hudson.aikins@blanoire.co>
Date: Tue, 7 Jul 2026 16:27:34 -0700
Subject: [PATCH 3/9] Harden Evident toolkit resolution

---
 .github/workflows/evident-evidence.yml | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/evident-evidence.yml b/.github/workflows/evident-evidence.yml
index fa290eb..45469af 100644
--- a/.github/workflows/evident-evidence.yml
+++ b/.github/workflows/evident-evidence.yml
@@ -51,7 +51,7 @@ jobs:
           fetch-depth: 0
 
       - name: Checkout Evident toolkit
-        if: ${{ hashFiles('scripts/write-evident-evidence-envelope.mjs') == '' }}
+        if: ${{ hashFiles('scripts/write-evident-evidence-envelope.mjs') == '' || hashFiles('scripts/check-evident-evidence-envelope.mjs') == '' || hashFiles('scripts/check-evident-external-actions.mjs') == '' }}
         uses: actions/checkout@v5
         with:
           repository: IntelIP/agentic-git-workflow
@@ -68,7 +68,9 @@ jobs:
         id: toolkit
         shell: bash
         run: |
-          if [ -f scripts/write-evident-evidence-envelope.mjs ]; then
+          if [ -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 "path=.evident/toolkit" >> "$GITHUB_OUTPUT"

From 0417c109701ad68ebb85ea7b11d7d8c9defee1e0 Mon Sep 17 00:00:00 2001
From: hudsonaikins-crown <hudson.aikins@blanoire.co>
Date: Tue, 7 Jul 2026 16:31:49 -0700
Subject: [PATCH 4/9] Keep toolkit PR evidence self-validating

---
 .github/workflows/evident-evidence.yml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/evident-evidence.yml b/.github/workflows/evident-evidence.yml
index 45469af..908c82a 100644
--- a/.github/workflows/evident-evidence.yml
+++ b/.github/workflows/evident-evidence.yml
@@ -51,7 +51,7 @@ jobs:
           fetch-depth: 0
 
       - name: Checkout Evident toolkit
-        if: ${{ hashFiles('scripts/write-evident-evidence-envelope.mjs') == '' || hashFiles('scripts/check-evident-evidence-envelope.mjs') == '' || hashFiles('scripts/check-evident-external-actions.mjs') == '' }}
+        if: ${{ github.repository != 'IntelIP/agentic-git-workflow' && (hashFiles('scripts/write-evident-evidence-envelope.mjs') == '' || hashFiles('scripts/check-evident-evidence-envelope.mjs') == '' || hashFiles('scripts/check-evident-external-actions.mjs') == '') }}
         uses: actions/checkout@v5
         with:
           repository: IntelIP/agentic-git-workflow
@@ -72,6 +72,8 @@ jobs:
             [ -f scripts/check-evident-evidence-envelope.mjs ] && \
             [ -f scripts/check-evident-external-actions.mjs ]; then
             echo "path=." >> "$GITHUB_OUTPUT"
+          elif [ "$GITHUB_REPOSITORY" = "IntelIP/agentic-git-workflow" ]; then
+            echo "path=." >> "$GITHUB_OUTPUT"
           else
             echo "path=.evident/toolkit" >> "$GITHUB_OUTPUT"
           fi

From abaa9ec26bbb59c446ead287723ec142a04ea5ac Mon Sep 17 00:00:00 2001
From: hudsonaikins-crown <hudson.aikins@blanoire.co>
Date: Tue, 7 Jul 2026 16:41:47 -0700
Subject: [PATCH 5/9] Pin fallback toolkit workflow usage

---
 .github/workflows/evident-evidence.yml | 32 ++++++++++++--------------
 README.md                              |  8 ++++---
 docs/getting-started.md                |  8 +++----
 3 files changed, 24 insertions(+), 24 deletions(-)

diff --git a/.github/workflows/evident-evidence.yml b/.github/workflows/evident-evidence.yml
index 908c82a..7660f11 100644
--- a/.github/workflows/evident-evidence.yml
+++ b/.github/workflows/evident-evidence.yml
@@ -15,9 +15,8 @@ on:
         default: ""
         type: string
       toolkit_ref:
-        description: Evident toolkit ref to use when scripts are not vendored in the caller repo.
-        required: false
-        default: main
+        description: Evident toolkit ref for fallback scripts. Pin to the same ref as the reusable workflow.
+        required: true
         type: string
   workflow_call:
     inputs:
@@ -32,9 +31,8 @@ on:
         default: ""
         type: string
       toolkit_ref:
-        description: Evident toolkit ref to use when scripts are not vendored in the caller repo.
-        required: false
-        default: main
+        description: Evident toolkit ref for fallback scripts. Pin to the same ref as the reusable workflow.
+        required: true
         type: string
 
 permissions:
@@ -50,20 +48,25 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+
+      - name: Optional validation command
+        id: validation
+        if: ${{ inputs.validation_command }}
+        run: ${{ inputs.validation_command }}
+
       - name: Checkout Evident toolkit
         if: ${{ github.repository != 'IntelIP/agentic-git-workflow' && (hashFiles('scripts/write-evident-evidence-envelope.mjs') == '' || hashFiles('scripts/check-evident-evidence-envelope.mjs') == '' || hashFiles('scripts/check-evident-external-actions.mjs') == '') }}
         uses: actions/checkout@v5
         with:
           repository: IntelIP/agentic-git-workflow
-          ref: ${{ inputs.toolkit_ref || 'main' }}
+          ref: ${{ inputs.toolkit_ref }}
           path: .evident/toolkit
           persist-credentials: false
 
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: "20"
-
       - name: Resolve Evident toolkit path
         id: toolkit
         shell: bash
@@ -78,11 +81,6 @@ jobs:
             echo "path=.evident/toolkit" >> "$GITHUB_OUTPUT"
           fi
 
-      - name: Optional validation command
-        id: validation
-        if: ${{ inputs.validation_command }}
-        run: ${{ inputs.validation_command }}
-
       - name: Write evidence envelope
         if: always()
         run: node "${TOOLKIT_PATH}/scripts/write-evident-evidence-envelope.mjs" --out "${EVIDENCE_PATH}"
diff --git a/README.md b/README.md
index 960fb8d..2b8a433 100644
--- a/README.md
+++ b/README.md
@@ -111,7 +111,7 @@ jobs:
       toolkit_ref: v0.1.0
 ```
 
-Before the first release tag exists, use `main` instead of `v0.1.0`.
+`toolkit_ref` is required for reusable workflow calls. Consumer repositories that do not vendor the Evident scripts use it for fallback toolkit checkout. 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:
 
@@ -177,11 +177,13 @@ on:
 jobs:
   evidence:
     uses: IntelIP/agentic-git-workflow/.github/workflows/evident-evidence.yml@main
+    with:
+      toolkit_ref: main
 ```
 
-For consumer repositories, pin both the workflow ref and `toolkit_ref` to the same release tag.
+For consumer repositories, pin both the workflow ref and required `toolkit_ref` to the same release tag.
 
-The workflow writes `evident-pr-evidence.json`, validates the envelope, checks the external-action policy, and uploads the evidence artifact.
+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
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
index bf1574e..8421cf6 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -32,14 +32,14 @@ jobs:
       toolkit_ref: v0.1.0
 ```
 
-Use `toolkit_ref` to keep the workflow runner on the same Evident release as the reusable workflow. Before the first release tag exists, use `main` for both refs.
+`toolkit_ref` is required for reusable workflow calls. Consumer repositories that do not vendor the Evident scripts use it for fallback toolkit checkout. Pin it to the same release tag or SHA as the reusable workflow. Before the first release tag exists, use `main` for both refs.
 
 ## What The Workflow Does
 
 1. Checks out the pull request repository.
-2. Uses local Evident scripts when the repository vendors them.
-3. Otherwise checks out the Evident toolkit at `toolkit_ref`.
-4. Runs the optional validation command.
+2. Runs the optional validation command before adding any fallback toolkit files.
+3. Uses local Evident scripts when the repository vendors them.
+4. Otherwise checks out the Evident toolkit at `toolkit_ref`.
 5. Writes `evident-pr-evidence.json`.
 6. Validates the evidence envelope.
 7. Checks the default-deny external action policy.

From 5ddb15d940e0da40d906c464600fe0938ebbcedd Mon Sep 17 00:00:00 2001
From: hudsonaikins-crown <hudson.aikins@blanoire.co>
Date: Tue, 7 Jul 2026 16:47:29 -0700
Subject: [PATCH 6/9] Keep evidence generation after failed validation

---
 .github/workflows/evident-evidence.yml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/evident-evidence.yml b/.github/workflows/evident-evidence.yml
index 7660f11..f32e29c 100644
--- a/.github/workflows/evident-evidence.yml
+++ b/.github/workflows/evident-evidence.yml
@@ -59,7 +59,7 @@ jobs:
         run: ${{ inputs.validation_command }}
 
       - name: Checkout Evident toolkit
-        if: ${{ github.repository != 'IntelIP/agentic-git-workflow' && (hashFiles('scripts/write-evident-evidence-envelope.mjs') == '' || hashFiles('scripts/check-evident-evidence-envelope.mjs') == '' || hashFiles('scripts/check-evident-external-actions.mjs') == '') }}
+        if: ${{ always() && github.repository != 'IntelIP/agentic-git-workflow' && (hashFiles('scripts/write-evident-evidence-envelope.mjs') == '' || hashFiles('scripts/check-evident-evidence-envelope.mjs') == '' || hashFiles('scripts/check-evident-external-actions.mjs') == '') }}
         uses: actions/checkout@v5
         with:
           repository: IntelIP/agentic-git-workflow
@@ -69,6 +69,7 @@ jobs:
 
       - name: Resolve Evident toolkit path
         id: toolkit
+        if: ${{ always() }}
         shell: bash
         run: |
           if [ -f scripts/write-evident-evidence-envelope.mjs ] && \

From 0aa17c87209e526a784838b3bbf6c03cf4d550b0 Mon Sep 17 00:00:00 2001
From: hudsonaikins-crown <hudson.aikins@blanoire.co>
Date: Tue, 7 Jul 2026 16:55:40 -0700
Subject: [PATCH 7/9] Preserve optional toolkit refs

---
 .github/workflows/evident-evidence.yml      | 37 ++++++++++++---------
 README.md                                   |  4 +--
 docs/getting-started.md                     |  2 +-
 scripts/write-evident-evidence-envelope.mjs | 10 ++++--
 4 files changed, 32 insertions(+), 21 deletions(-)

diff --git a/.github/workflows/evident-evidence.yml b/.github/workflows/evident-evidence.yml
index f32e29c..d296983 100644
--- a/.github/workflows/evident-evidence.yml
+++ b/.github/workflows/evident-evidence.yml
@@ -16,7 +16,7 @@ on:
         type: string
       toolkit_ref:
         description: Evident toolkit ref for fallback scripts. Pin to the same ref as the reusable workflow.
-        required: true
+        required: false
         type: string
   workflow_call:
     inputs:
@@ -32,7 +32,7 @@ on:
         type: string
       toolkit_ref:
         description: Evident toolkit ref for fallback scripts. Pin to the same ref as the reusable workflow.
-        required: true
+        required: false
         type: string
 
 permissions:
@@ -58,19 +58,12 @@ jobs:
         if: ${{ inputs.validation_command }}
         run: ${{ inputs.validation_command }}
 
-      - name: Checkout Evident toolkit
-        if: ${{ always() && github.repository != 'IntelIP/agentic-git-workflow' && (hashFiles('scripts/write-evident-evidence-envelope.mjs') == '' || hashFiles('scripts/check-evident-evidence-envelope.mjs') == '' || hashFiles('scripts/check-evident-external-actions.mjs') == '') }}
-        uses: actions/checkout@v5
-        with:
-          repository: IntelIP/agentic-git-workflow
-          ref: ${{ inputs.toolkit_ref }}
-          path: .evident/toolkit
-          persist-credentials: false
-
       - name: Resolve Evident toolkit path
         id: toolkit
         if: ${{ always() }}
         shell: bash
+        env:
+          TOOLKIT_REF: ${{ inputs.toolkit_ref || '' }}
         run: |
           if [ -f scripts/write-evident-evidence-envelope.mjs ] && \
             [ -f scripts/check-evident-evidence-envelope.mjs ] && \
@@ -78,12 +71,26 @@ jobs:
             echo "path=." >> "$GITHUB_OUTPUT"
           elif [ "$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"
           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()
+        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 }}
@@ -92,21 +99,21 @@ jobs:
           EVIDENT_VALIDATION_STATUS: ${{ steps.validation.outcome || 'skipped' }}
 
       - name: Validate evidence envelope
-        if: always()
+        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()
+        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
diff --git a/README.md b/README.md
index 2b8a433..cceefdf 100644
--- a/README.md
+++ b/README.md
@@ -111,7 +111,7 @@ jobs:
       toolkit_ref: v0.1.0
 ```
 
-`toolkit_ref` is required for reusable workflow calls. Consumer repositories that do not vendor the Evident scripts use it for fallback toolkit checkout. 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`.
+`toolkit_ref` is required when the consumer repository does not vendor the Evident 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:
 
@@ -181,7 +181,7 @@ jobs:
       toolkit_ref: main
 ```
 
-For consumer repositories, pin both the workflow ref and required `toolkit_ref` to the same release tag.
+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.
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 8421cf6..9799d44 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -32,7 +32,7 @@ jobs:
       toolkit_ref: v0.1.0
 ```
 
-`toolkit_ref` is required for reusable workflow calls. Consumer repositories that do not vendor the Evident scripts use it for fallback toolkit checkout. Pin it to the same release tag or SHA as the reusable workflow. Before the first release tag exists, use `main` for both refs.
+`toolkit_ref` is required when the consumer repository does not vendor the Evident scripts. Pin it to the same release tag or SHA as the reusable workflow. Before the first release tag exists, use `main` for both refs.
 
 ## What The Workflow Does
 
diff --git a/scripts/write-evident-evidence-envelope.mjs b/scripts/write-evident-evidence-envelope.mjs
index 31f5357..6d63585 100644
--- a/scripts/write-evident-evidence-envelope.mjs
+++ b/scripts/write-evident-evidence-envelope.mjs
@@ -105,17 +105,21 @@ function getChangedFiles() {
     const mergeBase = git(["merge-base", `origin/${base}`, "HEAD"]);
     if (mergeBase) {
       const files = git(["diff", "--name-only", `${mergeBase}...HEAD`]);
-      if (files) return files.split("\n").filter(Boolean).sort();
+      if (files) return filterChangedFiles(files.split("\n").filter(Boolean).sort());
     }
   }
 
   const stagedOrWorking = git(["diff", "--name-only", "HEAD"]);
   const untracked = git(["ls-files", "--others", "--exclude-standard"]);
   const localFiles = [...splitLines(stagedOrWorking), ...splitLines(untracked)];
-  if (localFiles.length > 0) return [...new Set(localFiles)].sort();
+  if (localFiles.length > 0) return filterChangedFiles([...new Set(localFiles)].sort());
 
   const lastCommit = git(["diff-tree", "--root", "--no-commit-id", "--name-only", "-r", "HEAD"]);
-  return splitLines(lastCommit).sort();
+  return filterChangedFiles(splitLines(lastCommit).sort());
+}
+
+function filterChangedFiles(files) {
+  return files.filter((file) => file !== ".evident/toolkit" && !file.startsWith(".evident/toolkit/"));
 }
 
 function defaultActionClasses() {

From 59819c39c71d9f9908c419f41e9f24cde5554c8a Mon Sep 17 00:00:00 2001
From: hudsonaikins-crown <hudson.aikins@blanoire.co>
Date: Tue, 7 Jul 2026 17:03:51 -0700
Subject: [PATCH 8/9] Keep fallback evidence accurate

---
 .github/workflows/evident-evidence.yml      |  1 +
 scripts/write-evident-evidence-envelope.mjs | 17 +++++++++--------
 2 files changed, 10 insertions(+), 8 deletions(-)

diff --git a/.github/workflows/evident-evidence.yml b/.github/workflows/evident-evidence.yml
index d296983..e92ddca 100644
--- a/.github/workflows/evident-evidence.yml
+++ b/.github/workflows/evident-evidence.yml
@@ -97,6 +97,7 @@ jobs:
           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() && steps.toolkit.outcome == 'success' }}
diff --git a/scripts/write-evident-evidence-envelope.mjs b/scripts/write-evident-evidence-envelope.mjs
index 6d63585..53b014a 100644
--- a/scripts/write-evident-evidence-envelope.mjs
+++ b/scripts/write-evident-evidence-envelope.mjs
@@ -9,6 +9,7 @@ const now = new Date().toISOString();
 const changedFiles = getChangedFiles();
 const validationCommand = env("EVIDENT_VALIDATION_COMMAND");
 const validationStatus = normalizeStatus(env("EVIDENT_VALIDATION_STATUS") || "skipped");
+const writerCommand = env("EVIDENT_WRITER_COMMAND") || `node ${process.argv[1] || "scripts/write-evident-evidence-envelope.mjs"}`;
 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";
@@ -52,7 +53,7 @@ const evidence = {
       ]
     : [
         {
-          command: "node scripts/write-evident-evidence-envelope.mjs",
+          command: writerCommand,
           status: "passed",
           exitCode: 0,
           completedAt: now,
@@ -105,20 +106,20 @@ function getChangedFiles() {
     const mergeBase = git(["merge-base", `origin/${base}`, "HEAD"]);
     if (mergeBase) {
       const files = git(["diff", "--name-only", `${mergeBase}...HEAD`]);
-      if (files) return filterChangedFiles(files.split("\n").filter(Boolean).sort());
+      if (files) return files.split("\n").filter(Boolean).sort();
     }
   }
 
-  const stagedOrWorking = git(["diff", "--name-only", "HEAD"]);
-  const untracked = git(["ls-files", "--others", "--exclude-standard"]);
-  const localFiles = [...splitLines(stagedOrWorking), ...splitLines(untracked)];
-  if (localFiles.length > 0) return filterChangedFiles([...new Set(localFiles)].sort());
+  const stagedOrWorking = splitLines(git(["diff", "--name-only", "HEAD"]));
+  const untracked = filterFallbackToolkitFiles(splitLines(git(["ls-files", "--others", "--exclude-standard"])));
+  const localFiles = [...stagedOrWorking, ...untracked];
+  if (localFiles.length > 0) return [...new Set(localFiles)].sort();
 
   const lastCommit = git(["diff-tree", "--root", "--no-commit-id", "--name-only", "-r", "HEAD"]);
-  return filterChangedFiles(splitLines(lastCommit).sort());
+  return splitLines(lastCommit).sort();
 }
 
-function filterChangedFiles(files) {
+function filterFallbackToolkitFiles(files) {
   return files.filter((file) => file !== ".evident/toolkit" && !file.startsWith(".evident/toolkit/"));
 }
 

From b8f5d3c8dca1764afb1a6807d1654100c34327de Mon Sep 17 00:00:00 2001
From: hudsonaikins-crown <hudson.aikins@blanoire.co>
Date: Tue, 7 Jul 2026 17:08:47 -0700
Subject: [PATCH 9/9] Prefer pinned toolkit for consumers

---
 .github/workflows/evident-evidence.yml | 10 +++++-----
 README.md                              |  2 +-
 docs/getting-started.md                |  2 +-
 3 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/evident-evidence.yml b/.github/workflows/evident-evidence.yml
index e92ddca..e745cc5 100644
--- a/.github/workflows/evident-evidence.yml
+++ b/.github/workflows/evident-evidence.yml
@@ -65,15 +65,15 @@ jobs:
         env:
           TOOLKIT_REF: ${{ inputs.toolkit_ref || '' }}
         run: |
-          if [ -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"
-          elif [ "$GITHUB_REPOSITORY" = "IntelIP/agentic-git-workflow" ]; then
+          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"
diff --git a/README.md b/README.md
index cceefdf..55491b3 100644
--- a/README.md
+++ b/README.md
@@ -111,7 +111,7 @@ jobs:
       toolkit_ref: v0.1.0
 ```
 
-`toolkit_ref` is required when the consumer repository does not vendor the Evident 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`.
+`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:
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
index 9799d44..ca61515 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -32,7 +32,7 @@ jobs:
       toolkit_ref: v0.1.0
 ```
 
-`toolkit_ref` is required when the consumer repository does not vendor the Evident scripts. Pin it to the same release tag or SHA as the reusable workflow. Before the first release tag exists, use `main` for both refs.
+`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` for both refs.
 
 ## What The Workflow Does