Epic: Assimilate Guardrails AI as an Ouroboros-native agentOS capability

[shaun0927]

Summary

Create an Ouroboros-native plugin/adaptation layer for guardrails-ai/guardrails that preserves the Guardrails user experience while translating Guardrails capabilities into the Ouroboros plugin contract: explicit commands, declared capabilities, scoped permissions, audit/provenance events, durable state, and handoff artifacts.

The goal is not to reduce Guardrails to a thin shell wrapper. The goal is to make Guardrails feel like Guardrails inside Ouroboros while letting Ouroboros act as a true agentOS: a substrate that can run external capability systems smoothly, safely, audibly, and resumably.

Related context: #27 defines the plugin layer as the capability assimilation layer for external tools, OSS libraries, and domain workflows.

Product Goal

A user who already understands Guardrails should be able to bring the same mental model into Ouroboros:

• define or reference a Guardrails guard/spec/config;
• install or use Guardrails validators where appropriate;
• validate LLM inputs, outputs, or generated artifacts;
• inspect familiar Guardrails-style validation outcomes;
• optionally use Guardrails server-style flows;
• receive normalized Ouroboros evidence, audit, provenance, state, and handoff artifacts without losing the original Guardrails workflow feel.

In short:

Guardrails experience
  + Ouroboros plugin contract
  + Seed / Ledger / State / Provenance / Permission / Audit / Handoff
  = Guardrails as an Ouroboros-native agentOS capability

Why This Belongs in ouroboros-plugins

Guardrails is a strong reference candidate for the open-source library assimilation model described in #27:

• It is an external OSS capability system, not an Ouroboros core primitive.
• It has a clear domain: LLM input/output validation, risk detection, structured-output enforcement, and validator composition.
• It has multiple execution surfaces: Python SDK, CLI, Hub validators, and optional server mode.
• It requires careful boundary management around file reads/writes, network access, dependency installation, model downloads, and possible remote inference.
• It can produce high-value downstream evidence for ooo auto, Seed validation, artifact review, eval loops, and agent run acceptance gates.

This should prove a reusable pattern for future validation/evaluation adapters such as Semgrep, CodeQL, pytest, Hypothesis, mutation testing, OpenAPI validators, and other external harnesses.

Core Thesis

Do not implement this as:

ooo guardrails raw -- <anything>

Implement it as:

Guardrails guard/spec/config
  + bounded artifact/input/output target
  + declared plugin command
  + declared permissions
  + Guardrails ValidationOutcome
  + normalized Ouroboros report
  + audit/provenance/state updates
  + handoff artifact

The plugin should preserve Guardrails semantics while making every invocation legible to Ouroboros.

Guardrails Capabilities to Assimilate

Primary Capability: Validation Harness

Assimilate Guardrails as an LLM validation harness:

• validate known LLM output;
• validate generated artifact content;
• validate input/output text using configured validators;
• produce pass/fail/blocking evidence;
• expose validator summaries and remediation information;
• generate a handoff artifact for downstream Ouroboros workflows.

This should be the MVP.

Secondary Capability: Structured Output Contract Checking

Guardrails supports structured-output generation/validation using Pydantic/RAIL-style specs. The plugin should eventually support using Guardrails as an artifact contract checker for generated JSON, structured reports, and Seed-derived outputs.

Tertiary Capability: Hub/Validator Lifecycle

Guardrails Hub validators are powerful but require stricter permission boundaries. Hub installation should be optional and separated from read-only validation commands.

Tertiary Capability: Server Mode

Guardrails server mode may be valuable for long-running agentOS integrations, but it should be treated as a later lifecycle/runtime feature, not the MVP.

UX Principle: Preserve Guardrails Experience

The plugin should not force users to abandon Guardrails idioms. It should support familiar concepts and names where possible:

• Guard
• validator
• RAIL/spec/config
• validate / parse
• ValidationOutcome
• validation summaries
• Hub validator URI
• local model vs remote inference choices, if/when supported

However, every familiar Guardrails operation must be projected into the Ouroboros contract.

Example desired UX:

# Validate a known LLM output with a Guardrails spec and emit an Ouroboros report.
ooo guardrails validate-output \
  --spec ./guards/toxic-language.rail \
  --output ./.omx/artifacts/model-output.txt \
  --report ./.omx/reports/guardrails-toxic-language.json

# Validate an Ouroboros artifact and attach the result as a handoff/evidence bundle.
ooo guardrails validate-artifact \
  --spec ./guards/structured-report.py \
  --artifact ./.omx/artifacts/research-summary.md \
  --handoff ./.omx/handoffs/guardrails-research-summary.json

