Skip to content

PROJECT_CONSTITUTION.md

Latest commit

 

History

History
320 lines (224 loc) · 16.3 KB

PROJECT_CONSTITUTION.md

File metadata and controls

320 lines (224 loc) · 16.3 KB
Raw

PROJECT CONSTITUTION — PatchGate

Status: focused product charter
Version: 1.0
Baseline date: 2026-08-12
Working name: PatchGate
Tagline: Make every contribution prove it is reviewable before it consumes maintainer time.

1. Product decision

PatchGate is an open-source review-readiness gate for GitHub pull requests.

It does not ask whether a pull request was written by a human or an AI. It asks whether the pull request has provided the evidence, approvals, and scope control that a repository requires before a maintainer invests review time.

trusted base policy + GitHub metadata + verified CI evidence
                         ↓
             deterministic PatchGate evaluator
                         ↓
      ContributionReceipt + actionable remediation
                         ↓
          required GitHub check and human review gate

The product is a developer-infrastructure tool for open-source maintainers and teams with public repositories. It is not a replacement for GitHub Rulesets, branch protection, CODEOWNERS, CI, code review, or maintainer discretion. It connects those controls into one explainable review-readiness decision.

2. Why this should exist

Repositories already have contribution rules, but they are often scattered across CONTRIBUTING.md, AGENTS.md, PR templates, CODEOWNERS, CI workflows, security guidance, and GitHub settings. Human contributors and coding agents alike can miss them; maintainers then discover missing issue links, unrun tests, wrong reviewers, risky scope, or policy violations only after opening a review.

This pressure increases with coding agents: code can be created faster than maintainers can evaluate it. RepoComplianceBench found that current coding agents rarely proactively retrieve AI contribution rules, and that refusal and human escalation remain particularly hard to enforce. RepoComplianceBench

PatchGate's goal is not to automate a subjective code review. Its goal is to move deterministic and evidence-based contribution requirements before that review.

3. Target users and jobs

User Job to be done
OSS maintainer See whether a PR is ready, blocked, or waiting for a specific human before opening a deep review.
Contributor or coding agent Run preflight, receive machine-readable requirements, and repair a PR before asking for review.
Repository administrator Express review boundaries that combine native GitHub controls, path ownership, CI evidence, and local policy.
Security owner Require qualified review for sensitive paths without depending on the contributor's branch policy.
Tool builder Consume a stable receipt to automate PR preparation, triage, or reporting.

4. Exact product boundary

PatchGate does:

  • discover contribution guidance and identify ambiguity;
  • compile explicit, confirmed rules into a deterministic contribution contract;
  • evaluate a PR against trusted base policy and GitHub metadata;
  • verify that evidence is linked to the relevant commit;
  • assess explainable reviewability signals;
  • require configured human approvals for sensitive changes;
  • produce a receipt and a required status check.

PatchGate does not:

  • determine whether code was generated by AI;
  • decide functional correctness, security safety, license validity, or merge worthiness;
  • execute untrusted contributor code in a privileged workflow;
  • infer blocking governance requirements from prose;
  • prevent a contributor from opening a PR;
  • replace human approval with a bot approval;
  • sell a compliance certification or cryptographic guarantee that it has not implemented.

5. Authority and trust model

The most important design decision is to separate policy discovery from enforcement.

5.1 Enforceable authority

Only these sources can create a blocking or human-gate requirement:

  1. patchgate.yml fetched from the PR's base SHA;
  2. GitHub Rulesets and branch protection retrieved through authenticated GitHub APIs;
  3. CODEOWNERS fetched from the base SHA;
  4. trusted GitHub check/workflow data tied to the required revision;
  5. pull-request metadata, review state, labels, linked issues, and merge state from GitHub.

The evaluator records every source's path/API identity, revision, digest where applicable, and time of retrieval.

5.2 Discovery-only sources

The following can inform a preflight report but cannot silently create enforcement:

  • CONTRIBUTING.md;
  • AGENTS.md and other agent instructions;
  • SECURITY.md;
  • README content;
  • PR templates;
  • AI contribution policy files;
  • CI files that contain prose rather than an explicit PatchGate/native rule.

PatchGate can say, “This policy appears to require a changelog entry; confirm it in patchgate.yml.” It cannot say, “Merge is blocked,” until a maintainer establishes authoritative structured policy.

5.3 Base-policy rule

