Clarify the governed lifecycle for retiring obsolete guards without losing provenance
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 71
- Forks
- 64
- Avg merge
- 15h 38m
- Merged PRs (30d)
- 66
Description
The problem
The delivery loop describes the ratchet as a process where recurring failures become deterministic guards and “the guard set only grows.” At the same time, guards are registry items whose versions can become deprecated.
It is unclear whether monotonic growth applies to the historical knowledge of failures or to the set of guards that remain actively enforced.
In a long-running project, a guard may eventually become obsolete, duplicate another control, or encode an architectural assumption that is no longer true. If every historical guard must remain active indefinitely, the enforcement set can accumulate false positives and unnecessary friction. Removing it manually, however, risks losing the reason it existed and making historical runs harder to explain.
What you propose
Clarify and, where necessary, define a governed path for superseding or retiring an active guard while preserving its provenance.
A retirement could require:
- a human-approved proposal or pull request;
- evidence explaining why the guard is obsolete or what supersedes it;
- a reference to the failure or learning that originally introduced it;
- preservation of the guard version or content hash used by historical receipts; and
- post-retirement observation so recurrence can create a new proposal.
This would keep the history of learned failures append-only without necessarily making the active enforcement set append-only.
If registry deprecation already provides this lifecycle, a clarification in the loop, registry, or guards documentation may be sufficient. If active guards are deliberately permanent, documenting that invariant and its operational tradeoff would also resolve the ambiguity.
What you considered instead
Doing nothing keeps the ratchet simple, but leaves operators without a defined response when a guard’s assumptions expire.
Deleting or disabling the guard directly removes immediate friction but weakens provenance and may make historical evidence difficult to reproduce.
Adding exceptions or allowlists preserves the guard, but repeated exceptions can become another form of configuration debt and may hide that the underlying control is no longer valid.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start by reading the delivery loop, registry, and guards documentation to compare the monotonic-growth language with existing deprecation behavior. Trace how guard versions or content hashes are preserved in historical receipts. Done means the project documents either a governed retirement path with provenance and post-retirement observation, or an explicit permanent-enforcement invariant and its tradeoffs.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100