ace-git 0.18.0

data/handbook/workflow-instructions/github/pr/create.wf.md

@@ -0,0 +1,282 @@
+---
+doc-type: workflow
+title: Pull Request Creation Workflow
+purpose: pull request creation workflow
+ace-docs:
+  last-updated: 2026-03-04
+  last-checked: 2026-03-21
+---
+
+# Pull Request Creation Workflow
+
+## Purpose
+
+Create pull requests with descriptions sourced from code evidence (diff, commits, tests, changelogs), using consistent section structure.
+
+## Variables
+
+- `$pr_type`: `feature`, `bugfix`, or `default`
+- `$target_branch`: target branch (default resolved from task/worktree context)
+- `$draft`: create as draft (`false` by default)
+
+## Instructions
+
+### 1. Pre-PR Verification
+
+```bash
+git branch --show-current
+git status
+git log origin/${target_branch:-main}..HEAD --oneline
+ace-test
+```
+
+Checklist:
+- [ ] All changes committed
+- [ ] Relevant tests pass
+- [ ] CHANGELOG updated if release notes changed
+- [ ] No sensitive data in diff
+
+### 2. Resolve Target Branch
+
+Prefer task/worktree metadata from `_current/*.s.md` (`worktree.target_branch`), fallback to `main`.
+
+```bash
+task_file=$(ls _current/*.s.md 2>/dev/null | head -1)
+```
+
+If subtask context exists and current target is `main`, switch target to parent task branch.
+
+### 3. Push Branch
+
+```bash
+git push -u origin "$(git branch --show-current)"
+```
+
+**If push is rejected (non-fast-forward)**:
+- For feature branches with worktree-based divergence, prefer `git push --force-with-lease`
+- For shared branches or uncertain divergence, ask the user before force-pushing or rebasing
+- Do NOT silently rebase — this is a potentially destructive operation requiring user consent
+
+### 4. Build Evidence Inputs
+
+Before writing the body, collect evidence:
+
+```bash
+git log origin/${target_branch:-main}..HEAD --oneline
+ace-git diff --format grouped-stats
+```
+
+And collect:
+- Behavioral evidence from diff (old behavior vs new behavior)
+- Test evidence (test names -> behavior proved, suite totals)
+- Release evidence (CHANGELOG additions)
+
+### 5. Draft PR Body with Required Sections
+
+Use this order:
+
+```markdown
+## 📋 Summary
+## ✏️ Changes
+## 📁 File Changes
+## 🧪 Test Evidence
+## 📦 Releases
+## 🎮 Demo
+```
+
+Section sourcing rules:
+
+| Section | Data Source | Avoid |
+|---|---|---|
+| Summary | Diff behavior and user pain removed | Restating task objective text |
+| Changes | Concern-grouped code changes linked to commits | Raw commit dump |
+| File Changes | `ace-git diff --format grouped-stats` | Manual unstructured file list |
+| Test Evidence | Test names mapped to behaviors + totals | Raw command output paste |
+| Releases | CHANGELOG diff entries | Duplicating Changes section |
+| Demo | Runnable commands from README/usage.md + observed output | Screenshots, prose-only descriptions without commands |
+
+**Grouped-stats formatting rule:**
+- The `## 📁 File Changes` section must wrap grouped-stats output inside a fenced code block (```)
+- Paste the output exactly as produced — preserve all column alignment, tree indentation, and emoji markers
+- Never convert grouped-stats output into bullet lists, tables, or prose
+
+Summary writing rules:
+- Start with what is easier now
+- Mention what users/reviewers had to do before
+- Do not lead with method/class names
+- Do not use task-spec text as prose source
+
+Bullet formatting rules:
+- **Bold the first key term** in each bullet (feature name, class name, CLI flag, or config key) so it serves as a visual anchor before the explanation. Example: `- Add **\`GroupedStatsFormatter\`**: formats numstat output into...`
+- In Test Evidence, bold the test class name: `- **GroupedStatsFormatterTest** (6 tests) — validates...`
+- In Releases, bold the package+version: `- **ace-git v0.11.0–v0.11.6** — Add grouped-stats format...`
+
+Demo section rules:
+- Include `## 🎮 Demo` when the PR introduces a user-facing CLI or runnable entry point
+- Structure: `### Run` (exact command), `### Expected Output`, `### Artifacts` (where to find results)
+- Omit when: no user-facing CLI, no runnable entry point, or purely internal refactoring
+
+Omission/fallback rules:
+- No changelog evidence -> omit `## 📦 Releases`
+- No test-file evidence -> `## 🧪 Test Evidence` may include totals-only validation
+- grouped-stats unavailable -> fallback to flat file list in `## 📁 File Changes`
+- No user-facing CLI or runnable entry point -> omit `## 🎮 Demo`
+- Omit any section lacking evidence; never leave empty placeholders
+
+#### Grouped-stats example
+
+Correct — output wrapped in a fenced code block preserving all formatting:
+
+````
+## 📁 File Changes
+
+```
+ +762,   -54   34 files   total
+
+  +358,   -35   10 files      ace-overseer/
+  +117,   -18    4 files   🧱 lib/
+   +19,    -3                 ace/overseer/cli/commands/work_on.rb
+```
+````
+
+Incorrect — reformatted into bullet list (loses tree structure and alignment):
+
+```
+## 📁 File Changes
+
+- ace-overseer/lib/ace/overseer/cli/commands/work_on.rb (+19, -3)
+- ace-overseer/lib/ace/overseer/molecules/assignment_launcher.rb (+42, -8)
+```
+
+### 6. Create PR
+
+```bash
+gh pr create \
+  --title "<task-id-or-type>: <user-impact-description>" \
+  --body-file pr-description.md \
+  --base "${target_branch:-main}"
+```
+
+Optional draft mode:
+
+```bash
+gh pr create --draft --title "..." --body-file pr-description.md --base "${target_branch:-main}"
+```
+
+### 7. Add Metadata (Optional)
+
+```bash
+gh pr edit --add-reviewer @reviewer1,@reviewer2
+gh pr edit --add-label "enhancement,needs-review"
+```
+
+### 8. Verify PR
+
+```bash
+gh pr view
+gh pr checks
+```
+
+## Success Criteria
+
+- PR created with evidence-based body
+- Section order matches required structure
+- Summary is user-impact-first and task-spec-independent
+- File changes sourced from grouped-stats (or fallback)
+- Test evidence maps tests to behavior
+- Releases only included when changelog evidence exists
+
+## Response Template
+
+**PR Created:** [URL]
+**PR Number:** #[number]
+**Title:** [PR title]
+**Type:** [feature/bugfix/default]
+**Status:** [created|draft|failed]
+
+<documents>
+<template path="ace-git/handbook/templates/pr/feature.template.md">
+## 📋 Summary
+
+[What is easier now for users/reviewers]
+[What pain/manual step/error existed before]
+
+## ✏️ Changes
+
+- Add **`[FeatureName]`**: [what it does]
+- Add **`[ClassName]`** to [what it enables]
+
+## 📁 File Changes
+
+[Paste `ace-git diff --format grouped-stats` output verbatim inside a fenced code block — preserve all spacing and tree structure]
+[Fallback: flat file list if grouped-stats unavailable]
+
+## 🧪 Test Evidence
+
+- **[TestClassName]** ([N] tests) — [behavior validated]
+- Suite totals: [passed]/[total]
+
+## 📦 Releases
+
+- **[package vX.Y.Z]** — [CHANGELOG entry from diff]
+
+## 🎮 Demo
+
+[Runnable command(s) demonstrating the feature — omit section if no user-facing CLI]
+[Expected output and artifact locations]
+</template>
+
+<template path="ace-git/handbook/templates/pr/bugfix.template.md">
+## 📋 Summary
+
+[What broke and what is now fixed]
+
+## ✏️ Changes
+
+- Fix **`[ErrorType]`** when [condition] ([commit-sha])
+- Add **`[TestName]`** to guard against regression ([commit-sha])
+
+## 📁 File Changes
+
+[Paste `ace-git diff --format grouped-stats` output verbatim inside a fenced code block — preserve all spacing and tree structure]
+
+## 🧪 Test Evidence
+
+- **[TestClassName]** ([N] tests) — [regression behavior covered]
+- Suite totals: [passed]/[total]
+
+## 📦 Releases
+
+- **[package vX.Y.Z]** — [CHANGELOG fix entry from diff]
+</template>
+
+<template path="ace-git/handbook/templates/pr/default.template.md">
+## 📋 Summary
+
+[What is easier now]
+[What changed from user/reviewer perspective]
+
+## ✏️ Changes
+
+- Add **`[PrimaryChange]`**: [description] ([commit-sha])
+- Update **`[SecondaryChange]`**: [description] ([commit-sha])
+
+## 📁 File Changes
+
+[Paste `ace-git diff --format grouped-stats` output verbatim inside a fenced code block — preserve all spacing and tree structure]
+
+## 🧪 Test Evidence
+
+- **[TestClassName]** ([N] tests) — [behavior validated]
+- Suite totals: [passed]/[total]
+
+## 📦 Releases
+
+- **[package vX.Y.Z]** — [CHANGELOG entry from diff, if any]
+
+## 🎮 Demo
+
+[Runnable command(s) demonstrating the change — omit section if no user-facing CLI]
+[Expected output and artifact locations]
+</template>
+</documents>

data/handbook/workflow-instructions/github/pr/update.wf.md

@@ -0,0 +1,199 @@
+---
+doc-type: workflow
+title: Update PR Description Workflow
+purpose: evidence-based PR documentation
+ace-docs:
+  last-updated: 2026-03-04
+  last-checked: 2026-03-21
+---
+
+# Update PR Description Workflow
+
+## Purpose
+
+Generate PR titles and descriptions from code evidence in the PR (diff, commits, tests, and changelog entries), not from task specification text.
+
+## Variables
+
+- `$pr_number`: PR number to update (optional - auto-detect from current branch)
+
+## Instructions
+
+### 1. Resolve PR Number
+
+```bash
+gh pr view --json number -q .number
+```
+
+If no PR exists for current branch, ask the user for the target PR number.
+
+### 2. Verify Target Branch
+
+```bash
+gh pr view $pr_number --json baseRefName,headRefName,title
+ace-taskflow status
+```
+
+If taskflow context indicates a subtask and the PR targets `main`, retarget to the parent task branch before continuing.
+
+### 3. Collect Evidence Inputs
+
+Collect the evidence used to write the PR:
+
+```bash
+# Changed files
+gh pr diff $pr_number --name-only
+
+# Full diff for behavior and error-message changes
+gh pr diff $pr_number
+
+# Commit headlines
+gh pr view $pr_number --json commits -q '.commits[].messageHeadline'
+
+# File-change grouping (preferred)
+ace-git diff $(git merge-base HEAD origin/main)..HEAD --format grouped-stats
+```
+
+Also gather test evidence and release evidence:
+- Test evidence: test files changed in diff + relevant test outputs/suite totals
+- Release evidence: CHANGELOG entries present in diff
+
+### 4. Generate Evidence-Based Title
+
+Title format:
+- If task ID available from `ace-git status --no-pr`: `<task-id>: <description>`
+- Otherwise: `<type>(<scope>): <description>`
+
+Title guidance:
+- Focus on user-facing impact
+- Keep concise (target < 60 chars after task-id)
+- Do not lead with class/method names unless unavoidable
+
+### 5. Generate PR Description
+
+Use this section order exactly:
+
+```markdown
+## 📋 Summary
+## ✏️ Changes
+## 📁 File Changes
+## 🧪 Test Evidence
+## 📦 Releases
+## 🎮 Demo
+```
+
+Section sourcing rules:
+
+| Section | Required Source | Avoid |
+|---|---|---|
+| Summary | Behavioral change in diff + commit intent | Task spec objective text |
+| Changes | Concern-grouped diff changes, traced to commits | Raw commit list dump |
+| File Changes | `ace-git diff $(git merge-base HEAD origin/main)..HEAD --format grouped-stats` output, pasted verbatim and in full | Manual hand-written file listing, trimming or abbreviating the grouped-stats output |
+| Test Evidence | Test names mapped to behaviors + suite totals | Raw unstructured test output paste |
+| Releases | CHANGELOG entries from diff | Repeating content already in Changes |
+| Demo | Runnable commands from README/usage.md + observed output | Screenshots, prose-only descriptions without commands |
+
+**Grouped-stats formatting rule:**
+- The `## 📁 File Changes` section must wrap grouped-stats output inside a fenced code block (```)
+- Paste the output exactly as produced — preserve all column alignment, tree indentation, and emoji markers
+- Never convert grouped-stats output into bullet lists, tables, or prose
+
+Bullet formatting rules:
+- **Bold the first key term** in each bullet (feature name, class name, CLI flag, or config key) so it serves as a visual anchor before the explanation. Example: `- Add **\`GroupedStatsFormatter\`**: formats numstat output into...`
+- In Test Evidence, bold the test class name: `- **GroupedStatsFormatterTest** (6 tests) — validates...`
+- In Releases, bold the package+version: `- **ace-git v0.11.0–v0.11.6** — Add grouped-stats format...`
+
+### 6. Summary Writing Rules
+
+Write Summary in this sequence:
+1. What is easier now for users/reviewers
+2. What pain/manual step/error state existed before
+3. What changed to remove that pain
+
+Constraints:
+- Do not copy wording from task specs
+- Do not start with method/class names
+- Prefer behavior language over implementation language
+
+### 7. Demo Section Rules
+
+Include `## 🎮 Demo` when the PR introduces a user-facing CLI command or runnable entry point that a reviewer can try.
+
+Structure:
+
+```markdown
+## 🎮 Demo
+
+### Run
+\`\`\`bash
+[exact command to copy-paste]
+\`\`\`
+
+### Expected Output
+[what the reviewer should see]
+
+### Artifacts
+[where to find generated files]
+```
+
+Omit when: the PR has no user-facing CLI, no runnable entry point, or is purely internal refactoring.
+
+### 8. Omission and Fallback Rules
+
+- If no changelog evidence: omit `## 📦 Releases`
+- If no test-file evidence: keep `## 🧪 Test Evidence` with suite totals only
+- If `ace-git diff $(git merge-base HEAD origin/main)..HEAD --format grouped-stats` is unavailable: use flat file list fallback under `## 📁 File Changes`
+- If no user-facing CLI or runnable entry point: omit `## 🎮 Demo`
+- Omit sections with no supporting evidence instead of leaving placeholders
+
+#### Grouped-stats example
+
+Correct — output wrapped in a fenced code block preserving all formatting:
+
+````
+## 📁 File Changes
+
+```
+ +762,   -54   34 files   total
+
+  +358,   -35   10 files      ace-overseer/
+  +117,   -18    4 files   🧱 lib/
+   +19,    -3                 ace/overseer/cli/commands/work_on.rb
+```
+````
+
+Incorrect — reformatted into bullet list (loses tree structure and alignment):
+
+```
+## 📁 File Changes
+
+- ace-overseer/lib/ace/overseer/cli/commands/work_on.rb (+19, -3)
+- ace-overseer/lib/ace/overseer/molecules/assignment_launcher.rb (+42, -8)
+```
+
+### 9. Update PR
+
+```bash
+gh pr edit $pr_number \
+  --title "Generated title" \
+  --body "$(cat <<'BODY'
+## 📋 Summary
+...
+BODY
+)"
+```
+
+### 10. Confirm Update
+
+```bash
+gh pr view $pr_number --json url,title -q '.url + "\n" + .title'
+```
+
+## Success Criteria
+
+- Description uses: `📋 Summary -> ✏️ Changes -> 📁 File Changes -> 🧪 Test Evidence -> 📦 Releases -> 🎮 Demo`
+- Summary leads with user impact and does not restate task specs
+- File Changes contains the complete, untruncated grouped-stats output (never trimmed, summarised, or selectively omitted)
+- Test Evidence maps tests to behavior and includes totals
+- Releases derived from changelog evidence only
+- Empty/no-evidence sections are omitted

data/handbook/workflow-instructions/github/release-publish.wf.md

@@ -0,0 +1,162 @@
+---
+doc-type: workflow
+title: GitHub Release Publish Workflow
+purpose: GitHub release publishing workflow
+ace-docs:
+  last-updated: 2026-03-21
+  last-checked: 2026-03-21
+---
+
+# GitHub Release Publish Workflow
+
+## Purpose
+
+Create GitHub releases from root `CHANGELOG.md` entries that have no corresponding GitHub release, supporting retroactive bulk publishing and ongoing single-version releases.
+
+## Variables
+
+- `$version`: explicit version like `v0.9.846`, or range like `v0.9.840..v0.9.846`
+- `$since`: time filter like `"3 days"` or `"this week"`
+- `$dry_run`: if set, print what would be created without creating anything
+
+## Instructions
+
+### 1. Determine Published Baseline
+
+Find the latest GitHub release with a `v*` tag, ignoring non-version releases:
+
+```bash
+gh release list --limit 50 --json tagName,name --jq '[.[] | select(.tagName | startswith("v"))] | first // empty'
+```
+
+If no `v*` release exists, treat all changelog versions as unpublished.
+
+### 2. Parse Root CHANGELOG
+
+Read `CHANGELOG.md` and extract all version entries matching `## [X.Y.Z] - YYYY-MM-DD`.
+
+Build a list of `{version, date, body}` records where:
+- `version`: the semver string (e.g., `0.9.846`)
+- `date`: the release date
+- `body`: the full markdown content between this heading and the next `## [` heading
+
+### 3. Filter Versions
+
+Apply filters based on arguments:
+
+| Argument | Filter |
+|---|---|
+| No args | All versions newer than latest published `v*` release |
+| Single version `v0.9.846` | Just that version |
+| Range `v0.9.840..v0.9.846` | All versions where `840 <= patch <= 846` (comparing full semver) |
+| `--since "3 days"` | Versions with changelog date within the time window |
+
+If no versions remain after filtering, report and stop:
+
+```text
+No unpublished versions found matching the given criteria.
+```
+
+### 4. Group by Date
+
+Multiple changelog versions on the same date are consolidated into one GitHub release per day:
+
+- **Tag/title**: uses the highest version of that day (e.g., `v0.9.846` if versions 840–846 all share 2026-03-18)
+- **Release body**: combines all changelog entries for that day, ordered from highest to lowest version, separated by `---` dividers with version headers
+
+Single-version days produce a release with just that version's changelog body (no divider needed).
+
+Format for multi-version daily release body:
+
+```markdown
+## [0.9.846] - 2026-03-18
+
+[changelog body for 0.9.846]
+
+---
+
+## [0.9.845] - 2026-03-18
+
+[changelog body for 0.9.845]
+
+---
+
+## [0.9.844] - 2026-03-18
+
+[changelog body for 0.9.844]
+```
+
+### 5. Resolve Target Commits
+
+For each daily release group, find the commit that introduced the highest version's changelog entry:
+
+```bash
+git log --all -1 --format=%H -S "[${HIGHEST_VERSION}]" -- CHANGELOG.md
+```
+
+If the commit cannot be found, try alternative approaches:
+
+```bash
+git log --all -1 --format=%H --grep="\\[${HIGHEST_VERSION}\\]" -- CHANGELOG.md
+git log --all -1 --format=%H --after="${DATE}T00:00:00" --before="${DATE}T23:59:59" -- CHANGELOG.md
+```
+
+If no commit is found for a version group, skip it and report:
+
+```text
+⚠ Could not find commit for v${VERSION} (${DATE}) — skipping
+```
+
+### 6. Create Releases
+
+Process each daily group from oldest date to newest:
+
+**Dry-run mode** (`--dry-run`):
+
+```text
+[DRY RUN] Would create release:
+  Tag:    v${VERSION}
+  Title:  v${VERSION}
+  Target: ${SHA}
+  Body:   ${LINE_COUNT} lines (${VERSION_COUNT} version(s) from ${DATE})
+```
+
+**Live mode**:
+
+```bash
+gh release create "v${VERSION}" \
+  --title "v${VERSION}" \
+  --notes "${COMBINED_BODY}" \
+  --target "${SHA}"
+```
+
+Verify each creation:
+
+```bash
+gh release view "v${VERSION}" --json tagName,targetCommitish --jq '{tag: .tagName, target: .targetCommitish}'
+```
+
+### 7. Report Results
+
+Summarize all created releases:
+
+```text
+✓ Created v0.9.846 targeting abc1234 (2026-03-18, 7 versions)
+✓ Created v0.9.839 targeting def5678 (2026-03-17, 3 versions)
+⚠ Skipped v0.9.835 — commit not found
+```
+
+## Success Criteria
+
+- Every unpublished changelog version is covered by a GitHub release
+- Releases are tagged at the correct commits
+- Multi-version days are consolidated with combined bodies
+- `--dry-run` produces accurate output without side effects
+- Oldest releases are created first to maintain chronological order
+
+## Response Template
+
+**Releases Created:** [count]
+**Versions Covered:** [range or list]
+**Skipped:** [count and reasons, if any]
+**Mode:** [live|dry-run]