ace-git 0.28.0 → 0.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f2aefd55e04cf20182ce9302454f857fb836a9948f8c5d3287d574fda05e73d0
-  data.tar.gz: 630a48152d3aaa43df4d6ec23dac65f6f2496fb1ea4fa7b4dbe968a677843751
+  metadata.gz: ecb7e3224f26cacff289f62d5199d90740ee07a4fbaa378649fc948133e6d05c
+  data.tar.gz: 13ac60da2a81dda68242bc0c9f5f21f5e44f764562f24877426e873b59137bbf
 SHA512:
-  metadata.gz: 38abefdfea8dc06b4b30804daaa0b9e9327a3d9042c6671c6bae876896bfc8473c5f364444142726008d49d91c50d6ad7bb4cdb8e92243f1f0c515c050030a77
-  data.tar.gz: 760780054d64d4cd58134ab8c6e3db5a47a8daf45dbc7080195e716a5a55b17535b986f0dbc7d383bedc2108a87e27aa3c2b8fd2bdde7ff1834654240839f2b2
+  metadata.gz: 19e1dfe5f0315b38572c0c8464852bfb7f2c25477f92f646c73df44d4b0c0f06d72c32cd6e961ef8185ed1ced37c57cd111a4980dec8f698d1eba3ad7596e8c7
+  data.tar.gz: 16ff4c84f2f86b690116792e97cfcbe323c5dd2209d63e5148f6d4aa35fc3725a99dc84b87695cb4d00b9187816ab6652f1194ba7940caf11f6d96dd065b4fdf

data/CHANGELOG.md

@@ -7,6 +7,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.29.0] - 2026-10-05
+
+### Removed
+
+- Remove the obsolete GitHub PR workflow and skill sources; canonical PR creation/update use only `git/pr` and `as-git-pr-*`, with no forwarding aliases.
+
+### Added
+
+- PR lifecycle selection can use an explicit repository and pinned forge identity; exact create reconciliation is read-only. Neutral PR workflow and skill sources are prepared for coordinated canonical adoption.
+
+## [0.28.1] - 2026-10-04
+
+### Technical
+
+- Verify the public PR lifecycle preserves provider uncertainty after accepted mutations.
+
 ## [0.28.0] - 2026-10-04
 
 ### Added

data/README.md

@@ -32,7 +32,7 @@
 
 **Rebase with changelog-safe workflow guardrails** - use the `as-git-rebase` agent workflow to run structured rebase flows that preserve package release metadata and reduce manual conflict-prone steps.
 
-**Prepare clean review history before publishing** - run the `as-git-reorganize-commits` workflow to reorganize commit stacks, then use `as-github-pr-create` or `as-github-pr-update` to manage PR metadata in a predictable workflow sequence. See [Handbook](docs/handbook.md) for the full skill and workflow catalog.
+**Prepare clean review history before publishing** - run the `as-git-reorganize-commits` workflow to reorganize commit stacks, then use `as-git-pr-create` or `as-git-pr-update` to manage PR metadata in a predictable workflow sequence. See [Handbook](docs/handbook.md) for the full skill and workflow catalog.
 
 **Coordinate with commit and worktree tools** - pair with [ace-git-commit](../ace-git-commit) for scoped commit authoring, [ace-git-worktree](../ace-git-worktree) for task-oriented worktree management, and [ace-bundle](../ace-bundle) for loading workflow instructions.
 

data/docs/handbook.md

@@ -17,8 +17,8 @@ Reference for package-owned handbook resources in `ace-git/handbook/`.
 |-------|--------------|
 | `as-git-rebase` | Guide changelog-preserving rebases |
 | `as-git-reorganize-commits` | Rework commit history into reviewable logical groups |
