cf15682d1c
* feat(#3028): responsive Markdown separators instead of fixed-width rules Stage banners, checkpoints, completion and error panels used fixed-width runs of box-drawing characters -- a 53-column heavy rule and a 62-column double-line box. Those runs are ordinary text to a Markdown-rendering host, so in a narrower pane they wrap and the border comes apart from the heading it framed. Shipped content now emits an ATX heading for a titled section and a blank-line-delimited --- for a break between sections, both of which adapt to the available width. The same convention is applied to the three code sites that built these strings at runtime: the UAT checkpoint renderer, the milestone-close audit report, and the TDD review checkpoint table. Removing the box also removes its only reason to exist -- the east-asian-width padding helpers that kept its right border aligned (checkpointBoxLine, displayWidth, isWideCodePoint, ZERO_WIDTH_MARK_RE, CHECKPOINT_BOX_WIDTH). RTL directional isolation is unchanged. The convention is specified in gsd-core/references/ui-brand.md and enforced across all shipped content by tests/responsive-separators.test.cjs. Refs #3028 * test(#3028): pin the heading form in checkpoint and audit-report assertions These suites asserted the exact box borders and the 62-column padded banner interior. With the box gone they assert the ### heading form, the --- break and the bolded instruction line, and each now carries a positive assertion that no box character remains -- which is what pins the fix rather than merely tolerating it. Language coverage is converted, not dropped: Japanese, Chinese, Korean, Hindi and Arabic all still assert their rendered banner, and the Arabic case still asserts the RTL directional isolates the box removal must not disturb. Adds a case for a banner longer than the old inner width, which previously produced a ragged border and now has none. Refs #3028 * chore(#3028): acknowledge execute-plan.md growth from the checkpoint display spec The checkpoint_protocol display spec described the drawn box; it now describes the heading, the --- break and the bolded action prompt, which costs 22 bytes (40111 -> 40133, 827 under the cap). Appended to the existing #3370 fragment rather than filed as a new one: a growth ack keys on the bare filename and #3370 already declares execute-plan.md, so a second source naming it would be a hard duplicate-key error. Same supersede-by-append route #3370 took for the spent #2652 fragment. Refs #3028 * docs(#3028): state the load-bearing half of the separator rule, and amend the zh-CN reference Review found three things. The rule as first written demanded a blank line above AND below every ---. Only the one above is load-bearing: it is what stops CommonMark reading the rule as a setext underline for the line above. The one below is cosmetic, because a thematic break is a leaf block. The rule now says that, with the reason, instead of asserting a stricter form the content does not keep. The zh-CN reference had received the mechanical box-to-heading swap but none of the prose behind it: it still claimed a 62-character checkpoint width and still listed --- among forbidden mixed banner styles, so it contradicted the convention it was translating. It now carries the separator section, the setext reasoning, the unconditional-vs-per-runtime rationale and a corrected anti-pattern list, in Chinese. The user guide asserted that a heading is not a degradation anywhere. That is an assertion, not a demonstration. It now says what was actually traded away in a plain terminal, points at the recorded rationale, and invites the report that would justify the capability flag instead. Refs #3028 * chore(#3028): backfill changeset PR number Refs #3028 --------- Co-authored-by: sim <sim@local>
13 KiB
13 KiB
Safe git revert workflow. Rolls back GSD phase or plan commits using the phase manifest with dependency checks and a confirmation gate. Uses git revert --no-commit (NEVER git reset) to preserve history.
Parse $ARGUMENTS for the undo mode:
Based on MODE, gather candidate commits.
Display the completion banner:
<required_reading>
@/.claude/gsd-core/references/ui-brand.md
@/.claude/gsd-core/references/gate-prompts.md
</required_reading>
If response_language is set: All user-facing questions, prompts, and explanations in this workflow MUST be presented in {response_language}. Technical terms, code, file paths, and subagent prompts stay in English — only user-facing output is translated.
### GSD ► UNDO
--last N→ MODE=last, COUNT=N (integer, default 10 if N missing)--phase NN→ MODE=phase, TARGET_PHASE=NN (two-digit phase number)--plan NN-MM→ MODE=plan, TARGET_PLAN=NN-MM (phase-plan ID)
If no valid argument is provided, display usage and exit:
Usage: /gsd:undo --last N | --phase NN | --plan NN-MM
Modes:
--last N Show last N GSD commits for interactive selection
--phase NN Revert all commits for phase NN
--plan NN-MM Revert all commits for plan NN-MM
Examples:
/gsd:undo --last 5
/gsd:undo --phase 03
/gsd:undo --plan 03-02
MODE=last:
Run:
git log --oneline --no-merges -${COUNT}
Filter for GSD conventional commits matching type(scope): message pattern (e.g., feat(04-01):, docs(03):, fix(02-03):).
Display a numbered list of matching commits:
Recent GSD commits:
1. abc1234 feat(04-01): implement auth endpoint
2. def5678 docs(03-02): complete plan summary
3. ghi9012 fix(02-03): correct validation logic
Text mode (workflow.text_mode: true in config or --text flag): Set TEXT_MODE=true if --text is present in $ARGUMENTS OR text_mode from init JSON is true. When TEXT_MODE is active, replace every AskUserQuestion call with a plain-text numbered list and ask the user to type their choice number. This is required for non-Claude runtimes (OpenAI Codex, Gemini CLI, etc.) where AskUserQuestion is not available.
Use AskUserQuestion to ask:
- question: "Which commits to revert? Enter numbers (e.g., 1,3) or 'all'"
- header: "Select"
Parse the user's selection into COMMITS list.
MODE=phase:
Read .planning/.phase-manifest.json if it exists.
If the file exists and manifest.phases?.[TARGET_PHASE]?.commits is a non-empty array:
- Use
manifest.phases[TARGET_PHASE].commitsentries as COMMITS (each entry is a commit hash)
If the file does not exist, or manifest.phases?.[TARGET_PHASE] is missing:
- Display: "Manifest has no entry for phase ${TARGET_PHASE} (or file missing), falling back to git log search"
- Fallback: run git log and filter for the target phase scope:
git log --oneline --no-merges --all | grep -E "\(0*${TARGET_PHASE}(-[0-9]+)?\):" | head -50 - Use matching commits as COMMITS
MODE=plan:
Run:
git log --oneline --no-merges --all | grep -E "\(${TARGET_PLAN}\)" | head -50
Use matching commits as COMMITS.
Empty check:
If COMMITS is empty after gathering:
No commits found for ${MODE} ${TARGET}. Nothing to revert.
Exit cleanly.
**Applies when MODE=phase or MODE=plan.**Skip this step entirely for MODE=last.
MODE=phase:
Read .planning/ROADMAP.md inline.
Search for phases that list a dependency on the target phase. Look for patterns like:
- "Depends on: Phase ${TARGET_PHASE}"
- "Depends on: ${TARGET_PHASE}"
- "depends_on: [${TARGET_PHASE}]"
For each dependent phase N found:
- Check if
.planning/phases/${N}-*/directory exists - If directory exists, check for any PLAN.md or SUMMARY.md files inside it
If any downstream phase has started work, collect warnings:
⚠ Downstream dependency detected:
Phase ${N} depends on Phase ${TARGET_PHASE} and has started work.
MODE=plan:
Extract the phase number from TARGET_PLAN (the NN part of NN-MM). Extract the plan number (the MM part).
Look for later plans in the same phase directory (.planning/phases/${NN}-*/). For each later plan (plans with number > MM):
- Read the later plan's PLAN.md
- Check if its
<files>sections orconsumesfields reference outputs from the target plan
If any later plan references the target plan's outputs, collect warnings:
⚠ Intra-phase dependency detected:
Plan ${LATER_PLAN} in phase ${NN} references outputs from plan ${TARGET_PLAN}.
If any warnings exist (from either mode):
- Display all warnings
- Use AskUserQuestion with approve-revise-abort pattern:
- question: "Downstream work depends on the target being reverted. Proceed anyway?"
- header: "Confirm"
- options: Proceed | Abort
If user selects "Abort": exit with "Revert cancelled. No changes made."
Display the confirmation gate using approve-revise-abort pattern from gate-prompts.md.Show:
The following commits will be reverted (in reverse chronological order):
{hash} — {message}
{hash} — {message}
...
Total: {N} commit(s) to revert
Use AskUserQuestion:
- question: "Proceed with revert?"
- header: "Approve?"
- options: Approve | Abort
If "Abort": display "Revert cancelled. No changes made." and exit. If "Approve": ask for a reason:
AskUserQuestion(
header: "Reason",
question: "Brief reason for the revert (used in commit message):",
options: []
)
Store the response as REVERT_REASON. Continue to execute_revert.
**HARD CONSTRAINT: Use git revert --no-commit. NEVER use git reset (except for conflict cleanup as documented below).**Dirty-tree guard (run first, before any revert):
Run git status --porcelain. If the output is non-empty, display the dirty files and abort:
Working tree has uncommitted changes. Commit or stash them before running /gsd:undo.
Exit immediately — do not proceed to any revert operations.
Sort COMMITS in reverse chronological order (newest first). If commits came from git log (already newest-first), they are already in correct order.
For each commit hash in COMMITS:
git revert --no-commit ${HASH}
If any revert fails (merge conflict or error):
- Display the error message
- Run cleanup — handle both first-call and mid-sequence cases:
# Try git revert --abort first (works if this is the first failed revert) git revert --abort 2>/dev/null # If prior --no-commit reverts already staged cleanly before this failure, # revert --abort may be a no-op. Clean up staged and working tree changes: git reset HEAD 2>/dev/null git restore . 2>/dev/null - Display:
ERROR
Revert failed on commit ${HASH}. Likely cause: merge conflict with subsequent changes.
To fix: Resolve the conflict manually or revert commits individually. All pending reverts have been aborted — working tree is clean.
4. Exit with error.
After all reverts are staged successfully, create a single commit:
For MODE=phase:
```bash
git commit -m "revert(${TARGET_PHASE}): undo phase ${TARGET_PHASE} — ${REVERT_REASON}"
For MODE=plan:
git commit -m "revert(${TARGET_PLAN}): undo plan ${TARGET_PLAN} — ${REVERT_REASON}"
For MODE=last:
git commit -m "revert: undo ${N} selected commits — ${REVERT_REASON}"
### GSD ► UNDO COMPLETE ✓
Show summary:
✓ ${N} commit(s) reverted
✓ Single revert commit created: ${REVERT_HASH}
Show next steps:
---
## ▶ Next Up — [${PROJECT_CODE}] ${PROJECT_TITLE}
**Review state** — verify project is in expected state after revert
/clear then:
/gsd:progress
---
**Also available:**
- `/gsd:execute-phase ${PHASE}` — re-execute if needed
- `/gsd:undo --last 1` — undo the revert itself if something went wrong
---
<success_criteria>
- Arguments parsed correctly for all three modes
- --phase mode reads .planning/.phase-manifest.json using manifest.phases[TARGET_PHASE].commits
- --phase mode falls back to git log if manifest entry missing
- Dependency check warns when downstream phases have started (MODE=phase)
- Dependency check warns when later plans reference target plan outputs (MODE=plan)
- Dirty-tree guard aborts if working tree has uncommitted changes
- Confirmation gate shown before any revert execution
- Reverts use git revert --no-commit in reverse chronological order
- Single commit created after all reverts staged
- Error handling cleans up both first-call and mid-sequence conflict cases
- git reset --hard is NEVER used anywhere in this workflow </success_criteria>