praxis-guard

GitHub App for traceability & decision governance (Praxis Guard)

Overview

Praxis Guard is a GitHub App that enforces traceability and decision governance for code repositories.

Phase 1 focuses on deterministic (non-LLM) PR checks plus repo-local conventions:

• Deterministic PR checks for decision-bearing changes
• Repo-local ledger conventions (/praxis-ledger)
• Contract/invariant validation (Phase 1 baseline)
• Traceability docs generation (Markdown / Mermaid)

Install

Note: this repo is an early-stage GitHub App. For local development and testing, see Development below.

Development

Prerequisites

• Node.js 18+ and npm
• A GitHub account
• (Optional) A GitHub App for testing webhooks and check runs

Setup

git clone https://github.com/plures/praxis-guard.git
cd praxis-guard
npm install
npm run build
npm test

Run locally

npm run dev

Server starts on http://localhost:3000.

Without GitHub App credentials, you can still iterate on the deterministic rule engine logic; check-run creation requires credentials.

GitHub App setup (optional)

1. Create a GitHub App: https://github.com/settings/apps
2. Configure permissions (minimum viable):
   • Checks: Read & write
   • Contents: Read-only
   • Pull requests: Read-only
3. Subscribe to events:
   • Pull request
   • Pull request review
   • Check suite
4. Export env vars:

export GITHUB_APP_ID=your_app_id
export GITHUB_PRIVATE_KEY="$(cat path/to/private-key.pem)"
export WEBHOOK_SECRET=your_webhook_secret

Then install the app on a test repo and use a webhook proxy (e.g. https://smee.io) to forward events to your local server.

Contributing

This is early-stage. Issues and PRs welcome.

Helpful docs:

• Roadmap
• Ledger conventions

License

MIT