Skip to content

fix(bridge): require plan.md step ticking, closing the verify §7 blind spot - #2

Merged
AdrianTheopold merged 1 commit into
mainfrom
fix/plan-md-step-ledger
Aug 4, 2026
Merged

fix(bridge): require plan.md step ticking, closing the verify §7 blind spot#2
AdrianTheopold merged 1 commit into
mainfrom
fix/plan-md-step-ledger

Conversation

@AdrianTheopold

Copy link
Copy Markdown
Owner

Problem

The apply-phase executor rule named tasks.md only, while plan.md ships - [ ] **Step N** boxes from its own template (templates/plan.md) and no instruction ever asked for them to be maintained. The READMEs reinforced this in both languages, framing progress tracking as tasks.md's job and plan.md as micro-steps with no tracking role.

Observed live: a full cycle ticked tasks.md conscientiously in the same message as every SDD ledger line and left all 20 plan.md step boxes empty. The rule was followed for the file it names and missed for the file it does not.

The stale ledger is the lesser half. Verify §7 reads plan.md for [~] deferred rows, to make "deferred-and-gapped" visible at archive. An unmaintained plan.md silently disarms it:

  • a manual/dogfood step genuinely deferred during apply never gets marked [~];
  • §7 then renders legitimately blank and the cycle reports "no deferrals" when it had them;
  • §7's blocking condition (empty §7 AND [~] rows present) cannot fire either, because the rows it looks for were never written.

So this is a correctness hole, not bookkeeping tidiness. It went unnoticed because the cycle that exposed it happened to defer nothing.

Changes

  • apply step 2 — the executor ticks both committed ledgers in the same bookkeeping step as the SDD ledger line, and marks a step [~] at the moment it defers it. Both failure modes are named, because neither reads as bookkeeping on its own. Also states the meta-reason: a rule written for one of two committed files gets followed for that one and missed for the other.
  • verify §7 — a blank §7 counts as "nothing deferred" only if plan.md was actually maintained; otherwise reconstruct the deferral state from the SDD ledger and the commits, tick plan.md, and re-run.
  • README.md + README.zh-TW.md — correct the framing that assigned progress tracking to tasks.md alone. tracks: tasks.md names what OpenSpec parses, not the whole bookkeeping duty.
  • VERSION 1.1.0 → 1.2.0, plus the release line in both READMEs.

The version bump is load-bearing for the install tooling, which compares version strings: a changed bundle left at 1.1.0 reports "up to date" while every consuming repo still resolves the old instructions — silent drift behind a green readout.

Verification

  • openspec schema validate superpowers-bridge → valid
  • openspec schemas lists the bundle and its artifact chain unchanged
  • Repo conventions followed: English schema.yaml/templates, English conventional commit, both README locales synced, validated against a throwaway project per CLAUDE.md's documented flow

Context

This is H1 of the fold-in list, reopened and widened — the v1.1.0 correctness pass (#1) fixed the tasks.md half; the plan.md half was never in scope.

…d spot

The apply-phase executor rule named tasks.md only, while plan.md ships
`- [ ] **Step N**` boxes from its own template and no instruction ever
asked for them to be maintained. Observed live: a full cycle ticked
tasks.md conscientiously in the same message as every SDD ledger line
and left all 20 plan.md step boxes empty — the rule was followed for the
file it names and missed for the file it does not.

The stale ledger is the lesser half. Verify §7 reads plan.md for `[~]`
deferred rows to make "deferred-and-gapped" visible at archive, so an
unmaintained plan.md silently disarms it: a manual or dogfood step that
really was deferred never gets marked `[~]`, §7 then renders
legitimately blank, and the cycle reports "no deferrals" when it had
them. §7's blocking condition (empty §7 AND `[~]` rows present) cannot
fire either, because the rows it looks for were never written.

- apply step 2: the executor ticks BOTH committed ledgers in the same
  bookkeeping step as the SDD ledger line, and marks a deferred step
  `[~]` in plan.md at the moment it is deferred. Names the two distinct
  failure modes so neither reads as cosmetic.
- verify §7: a blank §7 counts as "nothing deferred" only if plan.md was
  maintained; otherwise reconstruct from the ledger and commits, tick,
  and re-run.
- README (en + zh-TW): correct the framing that assigned progress
  tracking to tasks.md alone — `tracks: tasks.md` names what OpenSpec
  parses, not the whole bookkeeping duty.
- VERSION 1.1.0 → 1.2.0 (+ the release line in both READMEs), so
  `bridge check` sees the drift instead of reporting "up to date"
  against a changed bundle.

Validated: `openspec schema validate superpowers-bridge` passes.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@AdrianTheopold
AdrianTheopold merged commit 25bd569 into main Aug 4, 2026
1 check passed
@AdrianTheopold
AdrianTheopold deleted the fix/plan-md-step-ledger branch August 4, 2026 06:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant