ContribPreflight

Deterministic contribution-policy preflight for humans, CI systems, and coding agents.

Quick Start

npx contribpreflight .

That's it. ContribPreflight scans your repository and surfaces contribution requirements with exact file and line evidence.

Why ContribPreflight?

Repository contribution requirements are scattered across CONTRIBUTING.md, AGENTS.md, AI policy documents, pull request templates, and other files. Missing a requirement can mean rejected pull requests, wasted effort, or compliance issues.

ContribPreflight reads those files as data and surfaces high-confidence requirements before contribution work begins. It is:

• Deterministic — same input always produces the same output
• Local — reads files only, never executes repository content
• Explainable — every finding includes file, line, and evidence
• Bounded — scans a defined set of likely policy surfaces

Example

Given a CONTRIBUTING.md containing:

AI-assisted contributions are allowed only if their use is disclosed.
Contributors remain responsible for code they submit.
Run npm test before opening a pull request.

Running npx contribpreflight . produces:

Policy: conditional

Requirements:
  CP002  disclosure    CONTRIBUTING.md:1  "AI-assisted contributions are allowed only if their use is disclosed."
  CP003  responsibility CONTRIBUTING.md:2  "Contributors remain responsible for code they submit."
  CP005  verification  CONTRIBUTING.md:3  "Run npm test before opening a pull request."

Commands:
  npm test  (CONTRIBUTING.md:3)

Usage

# Scan current directory
npx contribpreflight .

# Scan a specific path
npx contribpreflight ./my-repo

# JSON output
npx contribpreflight . --json

# Agent-friendly output
npx contribpreflight . --agent

Commands

contribpreflight [path]         # Scan repository
contribpreflight files [path]   # List discovered policy surfaces
contribpreflight rules          # List CP001-CP010 rule definitions

Output Modes

Pretty (default)

Human-readable terminal output with color and formatting.

JSON

contribpreflight . --json

Single valid JSON document to stdout. No ANSI, no decorations. Suitable for CI pipelines and tooling.

Agent

contribpreflight . --agent

Concise plain text for supplying to a coding agent before repository work. No ANSI escape sequences. Does not replace reading original repository policies.

Rules (CP001-CP010)

Rule	Type	Description
CP001	ai-prohibition	Explicit AI contribution prohibition
CP002	disclosure	AI assistance disclosure required
CP003	human-responsibility	Human responsibility/understanding required
CP004	human-review	Human review/approval/sign-off required
CP005	verification	Verification/tests required before contribution
CP006	dco	Developer Certificate of Origin / Signed-off-by required
CP007	cla	Contributor License Agreement requirement
CP008	provenance	AI output provenance/copyright/licensing requirement
CP009	ai-condition	AI contribution condition/restriction detected
CP010	ai-permission	Explicit AI-assisted contributions allowed

Discovery Surfaces

ContribPreflight scans these files:

• CONTRIBUTING.md, CONTRIBUTING.*
• AGENTS.md, CLAUDE.md
• AI.md, AI_POLICY.md, AI-POLICY.md
• AI_CONTRIBUTION_POLICY.md, AI-CONTRIBUTION-POLICY.md
• GOVERNANCE.md, README.md
• .github/PULL_REQUEST_TEMPLATE.md
• .github/PULL_REQUEST_TEMPLATE/*
• docs/contributing/**, docs/CONTRIBUTING*

Excluded directories: node_modules, .git, dist, build, coverage, vendor

Policy Classification

Classification	Meaning
FORBIDDEN	AI contributions explicitly prohibited
CONDITIONAL	AI contributions allowed with conditions
ALLOWED	AI contributions explicitly allowed
UNKNOWN	No explicit AI policy detected

Precedence: FORBIDDEN > CONDITIONAL > ALLOWED > UNKNOWN

Exit Codes

Code	Meaning
0	No CP001 AI prohibition detected
1	CP001 AI prohibition detected
2	CLI/configuration error

Security Model

• Target repositories are treated as untrusted input
• ContribPreflight reads text files only
• No code execution from target repositories
• No child_process, eval, dynamic import, or require of target content
• Symlinked policy files are skipped

Deterministic Heuristics

ContribPreflight uses deterministic heuristics, not AI. It:

• Does NOT determine whether code was AI-generated
• Does NOT identify which model created code
• Does NOT provide legal advice
• Does NOT guarantee complete policy interpretation
• Does NOT enforce copyright law
• Does NOT replace reading repository contribution policies
• May miss policies or occasionally classify ambiguous language incorrectly

Limitations

• Only scans a bounded set of likely policy surfaces
• Symlinked policy files are skipped
• Cannot interpret ambiguous or implicit policies
• CRLF handling normalizes line endings (line numbers reference original lines)

Who Uses This?

• Contributors checking a repository before coding
• Maintainers validating that policies are discoverable
• Coding agents receiving a deterministic preflight before repository work
• CI/tooling consuming JSON output for policy checks

Roadmap

• Broader policy phrase corpus via community-submitted fixtures
• Additional safe policy surface formats
• Richer machine-readable diagnostics
• Agent and CI workflow integrations

Contributing

Found a policy phrase ContribPreflight misses or misclassifies? Open an issue with the minimal policy wording and expected result. This is especially useful for improving deterministic heuristics.

See CONTRIBUTING.md for development setup.

License

MIT