Policy is evaluated from the trusted base revision, never from the contributor's head branch. A PR that relaxes a policy is assessed under the old policy; the new policy takes effect only after merge.

This protects against policy self-relaxation and makes receipt results reproducible.

5.4 Evidence target and source strength

The evaluator must keep these values distinct:

  • baseSha — the trusted policy revision;
  • headSha — the contributor branch tip;
  • mergeSha — an optional pull-request test-merge revision;
  • testedSha — the exact revision bound to a check or approval;
  • targetKind — head, merge, or merge_group.

The GitHub adapter supplies testedSha explicitly. It must not assume that GITHUB_SHA is the contributor branch head. A merge_group evaluation uses the merge-group SHA. A required check also records its source strength: a distinct expected GitHub App, the generic GitHub Actions workflow identity, or an unattributed source. An Action-only implementation must not claim a distinct PatchGate App source until that App exists.

5.5 Linked-issue evidence

When issue linkage is enforced, the evaluator should use normalized GitHub linked-issue metadata. A pull-request-body string match is a discovery clue, not verified linkage, unless the adapter has independently confirmed the issue and repository relationship.

6. Contribution contract

The internal ContributionContract is a versioned representation of explicit requirements, their authority, scope, satisfaction method, and remediation.

It must distinguish:

  • enforced — a trusted source defines the rule;
  • advisory — a policy/doc signal may help review but cannot block;
  • needs_confirmation — prose suggests a rule but the maintainer has not confirmed it;
  • unsupported — a repository requirement PatchGate cannot safely interpret.

Each requirement includes a stable ID, rule class, source authority, path/condition, expected evidence, severity, and remediation text. Requirements should compose predictably; ambiguity or conflict is a result, not an opportunity for silent guessing.

7. First supported rules

Release 0.1 supports six classes.

Rule class Enforceable source Expected evidence
Issue linkage patchgate.yml and GitHub metadata valid linked issue/identifier under repository policy
Required checks GitHub Rulesets / patchgate.yml completed check from the configured source on the configured testedSha
Path ownership CODEOWNERS / patchgate.yml qualified required reviewer approval
Policy integrity trusted base policy base SHA and policy digest; no self-relaxation; explicit evidence target
Human handoff patchgate.yml path rules configured human/team approval remains required
Reviewability budget patchgate.yml explainable signal set: files, domains, generated paths, boundaries

Reviewability budget defaults to a warning. A repository may deliberately configure a blocking threshold, but PatchGate must explain every input into that result and must not reduce reviewability to line count.

8. User experience

8.1 Preflight

Before code is written or a PR is opened:

The npm name patchgate is already used by a different project. This CLI is unpublished (private: true). After npm ci && npm run build in a clone:

node dist/src/cli.js preflight --base origin/main

The command reports trusted policy sources, policy digest, required checks, path ownership, declared human-only boundaries, advisory guidance, and unresolved policy ambiguity. It is designed for people and coding agents.

8.2 Pull-request evaluation

After a PR is opened, the Action posts a check and receipt summary:

PATCHGATE: HUMAN REVIEW REQUIRED

Base policy: main@7f31ac2 (sha256:...)
Head: 201bf91

Satisfied
  ✓ linked issue #482
  ✓ unit and integration checks on 201bf91