The report should still make it easy to recognize the Guardrails outcome, but Ouroboros should also be able to consume it.

Proposed Plugin Name and Namespace

Candidate plugin names:

• guardrails-eval
• llm-guardrails
• guardrails-ai

Recommended MVP:

Plugin name: guardrails-eval
Command namespace: guardrails

Rationale: the plugin is an evaluation/validation adapter, not a full replacement for Guardrails Hub or server management.

Proposed Command Surface

MVP Commands

ooo guardrails validate-output

Validate a known LLM output string/file against a Guardrails spec/config.

Inputs:

• --spec <path>: repo-relative Guardrails RAIL/spec/config path;
• --output <path> or --text <string>: target output to validate;
• --metadata <path> optional runtime metadata JSON;
• --report <path> optional output report path;
• --handoff <path> optional handoff artifact path.

Expected outputs:

• normalized JSON report;
• human-readable summary;
• plugin audit events;
• provenance references to bounded inputs;
• handoff artifact that downstream Ouroboros workflows can consume.

Risk: write if report/handoff is emitted; read_only only if dry-run/no-write is supported.

ooo guardrails validate-artifact

Validate an Ouroboros artifact path against a Guardrails spec/config.

Inputs:

• --artifact <path>;
• --spec <path>;
• --report <path>;
• --handoff <path>.

Expected use:

• post-generation checks;
• ooo auto acceptance gates;
• Seed output validation;
• research/eval artifact verification.

Risk: write.

ooo guardrails summarize-report

Read a Guardrails/Ouroboros validation report and produce a concise human summary.

Risk: read_only or write if persisted.

Later Commands

ooo guardrails install-validator

Install a Guardrails Hub validator.

This must be a separate, explicitly trusted command because it may involve network access, dependency installation, filesystem writes, and local model downloads.

Potential scopes:

• network:read
• filesystem:write
• shell:execute

Risk: write; may require confirmation.

ooo guardrails create-config

Wrap Guardrails config creation while bounding output paths and recording provenance.

Risk: write.

ooo guardrails start-server

Run Guardrails server mode under Ouroboros runtime supervision.

This is not MVP. It likely needs a stronger lifecycle/process contract.

Risk: write or stronger depending on network/process exposure.

Manifest Direction

The MVP should fit the current 0.1 manifest schema without speculative schema expansion.

Illustrative direction, not necessarily final:

{
  "schema_version": "0.1",
  "name": "guardrails-eval",
  "version": "0.1.0",
  "description": "Assimilate Guardrails AI validation into Ouroboros audit and handoff artifacts.",
  "source": {
    "type": "local_path",
    "path": "plugins/guardrails-eval",
    "repository": "https://github.com/Q00/ouroboros-plugins"
  },
  "commands": [
    {
      "namespace": "guardrails",
      "name": "validate-output",
      "summary": "Validate an LLM output against a Guardrails spec and emit an Ouroboros handoff report.",
      "usage": "ooo guardrails validate-output --spec <path> --output <path> --report <path>",
      "risk": "write",
      "requires_confirmation": false,
      "arguments": [
        {
          "name": "spec",
          "type": "path",
          "required": true,
          "description": "Repo-relative Guardrails RAIL/config/spec path."
        },
        {
          "name": "output",
          "type": "path",
          "required": true,
          "description": "Repo-relative LLM output artifact to validate."
        },
        {
          "name": "report",
          "type": "path",
          "required": false,
          "description": "Repo-relative path for validation report JSON."
        }
      ]
    }
  ],
  "capabilities": [
    {
      "name": "ledger",
      "access": "write",
      "reason": "Record validation pass/fail evidence."
    },
    {
      "name": "provenance",
      "access": "write",
      "reason": "Record bounded guard spec and artifact references."
    },
    {
      "name": "handoff",
      "access": "attach",
      "reason": "Attach validation reports for downstream Ouroboros runs."
    },
    {
      "name": "state",
      "access": "write",
      "reason": "Persist validation session status and report paths."
    }
  ],
  "permissions": [
    {
      "scope": "filesystem:read",
      "risk": "read_only",
      "required": true,
      "reason": "Read guard specs and target output artifacts."
    },
    {
      "scope": "filesystem:write",
      "risk": "write",
      "required": false,
      "reason": "Write validation reports and handoff artifacts."
    }
  ],
  "entrypoint": {
    "type": "command",
    "command": "python -m guardrails_eval"
  }
}

