Metadata-Version: 2.4
Name: agents-md-compiler
Version: 1.1.1
Summary: Compile ordered Markdown policy modules into a deterministic, verifiable AGENTS.md.
Keywords: agents-md,codex,agent,policy,compiler,deterministic,provenance,cli
Author: netopsengineer
Author-email: netopsengineer <enterprise.code.developer@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: >=3.14
Project-URL: Homepage, https://github.com/netopsengineer/agents-md-compiler
Project-URL: Repository, https://github.com/netopsengineer/agents-md-compiler
Project-URL: Issues, https://github.com/netopsengineer/agents-md-compiler/issues
Project-URL: Changelog, https://github.com/netopsengineer/agents-md-compiler/blob/main/CHANGELOG.md
Description-Content-Type: text/markdown

# agents-md-compiler

Compile ordered Markdown policy modules into one deterministic, verifiable
`AGENTS.md` or `AGENTS.override.md`. The target can be global, repository-local,
nested, or another explicit path. The runtime has no dependencies, performs no
network access, invokes no shell, and uses no LLM.

**Keep your own local instructions without editing the repository's `AGENTS.md`.**
Compile to `AGENTS.override.md` when shared instructions are unsuitable and you
cannot change them. Codex prefers the override in that directory; the shared file
stays untouched. See the [local override quickstart](#local-override-quickstart).

## The mental model

One manifest owns one ordered module set and one default target. The compiler
does not need a scope flag because Codex scope comes from the target path and the
startup working directory:

| Purpose                      | Typical target              | Verification context           |
|------------------------------|-----------------------------|--------------------------------|
| Global policy                | `~/.codex/AGENTS.md`        | Isolated empty directory       |
| Repository policy            | `<repo>/AGENTS.md`          | Repository root or descendant  |
| Personal repository override | `<repo>/AGENTS.override.md` | Repository root or descendant  |
| Nested policy                | `<repo>/<area>/AGENTS.md`   | Target directory or descendant |
| Standalone export            | Any new path                | No Codex visibility promise    |

The same `lock`, `validate`, `check`, `install`, `status`, and `rollback`
workflow applies to every target. `verify-codex` adds the startup directory
needed to prove that Codex actually discovers project and nested targets.

Codex loads one global instruction file and then builds a project instruction
chain from the project root toward its startup working directory. A closer file
is applied later. See the official
[Codex AGENTS.md guide](https://developers.openai.com/codex/guides/agents-md).

## Why compile instruction files

Canonical modules are easier to review and reuse than one large hand-maintained
file, but Codex needs a self-contained file at startup. This compiler connects
those needs without hiding provenance:

- canonical Markdown modules remain the only editable policy sources;
- a strict manifest fixes the source set, order, and target;
- a portable lock records each lexical source path, byte size, and SHA-256;
- rendering preserves every accepted source byte between generated markers;
- checking detects source drift, output drift, a missing target, shadowing, and
  unmanaged content;
- installation is explicit, atomic, backed up, and concurrency-safe;
- `AGENTS.override.md` is a supported target for local customization without
  replacing the repository's shared `AGENTS.md`;
- rollback restores exact prior bytes and refuses after an external target edit;
- runtime verification inspects Codex prompt input instead of asking a model what
  it thinks it read.

The tool does not discover repositories, detect stacks, select targets, or
generate multiple files from one manifest. It does not author, rewrite,
summarize, lint-fix, normalize, or deduplicate policy prose.

## Requirements and installation

- Python 3.14 or newer.
- Linux, macOS, or Windows.
- `codex` on `PATH` only for optional runtime visibility verification.

```bash
# Recommended: install as an isolated tool.
uv tool install agents-md-compiler

# Or run without installing.
uvx agents-md-compiler --help

# Or install into an existing environment.
pip install agents-md-compiler
```

Both invocation forms are equivalent:

```bash
agents-md-compiler --help
python -m agents_md_compiler --help
```

## Global quickstart

`init` defaults to the active global base file and prints the exact lock command
to run next.

```bash
# Creates policy/agents-md.toml and policy/modules/*.md.
agents-md-compiler init --directory ./policy --bundle-id personal-policy

# Create the target parent when this is a new Codex home.
mkdir -p ~/.codex

agents-md-compiler lock --manifest ./policy/agents-md.toml
agents-md-compiler validate --manifest ./policy/agents-md.toml
agents-md-compiler render --manifest ./policy/agents-md.toml --locked
agents-md-compiler check --manifest ./policy/agents-md.toml

# Preview writes nothing.
agents-md-compiler install --manifest ./policy/agents-md.toml

# Explicitly mutate the target.
agents-md-compiler install --manifest ./policy/agents-md.toml --apply

# Prove the active global file is visible without project instructions.
agents-md-compiler verify-codex --manifest ./policy/agents-md.toml
```

## Repository quickstart

Run this from the repository root. The target argument resolves from the current
directory. `init` serializes it relative to `.agents`, so the generated manifest
contains the portable value `../AGENTS.md`.

```bash
agents-md-compiler init \
  --directory ./.agents \
  --target ./AGENTS.md \
  --bundle-id project-policy

agents-md-compiler lock --manifest ./.agents/agents-md.toml
agents-md-compiler validate --manifest ./.agents/agents-md.toml
agents-md-compiler check --manifest ./.agents/agents-md.toml
agents-md-compiler install --manifest ./.agents/agents-md.toml
agents-md-compiler install --manifest ./.agents/agents-md.toml --apply

# Prove the repository file is visible from this startup directory.
agents-md-compiler verify-codex \
  --manifest ./.agents/agents-md.toml \
  --cwd .
```

For a nested target, use the same layout and pass a working directory equal to or
below the target's parent:

```bash
agents-md-compiler verify-codex \
  --manifest ./.agents/backend/agents-md.toml \
  --cwd ./backend/service
```

`CURRENT` means the selected target is byte-identical to a fresh locked render.
It does not claim that Codex discovers that target from every possible working
directory. A successful `verify-codex` makes the visibility claim only for its
reported startup directory.

## Local override quickstart

Use this when you need your own instruction setup in a repository whose existing
`AGENTS.md` you cannot edit. The compiler manages `AGENTS.override.md` with the
same lock, validation, installation, rollback, and runtime verification workflow.
No change to the shared instruction file is required.

Run from the root of a Git checkout where `AGENTS.override.md` and `.agents-local`
do not already exist or belong to tracked files. The local exclude file keeps
these new files out of ordinary Git staging without editing tracked `.gitignore`.
Ignore rules do not hide changes to files Git already tracks.
Before the first install, the preview reports `MISSING` with exit code 2;
review that planned change, then run the `--apply` command.

```bash
printf '\n/AGENTS.override.md\n/.agents-local/\n' >> "$(git rev-parse --git-path info/exclude)"

agents-md-compiler init \
  --directory ./.agents-local \
  --target ./AGENTS.override.md \
  --bundle-id personal-project-policy

# Edit .agents-local/modules/*.md with your own instructions before locking.
agents-md-compiler lock --manifest ./.agents-local/agents-md.toml
agents-md-compiler validate --manifest ./.agents-local/agents-md.toml
agents-md-compiler render --manifest ./.agents-local/agents-md.toml --locked

# Preview, then explicitly install only the override target.
agents-md-compiler install --manifest ./.agents-local/agents-md.toml
agents-md-compiler install --manifest ./.agents-local/agents-md.toml --apply
agents-md-compiler check --manifest ./.agents-local/agents-md.toml
agents-md-compiler verify-codex \
  --manifest ./.agents-local/agents-md.toml \
  --cwd .
```

**The override replaces, rather than appends to, the sibling `AGENTS.md` in Codex's
startup input.** Keep any repository guidance you still need in your canonical
modules. Global instructions and files at other levels of the project instruction
chain still apply. Start a fresh Codex session after installation. This precedence
comes from [Codex instruction discovery](https://learn.chatgpt.com/docs/agent-configuration/agents-md#how-codex-discovers-guidance),
not a compiler-specific setting.

If an override already exists, use the [existing-file adoption workflow](#adopting-an-existing-agentsmd)
with its path and digest; the compiler never replaces an unmanaged override
silently. To restore the previous file or its prior absence, use the install
receipt with the [rollback workflow](#safety-and-operational-state), then start a
fresh session. A nested override works the same way at its own directory level.

## Normal edit workflow

1. Edit canonical module files, never the generated target.
2. Review the module and manifest changes.
3. Run `lock` explicitly to refresh source identity.
4. Run `validate` and review `render --locked` when needed.
5. Run `check` to see whether the selected target needs installation.
6. Preview `install`, then rerun it with `--apply`.
7. Run `verify-codex` with the applicable startup context.

Editing a module after locking produces `LOCK_STALE` and exit code 2. Read-only
commands never refresh a lock or install a target implicitly.

When `--manifest` is omitted, the CLI uses `./agents-md.toml`. It falls back to
legacy `./global-agents.toml` only when the neutral default is absent. If both
exist, the invocation is ambiguous and must use explicit `--manifest`.

## Choosing a destination

- Manifest `default_target` is the persistent managed destination. A relative
  value resolves from the manifest directory. A leading `~` expands through the
  standard home lookup.
- `--target PATH` overrides the managed destination for one invocation. A
  relative command-line path resolves from the current working directory.
- `render --locked --output PATH` writes one standalone file only when the path
  does not exist. It never replaces an existing file or creates its parent.

Codex visibility is promised only for paths Codex actually discovers. A custom
file name can still use compilation, checking, installation, and rollback, but a
runtime probe will not pass unless Codex includes those bytes through its normal
instruction discovery.

## Adopting an existing AGENTS.md

An existing file without a recognized generated header is unmanaged and is never
replaced silently. First preview the install and capture the current file digest.
Then provide both adoption flags:

```bash
shasum -a 256 ./AGENTS.md

EXPECTED_TARGET_SHA256=<captured-64-character-digest>
agents-md-compiler install \
  --manifest ./.agents/agents-md.toml \
  --apply \
  --replace-unmanaged \
  --expect-target-sha256 "${EXPECTED_TARGET_SHA256}"
```

A digest mismatch refuses the write. A successful adoption stores the exact
handwritten predecessor as a backup before replacing it.

## Safety and operational state

All target mutations require `--apply`. Dry runs create no target, backup,
receipt, deployment directory, or advisory lock.

New operational evidence is scoped by bundle ID and resolved target digest under
the user state root:

- Linux and macOS: `${XDG_STATE_HOME:-~/.local/state}/agents-md-compiler/`
- Windows: `%LOCALAPPDATA%/agents-md-compiler/`

Advisory locks live in one distribution-wide namespace and are keyed only by the
resolved protected path. Two different bundle IDs therefore coordinate when they
select the same target. Two targets using one bundle ID retain separate receipts,
backups, preserved files, and last-install state.

Rollback consumes one explicit install receipt:

```bash
agents-md-compiler rollback \
  --manifest ./.agents/agents-md.toml \
  --receipt <path/to/install-receipt.json> \
  --apply
```

Rollback refuses unless the target still matches the receipt's installed digest.
Backups are never deleted or rotated automatically. When an install created a
previously missing target, rollback moves the generated file into private state
instead of deleting it irrecoverably.

Other safety boundaries:

- sources and targets that are symbolic links are refused;
- target parents must already exist and be directories;
- a non-empty sibling `AGENTS.override.md` shadows a selected `AGENTS.md` and
  causes `SHADOWED`;
- a source may not alias the selected output;
- a source containing the compiler marker prefix is rejected;
- an unknown future rendered format is unmanaged and requires explicit adoption.

If a post-replacement step fails, recovery runs under the same target lock. It
first proves that the target still contains the operation's bytes, then restores
the predecessor from its verified backup or preserves a newly generated file and
restores prior absence.

## Format-1 migration

Current releases emit portable lock format 2 and neutral rendered format 2.

- A strict format-1 lock is migration input. Read-only commands report
  `LOCK_STALE`; explicit `lock` replaces it atomically with format 2.
- Exact format-1 and format-2 rendered targets are managed. A format-1 target is
  `DRIFTED` and upgrades through ordinary explicit install without unmanaged-file
  adoption flags.
- Upgrade installation backs up exact format-1 bytes. Receipt-based rollback can
  restore them when the format-2 target has not changed.
- Legacy bundle-only install receipts remain accepted for explicit validated
  rollback. New evidence is written only to target-qualified deployment state.

## Repository CI

Commit the manifest, canonical modules, portable lock, and generated target when
the repository chooses to track generated output. A read-only CI gate can run:

```bash
agents-md-compiler lock --manifest ./.agents/agents-md.toml --check
agents-md-compiler validate --manifest ./.agents/agents-md.toml
agents-md-compiler check --manifest ./.agents/agents-md.toml
```

`verify-codex` is an environment integration gate, not a deterministic unit gate.
Run it where the intended Codex executable and startup context are available.

## Determinism and preservation guarantees

- Equal manifest and source bytes produce equal format-2 lock and rendered bytes
  across checkout roots.
- Output contains no timestamp, host name, process ID, random value, temporary
  path, resolved source path, package version, or working directory.
- Manifest order is output order. Rendering does not enumerate source folders.
- Sources must be non-empty strict UTF-8 with LF line endings and exactly one
  final LF. BOM, NUL, CR, invalid UTF-8, and marker collisions are rejected.
- Accepted source bytes are copied exactly. The compiler never trims, reflows,
  normalizes, lint-fixes, summarizes, or deduplicates them.

Digests prove that bytes did not change between locking and rendering. They do
not establish authorship, correctness, or safety. See
[`docs/security-model.md`](docs/security-model.md).

## JSON automation

Every command accepts `--format json` and emits exactly one JSON object to stdout.
Runtime verification includes structured findings in that envelope. Text-mode
findings and error messages use stderr.

```bash
agents-md-compiler status \
  --manifest ./.agents/agents-md.toml \
  --format json
```

Drive automation from the exit code and inspect `state` for the reason:

| Code | Meaning                                                                  |
|------|--------------------------------------------------------------------------|
| 0    | Succeeded; `CURRENT` when a target state applies                         |
| 1    | Invalid invocation, input, I/O, or runtime verification failure          |
| 2    | Read-only difference: `LOCK_MISSING`, `LOCK_STALE`, `DRIFTED`, `MISSING` |
| 3    | Safety refusal: `SHADOWED`, `UNMANAGED_TARGET`, `CONCURRENT_CHANGE`      |

`--quiet` suppresses non-error stderr. It never suppresses JSON or requested
render output.

## Codex verification limits

`verify-codex` resolves `codex` from `PATH`, captures `codex --version`, confirms
that `debug prompt-input` is available, and verifies the complete selected bundle
in supported startup instruction evidence. It reports `CURRENT` only when exactly
one occurrence of the selected bundle ID has the expected header identity,
module order, boundaries, byte lengths, body digests, and complete rendered bytes.
Removing or changing a middle module cannot pass by retaining its markers.

The supported evidence is a root JSON array of response items, with typed
`input_text` content in system/developer messages or the producer's AGENTS wrapper
in user messages. Arbitrary user text, assistant/tool output, metadata, and keys
are not instruction evidence. Each accepted field is inspected separately:
fragments split across fields cannot make a complete bundle. Only JSON decoding
and strict UTF-8 encoding are allowed; whitespace, line endings, final newlines,
and Unicode are never normalized. This adapter follows an inspected producer
representation, not a promise of compatibility with every Codex version. See
[fixture provenance](tests/fixtures/README.md#codex).

Multiple bundles are distinguished by bundle ID. Identical complete module bodies
under different bundle IDs produce `CROSS_BUNDLE_CONTENT_OVERLAP` warnings, even
when module IDs differ. A verified selected bundle remains `CURRENT` with exit
code 0. Reusing a module ID for different content is informational
`MODULE_ID_REUSE`, not content overlap. Two copies of the selected bundle fail;
a current and stale or altered copy with the same ID fail as ambiguous identity.

JSON results expose `content_verified`, `modules_verified`,
`selected_bundle_occurrences`, and structured diagnostics. Legacy marker and
sentinel counters are diagnostic only; short or repetitive modules need no unique
sentinel to pass. A malformed foreign bundle makes `overlap_scan_complete` false
and produces a diagnostic. It does not fail an otherwise verified selection
unless its structure makes selected identity or boundaries ambiguous.

For the active global base or override file, the probe runs from a disposable
empty directory. For a project or nested target, it runs from explicit `--cwd` or
the target parent. The project directory must be equal to or below the target
parent.

The command sends no model request, requires no API authentication, changes no
Codex configuration, and makes no semantic-compliance claim. Complete content
visibility is not proof that a model follows the instructions. If the debug
interface is missing, fails, or returns an unsupported representation, the state
is `RUNTIME_UNVERIFIED` and the exact failing command is reported in both text and
JSON modes, including under `--quiet`. Contaminated values are redacted. Synthetic
adapter tests do not establish successful integration with an installed host;
that requires a successful live probe in the intended startup context.

## Documentation

| Document                                                   | Contents                                          |
|------------------------------------------------------------|---------------------------------------------------|
| [`docs/manifest-v1.md`](docs/manifest-v1.md)               | Manifest schema, path bases, and rejection rules  |
| [`docs/rendered-format-v1.md`](docs/rendered-format-v1.md) | Frozen legacy lock and rendered format            |
| [`docs/rendered-format-v2.md`](docs/rendered-format-v2.md) | Current portable lock and neutral rendered format |
| [`docs/cli-contract.md`](docs/cli-contract.md)             | Commands, options, JSON, states, and exits        |
| [`docs/security-model.md`](docs/security-model.md)         | Trust, path, concurrency, and recovery boundaries |
| [`AGENTS.md`](AGENTS.md)                                   | Generated project contract for repository agents  |
| [`CONTRIBUTING.md`](CONTRIBUTING.md)                       | Development, tests, and release boundaries        |

## License

MIT. See [`LICENSE`](LICENSE).
