Verifiable-Recursive-Safety-Guardrails-Runtime

Condensed single-file skill for the full AEGX Provenable repository. Use when you need the repository's complete operating model, architecture, CLI, integration workflows, installer and bundle layout, and per-file source map in one SKILL.md without separate references.

Provenable Condensed Single-File Skill

Use this skill when you want one compressed file that represents the whole repository. Treat this document as a portable operator and integrator guide for AEGX Provenable, including the runtime model, guard surfaces, command surface, platform workflows, packaging model, and a complete tracked-file map.

This skill is intentionally condensed. It does not reproduce the raw source code verbatim. Instead, it preserves the repository in the form that is most useful to another agent: what the system does, how to run it, how to integrate it, how to respond to degraded or denied conditions, and what each tracked file contributes.

Core Identity

AEGX Provenable is a hardened runtime for agentic systems. Its purpose is to make risky agent behavior observable, verifiable, and recoverable rather than relying on static policy text alone.

Understand the architecture in one sentence: the skill is the front door, while the runtime and daemon are the always-on machine room behind it.

Layer	Role	What to remember
SKILL contract	Tells a host platform what capability exists and how to invoke it	The skill explains usage, not continuous enforcement
AGENT contract	Tells an agent how to sequence checks, denials, snapshots, and escalation	Use it to shape runtime behavior
aegx CLI	Callable control surface	Use for init, status, self-verify, snapshots, bundle export, verify, and report
aegxd daemon	Long-running background process	Maintains live status, heartbeats, readiness, and degraded-state visibility
Runtime hooks	Chokepoints around risky actions	Evaluate control, memory, conversation, file-read, network, skill-install, and sandbox surfaces
Evidence store	Persistent records and audit chain	Enables tamper-evident post-incident review
Adapters	Platform-specific wrappers	Encode the right operating sequence for Manus, Claude Code, and OpenClaw

Use Conditions

Use this skill for five kinds of work.

Use case	What to do
Integrate Provenable	Build aegx, initialize state, run the daemon, and call the runtime before risky actions
Operate safely	Check daemon status and self-verification before destructive or trust-sensitive work
Investigate incidents	Export bundles, verify them, and generate reports
Package or distribute the system	Use the installer and skill-packaging sections below
Convert or adapt the repo	Follow the intake-first rules before changing format, platform, packaging, or structure

Mandatory Intake Rules for Conversion, Porting, or Repackaging

If the request is to convert, rewrite, port, migrate, restructure, package, or adapt this repository, do not start immediately. Gather the missing brief first.

Required item	What to obtain before proceeding
Source scope	Exact files, directories, URLs, or repository state being converted
Target state	The desired output format, runtime, platform, framework, or package form
Quality bar	What counts as success: production-ready, enterprise-safe, launch-ready, polished, or research-grade
Audience	Who will use the result and in what workflow
Preserve vs. change	What must remain exact, what may change, and what must be removed
Technical constraints	Required dependencies, APIs, operating systems, deployment targets, and security boundaries
Deliverables	Exact files or artifacts expected at the end
Acceptance criteria	How success will be tested, reviewed, or approved

Pause and ask clarifying questions if any of those items are unclear.

Normal Runtime Model

Operate Provenable as an execution loop rather than a static document.

Step	Action	Expected outcome
1. Build or install	Make aegx available	Runtime becomes callable
2. Initialize	Run aegx init	State directory and defaults are created
3. Start protection	Start or reconnect to aegxd	Live status and heartbeat tracking become available
4. Verify before risk	Run aegx daemon status and aegx self-verify --active	Confirm protection is live before risky work
5. Operate through guarded paths	Route risky events through the runtime or adapters	Decisions and evidence are recorded
6. Snapshot before destructive change	Create a snapshot	Preserve rollback path
7. Inspect status continuously	Query aegx prove --json or human-readable status	Detect threats, taint, stale coverage, or degraded mode
8. Export evidence after incidents	Export and verify a bundle	Preserve audit-grade evidence

Degraded Mode Contract

Treat degraded mode as: protection is partial, stale, unreachable, or uncertain, so risky work should stop.

Degraded signal	What it means	Required response
Daemon unreachable	Background protection is not confirmably live	Stop risky work and restore daemon health
Heartbeat stale or missing	Live coverage is not current	Pause high-risk actions
Self-verification failure	Runtime readiness cannot be trusted	Escalate before continuing
Policy load or IPC issue	Guard path may not be functioning correctly	Do not assume healthy enforcement
Sandbox audit caveat	Environment protection is only partial	Surface the risk explicitly