Required before merge
  ! security owner approval: src/auth/** changed

Advisory
  ! change spans 4 ownership domains and 57 files
    Suggested split: migration, auth, and UI changes

The machine-readable receipt is the authoritative result. PR comments and UI summaries are derived views.

9. Security architecture

PatchGate must be safer than the workflow it is trying to govern.

9.1 Three lanes

1. Trusted metadata/policy lane
   Reads base policy and GitHub metadata.
   Never checks out, installs, or executes PR code.

2. Untrusted verification lane
   May test contributor code only through `pull_request`-style,
   isolated execution with a read-only token and no secrets.

3. Trusted decision lane
   Consumes authenticated GitHub metadata and explicitly verified evidence.
   Posts PatchGate's check result without executing PR code.

GitHub warns that pull_request_target runs with base-repository credentials and becomes dangerous when PR-controlled code is checked out or executed. PatchGate must treat this as a hard design constraint. GitHub guidance

9.2 Evidence integrity

Evidence must include the check/app identity, conclusion, commit SHA, workflow/run identity, and retrieval time. A completed check on an old commit cannot satisfy a requirement for a newer head.

GitHub rulesets can require status checks and specify the expected source application. PatchGate documentation and integration tests must use this control when its check blocks merge. GitHub Rulesets

For an Action-only release, the observable source is GitHub Actions rather than a distinct PatchGate App. The project must expose this limitation and return evidence_missing when a policy explicitly requires a stronger App identity that the installed adapter cannot provide. Required workflows must also support merge_group when the repository uses a merge queue.

Artifact attestations can prove provenance for an artifact produced in GitHub Actions. They are optional evidence inputs, not a universal proof that contribution policy was obeyed. GitHub Artifact Attestations

9.3 Threat model

At minimum, test and document:

  • policy self-relaxation in a PR;
  • check-status source spoofing;
  • stale approval or evidence after a push;
  • comment/body edits used as purported evidence;
  • malicious fork PRs;
  • pull_request_target checkout or artifact-execution misuse;
  • dependency/install hooks in untrusted test execution;
  • confused-deputy permissions in GitHub Apps and Actions;
  • receipt tampering or schema downgrade;
  • policy discovery output that is mistaken for enforcement.

10. Architecture

PatchGate begins as one TypeScript package, CLI, and Action in one repository:

src/
  discovery/       locate, classify, and explain repository guidance
  policy/          parse PatchGate and native GitHub policy sources
  contract/        typed contribution contract and authority data
  evaluator/       deterministic requirement evaluation
  evidence/        commit-bound check/workflow evidence and receipts
  risk/            explainable reviewability signals
  github/          GitHub API/event boundary
  cli/             preflight and evaluation commands
  action/          GitHub Action adapter
fixtures/
test/
docs/

The deterministic core consumes a normalized snapshot and produces a receipt digest. Retrieval timestamps, URLs, and delivery metadata belong to the outer adapter envelope and must not make fixture replay impossible.

Do not create a dashboard, database, multi-tenant SaaS, LLM core, policy marketplace, cryptographic ledger, GitLab adapter, or a public standard during 0.1.

The project may later publish an Open Contribution Governance Corpus and benchmark, but only from legally reusable/opt-in policy material with provenance. The corpus is not required to make the initial product useful.

11. Competitive position

The product is not a blank-slate category. Existing tools already demonstrate policy-as-code and PR automation:

  • GitHub Rulesets can require reviews and status checks before merge.
  • Palantir Policy Bot provides rule-based PR approval policies, target-branch policy loading, and required status checks.
  • Reviewpad and Danger automate project-specific PR checks and review conventions.

PatchGate's intended differentiation is the combination of:

  1. a strict trusted-base authority model across several native governance sources;
  2. preflight output designed for coding agents and contributors before PR creation;
  3. a typed contract that separates enforceable requirements from prose discovery;
  4. commit-bound evidence and a portable machine-readable receipt;
  5. explicit review-readiness and human-boundary reporting rather than AI authorship detection.

This is a product hypothesis, not a claim of uniqueness. Adoption must prove it.

12. Definition of done for v0.1

v0.1 is ready for public use only when:

  • CLI preflight works on fixture repositories and reports source authority, digest, requirements, advisory findings, and ambiguity;
  • GitHub Action evaluates all six rule classes deterministically;
  • every receipt binds decisions to the correct base/head SHA and policy digests;
  • every receipt also records testedSha, targetKind, check source strength, and evidence retrieval metadata;
  • structured base policy takes precedence over conflicting prose without hiding the conflict;
  • sensitive-path changes correctly require qualified configured human approval;
  • stale/foreign/spoofed check evidence cannot satisfy a required rule;
  • security tests prove that the trusted lane does not execute PR code;
  • the Action requests minimal documented GitHub permissions;
  • semantic, fixture, integration, security, and receipt-schema tests pass in CI;
  • two external public repositories have tested the CLI/Action and their feedback is incorporated;
  • README documents supported policy behavior, unsupported cases, threat model, safe GitHub setup, and removal/rollback.

The repository must not describe an Action-only check as a distinct PatchGate App source, and must not describe a passing local evaluator as proof of live GitHub integration, merge protection, or release readiness.

13. Adoption and sustainability

The initial adoption loop is:

useful preflight
  -> safe Action
  -> maintainer feedback
  -> fixture from a real governance edge case
  -> stronger policy adapter and receipt
  -> external repository adoption

The project must not optimize for stars or a Codex for Open Source application. If it becomes active public infrastructure with releases, external issues, maintainer workflows, and real repository usage, its fit for that program will follow naturally.

14. Authoritative baseline