Report / Handoff Contract

The plugin should emit a normalized report that preserves Guardrails-native fields while adding Ouroboros metadata.

Suggested report shape:

{
  "schema_version": "0.1",
  "tool": {
    "name": "guardrails-ai",
    "source_repository": "https://github.com/guardrails-ai/guardrails",
    "package": "guardrails-ai"
  },
  "plugin": {
    "name": "guardrails-eval",
    "version": "0.1.0"
  },
  "input": {
    "spec_path": "./guards/example.rail",
    "target_path": "./.omx/artifacts/output.txt",
    "metadata_path": null
  },
  "guardrails_outcome": {
    "validation_passed": true,
    "validated_output": {},
    "validation_summaries": [],
    "error": null
  },
  "ouroboros_result": {
    "status": "success",
    "risk": "write",
    "permissions_used": ["filesystem:read", "filesystem:write"],
    "capabilities_used": ["ledger:write", "provenance:write", "handoff:attach"]
  },
  "handoff": {
    "consumer_hint": "Use this report as validation evidence for the associated artifact.",
    "artifact_status": "accepted"
  }
}

The handoff should be stable enough for future ooo auto, workflow IR, run/step/artifact projections, or agentOS gates to consume.

Permission and Risk Model

MVP permissions

Required:

• filesystem:read — read Guardrails specs/configs and target artifacts.

Optional:

• filesystem:write — write reports and handoff artifacts.

Later permissions

Optional and command-specific:

• network:read — fetch Guardrails Hub metadata or remote inference metadata;
• network:write — only if invoking remote inference or external APIs that mutate/session-log;
• shell:execute — run Guardrails CLI or install commands;
• filesystem:write — install validators, write configs, cache models;
• runtime:execute capability — supervise server mode or long-running validation processes, if supported by contract.

Important risk split

Local validation and Hub installation must not share the same trust path.

A user should be able to trust local validation without trusting dependency installation or server launch.

Boundary Rules

• Default to repo-relative paths.
• Do not persist raw secrets, raw API keys, or unbounded prompts in provenance.
• Do not enable Hub installation by default.
• Do not start long-running servers in the MVP.
• Do not expose arbitrary passthrough execution.
• Do not mutate production systems.
• Do not treat Guardrails Hub as an Ouroboros plugin marketplace.
• Do not add domain-specific Guardrails branches to ooo auto; consume handoff artifacts instead.

Dependency Strategy

Open question for implementation planning:

• Should guardrails-ai be a plugin dependency installed in the plugin environment?
• Should the plugin call an existing guardrails CLI if present?
• Should the plugin vendor no Guardrails code and require explicit environment setup?

Recommended starting point:

• implement as an out-of-process Python plugin package;
• depend on guardrails-ai in plugin packaging or dev requirements;
• keep Hub validator installation outside the MVP;
• provide a clean error if guardrails-ai is missing.

Implementation Plan

Phase 0 — Contract spike

• Confirm current manifest schema can represent the MVP without changes.
• Define report JSON shape.
• Define handoff JSON shape.
• Define path-bounding and redaction rules.
• Decide how the plugin locates/loads Guardrails specs/configs.

Phase 1 — MVP plugin skeleton

• Add plugins/guardrails-eval/ouroboros.plugin.json.
• Add Python entrypoint package, e.g. plugins/guardrails-eval/guardrails_eval/.
• Implement argument parsing for validate-output.
• Implement repo-relative path validation.
• Load Guardrails spec/config and validate known output.
• Emit normalized report JSON.
• Emit concise human summary.
• Exit non-zero on validation failure only if configured, or define clear exit semantics.

Phase 2 — Ouroboros-native evidence

• Attach ledger/provenance-compatible event payloads.
• Emit handoff artifact.
• Include bounded source references rather than raw sensitive payloads.
• Include validation summaries and remediation hints.
• Support artifact validation as a first-class command.

Phase 3 — Tests and contract validation

• Add manifest validation test.
• Add fixture Guardrails spec/config.
• Add passing validation fixture.
• Add failing validation fixture.
• Test report shape.
• Test path bounding.
• Test missing dependency error.
• Run python3 scripts/validate_contract.py.

Phase 4 — Optional Hub support

• Add explicit install-validator command only after MVP is stable.
• Require separate permission scopes.
• Record install provenance.
• Avoid silent model downloads.
• Ensure install cannot be confused with plugin trust.

