Status
Open, not started. On 2026-10-08 the developer said that when a finished plan leaves the plans in progress is the user's to decide, and the chain no longer places the conformity check at a moment (#116, ADR 0037): see the comment of that day. What is described below still holds for the script. Read again on 2026-10-05: only the words changed, with #52: the state is conformant, and the overview is the blueprint.
What happens today
A plan that is finished, conformant or abandoned, stays where it was written: its folder sits in docs/plans/ next to the plans still in progress, for as long as the repository lives. Nothing separates what still asks for work from what is only history.
What that gives today:
discover (surface_status/report.py) lists every folder of the plans directory that holds a journal, whatever its state. Outside a git work tree that is what surface-status, check and resolve see.- In a git work tree the scope is the plans of the branch, the folders it adds against its merge base (
resolve.py), finished ones included: a branch that carries a conformant plan and a plan in progress shows both, and /surface-status reports both.
check --require conformant reads the finished plans too. A conformant plan passes. A plan abandoned after its approval fails the check from then on, on purpose (_problems_for_conformant): the branch may carry code written under it that was never declared conformant.- Once merged, the folders pile up on the main branch, in the same folder a new plan opens in.
Proposal
A finished plan, conformant or abandoned, is set apart:
- it no longer sits in the folder of the plans in progress: it moves to a folder of its own, an archive under the plans directory for instance, so that the plans directory shows only what is still in hand;
- it is no longer part of the status:
/surface-status and the script's list report the plans in progress, and the check does not go through finished plans.
To settle when taking this up
- What "the status check" leaves out. The list of
/surface-status, the conformity check check --require conformant, or both. For the conformity check, a conformant plan can leave without loss, but a plan abandoned after its approval is today the one case that makes it fail: leaving abandoned plans out drops that alarm, unless it is kept another way.
- When a plan moves, and who moves it. At
conformant and at abandoned, on the branch, or only once the pull request is merged. The script never writes to git, and it is the only writer of a journal: either the command moves the folder in the commit that records the event, or the script gains a subcommand that moves it on disk.
- What must still find a moved plan. The plans of a branch are found by the folders it adds against its merge base,
commits assigns a commit to a plan by the journal it touches, pr-body links the blueprint and reads conformity.md for the critical files, and the host's CI runs the conformity check on the branch that carries the plan. A plan moved before the merge must stay readable by all of them, at its new path.
- The frozen blueprint. The alarm on a blueprint edited after conformity holds as long as the approval binds: say whether it still does once the plan is archived.
- Where, and under which name. One archive folder or one per outcome, a fixed name or a setting next to
plans_dir, and what happens to the plans already finished in host repositories, this one included (docs/plans/2026-09-30-quieter-install/).
Status
Open, not started. On 2026-10-08 the developer said that when a finished plan leaves the plans in progress is the user's to decide, and the chain no longer places the conformity check at a moment (#116, ADR 0037): see the comment of that day. What is described below still holds for the script. Read again on 2026-10-05: only the words changed, with #52: the state is
conformant, and the overview is the blueprint.What happens today
A plan that is finished, conformant or abandoned, stays where it was written: its folder sits in
docs/plans/next to the plans still in progress, for as long as the repository lives. Nothing separates what still asks for work from what is only history.What that gives today:
discover(surface_status/report.py) lists every folder of the plans directory that holds a journal, whatever its state. Outside a git work tree that is whatsurface-status,checkandresolvesee.resolve.py), finished ones included: a branch that carries a conformant plan and a plan in progress shows both, and/surface-statusreports both.check --require conformantreads the finished plans too. A conformant plan passes. A plan abandoned after its approval fails the check from then on, on purpose (_problems_for_conformant): the branch may carry code written under it that was never declared conformant.Proposal
A finished plan, conformant or abandoned, is set apart:
/surface-statusand the script's list report the plans in progress, and the check does not go through finished plans.To settle when taking this up
/surface-status, the conformity checkcheck --require conformant, or both. For the conformity check, a conformant plan can leave without loss, but a plan abandoned after its approval is today the one case that makes it fail: leaving abandoned plans out drops that alarm, unless it is kept another way.conformantand atabandoned, on the branch, or only once the pull request is merged. The script never writes to git, and it is the only writer of a journal: either the command moves the folder in the commit that records the event, or the script gains a subcommand that moves it on disk.commitsassigns a commit to a plan by the journal it touches,pr-bodylinks the blueprint and readsconformity.mdfor the critical files, and the host's CI runs the conformity check on the branch that carries the plan. A plan moved before the merge must stay readable by all of them, at its new path.plans_dir, and what happens to the plans already finished in host repositories, this one included (docs/plans/2026-09-30-quieter-install/).