These docs capture durable Pushgate knowledge: domain language, architecture, reference contracts, and decisions that explain why the system has its current shape.
They complement source comments and TSDoc. Do not remove useful code comments just because related reference material exists here.
The docs are intentionally not an issue tracker. Temporary implementation plans, refactor prompts, demo notes, and ticket briefs should live outside this directory unless they are distilled into one of the maintained doc types below.
- Domain Model explains what Pushgate is in product terms.
- Domain Glossary defines the canonical language used in code, docs, and tickets.
- Architecture Overview gives the system map.
- Runtime Flow follows one push from Git hook to final local verdict.
- Module Map lists the main modules and stable interfaces.
Architecture decisions live in ADR:
- 0001 - Local Hook Delegates To Managed Runner
- 0002 - Local Gate Is Not Final Enforcement
- 0003 - Strict V2 Config With Normalized Defaults
- 0004 - Centralized Changed-File Resolution
- 0005 - Provider-Neutral Local AI Review Contract
- 0006 - Checked-In Generated Runner
- Configuration Reference documents
.pushgate.yml. - Changed-File Policy documents Git range, ignore, and live-path semantics.
- Local AI Review documents provider behavior, guardrails, and the structured output contract.
- Distribution Runner documents
bin/pushgate.mjsand regeneration.
Keep these docs current as the product changes:
- Domain model: update when user-facing terms or push-gate outcomes change.
- ADRs: add one only when a decision is hard to reverse, non-obvious without context, and the result of a real trade-off.
- Architecture docs: update when module responsibility or runtime order changes.
- Reference docs: update alongside schema, provider, path-policy, or distribution changes.
- Support diagnostics: add a focused reference doc when helper commands, debug artifacts, or support workflows become part of the product.
- CI/PR parity: add a focused doc when Pushgate starts emitting or checking remote enforcement guidance.
Do not keep one-off implementation plans, refactor wishlists, delegated-agent briefs, generated analysis exports, or ticket drafts in this directory. If they contain a lasting decision, promote that decision into an ADR or reference doc and delete the draft.