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, 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 to the human after N failed attempts, rather than looping indefinitely.
• 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)