-| `as-github-pr-create` | Create pull requests with the package templates and workflow |
-| `as-github-pr-update` | Refresh an existing PR body from current branch context |
+| `as-git-pr-create` | Create an attempt-bound draft on the selected forge |
+| `as-git-pr-update` | Update the exact attempt-bound PR and consume current evidence |
 | `as-github-release-publish` | Publish a GitHub release from the ACE workflow |
 
 ## Workflow Instructions
@@ -27,8 +27,8 @@ Reference for package-owned handbook resources in `ace-git/handbook/`.
 |--------------|---------|------------|
 | `wfi://git/rebase` | Rebase a branch while preserving changelog/version files | `as-git-rebase` |
 | `wfi://git/reorganize-commits` | Consolidate or regroup commit history before review | `as-git-reorganize-commits` |
-| `wfi://github/pr/create` | Create a PR with the package templates | `as-github-pr-create` |
-| `wfi://github/pr/update` | Update a PR description from current state | `as-github-pr-update` |
+| `wfi://git/pr/create` | Create or reconcile the exact attempt-bound draft | `as-git-pr-create` |
+| `wfi://git/pr/update` | Update the recorded PR and retain delivery identity | `as-git-pr-update` |
 | `wfi://github/release-publish` | Publish a GitHub release | `as-github-release-publish` |
 
 ## Guides

data/handbook/guides/version-control-system-git.g.md

@@ -183,13 +183,19 @@ git remote prune origin
    git push -u origin feature/your-feature
    ```
 
-2. **Create PR through GitHub interface** or CLI:
+2. **Create an attempt-bound draft on the selected forge**:
 
    ```bash
-   gh pr create --title "feat(feature): add new functionality" \
-                --body "Description of changes..."
+   ace-bundle wfi://git/pr/create
    ```
 
+   Use the managed assignment and active delivery attempt with explicit
+   fork/canonical repository and ref provenance. The canonical operation is
+   `ace-assign delivery --assignment ID --attempt ATTEMPT --operation create --title TITLE --body-file DESCRIPTION`.
+   Preserve the resolved forge and exact candidate SHA. Continue through
+   `wfi://git/pr/update` only with accepted current test and independent review
+   receipts; CI status remains advisory. Inside ACE use source `bin/ace-*`.
+
 3. **Link to relevant issues/tasks**:
 
    ```markdown
@@ -219,7 +225,8 @@ git push --force-with-lease origin feature/your-feature
 
 #### Fork-Based Workflow
 
-For external contributors:
+Provider-specific GitHub clone example for external contributors; canonical
+assignment delivery above uses the explicitly selected forge and provenance:
 
 ```bash
 # Fork repository on GitHub, then:

data/handbook/skills/as-git-pr-create/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: as-git-pr-create
+description: Create an attempt-bound forge-neutral pull request
+user-invocable: true
+source: ace-git
+allowed-tools:
+  - Bash(ace-assign:*)
+  - Bash(ace-git:*)
+  - Bash(ace-bundle:*)
+  - Read
+assign:
+  steps:
+    - name: create-pr
+      description: Create the exact assignment pull request
+      produces: [pull-request]
+      consumes: [code-changes, execution-attempt]
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://git/pr/create
+---
+
+Load and run `ace-bundle wfi://git/pr/create` in the current project, then execute its complete workflow. Use source `bin/ace-*` entrypoints inside the ACE repository.

data/handbook/skills/as-git-pr-update/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: as-git-pr-update
+description: Update an attempt-bound forge-neutral pull request
+user-invocable: true
+source: ace-git
+allowed-tools:
+  - Bash(ace-assign:*)
+  - Bash(ace-git:*)
+  - Bash(ace-bundle:*)
+  - Read
+assign:
+  steps:
+    - name: update-pr-desc
+      description: Update the exact assignment pull request
+      produces: [pull-request]
+      consumes: [code-changes, execution-attempt]
+skill:
+  kind: workflow
+  execution:
+    workflow: wfi://git/pr/update
+---
+
+Load and run `ace-bundle wfi://git/pr/update` in the current project, then execute its complete workflow. Use source `bin/ace-*` entrypoints inside the ACE repository.

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

