Refresh a proposal's current state

Type: types/instruction.md

Target: $PROPOSAL_PATH

Makes a live proposal's ## Current state (as of YYYY-MM-DD) section true on today's date, so an adoption decision can rely on it, and hands off any part the system has already decided.

When this does not apply

  • The proposal is archived. Archived proposals are frozen; do not refresh them. If something current was left behind in one, promote it into the frontier as a new or existing live proposal.
  • You intend to change the proposal's options or forces for design reasons. That is an ordinary revision under the design-proposal type; refresh the anchor as part of it.

Steps

  1. Collect what changed since the anchor date. List ADRs dated after it (ls kb/reference/adr/; each carries a **Date:**), and read every one whose title or description touches the proposal's subject. Run git log --since=<anchor date> -- <paths the proposal names> for the code and contracts it cites. If the clone is shallow, run git fetch --unshallow first.

  2. Check each current-state fact. For every bullet in the anchor, and for every factual claim about the system in the problem and options, find the live evidence — code, schema, command --help, reference doc, or ADR — and read it. Classify the fact as still true, false, or no longer relevant. Also note any new system fact the design now depends on, such as a later ADR that changes a force.

  3. Route decided content before editing.

  4. Part of the proposal has shipped → extract the adopted part of a proposal, then continue here.
  5. All of it has shipped, or a later decision forecloses all of it → retire an artifact and stop.
  6. A later decision forecloses one option but the question stays open → remove that option, and name the foreclosing ADR in the anchor.

  7. No decision forecloses it, but its problem no longer exists in the system or its adoption trigger has plainly lapsed → stop and report this to the operator with the evidence. Withdrawal is the operator's decision; if they withdraw it, use retire an artifact, whose destination for a withdrawn proposal is delete.

  8. Rewrite the anchor. Correct false facts, remove irrelevant ones, add new ones with their evidence (ADR link, file path, or command), and set the anchor date to today. Keep the anchor to facts the proposal rests on; the change history stays in git.

  9. Re-check the rest against the corrected facts. Where a corrected fact changes a force, an option's operativity path, or an adoption criterion, revise it. If an adoption criterion is now met, say so in the anchor; deciding is the operator's call, not the refresh's.

  10. Commit the refresh alone, with a body that lists what was false and what the new evidence is.

Verify

  • commonplace-validate on the proposal: no failures, no link warnings.
  • Every anchor bullet cites evidence you read in step 2.
  • The description and opening still describe the proposal's open question.

Relevant Notes: