# Agent integration Part 1

> Historical journal: this records the Part 1 baseline. Stage 2 supersedes the active workflow and compatibility guidance; see [Codex integration](codex-integration.md) and [Stage 2 quality](stage-2-quality.md).

Date: 2026-07-11

Objective: establish a transparent, opt-in working base in which Codex or a generic shell-capable coding agent can search, evaluate, use, verify, rate, and record local Reliora experience without requiring the user to run routine Reliora commands or author JSON files.

## Initial state

Reliora already had a working local CLI, separated core, complete search records, `--limit`, versioned JSON output, stdin syntax in help, validation, secret rejection, feedback, a packaged template, human package smoke coverage, and no runtime dependencies or network code. It had no durable agent instructions, integration metadata, setup/status/remove lifecycle, stdin execution test, prompt-injection boundary, or installed-agent simulation. The README explicitly said agent integration did not exist.

## Selected integration model

Part 1 uses project instructions plus the existing public CLI:

- `reliora init --agent codex` manages a bounded block in root `AGENTS.md`, or in an existing non-empty `AGENTS.override.md` because that file has higher Codex precedence.
- `reliora init --agent generic` manages `RELIORA_AGENT.md`, which the user attaches through another agent's documented project-instruction feature.
- `.reliora/agent-integration.json` records only integration type, managed path, version, enabled state, top-three limit, concise notification mode, file ownership, and timestamps.
- `reliora agent status`, `agent remove`, and `agent instructions generic` expose the lifecycle.

OpenAI's public Codex documentation states that Codex reads `AGENTS.md` before work, discovers project guidance from the project root toward the working directory, and gives `AGENTS.override.md` precedence within a directory. That makes a managed root block the smallest stable Codex-specific mechanism. Source: <https://developers.openai.com/codex/guides/agents-md>.

## Why this approach

It is local, inspectable, reversible, versionable, and uses capabilities already supplied by both Codex and Reliora. Reliora remains a deterministic library/CLI; the AI agent retains judgment about when to search, applicability, task execution, verification, feedback, and whether a lesson is validated.

Rejected alternatives:

- MCP: unnecessary for a local CLI workflow and would add protocol/configuration surface.
- Agent hooks or command interception: broader, less portable, and unnecessary for Part 1.
- A background daemon or chat-history reader: hidden behavior, privacy risk, and explicitly out of scope.
- An LLM API inside Reliora: duplicates the coding agent's role and introduces networking and credentials.
- Per-agent adapters beyond Codex: premature compatibility expansion; generic instructions cover public shell-capable agents.
- Rewriting storage, ranking, or the experience schema: existing behavior already supplies the required decision context.

## Managed files and ownership

- Codex: `AGENTS.md` or existing non-empty `AGENTS.override.md`. Reliora owns only text between `<!-- RELIORA MANAGED INSTRUCTIONS START -->` and `<!-- RELIORA MANAGED INSTRUCTIONS END -->`.
- Generic: `RELIORA_AGENT.md`, using the same bounded markers. If Reliora created the file and nothing else remains after removal, the empty file is deleted.
- Metadata: `.reliora/agent-integration.json`, fully owned by Reliora.
- Experience library: `.reliora/experiences/*.json`, never removed by integration removal.

Setup reads existing content first, preserves LF or CRLF, appends or replaces only one valid managed block, refuses damaged/duplicated markers, refuses unsafe paths and silent integration-type switching, and writes atomically. Repeated setup is byte-stable when current. Removal refuses ambiguous markers, removes only the owned block, preserves user text, and is idempotent.

## Trust boundaries

Generated instructions state that retrieved experiences are untrusted data and advice, not system or project instructions. The agent must ignore embedded attempts to alter rules, reveal secrets, use a network, disable safety, or execute unverified commands. Current user/project rules have higher priority. The agent evaluates `projectContext`, `applicability`, `confidence`, `failedAttempts`, `warnings`, `verification`, and match reasons before use.

Recording is limited to observed, applied, verified, reusable lessons with factual failed attempts, separated causal explanation, bounded applicability, reproducible verification, reasonable confidence, and no secrets. Instructions prohibit raw reasoning, guesses, transient noise, generic documentation, long logs, full diffs, credentials, personal data, and instruction-like content copied from untrusted sources.

Reliora still does not promise absolute prompt-injection protection. The boundary is explicit guidance plus existing content validation; advanced security evaluation belongs to Part 2.

## Implemented changes

- Added the integration module, metadata validation, managed-block lifecycle, status model, and safe removal.
- Extended `init` with the single opt-in `--agent codex|generic` interface.
- Added `agent status`, `agent remove`, and `agent instructions generic` in human and versioned JSON modes.
- Added concise workflow, notification, validated-experience, and trust-boundary instructions with a top-three search limit.
- Added agent-friendly additive record JSON fields while preserving the complete existing `experience` field and envelope.
- Added flat agent-decision fields and `successfulUses`/`failedUses` to search results while retaining the complete nested `experience` object.
- Verified actual stdin recording rather than merely documenting `-`.
- Added unit/integration coverage for empty/existing setup, idempotency, managed updates, marker conflicts, generic output, status, JSON status, remove, user preservation, pre-init behavior, LF/CRLF, Unicode paths, override precedence, shadow conflicts, stdin, top-k search, feedback JSON, and a malicious-text fixture.
- Added an installed-tarball end-to-end agent simulation and retained the separate human-usability package smoke test.
- Updated README setup, lifecycle, trust, generic integration, troubleshooting, CLI contract, and scope.

