The .adlc/ Runtime

.adlc/ is the project-local directory where ADLC keeps its runtime state. Tools read and write it through @adlc/core; none of them re-parse it by hand. The directory is created by /adlc-init (or the per-editor scaffolders) and grows as gates run.

Directory layout

.adlc/
├── tickets/                # canonical active store: manifest + one shard per ticket
├── ticket-archive/         # canonical immutable archive shards
├── tickets.json            # legacy 1.x bridge; absent after approved migration
├── current-ticket.json     # pointer to the in-flight ticket (rails/prosecution use it)
├── config.json             # runtime config (ticket-sync, security posture)
├── manifest.jsonl          # hash-chained gate provenance ledger
├── manifest.lock           # lock guarding manifest appends
├── findings.jsonl          # prosecution findings ledger
└── ticket-sync.state.json  # gitignored sync sidecar (rebuildable cache)

tickets/: the canonical ticket store

The executable contract between P2 decomposition, P3 rails, P4 build, and P5/P6 evidence. Each ticket carries { id, title, body, scope[], rails[], edges[], duration, category, budget }. Tools load it through @adlc/tickets, which validates ids, filenames, duplicate ids, closed layout, and graph edges. Each ticket is independently mergeable, while the logical store hash is independent of shard ordering. Legacy .adlc/tickets.json remains fully operational until an interactive user approves adlc ticket store migrate; declining leaves it unchanged. The full schema and rules live in docs/ticket-authoring.md, and .adlc/tickets.example.json is a complete fixture.

current-ticket.json: the active-ticket pointer

Names which ticket is "in flight" so rails-guard and prosecution know what to enforce. It holds either a bare id string or { "id": "T7" }. The active ticket is resolved from ADLC_TICKET or this file. If both are set and disagree, that is treated as a tamper signal rather than an ambiguity, and resolution fails closed (conflict: true) instead of guessing. An unparseable pointer file is likewise a tamper signal and fails closed. This resolution is shared verbatim across every harness integration (Codex, Cursor, Antigravity, OpenCode) and @adlc/build-gate.

config.json: runtime config

Created with safe defaults by the scaffolders and never clobbered on re-init. It carries the ticket-sync provider configuration and the security posture for signed bundles (securityMode, signers, revokedKeys, securitySensitivePatterns, maxBundleAgeDays).

Ledgers: manifest.jsonl and findings.jsonl

Append-only JSON-lines ledgers, one object per line, written with appendEntry and read with readEntries (which reports malformed lines rather than swallowing them).

• manifest is the hash-chained provenance ledger written by gate-manifest when a gate is recorded. manifest.lock guards concurrent appends, and verify walks the chain to detect a break. Entries can be HMAC-signed when ADLC_MANIFEST_KEY is set.
• findings holds prosecution findings, each { ts, tool, file, line, category, severity, desc, verdict }, written by tools like lesson-foundry, model-ratchet, and gate-fuzzing.

Evidence snapshots

Behavior evidence is captured as JSON snapshots. behavior-diff writes a before/after route snapshot with writeSnapshot() and compares the two to prove a change is visible. Snapshots are plain files you point the tool at, not a fixed filename in .adlc/.

ticket-sync.state.json: the sync sidecar

Sync bookkeeping (tracker node ids, the 3-way base hash, create keys). It is a gitignored, rebuildable cache: no gate reads it, and it is never authored by hand. It is deliberately outside the rails trust root, so a routine sync leaves tickets.json byte-identical and never trips rails-guard. A missing or tampered sidecar fails safe (at worst it forces a conflict prompt on the next pull) and can be deleted and rebuilt at any time.

Rails trust root

A small set of runtime paths is the trust root the build gate treats specially. When computing whether a builder edited frozen rails, the active ticket store and .adlc/current-ticket.json are the trust-root inputs, and the mutable ledgers (manifest.jsonl, manifest.lock) are ignored so ordinary gate activity does not read as a rail edit.

Environment variables

Related

• Ticket authoring: the ticket schema and rules in full.
• The Lifecycle: which gate reads which state, phase by phase.
• Tool Conventions and Exit Codes: the contracts tools honor while reading this runtime.