Phase 5 — Optional server/runtime support

• Explore server mode as a separate lifecycle pattern.
• Define process ownership and shutdown semantics.
• Define network exposure policy.
• Define state recovery behavior.

Acceptance Criteria

• An epic-level design for Guardrails assimilation is captured in this issue.
• The proposed MVP preserves Guardrails concepts rather than replacing them with generic wrapper semantics.
• The plugin design maps Guardrails validation outcomes into Ouroboros audit/provenance/handoff artifacts.
• MVP scope avoids Guardrails Hub installation and server mode unless explicitly added in later phases.
• Local validation can run with bounded filesystem permissions.
• Report output includes both Guardrails-native outcome data and Ouroboros-native result metadata.
• The plugin does not expose arbitrary Guardrails CLI passthrough.
• The plugin does not require manifest schema expansion for MVP.
• Any future schema expansion is justified by a concrete reference-plugin need.
• The design keeps ooo auto coherent by consuming handoffs instead of embedding Guardrails-specific branching in core.

Non-goals

• Do not turn ouroboros-plugins into a Guardrails Hub mirror or marketplace.
• Do not auto-install arbitrary validators without explicit trust and permission boundaries.
• Do not add unbounded command passthrough.
• Do not start long-running servers in the MVP.
• Do not store raw secrets or unbounded user/model payloads in provenance.
• Do not move Guardrails logic into Ouroboros core.

Open Questions

1. Should the MVP support RAIL only, Python config only, or both?
2. What should the exact exit-code semantics be for validation failure vs plugin/runtime failure?
3. Where should reports be written by default: .omx/reports/, .ouroboros/, or caller-provided path only?
4. Should filesystem:write be required for the baseline command, or should the plugin support a pure stdout read-only mode?
5. How should Guardrails runtime metadata be bounded and redacted?
6. Should Guardrails Hub validator installation live in this plugin or a separate plugin/lifecycle command?
7. What minimum handoff shape should ooo auto or future Workflow IR consume?

References

• Guardrails AI repository: https://github.com/guardrails-ai/guardrails
• Guardrails documentation: https://www.guardrailsai.com/guardrails/docs
• Guardrails validators documentation: https://guardrailsai.com/guardrails/docs/concepts/validators
• Ouroboros plugin authoring/capability assimilation RFC issue: SSOT: UserLevel plugin authoring and capability assimilation #27

[shaun0927]

AgentOS 실검증 방법 / evidence collection plan

Guardrails MVP가 ouroboros-plugins에 들어온 뒤 “코드가 있다”를 넘어서 “Ouroboros AgentOS capability로 동작한다”를 보려면 아래 4단계로 검증하면 됩니다.

0. Contract / repository gate

목적: guardrails-eval이 manifest schema와 repo contract를 깨지 않는지 확인합니다.

python3 scripts/validate_contract.py
python3 tests/test_guardrails_eval_plugin.py
python3 -m unittest discover -s tests

수집 증거:

• contract validation passed (... plugin manifest(s) validated) 출력
• tests/test_guardrails_eval_plugin.py 통과 로그
• catalog/index.json에 guardrails-eval 등록 여부
• plugins/guardrails-eval/ouroboros.plugin.json의 commands/capabilities/permissions/risk 선언

1. AgentOS plugin lifecycle / trust gate

목적: 단순 Python module이 아니라 Ouroboros plugin manager가 발견, 설치, trust 상태로 관리할 수 있는지 확인합니다.

격리된 temp root를 써서 사용자 전역 trust store를 오염시키지 않는 방식:

TMP=$(mktemp -d /tmp/guardrails-agentos-proof.XXXXXX)

ouroboros plugin discover plugins/guardrails-eval \
  > "$TMP/discover.txt"

ouroboros plugin add . \
  --plugin guardrails-eval \
  --plugin-home-root "$TMP/plugins" \
  --lockfile "$TMP/plugins.lock" \
  --trust-root "$TMP/trust" \
  --catalog-state "$TMP/catalogs.json" \
  > "$TMP/add.txt"

ouroboros plugin inspect guardrails-eval \
  --lockfile "$TMP/plugins.lock" \
  --trust-root "$TMP/trust" \
  > "$TMP/inspect-before.txt"

ouroboros plugin trust guardrails-eval \
  --scope filesystem:read \
  --scope filesystem:write \
  --lockfile "$TMP/plugins.lock" \
  --trust-root "$TMP/trust" \
  --audit-log "$TMP/trust-audit.jsonl" \
  > "$TMP/trust.txt"