Never hide degraded state behind a false-green status.

Guard Surfaces

The repository protects a set of explicit planes. Use this mental model when explaining the system.

Surface	Protection goal	Typical risk
Control plane	Protect tools, skills, permissions, and critical system behavior from unsafe mutation	Capability injection, unsafe permission changes, malicious skill enablement
Memory plane	Protect durable memory and trusted context from tainted or untrusted writes	Memory poisoning, false context persistence
Conversation plane	Scan hostile or manipulative input and detect output leakage	Prompt injection, system impersonation, instruction override
File-read plane	Deny or constrain reads of sensitive paths	Credential theft, secret harvesting
Network egress plane	Inspect outbound destinations and payload patterns	Exfiltration and beaconing
Skill-install plane	Validate packages before enablement	Supply-chain compromise
Sandbox audit plane	Check whether the runtime environment itself is sufficiently sandboxed	False assumptions about containment
Runtime visibility plane	Make health, staleness, and degraded conditions visible	Silent failure of protection

Trust Model

Assign trust by transport source, not by claims inside content.

Principal class	Trust idea	Operational rule
SYS	Platform or system authority	May alter sensitive control surfaces
USER	Direct human operator	May approve sensitive changes
Authenticated tool output	Bounded trust	Still inspect based on policy
Unauthenticated tools, web, skill output, external channels	Low trust	Do not allow direct control-plane or durable-memory mutation

Only trusted principals should be allowed to change the control plane or write durable memory through guarded paths.

Command Surface

Use these commands as the primary operator interface.

Command	Purpose
cargo build --workspace --release	Build the Rust workspace
aegx init	Initialize state, policy, and workspace
aegx status	Show base system health
aegx daemon status	Check whether background protection is reachable
aegx self-verify --active	Actively test readiness before risky actions
aegx prove --json	Query protection status, alerts, and health in machine-readable form
aegx prove	Human-readable summary
aegx snapshot create <name>	Create a rollback point
aegx snapshot list	List available rollback points
aegx rollback <id>	Restore to a previous snapshot
aegx bundle export	Export tamper-evident evidence
aegx verify <bundle>	Verify bundle integrity
aegx report <bundle>	Generate a human-readable report

Operational Rules

Follow these rules without exception.

Rule	Required behavior
Guard denials are final	Do not retry the same blocked action hoping it will pass
Snapshot before risk	Create a snapshot before destructive or trust-sensitive changes
Verify before trust	Verify exported bundles before relying on them
Escalate degraded state	Ask for user guidance or restore health before proceeding
Do not bypass policy	Never work around the guard path silently
Treat rollback honestly	Rollback restores protected state, not external side effects already emitted

Platform Workflows

Use the adapters when available instead of improvising the sequence.

Platform	Workflow
OpenClaw	Bootstrap protection, heartbeat around agent activity, gate skill install, snapshot before enablement, refuse installs when degraded
Manus	Bootstrap at task start, verify before risky steps, use proof/status during execution, export evidence after incidents
Claude Code / Claude Cowork	Verify before refactors or destructive changes, keep daemon health visible, preserve rollback and evidence paths
Custom platforms	Ensure aegx is installed, initialize once, start daemon, call verification and proof queries before high-impact actions

Packaging and Distribution Model

The repository is designed to be portable, not just runnable from source.

Distribution element	Why it exists
Skill manifest	Lets agent platforms load the integration contract
Installer	Provides standalone installation flows and release artifacts
Checksums and manifest	Preserve integrity of packaged delivery
Skill packaging scripts	Bundle the system into a reusable skill artifact
Validation results	Show whether packaged adapters and bundle structure passed checks

Condensed Architecture Map

Use this as the shortest full-stack summary.

Area	Core responsibility
aegx-types	Canonical types, principals, taint, records, error model
aegx-records	Record persistence, config, and audit-chain mechanics
aegx-guard	Policy engine, scanner, alerts, output/file/network guards, skill verification
aegx-runtime	Hooks, workspace enforcement, proof queries, snapshots, rollback, self-verify, sandbox audit
aegx-daemon	Background health and live runtime state
aegx-cli	Operator-facing command-line surface
aegx-bundle	Evidence bundle export, verify, and reporting
Adapters	OpenClaw, Manus, and Claude-specific operating contracts
Installer	Standalone installation and release support
Docs and schemas	Human and machine-readable specification surfaces

