RAF — Rust Agentic Foundations

RAF is a set of dev-dependency libraries and cargo subcommands, not yet published, that keep Rust repositories free of duplicated helpers and keep their documentation an accurate, current account of the system. A census finds near-duplicate helper code and ratchets recorded debt down; a spec-first workplan reconciles capability documents with the code, tests and examples that implement them. Both are built to be driven by humans and coding agents alike, and both fail hard with a message that says how to fix the problem.

Crates

Delivered contracts and the remaining Census designs are listed in the capability catalogue, with resolved bindings and generated verification matrices. This repository runs the workplan gate on itself (tests/self_workplan.rs) and runs the production Census gate over its workspace and fuzz roots (tests/self_census.rs). The canonical helpers-ledger.ttl and census-debt.ttl hold its policy and exact adopted duplication. The use-path resolution of raf-source is checked against rustc on generated programs (crates/raf-source/tests/rustc_oracle.rs). raf-workplan delivers its document model, generated documentation blocks, reconcile step, verify and completion gate, entity history, execution evidence and its claims, prose assessments, two-way coverage and the current-rationale check, and cargo-workplan runs check, status, docs sync|preview, change new|impact|reconcile|complete, verify, history, evidence record|claims|for, assess and coverage code|tests: their contract is stated in workplan-cli. The complete policy is delivered and applies to every check, reconciliation and completion. It enforces section content, package ownership, claims, line coverage and change outcomes, with explicit debt recording that can only shrink.

raf-census delivers normal form 1, fingerprints, grouping, canonical RDF reports, the strict ledger, the production Gate, counted debt and bounded migration. cargo-census supplies registered check, job, count and fingerprint queries, migrate and direct debt --write. Complete detector/provider execution retains its own capability state in the catalogue.

Crate	Kind	Purpose	Status	Specification
raf-okf	library	Reads and writes the RAF profile of OKF documents.	delivered	okf-profile
raf-rdf	library	Canonical ground RDF 1.2 reports over native PurRDF storage.	delivered	rdf-report-profile
raf-source	library	Indexes Rust source so tools can bind documents to code.	delivered	source-index
raf-census	library	The duplicate-helper census, strict ledger, counted debt, migration and Gate.	delivered for the capabilities listed — not yet published	census-normal-form, census-ledger, census-debt-ratchet, census-migration
cargo-census	cargo subcommand	Runs registered checks and native job, count and fingerprint queries, migrates ledgers and writes admitted debt through the production Gate.	complete command interface delivered — not yet published	census-migration, census-debt-ratchet, census-cli
raf-workplan	library	The workplan document model, generated documentation blocks, reconcile step, completion gate, entity history, evidence and claims, prose assessments, two-way coverage and current rationale.	delivered for the capabilities listed — not yet published	workplan-document-model, workplan-generated-docs, workplan-reconcile, workplan-complete-gate, workplan-entity-history, workplan-evidence-claims, workplan-prose-assessment, workplan-two-way-coverage, workplan-current-rationale
cargo-workplan	cargo subcommand	Runs the workplan from the command line.	delivered — not yet published	workplan-cli

Usage

A project consumes RAF as dev-dependencies. The workplan gate runs on this repository. A repository binary or xtask can install the Census Gate with its registered rules and extensions. For read-only registered checking, expose that Gate in an example and run cargo census check --package PACKAGE --example EXAMPLE. Native job, count and fingerprint queries use the same registered Gate. Migration and direct debt commands use the same library paths. The crates are not published yet.

[dev-dependencies]
raf-workplan = "0.1"

// tests/workplan.rs
#[test]
fn workplan_is_reconciled() {
    raf_workplan::Gate::workspace(env!("CARGO_MANIFEST_DIR"))
        .assert_clean();
}

The census gate, once built, takes the same shape:

[dev-dependencies]
raf-census = "0.1"

// tests/census.rs
#[test]
fn no_new_duplicate_helpers() {
    raf_census::Gate::workspace(env!("CARGO_MANIFEST_DIR"))
        .assert_clean();
}

Development

The supported target through the 0.9 release is the primary native Linux target. Additional targets are subject to reassessment after that release; see supported targets.

See CONTRIBUTING.md. Run make check before sending a change and make hooks once to install the pre-commit hook. Agents should also read AGENTS.md.

Licensing

Code is licensed MIT OR Apache-2.0 OR MulanPSL-2.0, and documentation is licensed CC-BY-4.0. See LICENSING.md for the full statement.

Brand

The name, logo and colour system are described in docs/BRAND.md.