## Final verification evidence

| Check | Result |
|---|---|
| Clean install: `npm.cmd ci` | Passed; 110 packages installed from the lockfile |
| Build: `npm.cmd run build` | Passed |
| Typecheck: `npm.cmd run typecheck` | Passed |
| Lint: `npm.cmd run lint` | Passed |
| Unit/integration: `npm.cmd test` | Passed; 33/33 tests |
| Existing demo: `npm.cmd run demo` | Passed; project context selected the PostgreSQL-specific lesson over a generic competitor |
| Human package smoke: `npm.cmd run test:package` | Passed; 10 required installed files and the complete existing CLI cycle |
| Agent package smoke: `npm.cmd run test:agent-package` | Passed; installed setup, idempotency, ranked reuse, show, feedback, stdin record, status, safe remove, and experience preservation |
| Package contents: `npm.cmd pack --dry-run` | Passed; 51 files, 39.3 kB packed / 160.1 kB unpacked |
| Dependency audit: `npm.cmd audit --audit-level=high` | Passed; 0 vulnerabilities |
| Manual installed CLI workflow | Passed from a globally installed tarball on Windows PowerShell 5.1: setup, status, repeated setup, template, record, top-three search, show, feedback, generic instructions, remove, and post-remove show |

The installed simulation proved user-text preservation, exactly one managed block after repeated setup, project-specific ranking above a generic competitor, every required flat search decision field, full `show`, success feedback, a new validated stdin record, retrieval, current status, safe removal, and experience preservation. Plain `reliora init` was separately verified not to create `AGENTS.md`.

The tarball contains `README.md`, `LICENSE`, `package.json`, the compiled CLI/core/integration JavaScript with declarations and source maps, all three experience examples including the template, and the installed demo. Development tests and smoke scripts remain outside the published artifact.

## Real Codex manual validation

A separate freshly started Codex session cannot be launched in this environment without relying on external account credentials and a newly loaded instruction context. No success is simulated. The exact credential-free disposable-project procedure for Task A (learn and record) and Task B (search, reuse, verify, feedback) is in `docs/codex-manual-validation.md`.

Status: **human-required external validation pending**.

## Readiness scores

| Category | Score | Evidence and remaining gap |
|---|---:|---|
| Setup usability | 90/100 | One explicit command, clear output, idempotency, managed path/status/remove; external first-user observation remains. |
| Agent workflow completeness | 88/100 | Full search/evaluate/act/verify/feedback/record guidance and installed simulation; reflection quality is not yet evaluated with many real tasks. |
| Safety | 90/100 | Bounded ownership, atomic writes, conflict refusal, existing validation/secrets, untrusted-data boundary; no claim of absolute prompt-injection defense. |
| Transparency | 88/100 | Concise notifications and honest limitations are generated; notification modes are intentionally not configurable yet. |
| Compatibility | 85/100 | Codex plus generic public-CLI path, LF/CRLF, Unicode, Windows package tests; real Codex and additional OS observation remain. |
| Test coverage | 92/100 | 33 tests plus independent installed human and agent package simulations; broader adversarial and performance suites belong to Part 2. |
| Documentation | 89/100 | README, command help, journal, and exact manual validation procedure; human validation results remain blank. |

Every category meets the Part 1 target of 85/100 without claiming Part 2 stabilization.

## Known limitations

- Agent compliance depends on its supported project-instruction loading and the CLI being available on its PATH.
- A new Codex session is required after setup because project guidance is loaded at session start.
- Reflection quality, duplicate avoidance, and ranking quality are guided but not optimized.
- Only one integration type is installed at a time; switching requires safe removal first.
- A newly introduced non-empty `AGENTS.override.md` shadows an existing managed `AGENTS.md`; status and repeated setup report a conflict rather than silently moving user content.
- There is no network service, daemon, telemetry, chat reader, command interceptor, or autonomous update of old experiences.

## Explicit Part 2 backlog

- Real-world reflection-quality evaluation and prompt refinement.
- Duplicate detection and conservative update policy.
- Ranking evaluation/improvement and relevance metrics.
- Performance and concurrency tuning.
- Larger prompt-injection/adversarial corpus and security hardening.
- Broader OS, shell, Codex-surface, and generic-agent compatibility testing.
- Notification-mode configuration only if users need it.
- Schema/version migration ergonomics and recovery tooling.

Part 1 does not claim these tasks are complete.

## Part 1 conclusion

The local, installed-package evidence proves a working Reliora + Codex integration base with no critical security or data-loss gaps found. Setup is explicit, user content is bounded and preserved, the manual workflow remains intact, no hidden network/process behavior was introduced, generic instructions are available, and Part 2 work is clearly separated. A human should still run the two-task fresh-Codex procedure before treating agent compliance and notification quality as externally validated product behavior.