Ratchet system guide · v1.2
AvailableLearnings log
An append-only record of recent Ratchet improvements captured during delivery. Each learning is either incorporated into this guide — with the date it was folded in and a source link — or left pending with a one-line reason. Entries are never deleted or rewritten; status only moves forward.
Incorporated into the guide (7)
Every improvement below is reflected in the guide body and listed in the guide's Changelog.
- IncorporatedIncorporated · Shipped
Three deploy-gate strategies: version-endpoint, fixed-delay, and command. The gate can verify a deploy by polling a version signal (default), by waiting a fixed delay for products with no version endpoint, or by re-running a command until it exits 0.
Guide sections: core-workflow, loop-and-missionsSource: https://github.com/southu/ratchet/blob/main/README.md#deploy-strategies
- IncorporatedIncorporated · Shipped
CI-gated deploys via the command strategy. The gate can block on an external CI/deploy run by re-running a mission-supplied command; the command field is trusted input and is accepted only from the harness's own mission files.
Guide sections: core-workflow, footgunsSource: https://github.com/southu/ratchet/blob/main/README.md#deploy-strategies
- IncorporatedIncorporated · Shipped
Structurally sandboxed live tester with a three-pass protocol. The tester runs with no repo clone (only the live URL and the shared log) and works in priority order: a regression pass, an acceptance pass, then an expansion pass.
Guide sections: core-workflow, loop-and-missionsSource: https://github.com/southu/ratchet/blob/main/README.md#the-real-tester
- IncorporatedIncorporated · Shipped
Append-only TESTLOG bug ledger. Every bug the tester reports stays on the books across iterations and is re-verified against the live app each run; a bug is closed only when its original repro steps no longer reproduce. This is the ratchet property that keeps fixes from regressing.
Guide sections: core-workflow, overviewSource: https://github.com/southu/ratchet/blob/main/README.md#testlogmd
- IncorporatedIncorporated · Shipped
Per-invocation wall-clock timeouts with one retry. Every builder and tester invocation runs under a wall-clock supervisor; on timeout the whole process group is killed, the partial output is archived, and the role gets exactly one retry before the run stops.
Guide sections: core-workflow, troubleshooting-faqSource: https://github.com/southu/ratchet/blob/main/README.md#guardrails
- IncorporatedIncorporated · Shipped
Only consecutive live passes count toward finishing a mission: a single FAIL resets the pass-streak counter to zero, so the required streak must be reached with no failing iteration in between.
Guide sections: core-workflow, test-only-the-live-deployed-appSource: https://github.com/southu/ratchet/blob/main/README.md#pass-streak
- IncorporatedIncorporated · Shipped
TEST: contributor doc end-to-end cycle. This entry verifies docs/learning-cycle.md by driving one full learning through record -> draft -> review -> publish -> incorporated, following only that runbook. Pending: it is a documentation self-test and is incorporated by that very cycle; it is safe to leave incorporated.
Guide sections: overviewSource: https://github.com/southu/vygo/blob/main/docs/learning-cycle.md
Pending (2)
Identified but deliberately not folded into the public guide. These do not appear in the guide's Changelog as incorporated.
- PendingIdentified
Overnight helpers stay single-flight and respect operator holds: they never auto-unpause or requeue a run that is on hold or still live.
Reason not incorporated: this is host-private overnight-operations behavior, kept out of the public product-design guide, whose small-blast-radius helper principle already covers the concept.
Source: https://github.com/southu/ratchet/commit/1caad24bc9291f070c6f51d16716703ba393a0bf
- PendingIdentified
Run-state heartbeat plus the ratchet status / report / kill monitoring surface keep a live run's state file fresh and inspectable.
Reason not incorporated: this is an operator monitoring and host-operations surface, excluded by the pack's explicit no-host-ops scope.
Source: https://github.com/southu/ratchet/blob/main/README.md#run-state--monitoring