ouroboros plugin inspect guardrails-eval \
  --lockfile "$TMP/plugins.lock" \
  --trust-root "$TMP/trust" \
  > "$TMP/inspect-after.txt"

수집 증거:

• discover.txt: manifest valid: guardrails-eval 0.1.0, command count, capability count, permission count
• add.txt: installed plugin path + required scopes
• inspect-before.txt: trust_state: installed, missing filesystem:read
• trust.txt: granted filesystem:read, filesystem:write
• inspect-after.txt: trust_state: trusted, granted scopes
• trust-audit.jsonl: plugin.trusted audit events with granted_scope
• plugins.lock / temp plugin home: installed plugin artifact evidence

I ran this lifecycle proof locally after merge. Evidence observed:

• manifest valid: guardrails-eval 0.1.0
• commands: 3 in namespace 'guardrails'
• capabilities: 4
• permissions: 2
• before trust: trust_state: installed, missing filesystem:read
• after trust: trust_state: trusted, granted filesystem:read, filesystem:write
• trust audit emitted two plugin.trusted JSONL records

2. Real Guardrails library proof

목적: adapter가 fake test만 통과하는 게 아니라 실제 guardrails-ai package와 Guardrails spec을 통해 validation outcome을 생성하는지 확인합니다.

권장: 별도 venv에서 실행합니다.

python3 -m venv /tmp/guardrails-real-venv
. /tmp/guardrails-real-venv/bin/activate
pip install guardrails-ai

그 다음 Guardrails 공식 docs에서 쓰는 known-good .rail 또는 JSON guard spec을 repo 내부 경로에 둡니다. 먼저 Guardrails 자체가 spec을 읽는지 직접 확인합니다.

python3 - <<'PY'
from guardrails import Guard

guard = Guard.for_rail("guards/example.rail")
outcome = guard.parse(llm_output="<known sample output>", metadata={}, num_reasks=0)
print(outcome.validation_passed)
print(type(outcome).__name__)
PY

그 다음 동일 spec/output을 plugin으로 검증합니다.

PYTHONPATH=plugins/guardrails-eval python3 -m guardrails_eval validate-output \
  --spec guards/example.rail \
  --output .omx/artifacts/model-output.txt \
  --report .omx/reports/guardrails-output.json \
  --handoff .omx/handoffs/guardrails-output.json

PYTHONPATH=plugins/guardrails-eval python3 -m guardrails_eval summarize-report \
  --report .omx/reports/guardrails-output.json

수집 증거:

• command exit code: pass는 0, validation failure는 기본 1
• stdout summary: guardrails success|failed: validation_passed=...
• report JSON:
  • tool.name == guardrails-ai
  • plugin.name == guardrails-eval
  • guardrails_outcome.validation_passed
  • guardrails_outcome.validated_output
  • ouroboros_result.permissions_used
  • ouroboros_result.capabilities_used
  • provenance.bounded_inputs
  • raw output이 직접 저장되지 않고 sha256/length로 redacted 되는지
• handoff JSON:
  • artifact_status: accepted|rejected
  • evidence.validation_passed
  • report_path

실패 케이스도 반드시 같이 남기는 것을 권장합니다.

PYTHONPATH=plugins/guardrails-eval python3 -m guardrails_eval validate-output \
  --spec guards/example.rail \
  --output .omx/artifacts/bad-output.txt \
  --report .omx/reports/guardrails-bad-output.json \
  --handoff .omx/handoffs/guardrails-bad-output.json

echo $?

기대 증거:

• exit code 1
• report의 ouroboros_result.status == failed
• handoff의 artifact_status == rejected
• error / validation summary가 보존됨

3. Plugin firewall / command-dispatch proof

목적: 사용자가 직접 python -m guardrails_eval을 실행하는 수준을 넘어, AgentOS command dispatcher가 manifest/trust/permission boundary를 거쳐 실행하는지 확인합니다.

ooo guardrails ... dispatcher가 연결된 환경에서는 동일한 검증을 dispatcher 경로로 실행합니다.

ooo guardrails validate-artifact \
  --spec guards/example.rail \
  --artifact .omx/artifacts/research-summary.md \
  --report .omx/reports/guardrails-research-summary.json \
  --handoff .omx/handoffs/guardrails-research-summary.json

수집 증거:

• invocation이 trust 없이는 blocked 되는 로그
• trust 후 invocation 성공 로그
• audit stream에 아래 sequence가 남는지:
  • plugin.invoked
  • plugin.permission_used
  • plugin.completed 또는 plugin.failed
