Guarded Agentic Compaction / Contributing

Contribute evidence, not just features.

Every contribution should preserve the fail-closed contract: missing state, unknown effects, incompatible manifests, or inadequate support must never become a live rewrite.

High-value contribution areas

Trace adapters

Normalize another framework into typed Episodes without leaking framework-specific semantics into compiler passes.

Benchmark evidence

Add executable, revision-pinned traces with observed results, independent groups, effect contracts, and replay oracles.

Failure tests

Add drift, permission, partial-failure, guardrail, invalidation, retry, rollback, and adversarial effect-declaration cases.

Development setup

git clone https://github.com/rrahimi-uci/guarded-agentic-compaction.git
cd guarded-agentic-compaction
python -m venv .venv
.venv/bin/pip install -e '.[dev,live,figures]'
.venv/bin/python -m pytest

Engineering standards

  • Keep the framework-neutral Episode and artifact schemas backward compatible when practical
  • Add focused tests for every behavior change; safety boundaries need mutation or fault-injection coverage
  • Use deterministic identifiers and group-level splits; never count repeated variants as independent support
  • Preserve negative outcomes, rejection reasons, unavailable prerequisites, and substrate labels
  • Never serialize API keys, restricted prompts, customer payloads, or private traces
  • Regenerate derived tables, figures, manifests, documentation, and slide decks from their source flow

Benchmark contribution contract

A benchmark name is not an integration. A proposed adapter should document:

  1. exact upstream revision, license, checksums, and acquisition path;
  2. task, group, and partition identity;
  3. whether arguments and outputs are observed or only proposed;
  4. effect classifications and who owns their truth;
  5. the replay, execution, or final-outcome oracle;
  6. the precise claim the path licenses—and what it does not.

Gold plans without tool results may test parsing or official-checker compatibility. They must not be converted into compiler episodes or counted as failed compilations.

Pull-request checklist

.venv/bin/python -m pytest
.venv/bin/python scripts/verify_release.py
.venv/bin/python paper/scripts/build_artifacts.py
.venv/bin/python paper/scripts/validate_artifacts.py
.venv/bin/python scripts/build_pages.py --output _site
.venv/bin/python -m build

Describe the evidence boundary, compatibility impact, tests, and generated artifacts in the pull request. If a change alters promotion, effects, fallback, or statistical admission, include a focused threat analysis.

Conduct and security

Be specific, constructive, and evidence-led. Do not use public issues for vulnerabilities, credentials, production traces, personal data, or exploit payloads. Report security concerns through the repository host's private security-advisory feature.

Decision principles

  • Safety and evidence boundaries outrank apparent benchmark coverage
  • Simple, inspectable mechanisms outrank opaque optimization when quality is tied
  • Backward compatibility matters, but never at the cost of silently weakened refusal
  • Measured limitations belong in the main narrative, not hidden in issue history