ace-git 0.28.1 → 0.30.0

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

@@ -1,282 +0,0 @@
----
-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

@@ -1,203 +0,0 @@
----
-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-task 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.
-
-When a PR adds or changes multiple distinct user-facing modes, list each mode explicitly in `## 🎮 Demo` instead of showing only one representative command. Examples: mutually exclusive flags (`--yaml` vs `--task`) or sibling commands like `add --step`, `add --yaml`, and `add --task`.
-
-Structure:
-
-```markdown
-## 🎮 Demo
-
-### Run
-\`\`\`bash
-[exact commands 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.
-
-**Recorded demo integration**: If a recorded demo GIF has been attached as a PR comment (via `ace-demo record --pr`), reference it in the Demo section: "See attached demo recording in PR comments below" alongside the runnable commands. The recorded demo supplements but does not replace the runnable commands.
-
-### 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