Remove PROGRESS.md; status only in features/#8
Merged
Conversation
You flagged that docs-template was still listed as 'In progress' in PROGRESS.md after PR #7 merged. Same gap that bit harness-features after PR #6 and ci-actions after PR #3. Pattern, not lapse: PROGRESS.md encoded feature status in two places (PROGRESS.md sections AND features/*.json), and one of them always rotted. This commit removes the duplication. WHAT CHANGED - PROGRESS.md: dropped the '## Completed' and '## In progress' sections. Kept only the genuinely human content: - one-line Current state - Known issues - Next steps Result: ~18 lines, never gets stale after a merge because the sections that go stale don't exist. - features/*.json remains the single source of truth for status. Anyone wanting the derived view runs `npm run harness:features` (the validator already prints a one-line summary as a side effect). - features/docs-template.json: flipped to done with commitSha 2f58414 (PR #7 merge commit) — the bookkeeping that should have happened at the merge. Closes the issue you raised. - features/harness-progress.json: new feature (this work), status in_progress. WIP=1 preserved. - README.md: 'First things to edit' updated — the Completed/In progress clearing instruction goes away; new users only clear Known issues. Feature status itself is in features/. - DECISIONS.md: new entry 2026-05-20 documenting the choice and the alternatives considered (auto-update workflow; pre-merge gate). WHY NOT AUTOMATE INSTEAD A GitHub Action that flips status on push-to-main would work but adds a bot commit per merge + a write-token requirement + another workflow to debug. The same goal is achieved by deleting the source of staleness (duplicated state). When PROGRESS.md doesn't try to remember feature status, it can't get it wrong. The 'Next steps' section CAN still be briefly stale right after a merge — but it's the genuinely human content (which feature to pick up next, plus any out-of-band tasks). The next session updates it as the first thing they do, so it self-heals. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Per user direction: PROGRESS.md's only durable value (the next-best-step
pointer) is derivable from features/ — pick the highest-priority
in_progress feature, else the first todo. Everything else PROGRESS.md
tried to carry was duplicated elsewhere (status in features/, history
in git log, decisions in DECISIONS.md, per-branch context in PR
descriptions).
WHAT'S REMOVED
- PROGRESS.md (deleted)
- All references across AGENTS.md, CLAUDE.md, README.md, init.sh,
docs/{HARNESS,SESSION,ARCHITECTURE}.md, scripts/check-clean-state.sh,
scripts/harness-ci-checks.sh
WHAT'S NEW: CLOSE-BEFORE-MERGE CONVENTION
The in-flight feature's status is flipped to `done` in the LAST commit
on the branch BEFORE the merge, with `commitSha` set to that commit
(the latest implementation commit). The PR's merge then carries the
closed feature into main as part of its own diff. No follow-up
bookkeeping commit.
This is the harness's answer to the recurring post-merge bookkeeping
gap that bit ci-actions (PR #3), harness-features (PR #6), and
docs-template (PR #7) — three consecutive PRs, same shape, same fix
forgotten every time.
Documented in docs/SESSION.md → "The close-before-merge convention"
and surfaced in AGENTS.md's End-of-session steps. scripts/check-clean-state.sh
check 4 now warns if the in-flight feature is still in_progress
(soft warning — the work may legitimately not be ready to merge).
OTHER CHANGES
- init.sh: 7 steps → 6 (no PROGRESS tail at the end)
- scripts/harness-ci-checks.sh: 6 checks → 5 (dropped PROGRESS-has-Next-steps)
- scripts/check-clean-state.sh: check 4 reshaped to check feature status
- DECISIONS.md: replaced the 'trim PROGRESS.md' entry with the
'remove PROGRESS.md' decision documenting the convention
NOTE ON THIS PR'S OWN CLOSE-BEFORE-MERGE
This commit is the implementation. The close-before-merge flip
happens in the next commit on this branch (referencing this commit's
SHA as commitSha).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Demonstrates the close-before-merge convention this PR establishes. The previous commit (0bb7e12) carried the implementation; this commit flips harness-progress to status=done with commitSha=0bb7e12 (the implementation commit's SHA). The PR's merge will now land the closed feature into main as part of its diff — no follow-up bookkeeping commit needed on main. scripts/check-clean-state.sh check 4 confirms: "feature 'harness-progress' is done — ready to merge". Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
adamlutz
changed the title
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Scope-changed iteration on the original PR #8 ("trim PROGRESS.md") after your direction: delete PROGRESS.md entirely and adopt a close-before-merge convention so the post-merge bookkeeping gap stops recurring.
The pattern this fixes
Three consecutive PRs all hit the same bug: the closed feature was still listed as
in_progresson main after merge.ci-actions(wasci-001)harness-featuresdocs-templateState was duplicated between
PROGRESS.md(sectionsCompleted+In progress) andfeatures/*.json. Same fact in two places → one place always rots.Fix
features/*.json(the source of truth all along).donein the last commit on the feature branch before the merge, withcommitShaset to that commit's SHA (the latest implementation commit). The PR's merge carries the closed feature into main as part of its diff. No follow-up bookkeeping commit needed.scripts/check-clean-state.shcheck 4 now warns when the in-flight feature is stillin_progress(soft, since the PR may genuinely not be ready to merge).What replaces what PROGRESS.md tried to do
features/*.json(status: "done")features/*.json(status: "in_progress")in_progress, else firsttodonotesfield, or GitHub IssuesDECISIONS.md(already there)Each piece now lives in exactly one place. Nothing to keep in sync.
This PR demonstrates the convention
Commit
0bb7e12is the implementation. Commit5397f0ais the bookkeeping flip —harness-progressis nowdonewithcommitSha: 0bb7e12. The PR will merge in that state; main will see the closed feature land as part of the diff. No follow-up needed.Files touched
PROGRESS.mdAGENTS.md,CLAUDE.md,README.md,init.sh,docs/{HARNESS,SESSION,ARCHITECTURE}.md,scripts/{check-clean-state,harness-ci-checks}.shfeatures/harness-progress.json(and flipped todonein the close commit)Verification
npm run verify→ green (9 features — todo:3 in_progress:0 blocked:0 done:6)bash scripts/harness-ci-checks.sh→ all 5 invariants greenbash scripts/check-clean-state.sh→ reports "feature 'harness-progress' is done — ready to merge"🤖 Generated with Claude Code