Single source for "what does the agent-workflow CI gate actually block on". Each row names a predicate, what it checks, its disposition, and how to fix a failure.
The checker is in core/checker/. It runs in CI via core/templates/.github/workflows/agent-workflow.yml.template. It is vendored into each consuming repo as a single-file scripts/agent-workflow-check.py.
The checker reads:
agent-workflow.yamlat the repo root (backend, classifier, and approved applicability policy).- The Work Record at
<taskPath substituted with {slug}>, where the slug comes from the PR's source branch. - The risk classifier's verdict artifact at the path configured by
redlineVerdictPath(when CI ran the classifier first).
It runs every predicate against every Work Record the PR touched. With no record, it may instead evaluate the complete PR path set against an approved documentation-only rule. It aggregates the results into a single verdict and posts a sticky comment. Exit codes:
| Exit | Meaning | Effect on CI |
|---|---|---|
0 |
Every predicate passed. | Job green. |
1 |
Advisory failures only. | Job green. Sticky surfaces the warning. |
2 |
At least one blocking predicate failed. | Job red. Merge blocks if the check is required. |
The checker reads files and is reproducible offline by default: python scripts/agent-workflow-check.py --repo-root . --slug <slug> --base-ref <base> --head-ref <head> checks supplied Git history, including migration receipts. Reproducing CI also requires its exact changed paths, classifier verdict and review inputs. Ordinary local checks without a receipt may omit both refs and skip history validation. The optional --check-default-branch-protection gate is the exception: it calls GitHub through gh repo view and gh api; failed or ambiguous queries return unavailable.
For pickup and handoff, --resolve-work-record [--work-record-ref agent-workflow:] performs lookup only and returns the configured repository-relative path plus parsed state. A supplied identity wins over branch derivation. Invoke the copy from a trusted harness installation, not a repository under inspection; see SPEC §13.1 for its bounded JSON contract and absence/error semantics.
CI passes one NUL-delimited, no-rename path list to both Redline and the checker. The exemption passes only when every path is human-approved, none is a governance/protected surface, and Redline accounts for the exact set as blue with no watch, checkpoint, boundary, API, schema, security, or runtime-config signal. Newline input remains supported but cannot grant the exemption. Any missing, malformed, duplicated, mixed, or risky evidence requires the normal workflow.
workflow.applicability records this decision. A passing result means the PR needs no Work Record; Redline and repository tests still run. Direct default-branch work is not a CI permission: bootstrap enables its config flag only after explicit approval and conclusive live proof that the actual default branch is unprotected, and operating mode rechecks protection before suggesting it. Protected or unknown means branch/PR without a Work Record.
Disposition column legend:
- Blocking — failure exits 2.
- Advisory — failure exits 1.
- Non-waivable — cannot be downgraded by a task exception (see §Exceptions below).
| Predicate | Checks | Disposition | Fix |
|---|---|---|---|
workrecord.exists |
A file resolves at the configured taskPath for the slug. |
Blocking, non-waivable | Create the Work Record at the path the predicate names. Slug is derived from the branch — see "Slug derivation" below. |
workrecord.markers_present |
The marker pair <!-- agent-workflow:start --> … <!-- agent-workflow:end --> bounds a single block. |
Blocking, non-waivable | Use core/templates/work-record-routine.md or work-record-expanded.md as the reference. |
workrecord.required_for_branch_changes |
When --changed-files or --changed-files-z lists non-exempt paths but the checker resolved no Work Record at the branch slug, this synthetic predicate names the missing record. Fires only on changed-file runs. |
Blocking. Without applicability policy, workRecord.requiredForBranchChanges: false opts out. With applicability.documentationOnly, trusted -z paths must pass that rule or require a record regardless of the legacy flag. |
Create the Work Record, or use the legacy opt-out only when no applicability rule overrides it. |
Optional Relationships metadata is validated separately from the readable core record. workrecord.relationships_valid blocks malformed/unsafe known declarations; unsupported versions or safe PR profiles produce an advisory diagnostic, preserve the original field/core and do not alter resolver v1. A missing field remains legacy unknown. This syntax check cannot prove that all incoming references were captured; the normal agent edit/read-back comparison needs supplied expected inputs. Trusted passive consumers follow SPEC §13.1, not repository-provided code.
| Predicate | Checks | Disposition | Fix |
|---|---|---|---|
requirements.baseline_present |
The record carries the initial Outcome, Scope, Constraints, and Completion criteria baseline. Legacy records remain parseable but cannot advance without it. | Blocking, non-waivable | Establish the baseline from the task owner or an authoritative source; do not guess or reconstruct it silently. |
requirements.baseline_unchanged |
With supplied PR base/head refs, the parsed baseline matches its trusted committed version, except the exact version-specific approval-bound privacy migration below. New records need a baseline in their first commit; base-existing legacy records may establish one. Missing, invalid or unrelated supplied refs fail. Local runs with neither ref skip only when the current record has no migration receipt. | Blocking, non-waivable | Restore the committed baseline; record behavioral edits as Behavior changes. Privacy redaction requires the exact approved receipt and both refs with shared history. |
requirements.behavior_changes_well_formed |
Optional Behavior changes JSON parsed with exact fields, classifications, targets, paths, and approval shapes. | Blocking, non-waivable | Correct the structured entry described by the parse failure. |
requirements.task_context_traceable |
Ordered task-context entries start at the baseline, form an exact before/after chain, and end at current Task Context. | Blocking, non-waivable | Restore the baseline and complete ordered chain, or return to the owner when the authoritative history is unclear. |
requirements.requirement_changes_authorized |
Every task-local requirement-change uses task/task-owner authority and exact user approval evidence. |
Blocking, non-waivable | Keep the task Blocked until the task owner approves the exact before/after change. |
behavior_contracts.redline_evidence_complete |
The current canonical Redline policy and versioned verdict detail agree on protection mode, affected paths, verification, and applicable repository controls. | Blocking, non-waivable | Regenerate the verdict from the current policy and complete trusted path set; missing, omitted, stale, cross-mode, or mismatched detail cannot pass. |
behavior_contracts.changed_paths_complete |
Trusted NUL-delimited PR paths agree with versioned Redline contract detail; reported paths are safe, unique, current, and red. | Blocking, non-waivable | Repair changed-path or Redline evidence; malformed, duplicated, unsafe, non-red, stale, or unavailable evidence cannot pass. |
behavior_contracts.changed_paths_classified |
Every affected configured contract path has exactly one repository-contract entry across changed Work Records. | Blocking, non-waivable | Add one equivalent, coverage-only, or requirement-change entry for each named path. |
behavior_contracts.requirement_changes_authorized |
Repository protection requires one compatible CODEOWNERS set, the configured checkpoint, and exact approval by one reported owner token. Workflow protection requires exact task/task-owner authority and approval by user; this evidence is not authenticated repository authority. |
Blocking, non-waivable | Use the approval shape for the configured protection. Repository mode cannot use task approval; workflow mode cannot claim a CODEOWNER token. |
behavior_contracts.verification_linked |
An affected Work Record names the PR verification identifier reported by Redline. | Blocking, non-waivable | Reference the reported behaviorContractChanges.verification; bootstrap/review proves it runs on PRs and, for repository protection, is branch-required. |
An optional Baseline privacy migration receipt binds the exact record path, full checker-selected anchor and approved replacements. Version 1 remains source-only and preserves all functional values/current context and the parsed chain. Version 2 requires exactly source, constraints and completion_criteria: source and both baseline/current functional pairs change atomically; the prior current values must equal their baselines and the chain must not target either field. Every other raw marker field and the exact raw chain remain unchanged at introduction, including Target, approvals and State. Reviewers must preserve the same historical owners/reviewers/holds and obligations; the checker cannot judge equivalence. Visible history retains the exact receipt and migrated baseline through later bases, without rebinding, second migration or in-place version upgrade. Invalid history, unsupported keys, non-atomic pairs, unrelated edits, tamper/removal/restoration and ambiguous parents fail closed. Both refs are required for current receipts; a local no-ref skip does not prove historical absence. See SPEC §9.1 and the migration guide.
The checker validates structure and visible PR baseline history, not semantic equivalence, initial snapshot accuracy, rewritten branch history, approval authorship, CI execution, or merge enforcement. A migration changes current content; it neither removes earlier public disclosures nor proves that a replacement is privacy-safe or preserves its meaning. Under repository protection, the hosting platform authenticates Code Owner approval and enforces required checks. Under workflow protection, the PR check can fail visibly and Agent Workflow treats that as not ready, but the platform may still allow a manual merge.
| Predicate | Checks | Disposition | Fix |
|---|---|---|---|
risk.declared |
The Risk: field is one of Routine, Elevated, High. |
Blocking, non-waivable | Set the Risk field. Boundary Violation is not a valid Work Record value — the workflow must stop before a record is written. |
complexity.declared |
The Complexity: field is one of Simple, Moderate, Large. |
Blocking, non-waivable | Set the Complexity field. |
workrecord.shape_matches_classification |
The record's actual shape matches (Risk, Complexity): compact only at (Routine, Simple), expanded everywhere else. |
Blocking, non-waivable | Migrate the record between compact/expanded as needed. The expanded shape requires Discovery, Material assumptions, Plan, Verification plan, Plan review, Approvals. |
workrecord.routine_fields_present (compact records only) |
Every compact-path field is present and non-empty. | Blocking | Fill in the missing field named in the detail. |
workrecord.expanded_fields_present (expanded records only) |
Every expanded-path field is present and non-empty. | Blocking | Fill in the missing field named in the detail. |
workrecord.state_valid |
The State: value is one of Ready to implement, Blocked, Blocked or returned to planning, Ready for review. |
Blocking | Set the State to one of the allowed values. |
The classifier (the agent-redline job in CI) runs first and writes a JSON verdict artifact to the path configured by redlineVerdictPath (default build/redline-verdict.json). The agent-workflow job reads that artifact; the predicates below verify what's recorded in the Work Record against what the classifier detected on the diff.
The "redline" prefix in these predicate names is the literal identifier in the verdict JSON. It refers to the bundled risk-classification subsystem (agent-redline-policy.yaml); see INTEGRATION.md for how to configure and tune it.
| Predicate | Checks | Disposition | Fix |
|---|---|---|---|
risk.redline_findings_available |
The classifier's verdict artifact is present and parsed. | Blocking under redline: required; advisory under redline: optional. Always blocking when the file exists but failed to parse. |
Check the classifier CI job. A missing artifact under redline: required is a CI configuration error. |
risk.boundary_violation_absent |
No architectural-boundary violation was flagged on the diff. | Blocking, non-waivable | A boundary violation stops the workflow. Either remove the offending change or change the governing policy through its own reviewed change. Boundary-violation findings are never waivable through a task exception (SPEC §11). |
risk.declared_not_below_detected |
The declared Risk meets the minimum the classifier detected on the diff. Its detail distinguishes provisional gray-only uncertainty from red, checkpoint, or operational signals; gray still has an Elevated floor until policy approval. | Blocking | Re-classify upward in the Work Record. Migrate the record's shape if it crosses the (Routine, Simple) boundary. |
| Predicate | Checks | Disposition | Fix |
|---|---|---|---|
review.checkpoints_satisfied |
Every classifier-triggered checkpoint is satisfied (PR label or CODEOWNER approval). | Disposition follows the redline policy's modes (perCheck.report if set, else modes.default): blocking under binding, advisory under shadow. Non-waivable via task exception either way. |
Apply the satisfying label named in the detail, or get the named CODEOWNER review. During the calibration window (modes.default: shadow), unmet checkpoints surface in the sticky as advisory and don't block CI. |
approval.elevated_clean_context_review_present / approval.high_clean_context_review_present |
At Risk=Elevated / High, Plan review or ## Plan review carries Agent technical review: <source ref>; human approval and placeholders do not count. |
Blocking | Run the non-implementer agent plan review and record its source reference. See core/templates/checkpoints/plan-and-review.md. |
approval.high_risk_approval_recorded |
At Risk=High, the Approvals: field carries a verbatim Approved by user <timestamp>: "<quote>" line. |
Blocking | The human must explicitly approve; record the response verbatim. |
approval.clean_context_does_not_satisfy_human |
At Risk=High, the Plan review reference and the Approvals text are not the same. | Blocking, non-waivable | Record a distinct human approval; a clean-context review MUST NOT satisfy a human-approval requirement (SPEC §13.4). |
review.agent_result_review_present |
At Risk=Elevated/High and State=Ready for review, ## Result review carries an agent technical-review source reference, reviewed revision, and verification-adequacy assessment. |
Blocking | Run the non-implementer agent result review and record those lines. Human review/approval or a label cannot satisfy it. The checker does not judge authenticity, competence, or adequacy. |
| Predicate | Checks | Disposition | Fix |
|---|---|---|---|
evidence.criteria_have_methods |
On expanded records, each Verification plan line pairs a completion criterion with a verification method. | Advisory | Use one of the accepted grammars: criterion → method, criterion -> method, criterion — method, method: criterion, or manual: <description>. |
evidence.failure_not_claimed_as_success |
Implementation / Evidence prose does not name a failed/skipped check as the basis for Ready for review. |
Advisory (temporarily downgraded — slice E) | Re-read your evidence prose. A failed required check MUST NOT be presented as success (SPEC §9.6). |
workrecord.commit_order |
The Work Record's first commit on this branch lands at or before the first code commit on the same branch. Walks origin/main..HEAD first-parent history. |
Advisory | If this fails, the WR was likely written retroactively. Check whether plan-first discipline held — if a session had been killed mid-task, would the WR have been useful as recovery state? Non-blocking. Skipped when git isn't available or the branch has no WR file yet. |
| Predicate | Checks | Disposition | Fix |
|---|---|---|---|
exceptions.well_formed |
Each entry in the optional Exceptions field parses with the required sub-fields. | Blocking, non-waivable | Use the dash-bullet format with rule, reason, scope, approver, expiry?, compensating_validation. |
exceptions.not_against_boundary |
No exception names a non-waivable predicate. | Blocking, non-waivable | Remove the entry — non-waivable predicates cannot be downgraded. The current set is listed in §Non-waivable predicates. |
exceptions.not_expired |
No exception has an expiry date in the past. ISO YYYY-MM-DD. |
Blocking, non-waivable | Renew the exception through its approval path, or remove it and address the underlying finding. |
The slug is the per-task identifier — the {slug} substituted into the taskPath template. The checker derives it from the PR's source branch:
- Strip the first matching prefix:
slice/,feat/,feature/,fix/,bug/,chore/,demo/. - Replace remaining
/with-.
If the PR touched Work Records (the lossless --changed-files-z mode used in CI), each touched record is checked. If changed-file discovery finds no records, the checker falls back to --slug and validates the Work Record at the configured taskPath for that slug — closing the case where a feature branch's WR landed on an earlier commit and this push touches only code. PRs with no matching WR at the slug AND code paths in the diff fail blocking via workrecord.required_for_branch_changes by default — set workRecord.requiredForBranchChanges: false in agent-workflow.yaml to opt out for genuine housekeeping repos (vendored-script bumps, formatter passes).
A task exception MUST NOT downgrade these. The list is enforced by exceptions.not_against_boundary.
risk.boundary_violation_absent— SPEC §11.workrecord.exists,workrecord.markers_present,risk.declared,complexity.declared,workrecord.shape_matches_classification— preconditions; without them the verdict is unreliable.- All
requirements.*andbehavior_contracts.*predicates above — the task baseline, exact change chain, authority separation, complete path evidence, classification, and verification linkage cannot be waived. exceptions.well_formed,exceptions.not_against_boundary,exceptions.not_expired— circular waivers are not honoured.approval.clean_context_does_not_satisfy_human— SPEC §13.4 structural invariant.review.checkpoints_satisfied— SPEC §13.4 (checkpoint satisfaction MUST remain distinct from human approval). Disposition is mode-dependent (blocking underbinding, advisory undershadow), but a task exception cannot waive it either way.
By design. Each is a reviewer judgment:
- Whether the Work Record's prose accurately describes the change.
- Whether the discovery was thorough.
- Whether the plan is sound.
- Whether the implementation is correct.
- Whether the verification method actually proves the criterion. Today the checker validates structural mapping (each Verification plan line names a method via one of the accepted grammars) and scans for explicit contradictions (a failure marker and a success marker against the same test identifier). Both are advisory. SPEC §13.3 names a fuller contract — presence, status, revision, freshness of the Verification Record — as the target shape; status/revision/freshness enforcement is not yet implemented and lives on the PR-status side of the harness. The checker does not validate adequacy — whether the named check meaningfully proves the criterion — in any slice; that stays a reviewer judgment.
- Whether tests pass. GitHub already knows that — the workflow does not re-verify CI results.
- Whether a human actually wrote a given approval. The checker enforces that something approval-shaped is recorded, not that a human authored it; the cheating window is acknowledged.
- Whether a configured behavior-contract verification ran or passed. Bootstrap/review validates PR execution; repository protection additionally validates required-check linkage. GitHub or the equivalent CI platform reports execution and controls merge enforcement.
If you find the checker passing on something a reviewer should have caught, that is by design — the gates the checker enforces are structural. Human review remains the authority for everything else.
SPEC.md— the normative workflow and harness contract.INTEGRATION.md— what the risk classifier does in agent-workflow's context, how to configure and tune the policy.DEFAULT_PROFILE.md— default profile mapping (GitHub, CI, Redline).../core/checker/predicates.py— the predicate source. Each predicate has a docstring matching its row above.