Thank you for your interest in contributing! FORGE is built on a spec-driven, test-first workflow. This guide walks through everything from setting up your environment to getting a PR merged.
- Rust stable 1.93.0 or later (rustup)
- Git for version control
- cargo-audit —
cargo install cargo-audit --locked - cargo-deny —
cargo install cargo-deny --locked - cargo-vet —
cargo install cargo-vet --locked
git clone https://github.com/policy-forge/forge.git
cd forge
cargo buildVerify everything works end-to-end:
# Quick smoke test: produce JSON output
cargo run -- convert tests/fixtures/sample_policy.md --strategy catalog --format jsonA local pre-commit hook runs format, lint, and test on every commit:
./scripts/install-hooks.shTo bypass it once: SKIP_FORGE_PRECOMMIT=1 git commit -m "...".
For stricter checks (bench + audit + deny): FORGE_PRECOMMIT_STRICT=1 git commit -m "...".
Before opening a PR, replicate the CI pipeline:
./scripts/ci-local.shThe maintained local CI script runs format, all-target Clippy, tests, the API contract gate, cargo audit, cargo deny check and cargo vet --locked. Each enabled gate must pass. Set CI_LOCAL_BENCH=1 to add the optional local benchmark; check the script and workflow for exact commands.
FORGE uses a structured specification process that produces living documents checked into the repo alongside the code. Every feature starts as a spec.
specs/ # All feature specifications
NNN-feature-name/
spec.md # Feature specification (user stories, acceptance criteria)
plan.md # Implementation plan (technical context, constitution check, project structure)
tasks.md # Task breakdown (phased, checkpoints, per-story grouping)
research.md # Phase 0: research and decision logs
data-model.md # Phase 1: data model design
quickstart.md # Phase 1: API surface and example usage
contracts/ # Phase 1: Rust interface contracts
checklists/
requirements.md # Quality checklist
Supporting documents are generated into docs/:
docs/
PRD/NNN-prd-*.md # Product Requirement Documents
SEC/NNN-sec-*.md # Security review
AR/NNN-ar-*.md # Architecture Review
- Pick the next work item number from
docs/FORGE_PRODUCT_ROADMAP.md. - Create the spec directory:
specs/NNN-brief-name/(use the WI number, zero-padded to 3 digits). - Write
spec.mdwith user stories and acceptance scenarios. Model from existing specs likespecs/043-diff-report/spec.md. - Write
plan.mdwith technical context, constitution check, and project structure. Model fromspecs/043-diff-report/plan.md. - Generate supporting docs: PRD, SEC, AR, research, data-model, quickstart, contracts.
- Write
tasks.md: phased task breakdown with checkpoints, grouped by user story. - Open a PR for the spec documents first (or commit them as the first commit on your feature branch).
Every plan.md must pass the project's 11-point constitution check before implementation begins. See any existing plan.md for the template. The check covers: crate-first architecture, Rust-first implementation, contract-first development, test-first development, complete requirement delivery, performance/scope discipline, security-first design, error handling standards, observability, simplicity, and dependency policy.
cargo test # All tests (unit + integration)
cargo test --all # Same — runs all tests (workspace-compatible alias)
cargo test --lib # Library unit tests only
cargo test --doc # Documentation tests
cargo test <test_name> # Run a single test by name (e.g., `cargo test diff_added`)FORGE targets zero test failures. As of v1.0.0, there are 1,433 passing tests across 24 integration test files and extensive unit tests.
Snapshots use the insta crate. Snapshot files in tests/snapshots/ are checked into git. When you change serialization output:
cargo test # Tests that change snapshots will FAIL
cargo insta review # Interactively review and accept new snapshots
cargo test # Verify everything passescargo bench # All benchmarks
cargo bench --bench pipeline_benchmark # Pipeline benchmark onlyBenchmarks use Criterion. The workflow invokes the pipeline benchmark with its maintained configuration; the local CI script includes it only with CI_LOCAL_BENCH=1. Do not treat a fixed three-second run as the current CI contract.
cargo mutants # Requires cargo-mutants- TDD is mandatory — write tests before implementation.
- Library code uses
ForgeError(thiserror); binary code (main.rs) usesanyhow. - Avoid
unwrap()/expect()in library code — propagate errors with?. - Integration tests live in
tests/*.rswith one file per feature area. - Test fixtures are in
tests/fixtures/; shared helpers intests/common/. - Use
instafor snapshot (golden-file) testing of JSON/XML/YAML output.
- Fork the repo or create a branch directly.
- Create a feature branch from
mainnamedNNN-short-name(matching the spec directory):git checkout -b 044-my-feature. - Commit spec documents as your first commit(s).
Follow conventional commits with a work-item prefix:
feat(wi-044): add summary dashboard subcommand
Implemented `forge summary` that prints pipeline statistics and
conversion metadata to stderr. Added 12 tests.
Closes WI-44
Prefixes: feat, fix, docs, test, refactor, chore, ci.
Include the work item number when applicable.
Run the full CI pipeline locally and verify all gates pass:
./scripts/ci-local.shThe script prints each enabled command. The benchmark appears only when
CI_LOCAL_BENCH=1; use the retained raw check output to determine which gates
actually passed rather than treating this guide as an execution transcript.
A PR that fails CI will not be reviewed. Save reviewer time by running locally first.
- Rust edition 2024, max width 100 columns (see
.rustfmt.toml). clippy::all+clippy::pedanticenabled inCargo.toml.unsafe_code = "warn"— avoid unsafe Rust.- Core conversion and embedded validation are offline; the explicit loopback workspace and configured external tools have separate documented boundaries.
- New crate dependencies require prior approval and a supply-chain entry. Check existing alternatives and record the crate, reason and approver in the introducing PR/PRD; see AGENTS.md and PRD 069.
- Spec first: ensure
spec.md,plan.md, andtasks.mdexist and match the implementation. - Tests: every user story must have corresponding tests. TDD is the expectation.
- Zero warnings:
cargo clippy -- -D warningsmust pass clean. - Zero format violations:
cargo fmt --checkmust pass clean. - Security: no vulnerabilities (
cargo audit), allowed licenses only (cargo deny check). - Maintainers may request changes; address them in the same branch.
- Update
CHANGELOG.mdwith your changes under the appropriate version header. - Mark tasks as done in the spec's
tasks.md(checkboxes:[x]).
src/
main.rs # CLI entry point
lib.rs # Public API re-exports
cli/ # Conversion utilities and current domain command dispatch
pipeline.rs # Catalog pipeline orchestrator
model/ # Core domain types
oscal/ # OSCAL data structures (catalog, component, profile, assessment_plan)
parse/ # Markdown → PolicyDocument
export/ # Format conversion (JSON ↔ XML ↔ YAML)
validate/ # JSON schema validation
diff/ # Artifact diff report
trace/ # Traceability report generation
summary/ # Conversion statistics dashboard
batch/ # Parallel batch conversion (rayon)
round_trip/ # Format round-trip serialization support
parameter/ # Parameter extraction from policy prose
oscal_cli/ # Profile resolution subcommand
testing/ # Test helpers (doc(hidden))
applicability/ # Framework applicability and policy-gap analysis
assessment_results/ # Human-authored Assessment Results and review
authoring/ # Human-assigned plans and traceable skeletons
framework/ # Read-only framework revision impact
lifecycle/ # Local lifecycle records and review queues
linkage/ # Evidence and implementation linkage
mapping/ # Human-reviewed Control Mapping
migration/ # Read-only policy revision analysis
policy/ # Hash-pinned Markdown component composition
reuse/ # Read-only local corpus retrieval
suggest/ # Quarantined offline suggestion contracts
workspace/ # Confined queries, preparation and confirmed single-file effects
tests/ # Integration tests
fixtures/ # Sample input files
snapshots/ # insta golden files (checked in)
common/ # Shared test utilities
specs/ # Feature specifications (spec.md, plan.md, tasks.md, ...)
docs/ # PRD, SEC, AR documents and roadmap
schemas/ # OSCAL JSON schemas (compile-time embedded)
scripts/ # ci-local.sh, pre-commit.sh, install-hooks.sh
benches/ # Criterion benchmarks
example_data/ # 25 sample policies
If you're stuck, open a draft PR with what you have and describe the blocker. The spec documents themselves are the best source of truth — check specs/ for how prior features were designed.
License: MIT — your contributions will be licensed under the same terms.