# deterministic gates

_Status: settled — as of 2026-07-16_
_Connects to: [pipeline-stages](pipeline-stages.md), [agent-design-principles](agent-design-principles.md), [plugin-factory](plugin-factory.md), [overview](../OVERVIEW.md)_

## 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](pipeline-stages.md)) 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)