Strength key
strong — mechanically blocked unless an explicit, named, logged bypass is in effect. medium — default-on, with a config opt-out. weak — advisory event, no block. deterministic — verified by xCoder TypeScript code (autopilot path), not the LLM.
I-1 to I-2 — The hook layer
| # | Invariant | Mechanism | Strength | Bypass | Event |
|---|---|---|---|---|---|
| I-1 | No Edit/Write/MultiEdit/NotebookEdit on integration branch | no-edit-on-integration policy | strong | XCODER_ALLOW_INTEGRATION_EDIT=1 · workflow.commitDirectly: true | flow.guard.{allow,block,bypass} |
| I-2 | No git commit/push on integration branch | no-edit-on-integration policy | strong | (same as I-1) | (same as I-1) |
I-3 to I-5, I-7 — The engine acceptance layer
| # | Invariant | Mechanism | Strength | Bypass | Event |
|---|---|---|---|---|---|
| I-3 | Tracking issue exists before BRANCH transition | trackingIssueExists | strong | xc flow override I-3 --reason "..." | flow.acceptance.{passed,failed} |
| I-4 | Branch matches branchPrefix | branchMatchesPrefix | strong | (same as I-3) | (same as I-3) |
| I-5 | Spec file exists if specsRequired | specFileExistsIfRequired | medium | workflow.specsRequired: false | (same as I-3) |
| I-7 | Conventional-commit format on subject | conventionalCommitFormat | strong | xc flow override I-7 --reason "..." | flow.commit.format.violation |
I-6, I-8 — Commit-time hooks
| # | Invariant | Mechanism | Strength | Bypass | Event |
|---|---|---|---|---|---|
| I-6 | Build / types pass before COMMIT | typecheck-must-pass-before-commit policy | strong | XCODER_SKIP_QA_GATE=1 · --no-verify · --amend | flow.guard.{allow,block} |
| I-8 | Commit message references tracking issue | commit-must-reference-issue policy | medium | XCODER_SKIP_ISSUE_REF=1 · --no-verify | (same as I-6) |
I-9, I-10 — PR & merge
| # | Invariant | Mechanism | Strength | Bypass | Event |
|---|---|---|---|---|---|
| I-9 | PR opened before "done" claim | prOpenedBeforeIdle + session-end-pr-backstop policy | strong | xc flow override I-9 --reason "..." | flow.acceptance.{passed,failed} |
| I-10 | Removals match stated intent | merge-gate analyzer (intent classification) | strong (kernel) | n/a — verified, not bypassable | gate.intent.classified |
I-11 to I-13 — Structural / observability
| # | Invariant | Mechanism | Strength | Bypass | Event |
|---|---|---|---|---|---|
| I-11 | Autopilot phase transitions go through FlowEngine | autopilot adapter (observability v1; hard-gate v2) | deterministic | n/a (architectural) | flow.transition |
| I-12 | Every state-mutating tool call is observable | PreToolUse track-tool-calls + flow.tool.invoked | strong | n/a | flow.tool.invoked |
| I-13 | Every bypass is logged | All bypass paths emit flow.bypass with reason | strong (structural) | n/a | flow.bypass |
I-14, I-15 — Supervisor protocol (post-v1)
| # | Invariant | Mechanism | Strength | Bypass | Event |
|---|---|---|---|---|---|
| I-14 | Autopilot questions never block the queue | supervisor protocol — task marked waiting-for-reply, queue continues | deterministic | n/a (architectural) | supervisor.question.sent |
| I-15 | Resource caps are honored | Pre-phase + mid-phase budget checks; halt on exceed | strong | xc autopilot continue --over-budget | supervisor.budget.{warning,halt} |
Post-v1 invariants
I-14 and I-15 are scoped to the supervisor protocol — Part 2 of the specs/flow-adherence.md design. The protocol covers non-blocking question/reply, performance profiling, scope-down behavior, and resource caps. Tracked separately from the core engine.
What we explicitly do NOT guarantee
Worth being honest about the limits of mechanism-time enforcement:
| Claim we don't make | Why |
|---|---|
| LLM-side properties | LLMs explore. The engine catches what it can, but inside a phase the agent can do anything its toolbox permits. |
| Cryptographic non-bypass | A motivated user can chmod -x .claude/hooks/.... xCoder protects against drift, not adversaries. |
| Cross-repo guarantees | Each repo is its own FlowEngine instance. The engine doesn't track state across repos. |
| Code-quality enforcement | The contract is about flow-following, not code review. The merge-gate handles intent verification; static review is out of scope here. |