Rail enforcement

A rail is a path glob that must not change while the ticket declaring it is in flight: the tests that define done, a lock implementation, a trust root. Rails are declared in each ticket's rails array. A rail declared by any active ticket is frozen for every change in the repo, not only that ticket's.

agb enforces rails at three points, and all three read the same active-ticket set.

Active tickets and their railsCopy Anchor Link

unionActiveRails unions rails across every active ticket in the store (lib/active-rails.mjs). A ticket is active unless it has completed: true or a completed, closed or archived status. A malformed ticket or an unknown status counts as active, and an unreadable store is reported as "rails present", so every caller fails closed (lib/active-rails.mjs).

In session: the PreToolUse policy guardCopy Anchor Link

The plugin registers one PreToolUse hook for every tool ("matcher": "*"), run through bin/hook-runner.sh with a 9-second watchdog (hooks.json). The guard reads the tool call and prints deny, ask, or nothing. It never prints allow (hooks/pre-tool-use.mjs).

• File and MCP tools are checked exactly: a write to a path matching an active rail is denied ("Target path matches frozen rail"), as is a write to the standing implicit rails: .git/, .adlc/config.json, .adlc/manifest.jsonl, .adlc/sessions.json, .adlc/tickets.json, .adlc/ticket-archive/, .adlc/ticket-transactions/ and .adlc/leases/ (hooks/policy/evaluate.mjs, hooks/policy/constants.mjs). An unreadable ticket store denies every mutation.
• Shell commands are lexed. In a repo with active rails, a command the guard cannot prove safe gets ask in an interactive session (hooks/policy/shell.mjs).
• agb workers are marked with AGB_WORKER_TICKET or AGB_WORKER_MODE. For them every ask becomes deny, and a builder may only write inside its own ticket's scope (hooks/policy/evaluate.mjs, hooks/policy/evaluate.mjs).

agy treats a hook that exits non-zero as a pass, so the runner always exits 0 and, on a crash or timeout, emits its fallback decision, which is deny by default (bin/hook-runner.sh).

During a runCopy Anchor Link

Before dispatching anything, agb run evaluates an enforcement gate (lib/scheduler.mjs, lib/run-integrity.mjs). It refuses to dispatch or merge any ticket when:

• a rail glob is malformed;
• the ticket store is unreadable;
• rails are declared (by the plan or by active tickets) but the adlc binary is not authenticated.

After each build, the ticket's own rails plus every active store rail are checked with adlc rails-guard --base <base> in the worktree (lib/scheduler.mjs). An operational error (missing adlc, timeout, unparseable output) counts as a violation and compromises the run (lib/scheduler.mjs).

In CICopy Anchor Link

On every pull request, .github/workflows/adlc-rails-guard.yml runs scripts/rails-guard-ci.mjs as stored on the base branch, so a PR cannot weaken the guard that judges it (adlc-rails-guard.yml). Since #87 (commit a99b3cd, after v1.0.0; decision D3) the guard reads rails from the .adlc/tickets/ directory store and falls back to a legacy .adlc/tickets.json. Both stores at once is an error (scripts/rails-guard-ci.mjs). Before #87 the CI gate saw no tickets.json on a migrated repo and enforced only the trust roots.

The guard:

1. Unions the rails of the active tickets in the base store.
2. Denies any change to a trust root: .adlc/config.json, .adlc/admin.pub, the workflow itself, CODEOWNERS, the guard script and its hash file, plus the store manifests (scripts/rails-guard-ci.mjs).
3. Allows only these ticket transitions: unchanged, completed in place, or archived with a verified envelope.
4. Runs adlc rails-guard against the base, then repeats the rail diff with rename detection off, so a frozen file cannot be moved out from under its glob (scripts/rails-guard-ci.mjs).

Exit codes: 0 pass, 1 fail closed, 2 deny.

Residual risksCopy Anchor Link

The guard's internals are covered in Policy guard. This repo's own rails and CI self-protection are covered in ADLC in this repo.