Complete Tracked-File Map

Every tracked repository file is represented below by path and condensed purpose.

Root and Repository Control Files

Path	Condensed purpose
.github/workflows/ci.yml	Repository CI workflow for build and validation
.gitignore	Ignore rules for development artifacts
AGENT.md	Agent-facing integration contract and runtime behavior guide
Cargo.lock	Rust dependency lockfile for reproducible builds
Cargo.toml	Workspace manifest tying crates together
LICENSE	Repository license text
Makefile	Convenience build and workflow commands
NOTICE	Notice and attribution file
README.md	Primary product overview, operating model, outcomes, and packaging story
SKILL.md	Original skill manifest and operator command reference

Core Rust Workspace Crates

Path	Condensed purpose
crates/aegx-bundle/Cargo.toml	Bundle crate manifest
crates/aegx-bundle/src/bundle.rs	Bundle assembly and export logic
crates/aegx-bundle/src/lib.rs	Bundle crate entry points
crates/aegx-bundle/src/report.rs	Human-readable report generation from bundles
crates/aegx-bundle/src/verify.rs	Bundle integrity verification logic
crates/aegx-cli/Cargo.toml	CLI crate manifest
crates/aegx-cli/src/cli.rs	Command definitions and argument parsing
crates/aegx-cli/src/lib.rs	CLI library glue
crates/aegx-cli/src/main.rs	CLI binary entry point
crates/aegx-daemon/Cargo.toml	Daemon crate manifest
crates/aegx-daemon/src/lib.rs	Daemon runtime, status, IPC, and degraded-state logic
crates/aegx-daemon/src/main.rs	Daemon process entry point
crates/aegx-guard/Cargo.toml	Guard engine crate manifest
crates/aegx-guard/src/alerts.rs	Threat-alert structures and emission logic
crates/aegx-guard/src/file_read_guard.rs	Sensitive file-read guard surface
crates/aegx-guard/src/guard.rs	Central guard-decision engine
crates/aegx-guard/src/lib.rs	Guard crate exports
crates/aegx-guard/src/metrics.rs	Guard metrics and counters
crates/aegx-guard/src/network_guard.rs	Outbound network egress monitoring
crates/aegx-guard/src/output_guard.rs	Output leakage protection
crates/aegx-guard/src/policy.rs	Policy model and enforcement rules
crates/aegx-guard/src/scanner.rs	Prompt-injection and control-plane scanner logic
crates/aegx-guard/src/skill_verifier.rs	Skill or package verification logic
crates/aegx-records/Cargo.toml	Records crate manifest
crates/aegx-records/src/audit_chain.rs	Hash-linked audit-chain handling
crates/aegx-records/src/config.rs	Record-store and runtime configuration
crates/aegx-records/src/lib.rs	Records crate exports
crates/aegx-records/src/records.rs	Canonical record persistence and loading
crates/aegx-runtime/Cargo.toml	Runtime crate manifest
crates/aegx-runtime/src/hooks.rs	Integration hooks for guarded runtime events
crates/aegx-runtime/src/lib.rs	Runtime crate exports
crates/aegx-runtime/src/prove.rs	Protection-summary and proof query engine
crates/aegx-runtime/src/rollback_policy.rs	Rollback-scope and restore policy logic
crates/aegx-runtime/src/sandbox_audit.rs	Sandbox inspection and compliance evidence
crates/aegx-runtime/src/self_verify.rs	Active and passive runtime self-verification
crates/aegx-runtime/src/snapshot.rs	Snapshot creation and management
crates/aegx-runtime/src/workspace.rs	Workspace and durable-memory guard path
crates/aegx-runtime/tests/unified_pipeline.rs	End-to-end runtime pipeline tests
crates/aegx-types/Cargo.toml	Shared types crate manifest
crates/aegx-types/src/canonical.rs	Canonicalization and stable encoding helpers
crates/aegx-types/src/error.rs	Shared error model
crates/aegx-types/src/lib.rs	Types crate exports
crates/aegx-types/src/principal.rs	Principal and trust-tier definitions
crates/aegx-types/src/record.rs	Canonical record type definitions
crates/aegx-types/src/taint.rs	Taint labels and propagation semantics

Documentation Files