@@ -0,0 +1,36 @@
+---
+doc-type: workflow
+title: Create an attempt-bound draft pull request
+purpose: Create or reconcile a forge-neutral draft for the exact candidate
+---
+
+# Create an attempt-bound draft pull request
+
+## Goal
+
+Create one draft PR on the selected forge and retain its exact source/base identity in the assignment attempt journal.
+
+## Prerequisites
+
+A reviewed task, managed assignment, active delivery attempt, committed candidate, and pushed source ref. Credentials permit transport only; they grant no integration authority.
+
+## Inputs
+
+Use `forge_server` or `forge_default: true`, mutually exclusive. Neither means resolve this repository's configured remote. Provide `pr_provenance` containing `mode` (`fork` or `canonical`), `head_repository_url`, `head_ref`, `base_repository_url`, and `base_ref`. Canonical repositories must match; fork mode explicitly names its source even when owners coincide. Inputs contain no credentials.
+
+```json
+{"forge_server":"forge-lab","pr_provenance":{"mode":"canonical","head_repository_url":"https://forge.example/team/repo","head_ref":"feature","base_repository_url":"https://forge.example/team/repo","base_ref":"main"}}
+```
+
+## Steps
+
+1. Read the task and actual committed diff; prepare a concrete title and description explaining behavior and executed validation. Save the description as a local file.
+2. Use the existing managed assignment and active delivery attempt IDs. If needed, start the delivery step with `ace-assign attempt start --assignment ID --step STEP --project PROJECT` (numeric step scope). The execution boundary supplies actor identity; do not impersonate a reviewer or integrator.
+3. Supply the assignment source's `delivery` mapping, or save the explicit input JSON and pass `--parameters FILE`. For task-mode creation, `ace-assign create --task TASK --delivery-parameters FILE` retains these inputs in the generated job.
+4. Execute `ace-assign delivery --assignment ID --attempt ATTEMPT --operation create --title TITLE --body-file DESCRIPTION`. Add `--parameters FILE` only when supplying an explicit file. In this repository invoke the source `bin/ace-assign` entrypoint.
+5. Read the structured result. Verify the retained server/provider/base and head repository/ref, draft PR number/URL, candidate SHA, base_head, evidence_git_ref, and separate journal_commit. The pushed ref must equal the candidate; journal commits never advance it.
+6. On interruption or unknown create outcome, repeat the delivery command to perform exact-selector reconciliation reads. One matching draft at the exact head is adopted without a second create. Zero remains unresolved; multiple matches conflict. Never bypass uncertainty with a direct provider command.
+
+## Success criteria
+
+The journal records exact identity, intent before the write, and proven draft outcome afterward. A report or shell exit alone proves nothing. Continue with actual tests and independent current-head review; keep the PR draft until those receipts are accepted. CI is visible and advisory. Publication is a separate authorized operation and is not required for delivery.

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

