Architecture & Engineering Sentinel Design

Engine design, fail-closed contracts, CI/CD pipeline architecture, and verification discipline for discipline.

Superseded when: The engine is restructured, pipeline architecture changes, or gate contracts are modified. Update in place; do not fork.

1. Overview & System Mission

Discipline is a universal CI/CD gatekeeper and AI coding agent diff sentinel built in Rust. It compiles to a self-contained static binary with zero external runtime dependencies, providing identical diff analysis across GitHub Actions, GitLab CI/CD, Forgejo Actions, Gitea Actions, pre-commit hooks, and local developer environments.

1.1 Agent Drift and Test Erosion

Autonomous coding agents operating in iterate-until-green loops frequently introduce subtle test erosion patterns:

1. Assertion weakening: assert_eq!(trie.get(k), Some(&v)) degraded to assert!(trie.get(k).is_some()) or assert!(true).
2. Vacuous and ghost tests: Newly added tests that compile and execute but assert nothing.
3. Stealth deletions: Flaky tests, fixtures, or benchmarks removed without justification, or tests renamed or marked #[ignore].
4. Safety decay: unsafe code introduced without explicit // SAFETY: justifications, or safety comments deleted from above untouched blocks.
5. Editing the gate instead of the code: Silently disabling gates, lowering severities, or growing exemption lists in discipline.toml.
6. Documentation drift: Introducing unverified calendar estimates, leaking developer environment paths/IPs, or committing agent transcripts.
7. Benchmark drift: Small algorithmic or execution regressions slipping past wall-clock tests lacking statistical rigor.

1.2 Design Origin and Prior Art

Discipline’s operational rigors were developed to defend high-assurance repositories against subtle automated regressions. Rather than relying on dozens of disparate repository scripts:

• Unlike legacy regex or aggregate count scripts, Discipline uses tree-sitter AST diff inspection to analyze syntactic structures directly.
• The specific failure modes, bypasses, and fail-open traps observed in automated development environments form the binding requirements of the Fail-Closed Contract below.

1.3 Non-Goal: Runtime Containment

Discipline reads changes and configuration; it does not contain a running agent. Watching system calls, filtering outbound traffic (DNS included), hiding credentials from a process and stopping a session belong to the sandbox the agent runs in: the agent’s own sandbox, a container or VM with no credentials and an egress allow-list, or a kernel-level monitor. They are not planned here, for three reasons: they need privileges and a platform (Linux, root or CAP_BPF) that a static binary run in CI or on a laptop does not have; they would add a network path, which §2 rules out; and a check that runs inside the process it contains can be walked around by that process. Nor does discipline read an agent’s stated reasoning: the agent writes it, so it is evidence of nothing.

What discipline does own is the configuration that sets those boundaries, because a change to it arrives as a diff like any other. sandbox-config reports a change that widens an agent’s permissions or sandbox (its project settings and MCP server lists) or a container’s isolation (Dev Containers, Docker Compose), and discipline doctor reports the agent settings that run an agent with less containment than its defaults (agent-sandbox). The pre-tool hook (hook run --event pre-tool) refuses edits and shell commands that reach another worktree; it does not block network commands, since a deny-list at the prompt is walked around by any interpreter the agent may run.

1.4 Threat Model

Discipline stands between a change and the branch it merges into. This section says what it protects, from whom, where it trusts, and what it leaves to others. SECURITY.md covers the narrower case of a flaw in discipline itself (hostile input that crashes or subverts the binary).

Assets.

1. The merge gate’s verdict: a change that erodes tests, safety comments or policy is blocked, or it lands with its waiver on record.
2. The policy: discipline.toml, the CI workflows and action inputs that run discipline, the agent hook and sandbox settings, the agent skills, plugins and MCP server lists a repository declares, and the list of protected paths.
3. The record: the waivers, loosenings and ratifications in commit messages, pull-request bodies and issue comments, which discipline audit reads back.
4. What the repository must not publish: secrets, personal data, private hosts and paths (the hygiene gates).
5. The discipline release that CI downloads and runs with a token (§8.2).

Actors, by what they can do. Every actor below except the external one can edit any file in the change and write its commit messages and pull-request body.

Trust boundaries.