• permissions_used가 manifest/trust scope와 일치하는지
• capabilities_used가 report/handoff와 일치하는지
• direct Python 실행 결과와 dispatcher 실행 결과의 report shape가 같은지

현재 core CLI에서 plugin manager lifecycle은 확인 가능합니다. Dispatcher alias가 아직 환경에 붙어 있지 않은 경우에도, 위 1단계 lifecycle proof + 2단계 entrypoint proof를 분리해서 수집하면 “plugin contract boundary”와 “Guardrails runtime adapter”를 각각 증명할 수 있습니다.

4. End-to-end AgentOS pipeline proof

목적: Guardrails가 core나 ooo auto에 domain-specific branch를 추가하지 않고도 AgentOS pipeline의 acceptance gate로 작동하는지 확인합니다. #27/#41의 핵심은 “ooo auto가 Guardrails를 직접 알게 만드는 것”이 아니라 “handoff/report를 소비 가능한 evidence로 만드는 것”입니다.

권장 시나리오:

1. ouroboros auto --skip-run 또는 기존 AgentOS workflow로 artifact를 생성합니다.

   ouroboros auto \
     --skip-run \
     "Generate a structured research summary artifact that must satisfy guards/example.rail"

2. 생성된 artifact path를 validate-artifact로 검증합니다.

   ooo guardrails validate-artifact \
     --spec guards/example.rail \
     --artifact .omx/artifacts/research-summary.md \
     --report .omx/reports/guardrails-research-summary.json \
     --handoff .omx/handoffs/guardrails-research-summary.json

3. downstream gate는 handoff/report JSON만 읽어 pass/fail을 결정합니다.

   python3 - <<'PY'
   import json, sys
   report = json.load(open('.omx/reports/guardrails-research-summary.json'))
   ok = report['guardrails_outcome']['validation_passed']
   print('guardrails_gate=', ok)
   sys.exit(0 if ok else 1)
   PY

4. 필요하면 ouroboros auto --attach-source guardrails-eval ... 또는 현재 run ledger에 handoff path를 evidence로 첨부합니다. 핵심은 handoff가 다음 단계의 machine-readable gate가 되는지입니다.

수집 증거 bundle 예시:

.omx/evidence/guardrails-agentos-proof/
  00-plugin-discover.txt
  01-plugin-add.txt
  02-inspect-before-trust.txt
  03-trust.txt
  04-inspect-after-trust.txt
  05-trust-audit.jsonl
  10-direct-guardrails-smoke.txt
  11-validate-output.stdout
  12-validate-output.report.json
  13-validate-output.handoff.json
  20-validate-artifact.stdout
  21-validate-artifact.report.json
  22-validate-artifact.handoff.json
  30-agentos-auto-session.txt
  31-agentos-gate-result.txt

Minimum acceptance checklist:

• Manifest validates under schema 0.1.
• Plugin can be discovered, installed, inspected, trusted.
• Trust audit emits plugin.trusted records.
• Invocation is blocked before required trust and allowed after trust.
• Real guardrails-ai package loads the chosen .rail/JSON spec.
• validate-output emits normalized report + handoff.
• validate-artifact emits normalized report + handoff for an AgentOS artifact.
• Passing and failing validation both produce deterministic evidence.
• Raw target text is bounded/redacted by path/hash/length references.
• Downstream gate can decide pass/fail using only report/handoff JSON.
• No Guardrails-specific branch is required in ooo auto or core.

References used for the runtime shape:

• Guardrails docs describe Guard.parse as the post-process path for already-known LLM output and return an outcome object with raw output, validated output, and validation success status.
• Guardrails API docs expose .rail loading (Guard.for_rail) and dictionary loading (Guard.from_dict) patterns, which match the MVP adapter boundary.

[shaun0927]

Reopening because full AgentOS real-world validation/evidence collection is not complete yet. Keep this epic open until end-to-end validation evidence is attached.

[shaun0927]

Current-session AgentOS validation proof

Requested follow-up: run everything that is realistically verifiable in the current session and record the evidence.

Evidence bundle path in this session:

/Users/jh0927/ouroboros-plugins-worktrees/issue41-guardrails/final-main/.omx/evidence/guardrails-agentos-session-proof-20260521T054536Z

What was verified in this session

1. Repository contract and regression suite

Commands run:

python3 scripts/validate_contract.py
python3 tests/test_guardrails_eval_plugin.py
python3 -m unittest discover -s tests