@@ -0,0 +1,28 @@
+---
+doc-type: workflow
+title: Update an attempt-bound pull request
+purpose: Update the exact forge-neutral PR and consume current delivery evidence
+---
+
+# Update an attempt-bound pull request
+
+## Goal
+
+Update the recorded PR description for the current candidate and preserve provider identity through readiness and integration handoff.
+
+## Prerequisites
+
+A managed assignment with a recorded PR and active delivery attempt. Reuse the original forge selection and complete fork/canonical provenance; changed configuration or identity is a conflict. A new committed candidate, including task-only changes, requires renewed tests and independent review.
+
+## Steps
+
+1. Inspect the committed changes and accepted test/review evidence. Prepare the final description with the concrete behavior, executed test results, independent verdict, and actual limitations. Save it as a local file; do not put credentials or terminal dumps in the attempt journal.
+2. Execute `ace-assign delivery --assignment ID --attempt ATTEMPT --operation update --body-file DESCRIPTION`. Supply `--parameters FILE` only if the assignment source lacks the original `delivery` mapping. In this repository use `bin/ace-assign`.
+3. On interrupted update, repeat the delivery command. It reads the exact remote title/body and compares the requested field digest before accepting; an unmatched or unreadable outcome remains unresolved. Never blindly resend a mutation.
+4. To mark ready, supply two JSON reference files, each containing only `attempt_id` and `receipt_digest`, from coordinator-accepted current-head test and independent review attempts in this assignment/project. Execute `ace-assign delivery --assignment ID --attempt ATTEMPT --operation ready --tests TEST-REF --review REVIEW-REF`. Missing, fabricated, stale, or self-approved evidence cannot authorize readiness. Red CI alone does not veto valid executed tests and review.
+5. Merge is an integrator/service operation under the existing exact qjx authorization policy. The authorized executor calls `ace-git pr merge IDENTIFIER --server NAME --expected-head CANDIDATE-SHA --method METHOD --format json` with the retained selection (or `--default-server`, otherwise remote resolution). Both expected SHA and the authorized squash/merge/rebase method are required; there is no default method. It does not recursively request its own future receipt. The worker consumes the completed, verified service receipt using `ace-assign delivery --assignment ID --attempt ATTEMPT --operation merge --tests TEST-REF --review REVIEW-REF --service-request REQUEST`. The request must bind this assignment, attempt, project, candidate and PR URL. No completed receipt means a routed blocker; credentials or caller assertions grant no authority.
+6. Unknown merge remains pending service reconciliation and is never automatically retried. Inspect the authoritative selected remote and verified executor evidence. Changed head or scope blocks acceptance. Merge does not authorize publication, deployment or synchronization.
+
+## Success criteria
+
+The exact remote outcome and existing qjl evidence agree. Real artifacts, current executed tests, independent verdict and required authorization gate completion. Preserve unresolved history and distinct candidate_head/journal_commit. qkb.1 supplies installed charter/proposal/service adoption; this workflow does not fabricate that acceptance.

data/lib/ace/git/organisms/pull_request_lifecycle.rb

@@ -29,8 +29,10 @@ module Ace
         # @param remote_name [String, nil] git remote used when nothing selected
         # @param timeout [Integer, nil] provider operation timeout
         # @param runner [Proc, nil] injectable provider command runner (tests)
-        def initialize(server_name: nil, use_default: false, remote_name: nil, timeout: nil, runner: nil)
+        def initialize(server_name: nil, use_default: false, remote_name: nil, timeout: nil, runner: nil, repo_root: nil, resolved_server: nil)
+          @pinned_server = resolved_server
           @selection = {server_name: server_name, use_default: use_default, remote_name: remote_name}
+          @selection[:repo_root] = repo_root if repo_root
           @timeout = timeout
           @runner = runner
         end
@@ -234,6 +236,22 @@ module Ace
           )
         end
 
+        # Freeze the selected provider identity for an assignment attempt.
+        def resolved_identity
+          resolve_selected_server.to_h.transform_keys(&:to_s).transform_values(&:to_s)
+        end
+
+        # Read-only reconciliation of a possibly completed create. Absence
+        # does not authorize another write; the assignment owns that policy.
+        def reconcile_create(head_repository_url:, head_ref:, base_repository_url:, base_ref:)
+          server = resolve_selected_server
+          unless Atoms::ServerUrl.match?(server.url, base_repository_url)
+            raise ProviderIdentityMismatchError, "Create reconciliation base does not match selected server"
+          end
+          provider_for(server).find_open_pull_requests(head_repository_url: head_repository_url,
+            head_ref: head_ref, base_repository_url: base_repository_url, base_ref: base_ref)
+        end
+
         def resolved_server_url(identifier)
           reference = parse_identifier(identifier)
           resolve_server_for(reference).url
@@ -255,7 +273,11 @@ module Ace
         end
 
         def resolve_selected_server
