54 lines
2.9 KiB
Markdown
54 lines
2.9 KiB
Markdown
|
# 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)
|