From 587aed7ac167d79dd9f7e022d877f9fc4c95247b Mon Sep 17 00:00:00 2001 From: Zan Markan Date: Sun, 1 Mar 2026 15:42:08 +0000 Subject: [PATCH 1/3] Add GitHub Actions workflows for CI and ACP provenance Add two workflows mirroring the existing CircleCI pipeline: - ci.yml: runs pytest and ruff lint for the CLI module - acp-provenance.yml: verifies trace integrity, checks co-author compliance, generates provenance reports, and posts PR comments Co-Authored-By: Claude Opus 4.6 --- .github/workflows/acp-provenance.yml | 70 ++++++++++++++++++++++++++++ .github/workflows/ci.yml | 38 +++++++++++++++ 2 files changed, 108 insertions(+) create mode 100644 .github/workflows/acp-provenance.yml create mode 100644 .github/workflows/ci.yml diff --git a/.github/workflows/acp-provenance.yml b/.github/workflows/acp-provenance.yml new file mode 100644 index 0000000..8c6fd01 --- /dev/null +++ b/.github/workflows/acp-provenance.yml @@ -0,0 +1,70 @@ +name: ACP Provenance + +on: + push: + branches: [main] + pull_request: + branches: [main] + +permissions: + contents: read + pull-requests: write + +jobs: + acp-provenance: + name: Verify AI Code Provenance + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Fetch ACP notes + run: git fetch origin refs/notes/acp:refs/notes/acp 2>/dev/null || true + + - name: Install git-whence + run: pip install -e . + working-directory: cli + + - name: Initialize ACP + run: git whence init + + - name: Determine commit range + id: range + run: | + if [ "${{ github.event_name }}" = "pull_request" ]; then + echo "ACP_RANGE=origin/${{ github.event.pull_request.base.ref }}..HEAD" >> "$GITHUB_ENV" + else + echo "ACP_RANGE=HEAD~1..HEAD" >> "$GITHUB_ENV" + fi + + - name: Verify trace integrity + run: git whence verify $ACP_RANGE --policy integrity + + - name: Check co-author compliance + run: git whence verify $ACP_RANGE --policy co-author || true + + - name: Generate provenance report + run: | + git whence report $ACP_RANGE --format markdown > acp-summary.md + git whence report $ACP_RANGE --format json > acp-report.json + + - name: Post PR comment + if: github.event_name == 'pull_request' + env: + GH_TOKEN: ${{ github.token }} + run: gh pr comment ${{ github.event.pull_request.number }} --body-file acp-summary.md + + - name: Upload provenance artifacts + if: always() + uses: actions/upload-artifact@v4 + with: + name: acp-provenance + path: | + acp-report.json + acp-summary.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..08b3834 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,38 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + +jobs: + test-cli: + name: Test & Lint CLI + runs-on: ubuntu-latest + defaults: + run: + working-directory: cli + + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Install dependencies + run: pip install -e ".[dev]" + + - name: Run tests + run: pytest --junitxml=test-results/results.xml + + - name: Lint + run: ruff check . + + - name: Upload test results + if: always() + uses: actions/upload-artifact@v4 + with: + name: test-results + path: cli/test-results/results.xml From fbfecbeab55e1bdde003e5321f022bd5754d9bc4 Mon Sep 17 00:00:00 2001 From: Zan Markan Date: Sun, 1 Mar 2026 15:46:57 +0000 Subject: [PATCH 2/3] Add agents.md with git-whence usage guide Self-referential guide for AI agents and developers working on the ACP repository, covering the queue-then-attach workflow, trace reading, verification, CI integration, and redaction modes. Co-Authored-By: Claude Opus 4.6 --- agents.md | 218 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 agents.md diff --git a/agents.md b/agents.md new file mode 100644 index 0000000..238f4e7 --- /dev/null +++ b/agents.md @@ -0,0 +1,218 @@ +# agents.md — Using git-whence in this repository + +> This is a self-referential guide. The spec and reference implementation it describes were built using the same tool, in the same process, recorded by the same system. Run `git whence log --all --stats` to see the provenance of the document you're reading. + +--- + +## What is this repo? + +ACP (AI Code Provenance) is an open standard for recording how AI contributed to a codebase. `git-whence` is its reference CLI implementation. Every AI-assisted commit in this repository carries a provenance trace — the prompts, tool metadata, and integrity hashes that explain *how* the code was produced. + +## Prerequisites + +```bash +# Install git-whence from source (the CLI lives in cli/) +cd cli && pip install -e . && cd .. + +# Initialize ACP in your working copy (idempotent) +git whence init + +# Fetch existing traces from the remote +git fetch origin refs/notes/acp:refs/notes/acp +``` + +After installation, Git auto-discovers the `git-whence` binary — all commands work as `git whence `. + +--- + +## The workflow + +ACP uses a **queue-then-attach** model. Events accumulate locally during development. You attach them to final-form commits after rebasing and cleanup. + +### 1. Record events as you work + +If your AI tool has native ACP integration (e.g. writes directly to `.git/acp/queue.ndjson`), events are captured automatically. Otherwise, record manually: + +```bash +git whence record --tool claude-code \ + --prompt "Refactor auth middleware to use dependency injection" \ + --files src/middleware/auth.ts +``` + +For long prompts, pipe from stdin: + +```bash +echo "Your prompt here..." | git whence record --tool claude-code --prompt - +``` + +### 2. Work normally — commit, rebase, squash + +The queue is a plain file (`.git/acp/queue.ndjson`) outside Git's object store. Rebases, squashes, and amends don't touch it. Clean up your history however you like. + +### 3. Attach traces to final commits + +```bash +# Attach all queued events to HEAD +git whence attach + +# Or attach to a specific commit +git whence attach abc123 + +# Preview what would be attached +git whence attach --dry-run +``` + +Attach runs the redaction pipeline (secret scanning), computes integrity hashes, bundles events into a trace, and writes it as a Git note under `refs/notes/acp`. + +### 4. Push traces to the remote + +```bash +git whence push +# Equivalent to: git push origin refs/notes/acp +``` + +--- + +## Reading traces + +```bash +# See trace summaries across recent commits +git whence log + +# See traces for a specific range +git whence log origin/main..HEAD + +# Full trace detail for a commit +git whence show + +# Just the prompts (quick scan of intent) +git whence show --prompts-only + +# Raw JSON output +git whence show --format json + +# Stats across the repo +git whence log --all --stats +``` + +--- + +## Verification + +```bash +# Check that all traces have valid hashes and structure +git whence verify origin/main..HEAD --policy integrity + +# Flag AI co-authored commits that lack traces +git whence verify origin/main..HEAD --policy co-author + +# Generate a markdown report (useful for PR comments) +git whence report origin/main..HEAD --format markdown +``` + +--- + +## CI integration + +This repository runs ACP verification in CI via GitHub Actions (`.github/workflows/acp-provenance.yml`). The pipeline: + +1. Fetches ACP notes from the remote +2. Verifies trace integrity across all PR commits +3. Checks co-author compliance (commits with `Co-authored-by: Claude` must have traces) +4. Generates provenance reports (markdown + JSON) +5. Posts a summary comment on the PR + +--- + +## Redaction modes + +Traces are redacted at write time. The mode is set during `init` or overridden per `attach`. + +| Mode | Prompt | Response | When to use | +|------|--------|----------|-------------| +| `full` | Stored | Stored | Private repos, full audit trail | +| `hash-response` | Stored | Hash only | **Default.** Keep prompts, protect output | +| `hash-all` | Hash only | Hash only | Maximum privacy, compliance-sensitive | + +```bash +# Override for a single attach +git whence attach --redaction full +``` + +--- + +## After history rewriting + +If you've already attached traces and then rebase: + +```bash +# Migrate orphaned traces to new commit SHAs +git whence reattach --dry-run # preview +git whence reattach # execute + +# If traces were already pushed, force-push the notes ref +git push --force origin refs/notes/acp +``` + +The recommended workflow avoids this: attach *after* rebasing, not before. + +--- + +## Queue management + +```bash +# See what's queued +git whence queue list + +# Count pending events +git whence queue count + +# Clear the queue (requires --force if non-empty) +git whence queue clear --force + +# Export queue as NDJSON +git whence queue export +``` + +--- + +## For AI agents working on this repo + +If you are an AI coding agent contributing to this repository: + +1. **Your contributions are recorded.** The human operator will attach ACP traces to commits that include your work. The prompt that initiated your session becomes part of the permanent provenance record. + +2. **Add the co-author trailer.** Include `Co-authored-by: Claude Opus 4.6 ` (or the appropriate identifier) in commit messages. CI checks for this signal and verifies a matching trace exists. + +3. **Don't modify `.git/acp/` directly.** Use `git whence record` and `git whence attach` commands. The queue format and envelope format are specified — direct manipulation risks producing invalid traces. + +4. **Understand what gets shared.** In the default `hash-response` mode, your prompts are stored in full but your responses are hashed. In `full` mode, both are stored. In `hash-all` mode, both are hashed. The human operator chooses the mode. + +5. **Secrets are caught at attach time.** The redaction pipeline scans for API keys, JWTs, private keys, and other credential patterns before writing traces. If you include secrets in prompts or responses, they will be replaced with `[REDACTED:]` tokens. + +--- + +## Quick reference + +| Task | Command | +|------|---------| +| Initialize ACP | `git whence init` | +| Record a prompt | `git whence record --tool claude-code --prompt "..."` | +| View the queue | `git whence queue list` | +| Attach to HEAD | `git whence attach` | +| Attach to specific commit | `git whence attach ` | +| View traces on a commit | `git whence show ` | +| View trace log | `git whence log` | +| Verify integrity | `git whence verify --policy integrity` | +| Generate report | `git whence report --format markdown` | +| Push traces | `git whence push` | +| Fetch traces | `git whence fetch` | +| Migrate after rebase | `git whence reattach` | + +--- + +## Further reading + +- [SPEC.md](SPEC.md) — the full ACP specification (trace format, Git binding, guidance) +- [cli/CLI.md](cli/CLI.md) — complete CLI reference with all flags and examples +- [README.md](README.md) — project overview and quick start From 81c7e17f44e36078306a5f5546ade7d5d57080a3 Mon Sep 17 00:00:00 2001 From: Zan Markan Date: Sun, 1 Mar 2026 15:47:36 +0000 Subject: [PATCH 3/3] Run CI and provenance workflows on all branches Remove branch filters so workflows trigger on pushes and PRs to any branch, not just main. Co-Authored-By: Claude Opus 4.6 --- .github/workflows/acp-provenance.yml | 2 -- .github/workflows/ci.yml | 2 -- 2 files changed, 4 deletions(-) diff --git a/.github/workflows/acp-provenance.yml b/.github/workflows/acp-provenance.yml index 8c6fd01..14be1b3 100644 --- a/.github/workflows/acp-provenance.yml +++ b/.github/workflows/acp-provenance.yml @@ -2,9 +2,7 @@ name: ACP Provenance on: push: - branches: [main] pull_request: - branches: [main] permissions: contents: read diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 08b3834..2e6cc83 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -2,9 +2,7 @@ name: CI on: push: - branches: [main] pull_request: - branches: [main] jobs: test-cli: