cc-os/plugins/os-sdlc/reference/deterministic-gates.md

deterministic gates

Status: settled — as of 2026-07-16 Connects to: pipeline-stages, agent-design-principles, plugin-factory, standards-and-conventions, debugger, overview

Purpose

States the core rule that keeps os-sdlc's trust model cheap: agents never self-certify their own work, hooks do. Load this when designing any pipeline stage that checks correctness, or when wiring hook events for os-sdlc.

Design

• Core rule: agents never run tests/lint/format. Hooks do — either Stop/SubagentStop hooks, or a between-turn pipeline script. This is the mechanism, not just a preference: it is what makes "red→green" something the pipeline proves rather than something an agent claims, at zero additional LLM cost.
• On failure, the failing output is injected into the same agent's next turn as context — not routed to a different agent, so the agent that wrote the code gets the direct feedback loop. A max-iteration counter escalates after N failed attempts, rather than looping indefinitely (v1: to the human; later: to the debugger).
• This feedback loop is what makes the residue rule possible: because the gate tells an agent which quality rule it broke, only on violation, no agent needs the rulebook in standing context. The depth of what the gates can enforce (rubocop/reek/flay/mutant for Ruby, and the symptoms-not-choices ceiling) lives in standards-and-conventions; this node owns only the mechanism.
• Red-assert and green-assert gates (defined in pipeline-stages) are the two concrete applications of this rule in the v1 pipeline: red-assert proves the tests actually exercise unbuilt behavior, green-assert proves the implementation actually satisfies them.
• Pluggable green command. A per-project config value — proposed home: next to the tracker key in .cc-os/config — names the command that proves work green: rake test + rubocop for a Rails app, the eval harness for a cc-os plugin itself. This one indirection is what lets the same factory drive arbitrarily different project types without os-sdlc knowing anything about their toolchains.
• Three-actors framing (from the SecondBrain vault note agentic-sdlc-ai-developer-workflow-taxonomy.md, IndyDevDan): code (deterministic, free, most reliable), engineer (fixed start/end points — prompting and reviewing), agent (judgment, most expensive and most variable). Every stage in os-sdlc is designed by first asking which actor it actually needs — the default is never "agent." Test-execution and lint/format are unambiguously code-actor work; routing them through an agent would be strictly worse on cost, reliability, and speed.

Open questions

• Exact hook events to use (Stop/SubagentStop) vs. a pipeline-invoked script called between agent turns — a runtime/implementation choice, not yet made.
• Where the max-iteration count lives (hook config, .cc-os/config, or hardcoded per stage) and what the escalation-to-human path looks like concretely.

Sources

• SecondBrain vault: agentic-sdlc-ai-developer-workflow-taxonomy.md (three-actors framing, IndyDevDan)
• ~/dev/delta-refinery (Pre/Post/Handoff pattern this generalizes from)
• plugins/os-sdlc/OVERVIEW.md
• ADR-0037, ADR-0042
• 2026-07-16 design session (this doc's origin)