{"id":50736323,"url":"https://github.com/provasign/shale","last_synced_at":"2026-06-10T14:01:01.113Z","repository":{"id":363720414,"uuid":"1264614029","full_name":"provasign/shale","owner":"provasign","description":"Agent PR evidence — intent capture and session evidence rendered as a card on pull requests","archived":false,"fork":false,"pushed_at":"2026-06-10T03:53:18.000Z","size":112,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-10T05:20:57.869Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/provasign.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-10T03:18:59.000Z","updated_at":"2026-06-10T03:53:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/provasign/shale","commit_stats":null,"previous_names":["provasign/shale"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/provasign/shale","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/provasign%2Fshale","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/provasign%2Fshale/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/provasign%2Fshale/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/provasign%2Fshale/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/provasign","download_url":"https://codeload.github.com/provasign/shale/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/provasign%2Fshale/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34155422,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-10T14:00:25.550Z","updated_at":"2026-06-10T14:01:01.084Z","avatar_url":"https://github.com/provasign.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Shale\n\n\u003e **Every agent PR comes with shale.**\n\u003e Shale shows reviewers what an AI coding agent was asked to do, what it actually\n\u003e changed, and what checks already ran — rendered as a card on the pull request.\n\u003e Five minutes to set up. Zero servers. Works with every coding agent.\n\n**License: Apache-2.0** (deliberately permissive — adoption is the moat; see\n`docs/05-decisions.md` D1).\n\n---\n\n## The problem\n\nAI coding agents now produce a large share of PR volume. The reviewer, the\nsecurity engineer, the risk officer, and the product owner all ask the same\nquestion from different angles:\n\n\u003e **\"Did the agent do the right thing? What was it asked, what did it touch,\n\u003e and can I trust this diff?\"**\n\nToday the answer is scattered or gone: the prompt died with the agent session,\nthe diff is huge, and CI findings arrive after the fact. GitHub is solving this\n*only* for its own Copilot cloud agent (commit → session-log tracing). Local\nagents — Claude Code, Cursor, Codex CLI, Gemini CLI, Windsurf — which produce\nmost agent code today, leave no trail.\n\n## What Shale does\n\n1. **Captures intent from the agent itself.** A steering prompt (written by\n   `shale init` into CLAUDE.md / AGENTS.md / .cursorrules /\n   copilot-instructions.md) has the agent declare its intent via\n   `shale intent` before the first edit and report completion via\n   `shale done` — plain CLI calls, no MCP, so it works with **every** agent\n   including Copilot (ADR D4). Agent-native hooks, where available, add\n   verified file-touch and command evidence automatically; a git-diff fallback\n   covers agents without hooks. The user changes nothing about how they work.\n2. **Makes the evidence travel with the code.** Evidence is written to\n   `.shale/` in the repo (schema-versioned YAML, redacted) and rides along\n   with the normal push. No server in the path.\n3. **Renders a Shale card on the PR.** `shale render` runs in the user's\n   own CI — a one-line GitHub Action for OSS, or the same binary in a\n   Jenkins/GitLab CI stage for enterprises — reads the PR diff and the shale files\n   via the forge API (no code checkout), and posts a card: intent, agent/model,\n   changed files vs. stated intent, locally-recorded check results, and\n   explicit gaps (\"2 files changed with no session evidence\").\n4. **Stays advisory.** The card never blocks a merge. Strict mode is a later,\n   explicit opt-in. The default posture is fail-open, zero friction.\n\nWhat Shale deliberately does **not** do:\n\n- It does **not** run quality gates. Scanners (Semgrep, Sonar, gitleaks) already\n  ship MCP servers that agents call in-loop; CI remains authoritative. Shale\n  *records* what ran and what the result was — it is a recorder and renderer,\n  not a gatekeeper.\n- It does **not** review code with an LLM. CodeRabbit/Greptile/Graphite own\n  that space. Shale is the evidence layer those reviews sit on top of.\n- It does **not** require an account, a backend, signing keys, or a GitHub App\n  in v1.\n\n## The one-line goal (hold every decision against this)\n\n\u003e **A stranger with an agent-built branch gets a Shale card on their next PR\n\u003e within 5 minutes of discovering this project, without creating an account or\n\u003e deploying anything.**\n\n## Relationship to Provasign\n\nShale is the open, lightweight market wedge. Provasign (sibling repo) remains\nthe enterprise certification platform (Sigstore notarization, org policy,\nserver-side attestation store, regulated-tier re-runs). The bridge is the\nshale format itself: a Provasign server can ingest `.shale/` files and\nupgrade them into signed attestations. Shale feeds Provasign; it does not\ndepend on it. Grove (sibling, MIT) is embedded in MVP 3 for intent↔diff\nconformance.\n\n## Repository layout (target)\n\n```\nshale/\n├── cmd/shale/              # CLI entry point (Go, single static binary)\n├── internal/\n│   ├── capture/            # agent hook adapters (claudecode, cursor, codex, generic)\n│   ├── store/              # .shale/ read/write, schema versioning, redaction\n│   ├── render/             # card rendering (markdown) for PR/MR comment\n│   ├── forge/              # forge drivers: github (MVP 1), gitlab (MVP 2)\n│   └── conformance/        # MVP 3: Grove-backed intent↔diff mapping\n├── action/                 # composite GitHub Action (packaging — see ADR D10)\n├── spec/                   # shale format JSON Schema + examples (the open spec)\n├── docs/\n│   ├── 01-product.md       # personas, UX flows, card mockups\n│   ├── 02-architecture.md  # components, data flow, language rationale\n│   ├── 03-shale-spec.md    # evidence format v0\n│   ├── 04-implementation-plan.md  # MVP 1/2/3 task breakdown (start here to build)\n│   └── 05-decisions.md     # decision records — do not relitigate these\n└── AGENTS.md               # instructions for the implementing agent\n```\n\n## Reading order for the implementing agent\n\n1. `AGENTS.md` — ground rules\n2. `docs/04-implementation-plan.md` — what to build, in order, with acceptance criteria\n3. `docs/02-architecture.md` + `docs/03-shale-spec.md` — how\n4. `docs/01-product.md` — why / UX north star\n5. `docs/05-decisions.md` — settled questions\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprovasign%2Fshale","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprovasign%2Fshale","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprovasign%2Fshale/lists"}