Evidence files:

• 00-contract.txt
• 01-guardrails-plugin-tests.txt
• 02-full-unittest.txt

Observed result:

contract validation passed (12 plugin manifest(s) validated)
Guardrails plugin tests: Ran 7 tests ... OK
Full unittest discovery: Ran 103 tests ... OK

2. Ouroboros AgentOS plugin lifecycle / trust proof

Commands run with isolated temp roots under the evidence directory:

ouroboros plugin discover plugins/guardrails-eval

ouroboros plugin add . \
  --plugin guardrails-eval \
  --plugin-home-root "/Users/jh0927/ouroboros-plugins-worktrees/issue41-guardrails/final-main/.omx/evidence/guardrails-agentos-session-proof-20260521T054536Z/plugin-roots/plugins" \
  --lockfile "/Users/jh0927/ouroboros-plugins-worktrees/issue41-guardrails/final-main/.omx/evidence/guardrails-agentos-session-proof-20260521T054536Z/plugin-roots/plugins.lock" \
  --trust-root "/Users/jh0927/ouroboros-plugins-worktrees/issue41-guardrails/final-main/.omx/evidence/guardrails-agentos-session-proof-20260521T054536Z/plugin-roots/trust" \
  --catalog-state "/Users/jh0927/ouroboros-plugins-worktrees/issue41-guardrails/final-main/.omx/evidence/guardrails-agentos-session-proof-20260521T054536Z/plugin-roots/catalogs.json"

ouroboros plugin inspect guardrails-eval \
  --lockfile "/Users/jh0927/ouroboros-plugins-worktrees/issue41-guardrails/final-main/.omx/evidence/guardrails-agentos-session-proof-20260521T054536Z/plugin-roots/plugins.lock" \
  --trust-root "/Users/jh0927/ouroboros-plugins-worktrees/issue41-guardrails/final-main/.omx/evidence/guardrails-agentos-session-proof-20260521T054536Z/plugin-roots/trust"

ouroboros plugin trust guardrails-eval \
  --scope filesystem:read \
  --scope filesystem:write \
  --lockfile "/Users/jh0927/ouroboros-plugins-worktrees/issue41-guardrails/final-main/.omx/evidence/guardrails-agentos-session-proof-20260521T054536Z/plugin-roots/plugins.lock" \
  --trust-root "/Users/jh0927/ouroboros-plugins-worktrees/issue41-guardrails/final-main/.omx/evidence/guardrails-agentos-session-proof-20260521T054536Z/plugin-roots/trust" \
  --audit-log "/Users/jh0927/ouroboros-plugins-worktrees/issue41-guardrails/final-main/.omx/evidence/guardrails-agentos-session-proof-20260521T054536Z/13-trust-audit.jsonl"

Evidence files:

• 10-plugin-discover.txt
• 11-plugin-add.txt
• 12-inspect-before-trust.txt
• 13-plugin-trust.txt
• 13-trust-audit.jsonl
• 14-inspect-after-trust.txt
• plugin-roots/plugins.lock
• plugin-roots/plugins/guardrails-eval/...

Observed result:

• manifest discovery succeeded: manifest valid: guardrails-eval 0.1.0
• command namespace recognized: commands: 3 in namespace 'guardrails'
• capability count: capabilities: 4
• permission count: permissions: 2
• before trust: installed but invocation would be blocked for missing filesystem:read
• after trust: trust_state: trusted, granted filesystem:read, filesystem:write
• trust audit file contains plugin.trusted JSONL events for both scopes

3. Runtime dependency boundary proof

The current session does not have guardrails-ai installed globally, so I verified the intended clean failure behavior.

Command run:

PYTHONPATH=plugins/guardrails-eval python3 -m guardrails_eval validate-output \
  --spec .omx/evidence/.../guards/missing-dep-spec.json \
  --text "safe output"

Evidence files:

• 20-missing-dependency.stdout
• 20-missing-dependency.stderr
• 20-missing-dependency.exitcode

Observed result:

exit code: 1
guardrails-eval: guardrails-ai is required for validation. Install it in the plugin environment, for example: pip install guardrails-ai

This confirms the adapter fails explicitly instead of silently bypassing validation when the external library is absent.

4. Deterministic runtime adapter proof with fake Guardrails

Because this session lacks the real guardrails-ai package, I used the same deterministic fake-Guardrails strategy as the merged test suite to verify the plugin runtime path end-to-end without network/package-install coupling.

Commands exercised:

