Generated roadmap: docs/ROADMAP.md rendered from GitHub state, regenerated per merge (#175) - #198
Merged
Merged
Conversation
) Add roadmap.sh, a gh-2.4.0-safe REST-only generator that renders docs/ROADMAP.md from live GitHub metadata: open milestones in natural version order, each with its issues (priority chip, derived open/in_flight/PR#N-open/closed state mirroring loop-census.sh's own ADVANCE logic, and a Mermaid "Blocked by" graph reusing cockpit.sh's --parse-blocking parser), plus a Feedback inbox of unmilestoned open feedback-labeled issues and a generated timestamp/commit-sha footer. Wire merge-ready.sh to regenerate docs/ROADMAP.md best-effort after every successful merge, strictly non-fatal on generator failure, with commit+push only when the local checkout is cleanly on the base branch. Extend merge-ready.test.sh to prove regen invocation, its non-fatal failure path, and that it never fires on a skip-only (no merge) run. Document docs/ROADMAP.md as generated/read-only in docs/USAGE.md.
…l back on push failure (issue #175) Both review lenses rejected the tip for a real correctness bug: the post-merge docs/ROADMAP.md commit/push could wedge the owner's local main forever -- it committed without verifying the whole tree was clean and $base was in sync with origin, and left a dangling local commit on any push failure (offline/branch-protection), which local_sync's ff-only merge can then never reconcile. - merge-ready.sh: gate the commit on local_sync's own success flag (checkout on $base, whole tree clean, origin/$base fast-forwarded) instead of a docs/ROADMAP.md-only diff; on push failure, `git reset --hard origin/$base` so main is never left diverged. Change-detection now ignores roadmap.sh's volatile footer line (timestamp/commit) so a semantically identical regen is never committed as no-op spam. Added a comment clarifying the plain-git (owner-auth) commit choice is deliberate, not an oversight. - merge-ready.test.sh: new scenarios K/L/M drive the real commit/push path against a hermetic local bare-origin remote (same pattern as worktree.test.sh/release.test.sh/worktree-cleanup.test.sh/ loop-census.test.sh), asserting the real push lands, the footer-only diff is skipped, and a rejected push rolls local main back in sync with origin. - roadmap.sh: soften the header's census-parity claim -- its in_flight branch detection lacks census's stale-merged-remote refinement; documented as a known, low-risk simplification rather than an unstated mismatch. - roadmap.test.sh: note the gh-unavailable scenario's one real (read-only) git branch listing call instead of leaving it unexplained. Co-Authored-By: Claude Sonnet 5 <[email protected]>
…hs (issue #175) roadmap.sh --write unconditionally rewrites docs/ROADMAP.md's footer (timestamp + commit SHA) every run, even on paths that don't commit it: "no changes" (semantically identical content) and "not in sync" (local_sync_ok=0). Both previously exited without restoring the file, leaving the owner's real checkout dirty and, worse, wedging local_sync's own clean-tree precondition on the NEXT run. Restore docs/ROADMAP.md via `git checkout --` on both non-committing paths so the tree always ends up clean unless the commit+push path actually lands. The push-failure rollback path was already safe via its existing `git reset --hard origin/$base`. Adds a clean-tree assertion to scenario L (no-changes path) and a new scenario N exercising the not-in-sync path with a real diverged git repo, both asserting docs/ROADMAP.md is restored to clean afterward. Co-Authored-By: Claude Sonnet 5 <[email protected]>
robercano-ghbot
added
the
needs-human
Collaborator
Author
|
Generated roadmap: docs/ROADMAP.md rendered from GitHub state, regenerated per merge (#175) (not yet reviewed) |
robercano
approved these changes
Jul 29, 2026
robercano-ghbot
removed
the
needs-human
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
2 participants
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.
Closes #175
What
Adds a generated
docs/ROADMAP.mdrendered from GitHub metadata (milestones / labels / blocked-by edges) so owner-visible roadmap state cannot drift from the single source of truth. The doc is never hand-edited.Changes
.claude/scripts/roadmap.sh(new) — REST-only, gh 2.4.0-safe generator. Renders open milestones in natural version order; per issue a priority chip + state (open/in_flight/PR#N open/closed, mirroringloop-census.sh); Blocked-by edges as a Mermaid graph by reusingcockpit.sh --parse-blocking(not reimplemented); a "Feedback inbox" of openfeedback-labeled issues with no milestone; a footer timestamp + generating commit.--writepersistsdocs/ROADMAP.md; default is stdout preview. Output is marked GENERATED / do-not-hand-edit. Allghviabot-gh.sh..claude/scripts/merge-ready.sh— after each successful merge, regenerates + commitsdocs/ROADMAP.mdto base, best-effort/non-fatal (a roadmap failure can never abort a merge). Commit gated on the same clean-tree + in-sync-with-origin preconditions aslocal_sync; rolls back (git reset --hard origin/$base) on push failure; restores the working copy on every non-committing path so the base checkout is never left dirty. Change-detection ignores the volatile footer to avoid no-op commit spam.docs/USAGE.md— documents thatdocs/ROADMAP.mdis generated and read-only (source of truth is GitHub metadata).roadmap.test.sh(27 checks: milestone ordering, all four state derivations, Mermaid edges, feedback-inbox include/exclude, degrade path) and extendedmerge-ready.test.sh(62 checks incl. hermetic bare-origin scenarios for real commit+push, footer-only "no changes", diverged not-in-sync, and rejected-push rollback).Notes
🤖 Generated with Claude Code