Repository navigation
docs: README rewrite for a fast first read - #111
Conversation
|
Important Draft PR not reviewedDraft PRs are not automatically reviewed by default.
To automatically review draft PRs, update your CodeRabbit configuration: reviews:
auto_review:
drafts: true
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
31ad743 to
8c56e3d
Compare
Leads with the problem and a 30-second fail-to-pass quickstart (pnpm demo:gate, output from a clean run), links the walkthrough films, adds a Mermaid sketch of the trust boundary, guardrails and non-goals, keeps the stage-neutral 0.6.4 sentence, and carries the HOST / GITPIN_ALLOWED_HOSTS rows from #112. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
9a0cd20 to
a763ae5
Compare
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: a763ae5da4
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| GitPin turns the description into evidence. The agent commits a small manifest | ||
| in which every material claim names the paths it covers and points at an exact | ||
| line slice with a SHA-256 of its text. A required check compares that manifest | ||
| with the real diff. Any changed file that no claim covers fails the build, and |
There was a problem hiding this comment.
With the policy users are told to copy below, not every changed file is checked: templates/gate.yml excludes package.json and docs/generated/**, and src/gate.ts removes excluded paths from requiredPaths before computing uncovered changes. A PR changing only one of those paths can therefore pass without a claim, so this statement overstates what the required check guarantees; describe coverage as applying to every policy-required changed file and make the same qualification in the diagram.
Useful? React with 👍 / 👎.
|
|
||
| ### Agent-authored pull requests must show exact evidence before they merge. | ||
|
|
||
| **A read-only PR gate and local MCP server that ties every claim an AI agent makes about its change to an exact committed line that anyone can re-check with plain `git`.** |
There was a problem hiding this comment.
Neither the gate nor the MCP reads an agent's pull-request description or conversation, so it cannot tie every claim the agent makes to evidence. The gate validates only claims the submitter chose to place in .gitpin/change-evidence.json; omitted prose claims remain invisible even when all policy-required paths are covered. Constrain this value proposition to manifest claims rather than promising enforcement over every agent claim.
Useful? React with 👍 / 👎.
|
|
||
| **Give your agent the evidence tools.** The local MCP server lets Claude Code, | ||
| Codex, Cursor and other MCP clients find candidates and produce the evidence | ||
| packs the gate checks: |
There was a problem hiding this comment.
The gate does not accept the evidence-pack shape returned by pin.prove; it exclusively reads .gitpin/change-evidence.json, whose claims require fields such as id, covers, ref, path, and lineStart that are absent or differently named in an evidence pack. Saying the MCP produces packs “the gate checks” suggests direct compatibility and leaves users without the required transformation step; state that agents must use pack fields to author the gate manifest.
Useful? React with 👍 / 👎.
| POL --> GATE{"gitpin gate<br/>read-only, never runs PR code"} | ||
| MAN --> GATE | ||
| DIFF --> GATE | ||
| GATE -- "uncovered path, wrong hash,<br/>sensitive path" --> FAIL(["exit 1: check fails"]) |
There was a problem hiding this comment.
The diagram makes sensitive path look like a failure condition for any changed or covered path. In src/gate.ts, however, isAlwaysSensitivePath is applied only to locator.path; a sensitive changed path can be named in covers and paired with evidence from another file without producing this violation. Since the documented boundary is blocking sensitive paths at read time, label this as a sensitive evidence locator rather than implying the gate rejects such changes.
AGENTS.md reference: AGENTS.md:L54-L54
Useful? React with 👍 / 👎.
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
Rewrites the README for a first-time visitor: one-line value proposition, why it exists, a quickstart, the walkthrough film and demo GIF, a Mermaid architecture sketch, guardrails, honest status and limits, and contributing, security and license sections.
Draft until the demo GIF (cut from the delivered film) and the hosted film files on saroshhussain.com land, and the quickstart is re-run from a clean environment.
🤖 Generated with Claude Code