-          ServerRegistry.resolve_for(**@selection)
+          selected = ServerRegistry.resolve_for(**@selection)
+          if @pinned_server && selected != @pinned_server
+            raise ProviderIdentityMismatchError, "Configured server identity changed from the pinned delivery identity"
+          end
+          @pinned_server || selected
         end
 
         # Resolve exactly one server for a parsed reference, validating any
@@ -270,7 +292,7 @@ module Ace
           end
 
           if @selection[:server_name] || @selection[:use_default]
-            selected = ServerRegistry.resolve_for(**@selection)
+            selected = resolve_selected_server
             unless candidates.any? { |candidate| candidate.name == selected.name }
               identity = reference.repository_url || reference.owner_repo
               raise ProviderIdentityMismatchError,

data/lib/ace/git/server_registry.rb

@@ -80,9 +80,9 @@ module Ace
         # @return [ResolvedServer] the single matching configured server
         # @raise [AmbiguousRemoteError] when the remote matches no configured
         #   server, or more than one
-        def resolve_remote(remote_name = nil)
+        def resolve_remote(remote_name = nil, repo_root: nil)
           remote_name ||= Ace::Git.config["remote"] || "origin"
-          remote_url = read_remote_url(remote_name)
+          remote_url = read_remote_url(remote_name, repo_root: repo_root)
           matches = entries.map(&:server).select { |server| Atoms::ServerUrl.match?(server.url, remote_url) }
 
           if matches.empty?
@@ -108,7 +108,7 @@ module Ace
         # @raise [ConfigError] when explicit selection and default conflict
         # @raise [UnknownServerNameError, NoDefaultServerConfiguredError,
         #   MultipleDefaultServersError, AmbiguousRemoteError] per resolution
-        def resolve_for(server_name: nil, use_default: false, remote_name: nil)
+        def resolve_for(server_name: nil, use_default: false, remote_name: nil, repo_root: nil)
           if server_name && use_default
             raise ConfigError,
               "Server selection is ambiguous: an explicit server ('#{server_name}') and " \
@@ -120,7 +120,7 @@ module Ace
           elsif use_default
             resolve_default
           else
-            resolve_remote(remote_name)
+            resolve_remote(remote_name, repo_root: repo_root)
           end
         end
 
@@ -173,8 +173,10 @@ module Ace
         end
 
         # Read a remote URL with local git only (no network, no forge CLI).
-        def read_remote_url(remote_name)
-          result = Atoms::CommandExecutor.execute("git", "remote", "get-url", remote_name.to_s)
+        def read_remote_url(remote_name, repo_root: nil)
+          argv = ["git"]
+          argv += ["-C", repo_root] if repo_root
+          result = Atoms::CommandExecutor.execute(*argv, "remote", "get-url", remote_name.to_s)
           result[:success] ? result[:output].to_s.strip : nil
         end
 

data/lib/ace/git/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Git
-    VERSION = "0.28.0"
+    VERSION = "0.29.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-git
 version: !ruby/object:Gem::Version
-  version: 0.28.0
+  version: 0.29.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-04 00:00:00.000000000 Z
+date: 2026-10-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-config
@@ -124,19 +124,19 @@ files:
 - handbook/guides/version-control/ruby.md
 - handbook/guides/version-control/rust.md
 - handbook/guides/version-control/typescript.md
+- handbook/skills/as-git-pr-create/SKILL.md
+- handbook/skills/as-git-pr-update/SKILL.md
 - handbook/skills/as-git-rebase/SKILL.md
 - handbook/skills/as-git-reorganize-commits/SKILL.md
-- handbook/skills/as-github-pr-create/SKILL.md
-- handbook/skills/as-github-pr-update/SKILL.md
 - handbook/skills/as-github-release-publish/SKILL.md
 - handbook/templates/commit/squash.template.md
 - handbook/templates/pr/bugfix.template.md
 - handbook/templates/pr/default.template.md
 - handbook/templates/pr/feature.template.md
