Rules the agent runs into, not reads.

a sign beside an unlocked door can say do not enter. it may be clear, polite, and ignored. a lock changes the conversation because the door now decides.

that is the plain version of the problem i kept finding in agent workflows. i had careful prompts describing when an agent could write, who could edit, when tests had to run, and what had to happen before a commit. the instructions sounded strict. the model still held the final choice.

so i started moving the important rules out of prose and into executable boundaries. the usual term is enforcement-as-code. i prefer the test underneath it: does the system merely describe the right action, or can it refuse the wrong one?

01 / THE DISTINCTIONA request can sound like a rule

prompts are useful. they establish intent, sequence, vocabulary, and judgement. they can tell a planner not to edit or tell a reviewer not to approve its own work. none of that makes the instruction impossible to skip.

IGRIS now keeps an explicit enforcement registry for this distinction. an obligation can be backed by a gate, handled by automation, or left to the honor system. the registry also names where the mechanism lives and whether it has shipped. that matters because the label gate is otherwise too easy to apply to anything sternly worded.

there is another distinction inside the registry: surfacing is not blocking. some checks warn because refusing would make the stored state less truthful, or because the check observes historical accumulation rather than the moment when a defect can still be prevented. a warning can be useful. it is not a wall.

my working definition became narrower: a hard gate sits before the side effect, evaluates current state, and can return a refusal. if it runs after the write, or can only remind the model, it is an advisory.

02 / BRIEF FIRSTThe write asks for a brief

for registered IGRIS projects, the pre-tool hook examines write and edit requests before the file operation. it resolves the project, checks the brain for an in-progress brief, falls back to the filesystem brief cache when needed, and returns a deny decision when neither source yields one.

this is not the broad claim that nothing anywhere can write without a brief. the implementation has a boundary. it applies to write and edit tool calls that reach the hook. some operating-system and test paths are exempt. an unregistered project is allowed through. if the brain is unavailable and registration cannot be confirmed, the registration check fails open rather than blocking unrelated work.

there is also a deliberate one-shot bypass. using it emits a warning and attempts to record an event. recovery needs an escape hatch; pretending otherwise tends to produce unofficial ones. the useful property is not that bypass is impossible. it is that the normal path refuses, while the exceptional path is named and observable.

in the current tests, an active brief allows the write, no active brief returns a deny decision, notation variants of the in-progress state resolve consistently, and the explicit bypass allows with a warning. that is evidence for the gate's tested behavior, not a metric for every write ever made.

03 / PHASEThe state machine reaches the commit

brief-first controls entry into modification. phase discipline controls when that work may become a commit.

IGRIS records a live phase for the active brief. the workflow moves through planning, building, testing, reviewing, and committing. the pre-commit hook resolves the active brief for the current machine, reads its phase from the brain, and exits non-zero when a commit is attempted during BUILDING or TESTING.

this places the veto at the useful boundary. the builder can change code and the tester can run the suite, but neither phase can quietly turn its current state into a commit. the orchestrator advances the work after review and owns the commit step.

again, the caveats are part of the architecture. the phase guard has a one-shot bypass for the orchestrated commit. it also fails open when it cannot discover the active state, because a global git hook that blocks non-IGRIS work on missing local data would be a different failure. --no-verify skips git hooks entirely.

the tests exercise both sides: building is refused, reviewing is allowed, the bypass is honored, foreign-machine state is ignored, and missing brain state does not block. the gate is real inside those edges. the edges are not hidden.

04 / ROLESA role should arrive without the wrong tool

not every boundary is a shell hook. some are capability boundaries.

IGRIS defines its core roles with different tool sets. the architect and warden are read-only. the sentinel can read and execute tests but does not receive write or edit tools. the forger receives the tools needed to implement. the workflow then assigns those roles to different phases.

where a harness materializes those declarations as separate agent tool surfaces, the restriction is stronger than a prompt saying “do not edit.” the tool is absent. the reviewer cannot casually fix the code it is reviewing because its role does not hold the editing capability.

but this guarantee depends on the harness's delegation model. some harnesses load static agents. others define them at runtime. Cursor uses an inline recipe: one agent reads the role prompt, adopts its constraints, performs the task, then resumes. that preserves the workflow shape, but it is not the same hardware boundary as a separately provisioned role with a reduced tool set. i should call that role discipline, not pretend every adapter provides identical isolation.

05 / COMMIT EDGEThe last boundary scans what will leave

the commit edge carries several checks because it is the last local moment before bad state becomes history.

one hook rejects a commit summary longer than the repository's limit. another pre-commit block runs gitleaks against the staged diff and refuses on a finding while keeping the detected value out of the hook log. the same ruleset is exercised by repository tests against synthetic secret shapes, and a server-side workflow runs it again on pushes to develop or main and on pull requests.

that defence is layered rather than absolute. the local scan warns and skips if gitleaks is not installed. --no-verify bypasses local hooks. the server-side job is the second net, but whether it is merge-blocking depends on repository branch protection outside the workflow file.

this is also why i removed the old operational receipt. the current repository proves that specific gates exist, that their refusal paths are implemented, and that targeted suites pass. it does not provide a complete audit log covering bypasses across all write mechanisms. a neat number without that denominator would weaken the piece it was meant to strengthen.

06 / HARNESS BOUNDARYThe workflow travels farther than the blocking

IGRIS derives a harness tier from one manifest property: whether that harness exposes a supported hook surface. when hooks are supported, the harness is first-class and the executable gates can bind. when they are not, the brain, skills, MCP tools, and workflow can still travel, but the hook-backed gates soften to advisories.

in the current manifest, Claude Code, OpenCode, and Antigravity carry supported hooks. Codex, Gemini CLI, and Cursor do not. that membership is not editorial taxonomy; it is derived from the descriptor and should change when the descriptor changes.

this split keeps two claims separate. portable workflow means a harness can receive the roles, state, skills, and tools needed to do the work. portable enforcement means it can also execute the blocking boundaries at the right lifecycle events. the first can exist without the second.

that is the lesson i am keeping: documentation tells an agent what the system expects. a gate decides what the system will accept. both belong in the design, but only one gets to claim a veto.

next comes the less photogenic work: reduce the fail-open edges where it is safe, improve the audit trail where bypass remains necessary, and keep every advisory labelled as an advisory until a real attachment point exists.