Add knowledge docs, agent definitions, and skill files

Add comprehensive documentation and GitHub Copilot configuration:

- docs/knowledge/: 17 deep-dive knowledge files covering value semantics,
  RVM architecture, builtins, FFI boundary, feature composition, error
  handling migration, policy evaluation security, Rego semantics,
  interpreter/compiler architecture, Azure Policy/RBAC, engine API,
  time builtins, language extension guide, tooling architecture,
  causality/partial eval, Rego compiler, Azure Policy aliases, and
  telemetry/diagnostics

- .github/agents/: 16 role-specific AI agent definitions (red-teamer,
  semantics-expert, architect, performance-engineer, test-engineer,
  verification-engineer, security-auditor, reliability-engineer,
  support-engineer, ci-engineer, refactorer, api-steward, program-manager,
  demo-engineer, dx-engineer, tech-lead)

- .github/skills/: 6 workflow skill definitions (thorough-review,
  design-alternatives, add-builtin, opa-conformance, security-review,
  verification)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Co-authored-by: anakrish <35780660+anakrish@users.noreply.github.com>
This commit is contained in:
copilot-swe-agent[bot]
2026-04-25 21:20:10 +00:00
committed by GitHub
parent 3d16489ec6
commit 524aab5528
42 changed files with 6773 additions and 0 deletions
+143
View File
@@ -0,0 +1,143 @@
---
name: verification
description: >-
Formal verification and memory safety verification for regorus. Use this
skill when asked about Miri, formal verification, Z3, Verus, property
testing, or when verifying safety properties of regorus code.
allowed-tools: shell
---
# Verification Skill
regorus uses multiple verification approaches to ensure correctness and
memory safety. This skill guides verification efforts.
## Verification Tiers
### Tier 1: Miri (Active — in CI)
Miri detects undefined behavior in unsafe code, memory leaks, and
concurrency bugs. regorus runs Miri in CI.
```bash
# Run Miri on the test suite
cargo +nightly miri test
# Run Miri on specific tests
cargo +nightly miri test -- test_name
# Run with stricter checks
MIRIFLAGS="-Zmiri-strict-provenance" cargo +nightly miri test
```
**What Miri catches:**
- Use-after-free, double-free
- Out-of-bounds memory access
- Uninitialized memory reads
- Data races (with `-Zmiri-check-stacked-borrows`)
- Memory leaks
**regorus context:** The core crate is `#![forbid(unsafe_code)]`, so Miri
is most relevant for FFI binding crates (`bindings/ffi/`) where unsafe is
allowed. Also useful for verifying `Rc::make_mut()` patterns.
### Tier 2: Property Testing (Recommended)
Use `proptest` or `quickcheck` to test properties that must hold for all
inputs:
```rust
use proptest::prelude::*;
proptest! {
#[test]
fn value_roundtrip(v in arb_value()) {
let json = v.to_json_str();
let parsed = Value::from_json_str(&json)?;
prop_assert_eq!(v, parsed);
}
#[test]
fn eval_deterministic(policy in arb_policy(), input in arb_input()) {
let r1 = engine.eval(&policy, &input)?;
let r2 = engine.eval(&policy, &input)?;
prop_assert_eq!(r1, r2);
}
}
```
**Properties worth testing in regorus:**
- Value serialization round-trips
- Evaluation determinism (same input → same output)
- Interpreter/RVM equivalence (both paths produce same result)
- Undefined propagation consistency
- Resource limit enforcement (instruction budget halts execution)
- RVM program serialization round-trips
### Tier 3: Z3 / SMT Solving (Planned)
For verifying policy properties symbolically:
- **Policy satisfiability**: is there any input that satisfies this policy?
- **Policy equivalence**: do two policies produce the same result for all inputs?
- **Policy subsumption**: does policy A imply policy B?
- **Unreachable rules**: are there rules that can never fire?
This connects to the partial evaluation vision in
`docs/knowledge/causality-and-partial-eval.md`.
### Tier 4: Verus (Planned)
Verus enables verified Rust — proving properties about Rust code at
compile time. Potential targets in regorus:
- **Value type invariants**: prove that Value operations preserve type safety
- **RVM instruction safety**: prove that well-formed programs cannot cause
register overflow or invalid memory access
- **Scheduler correctness**: prove that topological sort produces valid order
- **Resource limit enforcement**: prove that instruction budget is checked
## Verification Strategies by Subsystem
### Value Type (`src/value.rs`)
- Property test: all operations handle Undefined correctly
- Property test: comparison is total ordering
- Property test: serialization round-trips for all Value variants
- Miri: Rc::make_mut patterns don't alias
### RVM (`src/rvm/`)
- Property test: program serialization round-trips
- Property test: instruction budget halts execution within bounds
- Property test: register allocation stays within frame bounds
- Miri: frame stack operations are memory-safe
### FFI (`bindings/ffi/`)
- Miri: handle create/destroy cycles don't leak
- Miri: panic containment doesn't cause UB
- Property test: poisoned engine rejects all operations
### Builtins (`src/builtins/`)
- Property test: builtins return Undefined (not error) for type mismatches
- Property test: time parsing matches OPA reference for valid inputs
- Property test: string operations handle UTF-8 edge cases
## Running Verification
```bash
# Tier 1: Miri
cargo +nightly miri test
# Tier 2: Property tests (if added)
cargo test --test prop_tests
# Full verification suite
cargo +nightly miri test && cargo test && cargo test --test opa --features opa-testutil
```
## Reference
- `docs/knowledge/policy-evaluation-security.md` — Security properties to verify
- `docs/knowledge/value-semantics.md` — Value invariants
- `docs/knowledge/rvm-architecture.md` — RVM safety properties
- `docs/knowledge/ffi-boundary.md` — FFI safety requirements
- `docs/knowledge/causality-and-partial-eval.md` — Symbolic analysis vision