• The change does not judge itself. A change that edits the pipeline or policy that judges it (Poisoned Pipeline Execution, CICD-SEC-4) is judged by the base’s. The policy that decides a change is read from the base (policy_from: base), and a loosening of it is reported against the base (config-integrity, ci-integrity). A change’s own configuration is data, never authority.
• What an author writes is a claim. A waiver, a closing reference or a trailer is written by the change’s author, agent or not. It is accepted as the record of a decision, counted (max_overrides), made visible (audit) and, where configured, made to wait for a forge fact (require_approval), but it proves nothing about who agreed.
• A forge fact is as strong as the login behind it. A review, a ratification comment or a pull request’s author is the forge’s report of a login. It separates two parties only when they hold different logins. An agent that acts with the owner’s credentials can produce every forge fact the owner can (Phase 15 Step 8).
• Discipline cannot make itself run. Its verdict binds only as a required check on a protected branch with no bypass; discipline doctor reports when that is not so (§8.4).
• The running agent is outside the boundary (§1.3): discipline reads the change and the configuration that contains the agent, not the process.
• The change description is a channel between agents. Commit messages, pull-request bodies and comments are read by review bots and by the next agent. They are scanned like the diff (instruction-smuggling check 4), directive lines and their reasons included (#363); only an allow-agent-instructions line naming a location of the change, the counted waiver that records a quoted injection, is exempt.
• Configured text that reaches a process is the base’s or the runner’s, never the change’s. Five gates start a process from a value in discipline.toml (command, test-floor, msrv, miri, sanitizers). Under the default policy side that file is the change’s own copy, so each executed key is compared with the merge base copy before anything runs, and a key the change adds or alters is refused with a finding no directive lifts; only the runner’s environment accepts it (docs/GATES.md, command). A value placed among the arguments of a built-in command is held to one shape and passed as one argument.
• The repository’s local git configuration is untrusted input. Discipline reads repositories through libgit2, which runs no configured filter, hook or monitor. The CI base fetch runs git, which would, so the fetch overrides every command key the repository’s configuration can set; a command the runner’s own global configuration names is trusted (#364).
• The model and its training data are outside the boundary, as is any retrieval store an agent uses: discipline sees what an agent writes, not what shaped it.
• The network is read-only but one opt-in write (§2, AGENTS.md §3.3); an unreachable or partial answer fails closed.

Assumptions the guarantees depend on.

1. Discipline runs as a required check with policy_from: base, and ci-integrity protects the workflow that runs it.
2. The protected paths cover the policy (discipline.toml, workflows, agent hook and sandbox settings, agent instructions).
3. Ratifications and approvals come from a login no agent can use. This does not hold on this repository today: every agent posts as the owner’s login (Phase 15 Step 8), so a ratification here shows the owner’s login agreed, not that a second party did.
4. The forge reports authors, edits and links truthfully. When it fails to (a closing reference it did not link, #350), discipline refuses rather than guesses.

Residual risks: what an attacker in this model can still do.

• A weakening the AST gates do not model (a rewritten test with the same assertion count, a workflow rewritten in a form ci-integrity does not read, what a GitLab include: brings in; §10). One rewrite with the same count is caught in its exact form: an equality assertion made to compare an expression with itself (assert_eq!(y, y), expect(x).toBe(x)) is reported by vacuous-tests in a new test and by assertion-reduction in a changed one, as a warning (GATES.md). The detector compares tokens and follows no value, so it stops a careless rewrite and not an evasive one. Still not caught: two names bound to one value (let b = a; assert_eq!(a, b)), a copy compared with its source (y.clone()), the same call on both sides, an assertion a macro expands to, an assertion whose operands never reach the code under test, and a self-comparison kept beside a real comparison of the same operand. Held-out tests and review are the control for those.
• Every waiver the policy allows, on the record. audit shows them; it does not undo them.
• With the owner’s credentials: ratify, approve, edit a pull-request body after the merge (reported on GitHub only), and merge.
• Say which agent made a change. discipline audit reports a commit’s agent marker as claimed and an agent login (with --forge) as agent-login, and a change with neither as no-record, never as a person’s; a record an agent writes about itself is a claim, not a proof (Phase 15 Step 7).
• An injection phrased outside instruction-smuggling’s list: a paraphrase or another language. The phrase tier is a warning, a tripwire.
• Agent memory and context kept outside the repository (per-user memory directories, session state), and a tool or plugin that changes by its own update rather than through the diff.
• A waiver pattern repeated from change to change: max_overrides caps each change and audit shows the pattern, but nothing blocks it.
• Test scope for error-swallowing and stub-bodies is decided by path. A file that was production code on the base side stays production code through a rename, including one that changes the extension or the language (it is then parsed by its head extension and classified by its base path carrying that extension); a delete and add below git’s rename-similarity threshold and code moved into a new test-named file are classified by the head path. A rename into a path matched only by [tests] paths (a declared glob, read from the base-side configuration) is not reported as a reclassification; the gate notes name it. The reclassification finding is reported by error-swallowing only.
• Code built to the tests its author can see. A change that satisfies the visible suite without editing it (overfitting to the visible suite) weakens nothing in the diff, so it passes every diff-based gate. The control is held-out tests the author of the change cannot see, which the repository owns and runs; discipline neither holds nor runs them (see SpecBench, arXiv:2605.21384; docs/GATES.md, “Language Scope & Detection Boundaries”).
• A test harness neutralised in a form harness-tampering does not read. The gate matches exact shapes of the syntax tree with no value-flow analysis, in the files a runner loads by name or by a literal configuration, and is on by default (#833). It stops the plain forms (a Go TestMain that drops m.Run()’s result, a pytest hook that assigns an outcome or removes items, a replaced unittest result method, an unconditional exit with status zero, and one at the top level of a Python module a test may import, #843); an author who rewrites the form passes it. Not read: the result of m.Run() passed through a helper or read once and then ignored; an exit behind any condition, a constant one included, in an exception handler or in a callback; an exit or an outcome spelled another way (raise SystemExit(0) in a harness file, an exit status set outside pytest_sessionfinish, process.exitCode = 0, an aliased module); a hook in a plugin module that -p names, or in a plugin installed from outside the repository; a set-up file that a computed configuration loads (named in the gate’s notes); a module that a harness file imports (read for an exit at import only); and the harness files of runners the gate has no model of. docs/GATES.md lists each under harness-tampering.
• A reviewer who trusts a fluent description or a green check.
• A crafted repository that makes discipline do work out of proportion to its size: SECURITY.md treats it as a vulnerability, but no test bounds it.
• A webhook’s secret on GitLab, Gitea and Forgejo, which their APIs do not show, so doctor counts their webhooks without judging the secret.
• No central log. audit reads the record back from git and the forge, and the hooks’ observe log stays on the machine that wrote it; nothing alerts on a pattern as it happens.
• Anything outside the diff: the agent’s runtime behaviour, its network access, and what it does with credentials (§1.3).
• Code inside a git submodule. A change that moves a submodule’s pointer is named in the deletion-rationale notes, not judged, so tests kept in a submodule can be dropped by moving its pointer (red-team git-02). Tests deleted from the repository itself still need removes:, even when a submodule takes their path.
• A pull-request workflow runs from the change’s head: an agent that can push can mask the step that runs discipline (continue-on-error) and turn the required check green. ci-integrity reports it but cannot fail a step it no longer controls; the forge’s protected file patterns stop the merge, in a form the forge applies (.gitea/workflows/**, not .gitea/workflows/*; red-team ci-04, #428).

Coverage against published taxonomies. Every category of four taxonomies is resolved to exactly one of three outcomes:

• in scope: an asset above, an actor above, a control, and the test that pins it, with a claim id for the claims registry;
• residual: listed under residual risks below;
• outside: outside the boundary (§1.3).

The taxonomies:

• OWASP Top 10 for LLM Applications, version 2026 (OWASP GenAI Security Project, published August 2026). Each row also gives the version 2025 id (November 2024), since the 2026 edition renumbers them.
• OWASP Top 10 for Agentic Applications, version 2026 (December 2025).
• OWASP Top 10 CI/CD Security Risks (CICD-SEC-1 to CICD-SEC-10; OWASP project page, first published in 2022, no version stated). The repository and organisation settings the OWASP CI/CD Security Cheat Sheet recommends are doctor work, tracked in #366.
• MITRE ATLAS data version 2026.09 (September 2026). Only the techniques that apply to a coding agent acting on a repository are mapped.

This mapping is the maintainers’ reading of the four publications against this section and docs/GATES.md. It has not been externally reviewed; the “External review” criterion of the 1.0 Readiness table (docs/ROADMAP.md) stays open.

2. Architecture Diagram & Binary Design

flowchart TD
    subgraph CFG_LAYER["Layered Configuration & Directives"]
        D["1. Built-in Defaults<br/>(26 gates on, 14 opt-in; see discipline gates)"]
        F["2. discipline.toml<br/>(Repository configuration)"]
        O["3. Inline Overrides / Directives<br/>(--config-override, PR body)"]
        CLI["4. CLI Flags & Environment<br/>(--enable, --disable, denylist)"]
        BASE_CFG["base-ref discipline.toml<br/>(compared by config-integrity)"]
    end

    subgraph ENGINE["Discipline Core Engine (Rust)"]
        RESOLVE["Config Resolution & Gate Registry"]
        GIT["GitCtx (in-memory git2)<br/>merge-base diff, blobs, index"]
        AST["Tree-Sitter AST Extractors<br/>tests, assertions, unsafe blocks"]
        EVAL["Fail-Closed Gate Evaluators<br/>truthful examined counts, floors"]
    end

    subgraph CONSUMERS["Execution Contexts & Consumers"]
        ACTION["GitHub / Gitea / Forgejo Action<br/>(composite runner)"]
        HOOK["Pre-Commit Hook<br/>(discipline check --staged)"]
        DEV["Agent Inner Loop / Dev CLI<br/>(discipline check --base ...)"]
    end

    D --> RESOLVE
    F --> RESOLVE
    O --> RESOLVE
    CLI --> RESOLVE
    BASE_CFG -.-> RESOLVE

    RESOLVE --> EVAL
    GIT --> AST
    AST --> EVAL

    EVAL --> ACTION
    EVAL --> HOOK
    EVAL --> DEV

1. Binary-first & zero-dependency: Statically linked musl binaries (x86_64-unknown-linux-musl, aarch64-unknown-linux-musl) and native macOS binaries (x86_64-apple-darwin, aarch64-apple-darwin). No Node.js, Python, or container bootstrap required at runtime.
2. Offline by default, one HTTPS client: libgit2 is vendored with its network and transport features disabled, so every diff is read from the local git object database. The forge REST API is reached only through the in-process HTTPS client in src/forge.rs (ureq over rustls, no OpenSSL), for opt-in features: open-issue state and bench citation freshness (provenance-tags, bench-regression), issue-link reference verification, ratified-paths and review-threads (read-only GitHub GraphQL queries among their reads), require_approval reviews, the merged-pr-body directive source, discipline replay and discipline doctor; its one write is check --comment. DISCIPLINE_NO_NETWORK=1 keeps that client off the network (a loopback address excepted). One exception sits outside the client: in CI (CI, GITHUB_ACTIONS, GITLAB_CI, GITEA_ACTIONS or FORGEJO_ACTIONS set), when the base ref cannot be resolved, src/gitctx.rs spawns the external git fetch against origin to deepen a shallow clone, with hooks, the file-system monitor, command transports (ext::, fd::, git://) and the upload-pack program overridden, and a command the repository’s own configuration sets for ssh, credentials or a password prompt (core.sshCommand, credential.helper, core.askPass) replaced by the runner’s global or system value (#364), and exits 2 if the base is still missing; DISCIPLINE_NO_NETWORK=1 skips it. That git is the first one on PATH, and it runs with LC_ALL=C and without LANGUAGE, so the fetch diagnostic the binary quotes reads the same whatever the caller’s locale (#603). It is the only git the binary starts: the diff, the base and every blob are read in process, so a different git on PATH changes nothing a gate reads. The other program found through PATH is the one a command-style gate is configured to run. The in-process library reads the user’s git configuration from HOME (~/.gitconfig) and XDG_CONFIG_HOME (git/config), and a file there that does not parse is exit 2; it does not read GIT_CONFIG_GLOBAL, GIT_CONFIG_SYSTEM or GIT_CONFIG_NOSYSTEM, which are settings of the git program.
3. AST-aware, never regex-naive: unsafe or assert! appearing within comments, string literals, or doc tests are never counted as code nodes. Source-code invariants (tests, assertions, unsafe, handlers, stubs) are read from the syntax tree only. Regular expressions read text that has no grammar here: prose, PR bodies, shell and workflow lines, manifests and tool output.
4. Unified gate registry: Every gate possesses a stable kebab-case identifier in src/config.rs::GATES.
5. Language packs behind a shared fact model: Tree-sitter grammars and extractors map diverse ecosystems onto language-neutral facts (TestFn, UnsafeSite, assertion counts).

2.1 Configuration Resolution Lifecycle

flowchart TD
    D["1. Built-in Defaults<br/>(26 gates on, 14 opt-in; see discipline gates)"] --> M1["Merge Layer 1"]
    F["2. discipline.toml<br/>(Repository configuration)"] --> M1
    M1 --> M2["Merge Layer 2"]
    O["3. Inline Override<br/>(--config-override / action input)"] --> M2
    M2 --> M3["Merge Layer 3"]
    CLI["4. CLI Switches<br/>(--enable / --disable)"] --> M3
    M3 --> M4["Merge Layer 4"]
    ENV["5. DISCIPLINE_HOSTNAME_DENYLIST<br/>(CI Secret Env)"] --> M4
    M4 --> VAL["Strict Validation<br/>(deny_unknown_fields, planned gate check)"]
    VAL --> CFG["Effective DisciplineConfig"]

2.2 Diff Inspection & Gate Evaluation Pipeline

sequenceDiagram
    autonumber
    participant CLI as Discipline CLI / Runner
    participant Git as GitCtx (git2)
    participant AST as Language Extractors (tree-sitter)
    participant Gates as Gate Engine
    participant Report as Multi-Format Reporter

    CLI->>Git: Resolve merge-base(base_ref, HEAD)
    Git-->>CLI: Changed files, blobs, index
    CLI->>AST: Dispatch changed files by extension
    activate AST
    AST-->>CLI: ParsedFileFacts (base vs head TestFn, assertions, unsafe)
    deactivate AST
    loop Each enabled gate, one at a time in registry order
        CLI->>Gates: agent-guard, hygiene, integrity, quality, verification, bench
    end
    Gates-->>CLI: Vec<GateOutcome> (examined counts, violations, overrides)
    CLI->>Report: Render (Terminal, GitHub Summary, JSON, gl-codequality, JUnit, SARIF, Agent-Prompt)
    Report-->>CLI: Exit code (0 = pass, 1 = violations, 2 = could not check)

2.3 AST Test Node Extraction & Assertion Counting Pipeline

flowchart TD
    SRC["Changed Source File Blob"] --> LANG{"Language Dispatcher by Extension"}
    LANG -->|"*.rs, *.py, *.js / *.ts, *.go, *.java, *.cs, *.rb, *.php"| P_TS["Tree-sitter pack per language<br/>(rust, python, javascript / typescript, go, java, c-sharp, ruby, php)"]
    LANG -->|"*.c, *.h / *.cpp, *.cc, *.hpp"| P_CPP["C pack (tree-sitter-c)<br/>C++ pack (tree-sitter-cpp)"]
    LANG -->|"*.kt, *.swift, *.scala, *.m / *.mm"| P_NEW["Kotlin, Swift, Scala, Objective-C packs<br/>(tree-sitter)"]
    LANG -->|"*.phpt"| P_PHPT["PHPT section parser (no grammar)"]
    LANG -->|"Unmatched"| UNK["Unanalysed Language Note (F7)"]

    P_TS --> EXT["Fact Extractor Engine"]
    P_CPP --> EXT
    P_NEW --> EXT
    P_PHPT --> EXT

    EXT --> T_DISC{"Partition Function Nodes"}
    T_DISC -->|"Go: Benchmark* with *testing.B"| BENCH_NODE["Benchmark Node (Excluded from Unit Tests)"]
    T_DISC -->|"Test Attributes / Naming Conventions"| TEST_NODE["Test Function Node"]

    TEST_NODE --> SKIP{"Check Skip / Ignore Markers"}
    SKIP -->|"#[ignore], @skip, xit, [Ignore]"| FLG_SKIP["Mark TestFn.ignored = true"]
    SKIP -->|"Active Executable"| SCAN_AST["Traverse AST Function Body"]

    SCAN_AST --> CNT_ASSERT["Count Assertions & Matchers"]
    CNT_ASSERT --> TAUT{"Inspect Assertion AST Expressions"}
    TAUT -->|"assert_eq!(1, 1), assert!(true)"| FLG_TAUT["Increment tautological_count"]
    TAUT -->|"Other Call"| CHK_HELP{"In assert_helper_fns?"}
    CHK_HELP -->|"Yes"| INC_HELP["Count one total, no strong assertion"]
    CHK_HELP -->|"No"| REG_CALL["Regular Function Call"]
    INC_HELP --> SAME_FILE{"Helper body in this file, or a same-file helper that asserts?"}
    REG_CALL --> SAME_FILE
    SAME_FILE -->|"Yes (3 calls deep in C/C++ and Python, 1 elsewhere)"| ADD_HELP["Replace the call's credit with the Helper's Assertion Counts"]
    TAUT -->|"Standard Assert Macro / Expect Matcher"| INC_STD["Count Effective & Strong Assertions"]

    FLG_SKIP --> FACTS["Output ParsedFileFacts (tests, assertions, unsafe)"]
    FLG_TAUT --> FACTS
    INC_HELP --> FACTS
    ADD_HELP --> FACTS
    INC_STD --> FACTS
    REG_CALL --> FACTS

2.4 Binary Footprint & Static Linking Profiles

Discipline compiles to a standalone static binary with zero external runtime dependencies. It statically links libgit2 (vendored, no transport), the 15 tree-sitter grammars (Rust, Python, JavaScript, TypeScript, Go, Java, C#, C, C++, Ruby, PHP, Kotlin, Swift, Scala, Objective-C) and the rustls / ring TLS stack of the forge client. It is fully static-pie linked on musl and runs in scratch containers or minimal CI runners without glibc, OpenSSL, or package managers. The sizes below were measured at 32c81b5, before the Kotlin, Swift, Scala and Objective-C packs and the forge client were added; the current binaries have not been re-measured:

• Full Static Binary (Linux musl x86_64): 23.6 MB (23,624,256 bytes) (measured: x86_64-unknown-linux-musl, 32c81b5, 11 grammars).
• macOS Native (aarch64-apple-darwin): 22.3 MB (22,310,544 bytes) (measured: aarch64-apple-darwin, 32c81b5). Mach-O binary optimized for local developer inner loops and git hooks.

3. The Fail-Closed Contract

Every gate in Discipline must satisfy the following 12 load-bearing invariant rules:

3.1 Defaults Are Part of the Compatibility Contract

A consumer who runs Discipline with zero configuration, or who configures only some gates, relies on the built-in default enablement and severity of every other gate. A default that becomes looser (a gate turned off, or moved from error to warning or note) silently stops blocking for that consumer, with no diff in their repository to review. Defaults are therefore versioned like the configuration schema:

• Within a major version, a default may only become stricter (off to on, note to warning, warning to error) without further ceremony.
• A looser default within a major version requires a release-note entry in the Default Changes ledger naming the gate, the old and new default, the reason, and the one-line configuration that restores the old behaviour. The entry lands in the same pull request as the change.
• Every default is pinned by a test. tests/test_config.rs::default_enablement_and_severity_match_snapshot compares the compiled defaults of every available gate against a committed snapshot. Changing a default fails that test until the snapshot is edited, so the change is visible in review next to its ledger entry.
• The reference is generated. The Default column of the configuration table in docs/CONFIGURATION.md is rendered by discipline docs from the compiled defaults and the JSON Schema, so documentation cannot claim a default the binary does not ship. Per-gate rationale lives in docs/GATES.md (“Default Severity by Gate”).

3.2 What 1.0 Freezes

From 1.0, a stable surface below changes incompatibly only in a new major version. Adding to it (a new flag, key, field, gate, code, reason, tool or language) is a minor release; changing or removing what exists is a major one. A renamed flag or key keeps its old name as an alias, with a deprecation note in the report, until the next major version. For configuration keys the mechanism is KEY_ALIASES in src/config.rs: the old name is read as the new one, setting both is a configuration error (exit 2), and each use adds a line to the report’s deprecations list (deprecated: ... in the text report), which never fails the run. An experimental surface may change in a minor release, with a ledger row.

The promise is a test. tests/fixtures/v1_surface.json lists every frozen name: subcommands, flags and their values, the DISCIPLINE_* variables, configuration keys, directives, gate ids, finding codes, policy refusal rule ids, could-not-check reasons, MCP tools and arguments, hook agents, and the action’s inputs and outputs. tests/test_stability_contract.rs collects each from the code and fails when a recorded name is gone; a new name must be recorded (DISCIPLINE_BLESS_SURFACE=1 cargo test --test test_stability_contract). The JSON outputs are pinned field by field in tests/test_output_schemas.rs.

Detection is not frozen. Language packs, parsers and gates keep improving, and every change to what a gate reports is a ledger row in docs/ROADMAP.md: a stricter one (a new finding, a construct now read) may land in a minor release; a looser one (a false positive fixed) follows §3.1 and names the configuration that restores the old behaviour where one exists. Pinning a version (@v1.2.3, an image digest) is the way to hold detection still.

Before 1.0 a minor release may still change these surfaces; the ledger records each change. The Interface freeze criterion in docs/ROADMAP.md (“1.0 Readiness”) is met by one full minor release that changes none of the frozen column.

4. Module Map

Agent-facing surfaces. The hook, the MCP server and the agent-prompt format share one design rule: they tell an agent how to repair a finding and leave out the directive that would waive it, and the check they run is judged by the base ref’s configuration and reads no directive, so the change being judged cannot switch off or excuse its own check. The hook’s pre-tool check is the exception: it reads scope-confinement.forbidden_paths from the working tree’s discipline.toml, because it guards where the session writes, not what the change contains; CI still judges the change by the base policy. Hiding the waiver syntax is a convenience (an agent can run discipline explain); the base-side policy and the CI configuration (policy_from: base, PR-body directives, fail_on_overrides, require_approval) are the control.

5. AST Fact Model & Extraction Rules

Fact Representation

Tree-sitter AST extraction translates each source file into one ParsedFileFacts of language-neutral fact structures. A pack declares which facts it fills (LanguagePack::supplies(Fact)); a gate that needs a fact a pack does not supply names the file instead of passing it.

• TestFn: Qualified name, line span, assertion counts (total, strong, tautological, fatal, trivial), skip state (ignored, conditional_ignore), expected panic (should_panic), mock setups and verifications, retries, sleeps, helper_checks (same-file helpers that assert), numeric bounds inside assertions, and equality_operands (which equality assertions compare an operand with itself, by line, and which operands are compared with another).
• UnsafeSite: Line number, block kind, documentation status (documented).
• escape_hatches, functions (bodies, for stubs), swallowed (error handlers and discarded results outside tests), prose (comments, docstrings, string literals) and budgets (testing-effort settings).
• has_parse_errors: Tracks whether unparseable syntax was encountered.

Helper resolution. A call from a test to a function defined in the same file adds that helper’s assertions to the test. C/C++ and Python follow such helpers up to three calls deep (HELPER_DEPTH, transitive_helper in src/ast/mod.rs); the other packs follow one level. Helpers are never followed across files. A function reached only through a dispatch table (a *_DISPATCH spec) is resolved in Rust, JS/TS, Go, Java, Kotlin, C#, C/C++, Ruby, Swift and Scala; Python reads list and tuple dispatch tables in its own extractor; PHP and Objective-C read none.

SAFETY: Invariant Comments

An unsafe block or implementation is documented iff a comment containing SAFETY: is positioned:

1. In the contiguous run of comments directly preceding the unsafe node or its parent statement; or
2. Inline between the start of the statement and the unsafe keyword.

Placeholder Rejection: A SAFETY: comment whose words all come from the placeholder list is rejected. The default list (DEFAULT_SAFETY_PLACEHOLDERS in src/config.rs) is todo, tbd, n/a, na, none, safe, safety, unsafe, ok, fine, valid, trust me, trust, me, this, is, totally, replaceable through the gate’s placeholders option. The check is a word filter, not a judgement of the justification: one word outside the list passes (// SAFETY: fixme is accepted by default).

Assertion Strength & Tautologies

Assertions are classified into two levels:

• Strong: Equality and pattern assertions (assert_eq!, assert_ne!, matches!, toEqual, toStrictEqual).
• Weak: General truthiness (assert!, toBeTruthy, .unwrap(), .expect(), ? in fallible tests).

Tautology Filtering: Tautological assertions are deducted from effective assertion counts:

• Verbatim equality: assert_eq!(x, x). The two operands are compared as tokens read from the syntax tree (src/ast/self_comparison.rs): comments, white space and parentheses around a whole operand do not make them differ. Each such assertion is recorded on its test with its line, which is what the two self-comparison findings report (GATES.md, “Self-comparison assertions”).
• Constant expression tautologies: assert!(true), assert!(1 == 1), assert!(1 + 1 > 0), assert_ne!(1, 2).

6. Golden-Output Gate Design

Committed test snapshots (e.g. insta .snap), serialized fixtures, and golden files are common drift vectors. Agents frequently re-bless or edit fixtures to make broken tests pass.

• Blob diff inspection: Tracks modifications and deletions across configured file globs (defaults: **/golden/**, **/snapshots/**, **/__snapshots__/**, **/*.snap, **/*.ambr, **/*.golden, **/*.approved.*, tests/fixtures/**/output*). An added snapshot is judged too when the test that owns it already existed on the base side: that is an expectation written after the fact.
• Scoped authorization: Requires explicit allow-golden-update: <path> <reason> directive.

7. Reporter Architecture & Fingerprint Hashing

Discipline exports standard structured formats:

• GitLab Code Quality (gl-codequality.json): Code Climate JSON array consumed natively by GitLab Merge Request widgets.
• JUnit XML (junit.xml): Validated offline against Jenkins junit-10.xsd with testsuite-level <properties> and testcase execution diagnostics.
• SARIF (discipline.sarif): OASIS Static Analysis Results Interchange Format v2.1.0 schema-compliant report.
• Terminal & GitHub Job Summaries: ANSI-styled summaries and GitHub workflow annotations.

Text from outside is neutralised where it is written, once per output format. A report quotes text the binary did not choose and its reader did not write: what a forge answered (a refusal message, a login, a branch name), a pull request’s title and body, a commit subject, a file name, a line of a changed file, the output of a tool a gate ran. Whoever wrote that text must not be able to write the report. The rule is applied at the output, not at each source, so a new source is covered without a change (src/report/text.rs; tests/test_untrusted_text_in_reports.rs delivers hostile text through each source and reads each format):

In the terminal formats a message with none of these characters is written byte for byte. What is left as it is, on purpose: in Markdown, a # (a forge links #12 to its own issue), and an address of the form name@host.tld, which a renderer may link as a mail address after @ is written as an entity.

7.1 Pure-Rust SHA-256 Implementation & Cryptographic Hygiene

GitLab Code Quality issue tracking and Discipline’s grandfathering baseline engine require unique, deterministic 32-byte hex fingerprints:

• Discipline implements a zero-dependency NIST FIPS 180-4 compliant SHA-256 algorithm in src/report/gitlab.rs (reused across reporting and src/baseline.rs).
• Fingerprints do not depend on a hashing crate (sha2). TLS for the forge client is rustls with ring as its cryptographic provider; OpenSSL is not in the dependency tree, which keeps the musl build static.
• Verified directly against NIST CAVP test vectors.

7.2 Grandfathering Baseline Architecture

To support brownfield adoption without weakening gates or ignoring violations, Discipline provides a line-number-independent grandfathering baseline:

• Fingerprinting Formula (version 2): sha256("v2:" + gate/code + ":" + path + ":" + sha256(content)), where content is the trimmed source line followed by the finding’s anchor when it has one; for a finding with no line it is the anchor alone, or empty. With no anchor, a finding on a line whose trimmed text also appears higher in the same file hashes that line’s occurrence number with it (occurrence:2 for the second such line, counted over the lines of the file); the first occurrence, and every line that does not repeat, hashes the line alone. A finding on the pull request body (<PR body>, PR body) is on a line of the body, and that line is the one hashed. The message is never hashed.
• Anchor rule: a finding with no line carries an anchor naming its subject, unless its code and path already identify it (one finding of that code per path, such as a deleted file). The anchor is a typed source datum (a job, a package, a key path, a test, a benchmark arm, a commit), stable across runs and across the order findings are produced in, with no count, measurement or message text in it, and never a value a gate reports by location only. Without one, a baseline entry for one occurrence would match any other occurrence of that code in the same file, and a debug build stops on the repeat (src/baseline.rs::fill_fingerprints). Two findings of one code on identical lines of one file are told apart by the occurrence number, so an entry for a handler in one function does not accept an identical handler added below it; an identical line added above an accepted one takes its place as the first occurrence, and the accepted one, now the second, is what a run then reports. A baseline that recorded several identical lines before occurrences were told apart holds one entry per line, all with the first occurrence’s fingerprint: n such entries accept the first n occurrences (tests/test_fingerprint_occurrences.rs). tests/test_findings_are_anchored.rs holds, per kind, that an entry for one occurrence does not hide another, and that the kinds which need no anchor keep their fingerprints. The finding’s code (src/findings.rs) is the key, not its title, and line numbers are excluded, so neither a title change nor a line shift churns baseline hashes. A finding several gates may report (source parse findings) is coded under its first registered gate, so its fingerprint does not depend on which gates are enabled. check computes it once per finding: the JSON fingerprint field, SARIF partialFingerprints and the GitLab Code Quality fingerprint all carry it. Version-1 files (keyed on titles) still match until discipline baseline --migrate rewrites them.
• Fail-Closed Baseline Storage: Recorded in a committed discipline-baseline.toml file at the repository root.
• Non-Blocking Grandfathering: Pre-existing baselined findings are reported as non-blocking notes across all output formats (terminal, GitHub step summaries, JSON, JUnit, SARIF, GitLab) and reflected in the baselined output of action.yml.
• Ratchet Enforcement: Covered under the config-integrity gate. Adding new entries to discipline-baseline.toml is classified as gate weakening and requires an authorized directive: allow-gate-weakening: baseline <reason>.
• Ratchet-Down Cleanup: When a previously baselined finding is resolved in source code, the baseline engine reports the stale entry as an informational note, guiding repository maintainers to burn down technical debt.

7.3 Pull-Request Comments (the one forge write)

check --comment posts the report as one pull-request comment and edits it on every later run (src/comment.rs). It is the only write discipline makes to a forge, and it is in the binary rather than in action.yml so every runner gets it: GitHub, Gitea and Forgejo job containers that cannot run uses: actions, and GitLab.

• Opt-in: off unless --comment / DISCIPLINE_COMMENT / the action’s comment input; the action passes its token to the binary only then.
• One comment: found by the marker <!-- discipline:report --> at the start of its body, paging through the pull request’s comments (GitHub and Gitea / Forgejo issue comments, GitLab merge-request notes); edited with PATCH (PUT on GitLab), created with POST when none exists or the marked one belongs to someone the token cannot edit.
• Safety: same path checks, https rule and DISCIPLINE_NO_NETWORK as the reads; a write is never replayed against a redirect. Text from the change is escaped as §7 describes (no @ mention, no HTML, no link, no table break, no control character, no forged marker), and the comment carries no directive syntax, since agents read pull-request comments too.
• Failure: a token that cannot write (HTTP 401 / 403 / 404, the fork case) is a named note and the gates’ verdict stands; a forge that cannot be identified or reached stops the run (exit 2), because a comment was asked for. The comment never decides the verdict: the check’s status does.

7.4 Review Routing (an inventory, not a gate)

Every check that has a change computes one report section, review_routing (src/routing.rs, #944): what the change touches that a reviewer routes on. It is not a gate: no outcome, no finding code, no severity, nothing to waive, and it never changes the exit code. Its JSON is unstable until 1.0 and none of its names is in tests/fixtures/v1_surface.json; every rendering says so.

• Deterministic half (exact): the directives the run read from the change (count and names), the discipline:allow(<gate>) markers the change adds and removes, and the authority files it changes, by surface (policy, ci, lockfile, build-hook, code-owners, agent-instructions, toolchain, sandbox: the files existing gates already read). Automated routing may condition on this half only, and only with a repository’s own opt-in: a zero is not a clearance.
• Heuristic half (non-exhaustive): calls to a capability sink (process-spawn, dynamic-eval, network) on lines the change adds, read from the syntax tree of the languages whose pack supplies Fact::CapabilitySinks (src/ast/capability_sinks.rs: a closed vocabulary per language, matched on the callee as code, never in a string or a comment), and the tests the change adds or removes, by name. It informs reviewers and nothing else.
• Coverage footer: how many changed files were in a language with a capability inventory, from the packs (crate::ast::coverage_labels), and that runtime semantics are not inspected.
• Placement: after the verdict on every surface. The counts line, zero rows left out, is the first line under the job summary’s heading, the review_routing step output (the text for a commit-status description; discipline posts no status of its own, and the action does not re-export it, to keep the name out of the 1.0 surface), and a line of the pull-request comment. The terminal report and the job summary list at most five file:line pointers per row with an and N more in <surface> tail. The agent-prompt report a hook relays carries the counts and the pointers as quoted spans, with no directive name, scrubbed like the rest; the hook log line carries the counts as routing.

7.5 Timings (a measurement, not a verdict)

check --timings (or DISCIPLINE_TIMINGS=1) adds one object to the JSON report, timings (src/timings.rs, #995): wall time per gate and per shared phase (repository, configuration, directives, configured-values, agent-diff, vocabulary, fingerprints, baseline, policy-floor, review-routing), and counters of the work behind each: full extractions by a language pack and the bytes they read, and listings of the changed and the tracked files. Scopes nest: work done in a phase opened inside a gate (the diff extraction five gates share, the runner rules built on first use) is charged to the phase only, so the entries add up to the run. The counters are deterministic for one tree and configuration, which is what tests assert; the times are not, so the object is kept out of CheckSummary and added only as the JSON report is written: no baseline, fingerprint, replay comparison or replay cache key reads it (replay removes DISCIPLINE_TIMINGS from each check it runs). Its JSON is unstable until 1.0, like review_routing. The hook log carries the per-edit wall time on its own, as duration_ms.

8. CI and Release Pipelines

8.1 CI Pipeline (.github/workflows/ci.yml)

Third-party GitHub Actions are pinned by full commit SHA. Tooling binaries (act, actionlint) are installed by version with pinned SHA-256 checksums. Conditional test suites are gated by detect-changes; the ci-gate rollup enforces an allow-list: every required job must succeed or be legitimately skipped, verified at runtime by the ci-skip-set gate, and the total job count (11, the jobs below) is asserted.

8.2 Release Pipeline (.github/workflows/release.yml)

How a release is cut is under Cutting a release; the repository settings the pipeline relies on are in §8.4.

Releases are triggered exclusively by pushing a vX.Y.Z tag:

1. Verify: Asserts tag matches Cargo.toml version, tagged commit resides on main, tests/lints/deny pass, and generates a CycloneDX SBOM (discipline.cdx.json) under --locked semantics using pinned cargo-cyclonedx (0.5.9).
2. Build: Compiles 4 release targets (x86_64-musl and aarch64-musl, asserted static; x86_64-darwin, aarch64-darwin) and executes self-test on each target that can run on its runner: x86_64-darwin is cross-built on Apple Silicon, and when it cannot execute there its self-test is skipped with a notice. The musl legs also build the .deb and .rpm packages, which are checksummed into SHA256SUMS, attested and uploaded with the archives.
3. Publish: Generates SHA256SUMS (covering the archives, packages, and discipline.cdx.json), the Homebrew formula and the MacPorts Portfile (with the tag’s source-archive and crate checksums), attaches build-provenance attestations (one attestation for the archives and packages, also attached to the release as discipline.intoto.jsonl for offline gh attestation verify --bundle) and an SBOM attestation via actions/attest against the archives, creates the GitHub release (not yet latest), uploads release assets including discipline.cdx.json, reads its assets back and checks them against SHA256SUMS, and pushes the container image under its exact tags (0.7.0, v0.7.0) only, with a provenance attestation stored in the registry. Release binaries are built with the toolchain pinned in RELEASE_TOOLCHAIN, and the image from an Alpine base pinned by digest.
4. Smoke test: Action downloads published release assets on Linux and macOS, validates checksums, tests clean and negative fixtures, and verifies each archive’s GitHub attestation (signed by release.yml, for the tag).
5. Promote: Only after every smoke test succeeds: verifies the image’s provenance, marks the release latest, re-tags the proven image manifest as v0, 0, v0.7, 0.7 and latest (no rebuild), publishes the crate to crates.io via OIDC trusted publishing, and updates the Homebrew tap.
6. Move major tag: Advances floating major version tag (v0) last. A workflow using @v0 runs the binary of the version in that tag’s Cargo.toml, never latest, so the action code and the binary always come from the same release.
7. Post-release guard: Verifies via tests/action/check-major-tag.sh that the major tag dereferences to the release commit.

Supply-chain controls around these steps:

• Mutable refs: releases are immutable once published (tag and assets); a release tags ruleset refuses updates and deletions of v*.*.*, and a major tags ruleset lets only a deploy key move v0 / v1. The key (MAJOR_TAG_DEPLOY_KEY) and HOMEBREW_TAP_DEPLOY_KEY are secrets of the release environment, read by promote and move-major-tag only. The repository’s Actions policy requires full-SHA pins and allows only the actions the workflows use.
• Credentials: every checkout sets persist-credentials: false; the one push (move-major-tag) is handed its credential for that command. The release checks run without a build cache, so a cache written by CI cannot reach them.
• Egress: publish, promote and move-major-tag run step-security/harden-runner with egress-policy: block and telemetry off, allowing only GitHub, Sigstore, crates.io and the registries the image build pulls from. The macOS build legs and smoke hold no secret and no write token and run without it. The two container images publish pulls to build the release image, tonistiigi/binfmt (QEMU) and moby/buildkit (the buildx builder), are pinned by digest: their action defaults are moving tags.
• Consumers: the action checks the archive against SHA256SUMS and, on github.com with the default release store and gh on the runner, verifies its build provenance attestation: signed by release.yml, for the requested tag (gh attestation verify --signer-workflow --source-ref). A replaced asset with a matching replaced SHA256SUMS fails there.

Cutting a release

Every release follows a release candidate of the same version (next section) that passed the release pipeline on the same code. scripts/tag-release.sh refuses a stable tag without one (#925): v0.28.0 was tagged without a candidate, failed in verify on an advisory published after main’s CI had passed, and spent its version.

1. Bump PR (chore(release): bump version to X.Y.Z with its ledger rows): Cargo.toml, discipline’s entry in Cargo.lock, and every install instruction that names a release (the version-lockstep release group in discipline.toml lists them: README, docs, templates, man pages, .pre-commit-hooks.yaml, CITATION.cff’s version). Set CITATION.cff’s date-released by hand; nothing checks it. Relabel the unreleased rows of both ledger tables in docs/ROADMAP.md to vX.Y.Z (they become the notes’ “Upgrading” section), then discipline docs --write. Leave this repository’s own agent-hook files alone (.claude/hooks/discipline-bootstrap.sh, .github/workflows/copilot-setup-steps.yml), and the orieg/discipline@<sha> # vX.Y.Z pins of the CI examples in README.md, docs/index.html and docs/guides/ci-platforms.md: they pin a published release, whose commit the bump cannot know, and move to the new one in a follow-up once it is out. test_adoption::readme_ci_examples_pass_the_pull_request_that_adds_them fails while the README’s pin and copilot-setup-steps.yml’s differ.
2. Replay before tagging: run discipline replay over the recent history of downstream repositories under the current release and under the candidate, each with that repository’s own discipline.toml, and report every changed verdict or newly blocking gate before the tag. The candidate is a new binary, so none of its verdicts come from the replay cache: every change is rebuilt and checked, at the cost the README states for replay --last 50. A change whose merged pull request cannot be read (no token, or offline) is could_not_check and says nothing about the candidate.
3. Tag: scripts/tag-release.sh X.Y.Z --commit <sha> --push, with <sha> the bump’s commit on main (a squash merge, so not a merge commit; without --commit it takes origin/main as just fetched, never the shell’s HEAD). Before it creates the annotated, signed tag it checks that the commit is on origin/main, that its Cargo.toml and Cargo.lock carry X.Y.Z, that its CI run passed and that the tag exists neither locally nor on origin. For a stable X.Y.Z it also checks the newest candidate vX.Y.Z-rc.N on origin: its Release run completed with success on the candidate’s commit, that commit is an ancestor of <sha>, and between the two only release metadata changed (discipline’s own version in Cargo.toml and both Cargo.lock files, CITATION.cff, README.md, .pre-commit-hooks.yaml, docs/, man/, templates/). Then it creates the tag, reads it back, and pushes only when it dereferences to that commit (tests/action/test-tag-release.sh). Without --push it prints the push command. A pushed tag cannot be moved or deleted (step 6), so a wrong tag costs the version. The pipeline above does the rest, including latest, the floating image tags, crates.io publication, the Homebrew tap, the package repositories and v0.
4. Release notes come from GitHub’s generator, given only the new tag: it compares against the previous published release and skips drafts (measured with the v0.15.0-rc.2 draft present: the range for v0.15.0 was v0.14.4...v0.15.0), so release candidates do not shorten a release’s notes. The ledger rows labelled with the version are prepended as “Upgrading”.
5. After: Zenodo archives the published release (see §8.4). After the first archived release, a follow-up records the concept and version DOIs in CITATION.cff and the README badge.
6. A failed release is not re-run from a moved tag: the tag cannot move (release tags ruleset), and a re-run uses the workflow as it was at the tag. Fix main and release the next patch version, after its own candidate. The required candidate finds pipeline failures without spending a version; an advisory published between the candidate and the release can still fail verify, so tag the release soon after its candidate passes.

Release candidates

A release candidate (vX.Y.Z-rc.N) is required before every release. It runs the same pipeline as a release, up to smoke, and stays a draft GitHub release. Nothing about it is public except the container image under its exact tags (X.Y.Z-rc.N, vX.Y.Z-rc.N); no floating reference moves.

1. Bump PR: Cargo.toml to X.Y.Z-rc.N, Cargo.lock, and discipline docs --write (the man1 page). Install instructions (README, docs, templates, man5, .pre-commit-hooks.yaml) and CITATION.cff keep the latest stable release, so no user is pointed at a candidate; the commit body carries allow-version-mismatch: release <reason>. tests/action/check-links.py and tests/test_editor_integrations.rs read the stable version from CITATION.cff while Cargo.toml carries a candidate. Ledger rows stay unreleased, so the candidate’s notes have no “Upgrading” section.
2. Tag: scripts/tag-release.sh X.Y.Z-rc.N --commit <sha> --push, with <sha> the bump’s commit on main. verify checks the tag against Cargo.toml and main.
3. What runs: verify, build, publish and smoke; promote and move-major-tag are skipped. publish creates the draft, uploads every asset, reads them back against SHA256SUMS, and leaves the release a draft. A draft’s assets are not public, so smoke serves this run’s archives and SHA256SUMS to the action on 127.0.0.1 and verifies each archive’s attestation directly.
4. Zenodo needs no action. Zenodo archives every published release, pre-releases included, and skips only drafts: its GitHub receiver reads the release’s draft flag, never prerelease. A candidate is never published, so it never gets a record or a DOI. Do not publish a candidate’s draft by hand.
5. A failed candidate is replaced, not re-run. A re-run executes the workflow as it was at the tag, and the tag cannot move (release tags ruleset). Fix main, bump to X.Y.Z-rc.N+1, and tag again. The failed candidate’s draft can be deleted: it was never public.
6. The release is the ordinary bump to X.Y.Z, which moves every install instruction, CITATION.cff and the ledger rows. Nothing else may change between the candidate and the release: a fix to code, tests, workflows, scripts or a dependency after the candidate needs a new candidate, X.Y.Z-rc.N+1, first.

Packages: a candidate’s .deb and .rpm carry the version as X.Y.Z~rc.N (- is not allowed in an RPM version and is the Debian revision separator; ~ sorts before X.Y.Z), under file names that keep -, since GitHub renames release assets whose names carry ~.

8.2.1 Documentation Site and Package Repositories (.github/workflows/pages.yml)

The site is built from docs/ and deployed through GitHub Pages’ Actions source. The APT and RPM repositories are assembled at deploy time from the latest stable release’s .deb and .rpm assets (checked against its SHA256SUMS) and signed with the REPO_SIGNING_KEY secret: an APT InRelease / Release.gpg and an RPM repomd.xml.asc, with the public keys published as apt/discipline-archive-keyring.gpg and rpm/RPM-GPG-KEY-discipline. No package or repository metadata is committed. Without the key the workflow fails rather than publish an unsigned repository. It runs on every docs change and after each release (dispatched by promote). Three jobs: site renders docs/ with the Pages actions and holds no secret; sign downloads the packages, adds the signed repositories and is the only job that reads REPO_SIGNING_KEY (a secret of the package-signing environment), running no third-party action and with egress limited to GitHub; deploy publishes.

Signing Key Maintenance

One OpenPGP key signs the APT InRelease / Release.gpg and the RPM repomd.xml.asc. Its private half is held in two places only: the package-signing environment secrets (REPO_SIGNING_KEY, passphrase-protected, and REPO_SIGNING_PASSPHRASE), which GitHub never returns, and the maintainer’s copy, of which an encrypted offline backup (private key, passphrase and revocation certificate) is kept. The public half is not committed: sign exports it on every deploy to apt/discipline-archive-keyring.gpg and rpm/RPM-GPG-KEY-discipline.

The key carries an expiry date. Read it from what users have installed:

curl -fsSL https://orieg.github.io/discipline/apt/discipline-archive-keyring.gpg | gpg --show-keys

Extending it, well before that date, keeps the same key, so no user imports a new one; they only refresh their copy:

1. On the maintainer’s copy: gpg --quick-set-expire <fingerprint> <new-expiry>.
2. Replace REPO_SIGNING_KEY in the package-signing environment with the armoured export of the extended key (gpg --armor --export-secret-keys <fingerprint>, piped to gh secret set REPO_SIGNING_KEY --env package-signing; never written to a file in the repository). The passphrase does not change.
3. Run pages.yml (gh workflow run pages.yml --ref main). sign republishes the public key with the new date.
4. Check with the curl … | gpg --show-keys line above that the published key shows the new expiry.
5. Refresh the offline backup.
6. Tell users in the next release notes to refresh the key: APT users re-run the keyring curl line of the install instructions (the file under /usr/share/keyrings/ is written once and never refreshed, so apt update fails with an expired-key error after the old date); RPM users re-import RPM-GPG-KEY-discipline.

Replacing it (the private key is lost, or its expiry cannot be extended): generate a new passphrase-protected key, set both package-signing secrets, run pages.yml, and tell users to import the new public key the same way; until they do, their package manager refuses the repository. If it is compromised, publish its revocation certificate as well: import it into the key before exporting the public half, so the published keyring shows the old key revoked, then replace the key.

Major Tag Floating Pointer Invariant

Major tags (v0, v1) provide consumer convenience for action workflows (uses: orieg/discipline@v0). The release workflow contract mandates that major tags are moved exclusively by the release pipeline (release.yml) after all smoke tests pass against published release assets. Moving floating major tags manually or out-of-band bypasses compilation, static linkage verification, attestation generation, and smoke tests, which defeats the security guarantees of the sentinel. To prevent silent tag drift, two automated sentinels enforce this invariant:

• Post-release assertion: In release.yml, immediately after pushing the updated major tag, tests/action/check-major-tag.sh verifies that the tag dereferences to the release commit.
• Scheduled tag drift guard (tag-guard.yml): Runs on schedule to verify that every major tag dereferences to the newest non-prerelease semver tag’s commit in that major series, failing immediately if drift is detected.

8.3 CodeQL Security Pipeline (.github/workflows/codeql.yml)

Static security analysis runs on pull requests, pushes to main, and on a scheduled run (cron: '30 6 * * 1') using GitHub CodeQL Advanced setup (github/codeql-action pinned by SHA):

• Every change: the triggers have no paths-ignore, so a pull request that changes only documentation is analysed too. OpenSSF Scorecard’s SAST check (§8.5) counts a merged pull request with no CodeQL run as unchecked: one docs-only merge among its last 30 lowered the score to 9 (code-scanning alert 38).
• Matrix analysis: Analyzes rust, actions, and python.
• Query suite: Configured with queries: security-extended for deep vulnerability scanning.
• Toolchain: dtolnay/rust-toolchain, pinned to a commit of its master branch with toolchain: stable set explicitly (its stable branch is rewritten, which orphans a pinned commit), for Rust AST and macro expansion.

CodeQL Rust Build Mode

• Mode: Rust is analysed with build-mode: none (source-only extraction), as are actions and python.
• Why not a built mode: a built mode would be the more precise model, and switching was attempted. CodeQL CLI 2.27.0, the version github/codeql-action v4.38.1 installs, rejects it at database init with “Rust does not support the autobuild build mode. Please try using one of the following build modes instead: none.” (run 35563423549, job Analyze (rust)). manual is not offered either. Revisit when a CodeQL release adds a built mode for Rust.
• Known consequence: source-only extraction produced alert rust/cleartext-logging (CWE-312) on src/report/mod.rs. It was triaged as a false positive: no report format echoes a detected secret, and tests/test_report_redaction.rs pins redaction across every output format. Expect heuristic alerts of this kind until a built mode exists.

Advisory Security Sentinel Contract & Triage Procedures

• Advisory, not blocking: CodeQL is not a member of the ci-gate rollup’s needs list and is not counted in its asserted job count. It runs in its own workflow (codeql.yml); a job’s needs can only name jobs of the same workflow, so joining the rollup would mean moving the analysis into ci.yml. It stays separate by decision: a query-suite update or a heuristic false positive must not block an unrelated merge, while the gates in ci-gate are ones this repository controls and tests.
• Who reviews results: the repository maintainer. Pull-request runs surface new alerts on the pull request itself, and the maintainer reviews them before merging; scheduled runs are triaged in the repository’s code-scanning alert list as described below. A true positive is treated as a blocking defect even though the check itself is advisory.
• Scheduled Triage Procedures: Maintainers audit newly surfaced alerts following each scheduled run:
  1. Triage: Review all open alerts in GitHub Advanced Security across rust, actions, and python.
  2. True Positives: Classified as blocking security defects. Remediated immediately via prioritized patches with dedicated unit and end-to-end regression tests.
  3. False Positives / Heuristic Flags: Must be audited against engine behavior. An alert may only be dismissed if accompanied by a documented justification and pinned by executable regression tests (e.g., tests/test_report_redaction.rs verifying cross-format secret redaction across all 7 supported report formats).

8.4 Repository Settings the Pipelines Rely On

These live in the forge, not in the tree, so a review of the workflows alone does not show them. Check them with the gh api calls named in each row; discipline doctor reads branch protection, the Actions policy, the default workflow token, immutable releases, the tag rulesets and whether a repository-level secret is read only from environment-bound jobs (the admin-only settings need an admin token; under the workflow’s read token they are reported as not visible). It also checks each SHA-pinned action against its own repository (imposter-commit) and reads its metadata at that commit for refs that can move (nested-action-pins).

8.5 OpenSSF Scorecard (.github/workflows/scorecard.yml)

OpenSSF Scorecard scores the repository’s supply-chain practices from outside: a measurement this project does not grade itself, and a cross-check of the doctor mapping in docs/guides/ci-platforms.md (where the two disagree, one of them is wrong).

• Runs: on pushes to main, weekly (cron: '30 1 * * 1'), and on a pull request that changes the workflow, its policy (.github/scorecard-policy.yml) or the tool installer. It scores the default branch through the API, not a pull request’s tree, so a pull request’s run uploads nothing: code scanning would attach the default branch’s alerts to the pull request’s lines as review threads (RUN, #406: an alert on the Dockerfile line the pull request had already pinned).
• The CLI, not the action: tests/action/install-tool.sh scorecard installs the release binary pinned by version and checksum. ossf/scorecard-action runs an image pinned by tag (ghcr.io/ossf/scorecard-action:v2.4.4), which doctor nested-action-pins reports and the Actions allow-list would have to admit. The cost: only the action can publish to the Scorecard API, so there is no public score or badge. The CLI writes SARIF only with ENABLE_SARIF=1 and a policy file; the policy is the action’s default with Signed-Releases enforced.
• Output: SARIF uploaded to code scanning, one run per Scorecard group (categories supply-chain/branch-protection, supply-chain/local, supply-chain/online-scm): a check below its policy score is an alert. The aggregate and per-check scores are in the run’s step summary.
• Advisory, not blocking: not in ci-gate’s needs, for the reason CodeQL is not (§8.3): a separate workflow, and a third-party scoring change must not block an unrelated merge.
• Baseline (RUN, CLI v5.5.0, main at 0184ca1): aggregate 5.7. Held down by a solo-maintained repository: Code-Review 0 (no approved changesets), Contributors 3 (one organisation), Branch-Protection 3 (no required approvers, no last-push approval, no up-to-date policy). Held down by age: Maintained 0 (the repository is under 90 days old). Addressed: Signed-Releases 0 (attestations were not release assets; each release from the next one on attaches its bundle, and the check reads the last five), Pinned-Dependencies 9 (the Dockerfile builder image, now pinned by digest). Open: Dependency-Update-Tool 0, Fuzzing 0 (§8.6 adds the targets; the next run on main scores them), CII-Best-Practices 0.
• Current (RUN, CLI v5.5.0, main at fc4c7b7): aggregate 7.1. Since the baseline: Dependency-Update-Tool 10 (Dependabot, #413), Fuzzing 10 (§8.6), Pinned-Dependencies 10, CII-Best-Practices 5 (OpenSSF Best Practices badge at passing, project 15150), Branch-Protection 4 (up-to-date branches now required). Still below the policy: Signed-Releases 0 (rises as releases attach their provenance bundle), Maintained 0 (repository under 90 days old), Branch-Protection (no required approvers or last-push approval: both need a second reviewer, and last-push approval would block a sole maintainer’s own merges), Code-Review 0 (same reason; its alert is dismissed as won’t fix until a second reviewer exists).

8.6 Fuzzing (.github/workflows/fuzz.yml)

Scorecard’s Fuzzing check looks for a fuzzing integration; for Rust it is any *.rs file that names libfuzzer_sys (cargo-fuzz). The fuzz/ crate is that integration, and fuzz.yml runs it, so the targets are exercised and not only present. The threat model is fail-closed (§3): input that cannot be read is an Err or a named “not analysed”, never a panic, a hang or an unbounded allocation.

• Targets (fuzz/fuzz_targets/), each on code that reads input an attacker influences:

The two targets that reach a tree-sitter parser (language_packs, pretool_payload) run their body inside deep_stack::on_deep_stack, as the binary runs its work: an input of the job’s 64 KiB can nest to the tree depth limit, which a walker descends on that stack and not on the fuzzer’s own (#667).

There is no unified-diff parser in the tree to fuzz: the diff is read from the object database through libgit2 (gitctx), so the targets cover what is parsed from text instead. A target fails on a panic, abort, out-of-memory or timeout; an Err is a pass.

• Seed corpora: fuzz/corpus/<target>/, small files taken from tests/fixtures/ and hand-written edge cases; the first byte of a seed is the target’s selector byte. A crash found is minimised, fixed in the library with a regression test that fails without the fix, and its input is added to the corpus (RUN, #418: the first local runs found three panics, all slicing a string inside a multi-byte character, in tokens placeholder segmentation, references keyword detection and source_maps data-URL detection; their minimised inputs are the crash_* seeds; #618: an out-of-bounds read in the bash grammar’s scanner, found by the pretool_payload job under AddressSanitizer, its input is that target’s crash_wide_char_after_brace seed, and wide_char_after_brace and wide_char_after_brace_range are the shortest commands that reach the scanner’s two isdigit calls; #667: the *_nested_past_the_depth_limit seeds of language_packs and shell_nested_past_the_depth_limit of pretool_payload are sources and a command nested 4,200 levels, past the tree depth limit). cargo-fuzz writes the inputs it finds into the corpus directory it is given: run it with a scratch directory first and fuzz/corpus/<target> second to keep the tracked corpus small. The swift_* seeds of language_packs are the inputs of #621 (a file ending in a compiler directive, a NUL byte after one) and the *_nul_* seeds hold a NUL byte; the grammars’ C code is compiled without sanitizer instrumentation in this job (the read of #618 was reported because it faulted), so a read outside a table that does not fault is not something a run reports, and unit tests read the same seeds (src/ast/swift.rs, tests/test_nul_and_eof_sources.rs). timeout_rust_error_recovery is the input of #640, which the Rust grammar’s error recovery does not finish; src/ast/source_text.rs and tests/test_bounded_parse.rs read it.
• Runs: on pushes to main, pull requests, and weekly (cron: '30 2 * * 1'). One job per target in a matrix. A push or pull request runs each for 60 seconds, the weekly run for 300, with a 30-second per-input timeout, a 2048 MB resident-memory limit and inputs up to 64 KiB. A failing input is uploaded as a workflow artifact.
• Pinned: the nightly toolchain by date (FUZZ_TOOLCHAIN, libFuzzer needs a nightly rustc) and cargo-fuzz by version with --locked (CARGO_FUZZ_VERSION); bump them together, deliberately. Actions are pinned by commit SHA.
• Licence isolation: libfuzzer-sys is (MIT OR Apache-2.0) AND NCSA, and NCSA is not in deny.toml’s allow-list (§3.6 of AGENTS.md). fuzz/Cargo.toml is its own package with an empty [workspace] table (cargo-fuzz’s layout), so the root crate has no workspace, its Cargo.lock and cargo-deny never see the fuzz dependencies, and stable builds, the MSRV job and cargo test are unaffected. fuzz/Cargo.lock is committed for reproducible runs.
• Advisory, not blocking: not in ci-gate’s needs, for the reason CodeQL and Scorecard are not (§8.3, §8.5): a separate workflow, and a nightly update must not block an unrelated merge. A crash is a defect to fix, and the maintainer reads the failed run.
• Locally: cargo install cargo-fuzz --version 0.13.2 --locked, then from fuzz/: cargo +nightly-2026-09-05 fuzz run <target> "$(mktemp -d)" corpus/<target> -- -max_total_time=60 -rss_limit_mb=2048 (cargo fuzz list names the targets; the scratch directory takes the new inputs). On a shared machine run one target at a time. fuzz/target/, fuzz/artifacts/ and fuzz/coverage/ are ignored.

8.7 Mutation Testing (.github/workflows/mutants.yml)

AGENTS.md §3.4 asks each gate’s pull request for mutation evidence: one mutant, and the test that kills it. That is checked once, when the gate lands; nothing checks later that a refactor left every detector branch covered. This workflow does: cargo-mutants changes each function, operator and match arm in src/ast/ and src/guards/ in turn and runs the unit tests, and a mutant no test fails on is a survivor. The command gate’s cargo-mutants preset is scoped to a pull request’s diff (--in-diff); this is the sweep of the repository’s own detectors, one slice of it per run.

• Runs: on a schedule (cron: '30 3 * * 6') and on workflow_dispatch, whose optional slice input names the slice to test. A pull request that changes the workflow, scripts/mutants_ratchet.py, the ratchet or its fixtures runs the script’s --self-check and validates the committed ratchet; it tests no mutant.
• Why slices (#869): the first dispatched run (40235664265) found about 20,500 mutants, 1,282 per shard over 16 shards. Each cost about 150 s (an incremental build plus the 73 s lib-test run) after a 192 s baseline (119 s build, 73 s test), and every shard reached its step’s timeout-minutes: 320 after testing about a tenth of its mutants. The whole scope needs eleven times what a shard can hold, so no single run can sweep it.
• Slice count: scripts/mutants_ratchet.py --sizing derives it from those figures and the workflow’s limits, and tests/test_mutants_ratchet.rs pins the result and checks the limits against mutants.yml. The step’s 19,200 s, less two baselines (each shard runs cargo-mutants for the slice and for the diff slice), is 18,816 s; less 10% for variance in the per-mutant cost, 16,934 s; at 150 s a mutant, a shard holds 112 mutants (1,792 per run). 25% of that is kept for the diff slice, leaving 84 per shard, 1,344 per slice, so the scope needs ceil(20,500 / 1,344) = 16 slices, an average slice of 1,282 mutants, 81 per shard. The step (320) fits the job (timeout-minutes: 340), and the job fits a GitHub-hosted runner’s limit of 360.
• Rotation: tests/fixtures/mutants_ratchet.json gives every file its slice. A run tests the slice week % 16, where week counts the weeks (Monday to Sunday, UTC, as in an ISO week) since 1970-01-05 up to the run’s creation time, read from the run (gh api .../actions/runs/<id>). A re-run keeps its run’s creation time, so it tests the same slice; the run number would not do, since pull requests that run the self-check advance it too. Sixteen consecutive scheduled runs test every slice once, so every file once; a run covers about one sixteenth of the files and mutants. A file without a slice (new, or listed without one) goes on the slice holding the fewest mutants, largest file first, and the computed ratchet keeps that choice, so a file never moves on its own. A slice that does not fit a shard’s capacity fails the plan job; the remedy is more slices (clear every slice, and the next plan redistributes the files).
• Plan: the plan job lists the mutants (cargo mutants --list --json), picks the slice, and checks each shard’s share of the slice and of the diff slice against the capacity. Its artifact mutants-plan holds plan.json (the assignment, the slice’s files and the mutant count each shard must report), slice-files.txt and the diff. Each shard runs cargo mutants --in-place --no-shuffle --shard <k>/16 --file <each slice file> --timeout 300 --cargo-test-arg=--lib --output mutants-slice. Every shard takes the same arguments, or the shards disagree on how the mutants are split. A mutant counts as caught when a unit test (cargo test --lib) fails on it: each mutant would otherwise rebuild every integration test binary under tests/. --timeout bounds each mutant’s test run; a mutant that times out is listed apart and not counted as a survivor. cargo-mutants’ exit codes 0, 2 (missed mutants) and 3 (timeouts) leave the verdict to the ratchet; any other (bad arguments, a failing baseline, an internal error) fails the shard. Each shard uploads its slice/ and diff/ outcomes as the artifact mutants-shard-<k>.
• Diff slice: the ratchet keeps previous_commit, the commit of the last measured run. The plan job writes git diff <previous_commit>..HEAD -- src/ast src/guards to mutants-plan/diff.patch, and each shard also runs --in-diff mutants-plan/diff.patch over the whole scope with --exclude for each slice file (the slice measures those whole) and --output mutants-diff, so a changed detector is re-measured in the next run rather than when its slice comes round. Without a previous commit, or when that commit is not in the history, the diff slice is skipped and the plan and the summary say why. A diff that touches no mutant outside the slice is noted, not run. A diff whose share does not fit the room the slice leaves on a shard is skipped with a note: its files are measured when their slices run. The scope changes often, so expect that note after a large change. Every run’s commit becomes the next previous_commit, whether its diff slice ran or not, so a skipped diff does not grow without bound.
• Ratchet: tests/fixtures/mutants_ratchet.json holds, per file, slice, missed (the survivors its slice’s last run found) and run_id (that run). The ratchet job needs the plan and every shard and runs even when one fails. scripts/mutants_ratchet.py reads each shard’s outcomes and compares. For the slice’s files: above the recorded count fails the run; below passes and is listed as one whose count can be lowered. For the diff slice: the survivors in the changed code of a file are a floor for the whole file, so more than its recorded count fails too; a diff-slice count is never written. The job summary lists every survivor as file:line with its mutation, and uploads the computed ratchet as the artifact mutants-ratchet: the slice’s files with their new counts and this run’s id, every other file unchanged, files no longer in scope dropped, and this run’s commit as previous_commit. Committing it is a follow-up pull request; raising a count is the same edit, and its review is where a new survivor is accepted.
• Bootstrap: a file whose missed is null, or that the ratchet does not list, is not measured yet. Its slice’s first run records its count and fails nothing, and a diff-slice survivor in it is listed, not compared. Bootstrapping is complete once every slice has run once (sixteen scheduled runs, or sixteen dispatched runs naming each slice); the summary counts the files measured so far and names the slices not run yet. The ratchet is committed with "slices": 16, no previous_commit and no files.
• Survivors from a lib-only sweep overstate the gaps: a mutant that only an integration or end-to-end test kills survives --cargo-test-arg=--lib (READ, #869: the language_for match arms are exercised by the language-pack end-to-end tests). Decision for the first rotation: such survivors are accepted into the ratchet as counted, and the ratchet’s description says the counts are lib-only. Follow-up: a mapping file from each module to the integration tests that exercise it, with which the ratchet job re-tests a slice’s survivors before counting them; whether it is worth building is decided by the size of the survivor list after the first full rotation.
• Fail-closed: a shard job that did not succeed; a shard without the outcomes the plan expects; one whose run did not finish (cargo-mutants writes end_time last), whose baseline failed, whose cargo_mutants_version is not the pinned one, or that reports another number of mutants than the plan, or mutants of files on the wrong side of the slice; or a plan or ratchet that does not parse: each fails the ratchet job with exit 2 and compares nothing (AGENTS.md §2.4). Missing data is never read as zero survivors, and a file whose slice has not run yet is not missing data. A shard cut off by its step’s timeout-minutes is such a shard; the remedy is more slices.
• Tracking issue: a scheduled run with a file above the ratchet opens the issue “Scheduled mutation run: surviving mutants above the ratchet”, or comments on it while it is open. The track job holds the workflow’s only write permission (issues: write); it checks nothing out and runs gh with fixed text. The plan job reads the run’s creation time with actions: read. A run that could not check opens no issue: the failed run is the signal, as for fuzzing (§8.6).
• Pinned: cargo-mutants by version with --locked (CARGO_MUTANTS_VERSION; cargo checks the downloaded crate against the registry index’s checksum). The counts belong to that version’s mutation operators, so a bump is followed by a new rotation. The flags used (--shard, --file, --exclude, --in-diff, --output, --list --json) and the empty output of --list --in-diff on a diff that touches no mutant are those of cargo-mutants 27.1.0’s src/main.rs and src/in_diff.rs (READ). Actions are pinned by commit SHA.
• Advisory, not blocking: not in ci-gate’s needs, for the reason fuzzing, CodeQL and Scorecard are not (§8.3, §8.5, §8.6): a separate workflow, and a survivor is a missing test, not a defect in the change being merged.
• Locally: cargo install cargo-mutants --version 27.1.0 --locked, then cargo mutants --file 'src/guards/<file>.rs' --cargo-test-arg=--lib for one file (--list names its mutants without testing them). A slice is the workflow’s job; on a shared machine run one file at a time. python3 scripts/mutants_ratchet.py --outcomes-dir <dir> --plan-file <plan.json> --ratchet tests/fixtures/mutants_ratchet.json --run-id <id> judges a run’s downloaded mutants-shard-* and mutants-plan artifacts, --sizing prints the slice-count derivation, and tests/test_mutants_ratchet.rs runs the script over the fixtures in tests/fixtures/mutants/. mutants.out* is ignored.

9. Test Discipline for Gates

Every gate implemented in Discipline must satisfy the 4-point testing contract before shipping:

1. Unit tests: Detector-level unit tests with both positive and negative controls (src/** #[cfg(test)]).
2. End-to-end binary tests: Real binary executions driving throwaway git repositories and parsing JSON outputs (tests/test_gates_e2e.rs).
3. Mutation evidence: Detectors must be deliberately inverted or broken, with proof that the test suite fails on the mutant. After a detector ships, the scheduled mutation run (§8.7) re-checks the detectors in src/ast/ and src/guards/, one slice of the files per run and every changed detector in the next run, and fails when a file has more surviving mutants than its ratchet allows.
4. Self-test cases: Compiled directly into the binary (src/selftest.rs) to allow deployed binaries to verify their own discriminators.

Evasion cases, the shapes a change takes to weaken a test or the run without tripping a gate, are recorded with their verdict in tests/fixtures/evasion_corpus.json and driven through the binary by tests/test_evasion_corpus.rs: caught with the exact finding codes, or known_miss with the issue that tracks it. A caught case that stops being caught fails the suite, and so does a known miss that starts being caught, until its verdict and the gate’s “What it does NOT catch” list in docs/GATES.md are updated together. A new evasion shape goes there first, as a known miss, before the detector that closes it.

Threat model claims, adversarial attack probes, and isolated container reproduction environments are documented under tests/red_team/README.md.

10. Known Limits

• Macro opacity: A macro’s arguments are a token tree, which the tree-sitter grammar does not parse as code. The Rust pack reads the ones it knows by re-parsing their text: the functions inside proptest! { ... } and quickcheck! { ... }, and the closure handed to proptest!(|(..)| { ... }) inside a test (docs/GATES.md, assertion-reduction). Tests and assertions generated by any other macro are invisible to the extractors without macro expansion. Configure extra_assert_macros and assert_helper_fns.
• Grammar lag: Source syntax newer than bundled tree-sitter grammars triggers parse errors, failing closed by design. Use exempt_paths until grammars are updated.
• Untracked files: Untracked files are excluded from non-staged git diffs. CI inspects committed history and is unaffected.
• Report contents: --format agent-prompt prints violation titles, messages and locations, never override reasons. Gates whose finding could carry text written for an agent (instruction-smuggling) report the location and a class only; suppression-delta reports the location and suppression kind by default to preserve the locations-only contract, with opt-in quote_line = true restoring quoted annotations through directive scrubbing. Every message, and the error of a run that could not check, reaches an agent inside a fenced block one backtick longer than any backtick run in it (report::text::agent_block), and every location inside a code span on its line (report::text::agent_span), so quoted text cannot close the quote and read as the report’s own; titles are kept to one line. The pre-tool hook’s refusals and the MCP server’s answers quote the same way (§7, the table of outputs). tests/test_agent_hooks.rs pins this with a change whose line carries a fence and an instruction.
• Policy refusals outside the JSON report are a projection: the JSON report is the canonical record of a refusal: policy_failures holds one sentence per refusal that fails the run (an override budget exceeded, directive overrides without the approval require_approval needs, a protective gate disarmed or the policy file deleted by the change), and a gate’s notes name each hidden directive that was not read. The SARIF, JUnit and GitLab code-quality reports carry one entry per refusal, built from the registry in src/refusals.rs: the rule id (policy/max-overrides-exceeded, policy/max-inline-overrides-exceeded, policy/approval-required, policy/protective-gate-disarmed, policy/policy-file-deleted, policy/hidden-directive-refused), where the refusal is (the configuration key that refused the run; for a hidden directive the pull request body, the commit or the merged pull request it is written in) and fixed wording. They are lossy by design: the counts, the checked head and the reviewers’ logins of a policy_failures sentence, and the name of a hidden directive, stay in the JSON and text reports, and a directive’s subject and reason are in no report entry for a refusal (tests/test_policy_refusals_in_reports.rs, tests/test_report_redaction.rs). A consumer that needs the detail reads the JSON report. Two hidden directives in one source are told apart by their order in it, so removing the first moves the fingerprint of the second, as for a repeated source line (§7.2). A refusal has no baseline entry and no directive lifts it. Three things stay out of these reports and are read from the exit code and the text report: an applied override under fail_on_overrides, a directive source the policy disables (directives.sources), and a merged pull request whose author is not in allowed_override_actors. docs/CONFIGURATION.md (“Policy Refusals”) has the level each format gives each refusal.
• Workflow-level edits: The ci-integrity gate reads edits to Actions workflows under .github/, .gitea/ and .forgejo/workflows/. It recognises named weakenings (masked failures, dropped rollup needs, unpinned actions, the discipline step’s disable / advisory inputs); a workflow rewritten in a form it does not model passes. GitLab pipelines are read for their own weakenings (allow_failure, when: manual, masked script lines), except what arrives through include:. Protect workflow files with CODEOWNERS and a required check (discipline doctor).