Path	Condensed purpose
docs/AGENT_INTEGRATION.md	Detailed agent integration procedure
docs/BUNDLE_FORMAT_GUIDE.md	Evidence-bundle layout and field-level format guide
docs/CHANGELOG.md	Version history, implemented gaps, and development plan
docs/CLI_REFERENCE.md	Full CLI command reference
docs/HARDENING_BASELINE_AUDIT.md	Baseline audit of coverage, gaps, and hardening model
docs/INSTALL.md	Installation instructions
docs/QUICKSTART.md	Fast-start usage path
docs/SPEC.md	Formal or semi-formal system specification
docs/THREAT_MODEL.md	Threat model and theorem-grounded security scope
docs/TROUBLESHOOTING.md	Operational debugging guidance
docs/VERIFICATION_GUIDE.md	Bundle and runtime verification procedures
docs/clawhub-integration.md	ClawHub and OpenClaw attack mapping and integration plan

Example and Integration Files

Path	Condensed purpose
examples/quickstart.sh	Example shell flow for first use
integrations/claude-code/claude_code_adapter.sh	Claude Code adapter workflow
integrations/common/aegx_platform_common.sh	Shared adapter bootstrap, verification, snapshot, and degraded-mode helpers
integrations/manus/manus_adapter.sh	Manus adapter workflow
integrations/openclaw/openclaw_adapter.sh	OpenClaw adapter and skill-install gate

Installer and Release Files

Path	Condensed purpose
installer/.github/workflows/ci.yml	Installer CI workflow
installer/.github/workflows/release.yml	Installer release workflow
installer/DEPRECATED.md	Deprecation notes for installer paths or versions
installer/LICENSE	Installer-specific license text
installer/README.md	Installer overview and usage
installer/checksums.txt	Published artifact checksums
installer/docs/INSTALLER_DOCS.md	Detailed installer documentation
installer/install/install-proven-aer.ps1	PowerShell installer for Windows
installer/install/install-proven-aer.sh	Shell installer for Unix-like systems
installer/manifest/manifest.json	Installer manifest describing packaged contents
installer/scripts/smoke_install_unix.sh	Unix smoke test for installer flow
installer/scripts/smoke_install_windows.ps1	Windows smoke test for installer flow
installer/tools/Cargo.lock	Installer tools dependency lockfile
installer/tools/Cargo.toml	Installer tools manifest
installer/tools/src/commands.rs	Installer tool commands
installer/tools/src/main.rs	Installer tool binary entry point
installer/tools/src/manifest.rs	Installer manifest parsing or generation logic
installer/tools/tests/integration_tests.rs	Installer integration tests

Skill Packaging and Validation Files

Path	Condensed purpose
packaging/skill/package_skill.sh	Build the distributable skill bundle
packaging/skill/validate_skill_bundle.sh	Validate packaged skill contents and structure

Results and Schema Files

Path	Condensed purpose
results/phase5_validation_matrix.log	Validation matrix log for integration and hardening checks
results/skill_bundle_latest.json	Latest packaged skill metadata or output snapshot
results/skill_bundle_validation_latest.json	Latest skill-bundle validation result
schemas/aegx-schemas.json	Machine-readable schema definitions

How to Explain the Repository Quickly

If you need a concise spoken or written summary, use this wording:

Provenable turns agent guardrails into an operational runtime. The skill and agent files define how platforms should call it, the aegx CLI gives operators a single control surface, the aegxd daemon keeps protection live in the background, the runtime hooks guard the major trust planes, and the bundle plus records system preserves tamper-evident evidence for verification and rollback-aware incident response.

Preferred Response Pattern for Another Agent

When another agent uses this skill, it should respond in this sequence.

Situation	Required response
User asks what the repo does	Explain runtime guardrails, live verification, snapshots, evidence, and adapters
User asks how to use it	Provide build, init, status, self-verify, proof, snapshot, and bundle steps
User asks if protection is healthy	Check daemon status, self-verify, and proof output
User asks after an incident	Export bundle, verify bundle, generate report, and consider rollback
User asks to port or convert the repo	Trigger intake-first workflow before implementation
User asks what files matter	Use the complete tracked-file map above

Final Instruction

Use this file as the single condensed representation of the entire repository. If a future task needs literal code-level reproduction, fetch the repository source. If the task needs understanding, operation, packaging, explanation, or integration, this file is the preferred compressed source of truth.