+- handbook/workflow-instructions/git/pr/create.wf.md
+- handbook/workflow-instructions/git/pr/update.wf.md
 - handbook/workflow-instructions/git/rebase.wf.md
 - handbook/workflow-instructions/git/reorganize-commits.wf.md
-- handbook/workflow-instructions/github/pr/create.wf.md
-- handbook/workflow-instructions/github/pr/update.wf.md
 - handbook/workflow-instructions/github/release-publish.wf.md
 - lib/ace/git.rb
 - lib/ace/git/atoms/command_executor.rb

data/handbook/skills/as-github-pr-create/SKILL.md

@@ -1,72 +0,0 @@
----
-name: as-github-pr-create
-description: Create GitHub pull request with generated description and summary
-# bundle: wfi://github/pr/create
-# agent: general-purpose
-user-invocable: true
-allowed-tools:
-  - Bash(ace-git:*)
-  - Bash(ace-bundle:*)
-  - Bash(gh:*)
-  - Read
-argument-hint: pr-type
-last_modified: 2026-01-10
-source: ace-git
-integration:
-  targets:
-    - claude
-    - codex
-    - gemini
-    - opencode
-    - pi
-  providers:
-    claude:
-      frontmatter:
-        context: fork
-        model: haiku
-assign:
-  steps:
-    - name: create-pr
-      description: Create a pull request for the implemented changes
-      intent:
-        phrases:
-          - "create pr"
-          - "create a pr"
-          - "open pr"
-          - "open pull request"
-      prerequisites:
-        - name: work-on-task
-          strength: required
-          reason: "Must have code changes to create a PR"
-      produces: [pull-request]
-      consumes: [code-changes, commits]
-      context:
-        default: null
-        reason: "PR creation needs access to git state in main context"
-      when_to_skip:
-        - "PR already exists for this branch"
-        - "Changes don't warrant a PR (e.g., direct push allowed)"
-      effort: light
-      tags: [git, pr, publishing]
-skill:
-  kind: workflow
-  execution:
-    workflow: wfi://github/pr/create
----
-
-## Arguments
-
-Use the skill `argument-hint` values as the explicit inputs for this skill.
-
-## Variables
-
-None
-
-## Execution
-
-- You are working in the current project.
-- Run `ace-bundle wfi://github/pr/create` in the current project to load the workflow instructions.
-- Read the loaded workflow and execute it end-to-end in this project.
-- Follow the workflow as the source of truth.
-- Do the work described by the workflow instead of only summarizing it.
-- When the workflow requires edits, tests, or commits, perform them in this project.

data/handbook/skills/as-github-pr-update/SKILL.md

@@ -1,41 +0,0 @@
----
-name: as-github-pr-update
-description: Update PR description based on current work
-# bundle: wfi://github/pr/update
-# agent: general-purpose
-user-invocable: true
-allowed-tools:
-  - Bash(ace-git:*)
-  - Bash(ace-bundle:*)
-  - Bash(gh:*)
-  - Read
-  - Grep
-argument-hint: pr-number
-last_modified: 2026-01-10
-source: ace-git
-integration:
-  targets:
-    - claude
-    - codex
-    - gemini
-    - opencode
-    - pi
-assign:
-  source: wfi://github/pr/update
-  steps:
-    - name: update-pr-desc
-      description: Update PR description with implementation summary and final state
-      intent:
-        phrases:
-          - "update pr description"
-          - "update pull request description"
-          - "refresh pr description"
-          - "sync pr description"
-      tags: [git, pr, documentation]
-skill:
-  kind: workflow
-  execution:
-    workflow: wfi://github/pr/update
----
-
-Load and run `ace-bundle wfi://github/pr/update` in the current project, then follow the loaded workflow as the source of truth and execute it end-to-end instead of only summarizing it.

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