• validate-output success path
• validate-output validation-failure path
• validate-artifact artifact gate path
• summarize-report
• downstream gate script reading the normalized report JSON

Evidence files:

• 30-validate-output-good.stdout
• 30-validate-output-good.exitcode
• reports/good-output.report.json
• handoffs/good-output.handoff.json
• 31-validate-output-bad.stdout
• 31-validate-output-bad.exitcode
• reports/bad-output.report.json
• handoffs/bad-output.handoff.json
• 32-validate-artifact.stdout
• 32-validate-artifact.exitcode
• reports/artifact.report.json
• handoffs/artifact.handoff.json
• 33-summarize-report.stdout
• 34-downstream-gate-good.txt
• 98-summary.json

Observed structured summary:

{
  "artifact_exitcode": "0",
  "artifact_report_core": {
    "handoff_artifact_status": "accepted",
    "status": "success",
    "target_kind": "artifact",
    "validation_passed": true
  },
  "bad_exitcode": "1",
  "bad_report_core": {
    "artifact_status": "rejected",
    "error": "contains banned token: bad",
    "status": "failed",
    "validation_passed": false
  },
  "contract": "contract validation passed (12 plugin manifest(s) validated)",
  "full_unittest_tail": "Ran 103 tests in 92.511s\n\nOK",
  "gate": "guardrails_gate= True\nartifact_status= accepted\npermissions_used= filesystem:read,filesystem:write\ncapabilities_used= ledger:write,provenance:write,state:write,handoff:attach",
  "good_exitcode": "0",
  "good_report_core": {
    "capabilities_used": [
      "ledger:write",
      "provenance:write",
      "state:write",
      "handoff:attach"
    ],
    "permissions_used": [
      "filesystem:read",
      "filesystem:write"
    ],
    "raw_redacted": true,
    "status": "success",
    "target_kind": "llm_output",
    "validation_passed": true
  },
  "guardrails_plugin_tests_tail": "Ran 7 tests in 4.814s\n\nOK",
  "missing_dependency_exitcode": "1",
  "missing_dependency_stderr": "guardrails-eval: guardrails-ai is required for validation. Install it in the plugin environment, for example: pip install guardrails-ai",
  "proof_dir": "/Users/jh0927/ouroboros-plugins-worktrees/issue41-guardrails/final-main/.omx/evidence/guardrails-agentos-session-proof-20260521T054536Z",
  "summary_exitcode": "0"
}

Key proof points from the generated reports:

• passing output exits 0
• failing output exits 1
• failing output writes ouroboros_result.status == failed
• failing output writes handoff.artifact_status == rejected
• artifact validation writes input.target.kind == artifact
• report records permissions_used == [filesystem:read, filesystem:write]
• report records capabilities_used == [ledger:write, provenance:write, state:write, handoff:attach]
• raw LLM output is redacted and represented with hash/length metadata
• downstream gate can decide pass/fail from report JSON only:

guardrails_gate= True
artifact_status= accepted
permissions_used= filesystem:read,filesystem:write
capabilities_used= ledger:write,provenance:write,state:write,handoff:attach

What remains outside this session's current surface

The current installed ouroboros CLI exposes plugin lifecycle commands (discover/add/inspect/trust/list/disable/remove), but not a visible plugin invoke command or an ooo guardrails ... dispatcher alias in PATH. Therefore this session verified:

1. AgentOS plugin lifecycle/trust boundary through ouroboros plugin ....
2. Runtime adapter behavior through the plugin entrypoint.
3. AgentOS handoff/acceptance-gate behavior through generated report/handoff JSON.

A future environment with the command dispatcher wired should add one extra proof step:

ooo guardrails validate-artifact \
  --spec guards/example.rail \
  --artifact .omx/artifacts/research-summary.md \
  --report .omx/reports/guardrails-research-summary.json \
  --handoff .omx/handoffs/guardrails-research-summary.json

That would prove firewall-mediated invocation in addition to the lifecycle/trust and handoff evidence captured here.

Current-session verdict

Within the surfaces available in this session, guardrails-eval is verified as an Ouroboros AgentOS capability adapter:

• contract-valid plugin manifest and catalog entry;
• installable and trustable through Ouroboros plugin manager;
• trust audit evidence emitted;
• clean dependency-boundary behavior when guardrails-ai is absent;
• validation report/handoff generation proven for pass/fail/artifact flows;
• downstream AgentOS gate can consume report/handoff JSON without adding Guardrails-specific logic to core or ooo auto.