Gate: plan-revised
A plan revised by another tells whoever reads it.
| Property | Value |
|---|---|
| Checker | plan-revised |
| Confronts | plan |
| Blocking by default — new project | yes |
| Blocking by default — existing project | no — informs |
How it measures
Section titled “How it measures”Confronts plan nodes against declared revision relationships: when a plan is revised, the superseded document must explicitly warn readers at the top, and the revising document is reminded until that warning exists.
A plan is an anchor for architectural intent and execution. When planning errs — as it inevitably does once real implementation begins — editing an existing, already implemented plan destroys the historical record: it rewrites what was actually decided and executed into something that never happened.
For this reason, architectural revisions must be published as a new plan declaring which prior plan it revises. However, this discipline introduces a subtle and dangerous operational defect: out-of-order reading. A developer or agent opening an older, superseded plan has no natural indication that a newer revision exists, and will proceed to implement or follow decisions that have already been overturned. Because the old plan remains internally coherent — it was, after all, the accurate record of its own time — the reader cannot detect the obsolescence from the document alone.
This gate enforces bidirectional visibility across revised plans. When a plan is revised, it must display an explicit warning notice at its very top (within the first 40 lines) naming the revising plan, and must mark each section affected by the revision. Reciprocally, the author of a revising plan is reminded with a non-blocking pending verdict until that top notice is posted on the target file, ensuring that superseded documents are marked at the moment the revision is committed.
This gate operates in distinct territory from neighbouring gates:
- Unlike
plan-change-justified, which evaluates whether edits inside an existing plan justify their architectural delta, this gate governs the relationship between two distinct plans across the project map. - Unlike
phase-ordered, which ensures linear dependency ordering of phases within a single plan, this gate addresses the lifecycle obsolescence of entire plans and phases across revision boundaries. - Unlike
plan-seeds-valid, which ensures seed files cited by a plan actually exist in the repository, this gate ensures that revision targets resolve to valid plan nodes and that mutual revision markers exist on disk.
Declaring it
Section titled “Declaring it”gates: - name: plan-revised on: [plan] check: plan-revised