ace-git 0.30.0 → 0.31.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ecccf931f808308fde6ab00654e43fdcbe7b90e0f0c929ade43a25a427302756
-  data.tar.gz: 03af540433b453863a3d399a67565724c68288c0a4a2b283462f613293a4a6a0
+  metadata.gz: 83d5b624eab98d754e4bb770fdd1a80e00237d063bc07ba2b412e31cf0b4fa87
+  data.tar.gz: 1e8a556aedb3f9ba844ebe46a7b3c64adea58b979842bf6df7835742057c20c1
 SHA512:
-  metadata.gz: c999f3855347dda4bfac0ce490ec94666f1e9e2cf00b2907d0ad72fa5c083e00495e0f4296036770d106bb1decddca02a37b495e71d87552344899a4321cba08
-  data.tar.gz: 0decf0ad84220579f16b3606d9c6ee3d6193e0a4dfbee22474cd4ee8008b5a75c6fc4bfc9f77bb8d27ae14fbdf65a3c95c957644ac318e08caffe03f7d0e768c
+  metadata.gz: 8c33109eb792dea197dc9e29a9f63839ed10d53c95aa7e1817d22cbbe2cbecc51123f8fe90ad420a2e908b35a6aa1bbaef35612340bcd667ad21b5736dbdad49
+  data.tar.gz: a2b337d9084ff29b01cd0834e2e9e9a3ef36299d0c0704bdad61480d844cd1a0165f1d4b9c482c5acf0feb29d0dc6aaa715e992dca1e2fa50d6abeb736e234f7

data/CHANGELOG.md

@@ -7,6 +7,29 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.31.0] - 2026-10-23
+
+### Added
+
+- Formal reviewer-owned, exact-head provider approval and read-only approval verification through the forge-neutral review flow; comments do not substitute for approval.
+
+
+### Fixed
+
+- Serialize all local review correlations per normalized PR, validate selected/relevant review actors without rejecting unrelated historical comments, and preserve unsafe pending reviews with explicit refusal.
+
+## [0.30.1] - 2026-10-17
+
+### Changed
+
+- Document the ordinary local PR create/update/ready path; remove the protected worker boundary and `ace-lab service request/status` requirements from the git PR workflows and guide.
+- Document explicit remote read/compare reconciliation for an interrupted PR update instead of claiming the command compares and accepts the remote description; an interrupted create adopts one exact-head draft but does not compare or rewrite remote title/body.
+- Drop the `attempt-bound`/`execution-attempt` wording from the `as-git-pr-create` and `as-git-pr-update` skills; they wrap the same forge-neutral PR workflows.
+
+### Removed
+
+- Remove the protected merge boundary feature test and its fixture, which exercised the removed protected authority model.
+
 ## [0.30.0] - 2026-10-08
 
 ### Added

data/docs/handbook.md

@@ -9,6 +9,11 @@ ace-docs:
 
 # ace-git Handbook Catalog
 
+> **Planned (L5.5):** role rules, independent review rounds, and the
+> attempt-bound forge delivery workflow are not available yet. The PR
+> create/update skills below are projections of that planned workflow; the
+> ordinary `ace-git pr` CLI commands remain the supported local path.
+
 Reference for package-owned handbook resources in `ace-git/handbook/`.
 
 ## Skills

data/docs/usage.md

@@ -86,6 +86,7 @@ ace-git diff --raw
 ```
 
 **Options:**
+
 - `--format, -f` - Output format: `diff` (default), `summary`, `grouped-stats`
 - `--since, -s` - Changes since date/duration (e.g., "7d", "1 week ago")
 - `--paths, -p` - Include only these glob patterns
@@ -118,12 +119,14 @@ ace-git status --with-diff
 ```
 
 **Options:**
+
 - `--format, -f` - Output format: `markdown` (default), `json`
 - `--no-pr, -n` - Skip PR metadata and activity lookups (faster)
 - `--commits N` - Number of recent commits to show (default: 3 from config)
 - `--with-diff` - Include PR diff in output
 
 **Output includes:**
+
 - Current branch name with git status -sb output
 - Remote tracking status (ahead/behind)
 - Detected task pattern (from branch name)
@@ -153,6 +156,7 @@ ace-git branch --format json
 ```
 
 **Options:**
+
 - `--format, -f` - Output format: `text` (default), `json`
 
 ### `ace-git pr`
@@ -191,16 +195,24 @@ ace-git pr merge 25 --expected-head SHA --method squash
 ```
 
 **Behavior guarantees:**
+
 - Create is idempotent: one exact open base/head match returns the existing
+
   PR (`idempotency: existing`); multiple matches are a conflict.
+
 - `merge` requires the provider to enforce `--expected-head` atomically;
+
   providers without that capability return an unsupported-capability failure
   instead of racing.
+
 - A create request whose outcome is unknown (transport failure after send)
+
   reports an unknown outcome with the exact identity to reconcile; it never
   retries automatically.
+
 - With `--format json`, a failed operation prints the classified error as
-  JSON on stdout (`{"error": {"category": ..., "message": ...}}` — e.g.
+
+  JSON on stdout (`{"error": {"category": ..., "message": ...}}` -- e.g.
   `expected_head_conflict`, `unsupported_capability`, `unknown_outcome`)
   before the nonzero exit; text mode explains the same failure on stderr.
 
@@ -256,9 +268,10 @@ diff:
 | `grouped_stats.layers` | Array | `["lib","test","handbook"]` | Preferred layer grouping order |
 | `grouped_stats.collapse_above` | Integer | `5` | Collapse markdown groups above this file count |
 | `grouped_stats.show_full_tree` | String | `collapsible` | Tree rendering strategy hint |
-| `grouped_stats.dotfile_groups` | Array | `[".ace-task",".ace"]` | Dot-directories to prioritize in grouping |
+| `grouped_stats.dotfile_groups` | Array | `[".ace-tasks",".ace"]` | Dot-directories to prioritize in grouping |
 
 **Default exclude_patterns** (from `.ace-defaults/git/config.yml`):
+
 - Lock files: `**/*.lock`, `package-lock.json`, `yarn.lock`, `Gemfile.lock`
 - Vendored deps: `vendor/**/*`, `node_modules/**/*`
 - Build artifacts: `coverage/**/*`, `dist/**/*`, `build/**/*`, `.cache/**/*`
@@ -289,30 +302,24 @@ Note: `test/**/*` and `spec/**/*` are NOT excluded by default - test changes are
 
 ## Provider Packages
 
-`ace-git service create`, `service update`, `service ready` and `service merge`
-are fixed protected receiver handlers. It accepts no
-options; the receiver supplies its claimed JSON envelope on stdin and its
-private materialized candidate directory as the working directory. The handler
-checks the exact input digest, executor, candidate and forge provenance, calls
-the selected neutral operation once, and emits the existing bounded evidence
-response only after verifying the exact PR outcome (and merge commit for merge). An unverified or lost
-outcome emits no success and never retries. This command does not authorize a
-operation or replace the protected worker's canonical receipt acceptance.
-Create/update use an exact `{target,delivery,title,body}` input and remain draft;
-ready uses `{target,delivery}`, merge uses `{target,delivery,method}`. Create targets
-the base repository; all other operations target the exact PR URL. The original
-title remains part of the accepted input; the provider owns its draft encoding
-(Forgejo's WIP prefix). Updating a draft preserves that encoding. Each handler
-publishes the fixed `pr-result.txt` evidence only after its observed content,
-identity, head and draft/merge outcome agree.
+> **Planned (L5.5):** the forge-neutral worker/integrator role rules and the
+> attempt-bound PR delivery workflow are not available yet. The old protected
+> `service create|update|ready|merge` receiver handlers are not part of the
+> file-based flow and are not a requirement for opening or reviewing a PR.
+>
+> Use the ordinary `ace-git pr` commands documented above for now; they create
+> or reconcile a PR for the pushed branch.
 
 `ace-git` is forge-neutral. It defines the server registry (`Ace::Git::ServerRegistry`),
 the provider contract (`Ace::Git::Providers::Base`), and normalized evidence types;
 provider packages own all forge CLI behavior:
 
 - **ace-git-github** - GitHub behavior via the `gh` CLI (PR lookups, diffs, issue
+
   tracking operations). Registers under the `github` provider type.
+
 - **ace-git-forgejo** - Forgejo behavior via the `fj` CLI. Registers under the
+
   `forgejo` provider type.
 
 Both providers implement the same issue-tracking contract (issue lookup, comment
@@ -323,3 +330,66 @@ Configure servers in `.ace/git/config.yml` under `git.servers`, then
 resolve them by name, by default, or from a git remote URL. Every failure path is
 classified (missing CLI, unauthenticated, unreachable, malformed output, object
 not found) with no silent fallbacks.
+
+
+### Formal provider approval
+
+```sh
+ace-git pr approve 25 --expected-head FULL_SHA --body-file accepted-review.md --correlation review-123 --server forge --format json
+ace-git pr approval 25 --expected-head FULL_SHA --review-id 99 --server forge --format json
+```
+
+`approve` publishes an already accepted independent review under the configured
+provider identity; it does not invoke a model or decide the review verdict. The
+UTF-8 report must be nonempty, contain no reserved approval marker, and fit in
+64KiB. The PR must be open, ready and at the full lowercase expected SHA; its
+author cannot approve it. GitHub and Forgejo return a verified effective formal
+approval, including exact repository/PR/head, reviewer ID/login, review ID/URL,
+evidence SHA256, correlation, and `created|existing`. Forgejo additionally checks
+official review status. A comment or `pr ready` is a separate operation.
+
+`approval` is read-only and verifies the current effective approval identified by
+the numeric provider review ID. Integrators compare its receipt with the accepted
+reviewer artifact; they do not mint a substitute review. Existing server selection
+and JSON error categories apply. Role instructions confer no provider permission;
+credentials remain with the deployment-configured account.
+
+Correlation is scoped to the selected provider/server/repository/PR. Reusing it
+with changed visible evidence conflicts. A same-account local per-PR flock serializes all correlations/worktrees
+for concurrent publication; this is not a distributed uniqueness service. Provider
+visibility may hide another account's pending reviews, and separate hosts do not
+share this lock. No success is inferred for invisible evidence. Save the receipt
+in the existing review/assignment artifacts; there is no new journal.
+
+After an unknown direct-create outcome, explicitly resume the same publication
+to reconcile provider state first. Mutations are never automatically retried.
+Changed head, stale/dismissed/nonofficial approval, unavailable evidence or
+unsupported capability withholds success rather than using a comment, another
+identity, or weaker branch protection. Actual provider/account acceptance remains
+a separate deployment proof from deterministic package tests.
+
+
+Formal approval requires a **dedicated automation reviewer identity and one
+writer per actor/repository/PR**, supplied by deployment. All local correlations
+share a private per-PR lock in the system temporary directory, independently of
+worktree/TMPDIR. Another host or manual client sharing that identity violates
+the supported execution contract: neither provider offers a pending-review CAS
+through this path. This precondition must be verified before live use; role
+instructions and topology discovery do not establish it.
+
+Both adapters directly create approval with the accepted full commit ID.
+Forgejo 11+ preserves that explicit ID; its pending-submit route instead rebinds
+to current HEAD and is never used. Direct create can reuse pending, so visible
+unrelated pending refuses before mutation. A matching, comment-free own pending
+can resume through Forgejo's verified direct-create path. Pending with comments
+or an unverified safe recovery path (including current GitHub pending recovery)
+is retained with an explicit refusal. Lost direct-create replies reconcile the
+submitted review, without a second automatic POST. No claim of server-atomic
+pending isolation or cross-host mutual exclusion is made.
+
+GitHub actor proof uses authenticated GraphQL viewer login/databaseId under the
+same configured PAT, App user or App installation token. REST `/user` is not
+used for installation credentials. Unavailable/unverifiable viewer or integration
+access refusal is a truthful capability/authentication failure before approval,
+never a guessed bot identity, borrowed token or apparent network outage. Live
+App/account/public-review proof remains separate from deterministic fixtures.

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

@@ -21,7 +21,7 @@ This project uses a **mono-repo architecture** with all packages at the reposito
 
 - **ace-*/**: Ruby gems for specific functionality (ace-git, ace-task, ace-docs, etc.)
 - **docs/**: Project documentation and architecture decisions
-- **.ace-task/**: Task management and release coordination
+- **.ace-tasks/**: Task management and release coordination
 - **_legacy/**: Archived content from previous multi-repo structure
 
 #### Common Git Commands
@@ -183,18 +183,19 @@ git remote prune origin
    git push -u origin feature/your-feature
    ```
 
-2. **Create an attempt-bound draft on the selected forge**:
+2. **Create a draft on the selected forge**:
 
    ```bash
    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`.
+   Use the actual assignment and active attempt when the work belongs to an
+   assignment, with explicit fork/canonical repository and ref provenance. The
+   forge command is
+   `ace-git pr create --server NAME --head HEAD-REF --base BASE-REF --expected-head CANDIDATE-SHA --title TITLE --body-file DESCRIPTION --format json`.
    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-*`.
+   `wfi://git/pr/update` only with current exact-head test and independent review
+   evidence; CI status remains advisory. Inside ACE use source `bin/ace-*`.
 
 3. **Link to relevant issues/tasks**:
 
@@ -225,8 +226,8 @@ git push --force-with-lease origin feature/your-feature
 
 #### Fork-Based Workflow
 
-Provider-specific GitHub clone example for external contributors; canonical
-assignment delivery above uses the explicitly selected forge and provenance:
+Provider-specific GitHub clone example for external contributors; the neutral
+draft/update flow above uses the explicitly selected forge and provenance:
 
 ```bash
 # Fork repository on GitHub, then:

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

@@ -1,6 +1,6 @@
 ---
 name: as-git-pr-create
-description: Create an attempt-bound forge-neutral pull request
+description: Create a forge-neutral pull request
 user-invocable: true
 source: ace-git
 allowed-tools:
@@ -13,7 +13,7 @@ assign:
     - name: create-pr
       description: Create the exact assignment pull request
       produces: [pull-request]
-      consumes: [code-changes, execution-attempt]
+      consumes: [code-changes]
 skill:
   kind: workflow
   execution:

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

@@ -1,6 +1,6 @@
 ---
 name: as-git-pr-update
-description: Update an attempt-bound forge-neutral pull request
+description: Update a forge-neutral pull request
 user-invocable: true
 source: ace-git
 allowed-tools:
@@ -13,7 +13,7 @@ assign:
     - name: update-pr-desc
       description: Update the exact assignment pull request
       produces: [pull-request]
-      consumes: [code-changes, execution-attempt]
+      consumes: [code-changes]
 skill:
   kind: workflow
   execution:

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

@@ -1,18 +1,18 @@
 ---
 doc-type: workflow
-title: Create an attempt-bound draft pull request
+title: Create a draft pull request
 purpose: Create or reconcile a forge-neutral draft for the exact candidate
 ---
 
-# Create an attempt-bound draft pull request
+# Create a draft pull request
 
 ## Goal
 
-Create one draft PR on the selected forge and retain its exact source/base identity in the assignment attempt journal.
+Create one draft PR on the selected forge and record its exact source/base identity in the assignment report.
 
 ## Prerequisites
 
-A reviewed task, managed assignment, active delivery attempt, committed candidate, and pushed source ref. Credentials permit transport only; they grant no integration authority.
+A reviewed task or explicit implementation scope, a committed candidate, and a pushed source ref. Credentials permit transport only; they grant no integration permission.
 
 ## Inputs
 
@@ -22,49 +22,21 @@ Use `forge_server` or `forge_default: true`, mutually exclusive. Neither means r
 {"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"}}
 ```
 
-## Protected worker boundary
-
-The steps below are ordinary managed delivery only. An installed protected
-participant uses the configured receiver and the original canonical authority,
-with no caller-local journal or direct-provider fallback.
-
-The authenticated worker may create/update a draft before independent review.
-Save a nonsecret input object with exactly `target`, `delivery`, `title`, `body`;
-`delivery` is the normalized original forge/provenance mapping. `target` has
-`resource` and nullable `artifact_digest`: the selected base repository URL for
-create, the exact recorded PR URL for update. Title/body are bounded UTF-8 text.
-Request the installed receiver with:
-
-```sh
-ace-lab service request --project PROJECT --assignment ID --attempt ATTEMPT \
-  --mapping MAPPING --scope SCOPE --service SERVICE --operation OPERATION \
-  --candidate-head SHA --candidate-generation CANDIDATE-GENERATION \
-  --expected-generation AUTHORITY-GENERATION --authorization AUTHORIZATION \
-  --request-id REQUEST --input INPUT.json
-```
-
-Use `create` or `update` as OPERATION; each requires its own exact scoped grant.
-The receiver runs the fixed `ace-git service create` or `service update` handler.
-A claim acknowledges admission, not PR success. Retain its complete selection
-and observe `ace-lab service status` as described in
-`wfi://handbook/perform-delivery`. Lost replies stay uncertain; status does not
-repeat an effect. Only canonical completion supplies the created PR URL.
-
-For ready, use the same request with OPERATION `ready` and input containing only
-`target` and `delivery`. Ready and merge require executed checks, accepted
-independent review for the current revision and the matching authorization.
-Local report/reference files cannot replace those canonical proofs. Draft
-creation/update does not grant readiness, merge or publication.
-
 ## 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.
+2. When this work belongs to an assignment, use its actual ID and record the PR identity in the assignment report. The execution boundary supplies actor identity; do not impersonate a reviewer or integrator.
+3. Verify the pushed source ref resolves to the candidate SHA. The pushed ref must equal the candidate.
+4. Create the draft with the configured forge command; drafts are the default:
+
+   ```sh
+   ace-git pr create --server NAME --head HEAD-REF --head-repo HEAD-REPOSITORY-URL --base BASE-REF --expected-head CANDIDATE-SHA --title TITLE --body-file DESCRIPTION --format json
+   ```
+
+   Use the retained default/remote selection instead of `--server NAME` when applicable. In this repository invoke the source `bin/ace-git` entrypoint.
+5. Read the structured result. Verify the retained server/provider/base and head repository/ref, draft PR number/URL, candidate SHA and base head. Record the PR identity and observed candidate head in the assignment report.
+6. On interruption or an unknown create outcome, repeat the same command with the same selectors: the implementation re-reads open PRs and adopts one matching draft at the exact head without a second create. Adoption does not compare or rewrite the remote title/body, so verify the remote content explicitly before relying on it, and use `wfi://git/pr/update` if the description differs. Zero matches remain unresolved; multiple matches conflict. Never bypass an uncertain read with a different 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.
+The assignment report records exact identity and the proven draft outcome. A report or shell exit alone proves nothing. Continue with actual tests and independent current-head review; keep the PR draft until those results 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

@@ -1,10 +1,10 @@
 ---
 doc-type: workflow
-title: Update an attempt-bound pull request
-purpose: Update the exact forge-neutral PR and consume current delivery evidence
+title: Update a pull request
+purpose: Update the exact forge-neutral PR and record current delivery evidence
 ---
 
-# Update an attempt-bound pull request
+# Update a pull request
 
 ## Goal
 
@@ -12,51 +12,35 @@ Update the recorded PR description for the current candidate and preserve provid
 
 ## 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.
-
-## Protected worker boundary
-
-The steps below are ordinary managed delivery only. An installed protected
-participant uses the configured receiver and the original canonical authority,
-with no caller-local journal or direct-provider fallback.
-
-The authenticated worker may create/update a draft before independent review.
-Save a nonsecret input object with exactly `target`, `delivery`, `title`, `body`;
-`delivery` is the normalized original forge/provenance mapping. `target` has
-`resource` and nullable `artifact_digest`: the selected base repository URL for
-create, the exact recorded PR URL for update. Title/body are bounded UTF-8 text.
-Request the installed receiver with:
-
-```sh
-ace-lab service request --project PROJECT --assignment ID --attempt ATTEMPT \
-  --mapping MAPPING --scope SCOPE --service SERVICE --operation OPERATION \
-  --candidate-head SHA --candidate-generation CANDIDATE-GENERATION \
-  --expected-generation AUTHORITY-GENERATION --authorization AUTHORIZATION \
-  --request-id REQUEST --input INPUT.json
-```
-
-Use `create` or `update` as OPERATION; each requires its own exact scoped grant.
-The receiver runs the fixed `ace-git service create` or `service update` handler.
-A claim acknowledges admission, not PR success. Retain its complete selection
-and observe `ace-lab service status` as described in
-`wfi://handbook/perform-delivery`. Lost replies stay uncertain; status does not
-repeat an effect. Only canonical completion supplies the created PR URL.
-
-For ready, use the same request with OPERATION `ready` and input containing only
-`target` and `delivery`. Ready and merge require executed checks, accepted
-independent review for the current revision and the matching authorization.
-Local report/reference files cannot replace those canonical proofs. Draft
-creation/update does not grant readiness, merge or publication.
+An assignment with a recorded PR, or an explicit local PR scope. 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.
+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 assignment report.
+2. Update the PR with the configured forge command:
+
+   ```sh
+   ace-git pr update IDENTIFIER --server NAME --expected-head CANDIDATE-SHA --body-file DESCRIPTION --format json
+   ```
+
+   Use the retained default/remote selection instead of `--server NAME` when applicable. In this repository invoke the source `bin/ace-git` entrypoint.
+3. On an interrupted update, do not assume the command reconciles for you: `ace-git pr update` verifies the head and rewrites the title/body, so a retry is a new write. Explicitly read the exact remote title/body (for example `ace-git pr show IDENTIFIER --format json`), compare it with the prepared description; if identical, treat the update as done, otherwise re-run the command. An unreadable or uncertain read stays unresolved. Never blindly resend a mutation.
+4. Mark ready only after tests and independent review pass on the exact head. Record the executed tests and independent review evidence for that head, then run:
+
+   ```sh
+   ace-git pr ready IDENTIFIER --server NAME --expected-head CANDIDATE-SHA --format json
+   ```
+
+   Missing, stale, or self-approved evidence cannot authorize readiness. Red CI alone does not veto valid executed tests and review.
+5. Merge is a separate authorized operation for the exact candidate. The authorized executor runs:
+
+   ```sh
+   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 the expected SHA and the authorized squash/merge/rebase method are required; there is no default method. Credentials or caller assertions grant no permission.
+6. An unknown merge remains an unresolved effect. Inspect the authoritative selected remote and the actual executor evidence; never retry blindly. 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.
+The exact remote outcome and the locally recorded evidence agree. Real artifacts, current executed tests and an independent verdict gate completion. Preserve unresolved history and distinguish the candidate head from evidence commits.

data/lib/ace/git/cli/commands/pr.rb

@@ -204,6 +204,38 @@ module Ace
             end
           end
 
+          class Approve < BaseCommand
+            desc "Publish a formal approval under the configured reviewer identity"
+            argument :identifier, required: true, desc: "PR number, owner/repo#number, or URL"
+            option :expected_head, type: :string, required: true, desc: "Exact accepted head SHA"
+            option :body_file, type: :string, required: true, desc: "Accepted review report file"
+            option :correlation, type: :string, required: true, desc: "Stable approval publication identity"
+
+            def call(identifier:, expected_head:, body_file:, correlation:, **options)
+              result = lifecycle(options).approve(identifier, expected_head: expected_head,
+                body_file: body_file, correlation: correlation)
+              render_evidence(options, header: "Formal approval confirmed", **result.to_h)
+            rescue Ace::Git::Error, ArgumentError => e
+              render_failure(options, e)
+              raise Ace::Support::Cli::Error.new(e.message)
+            end
+          end
+
+          class Approval < BaseCommand
+            desc "Read and verify an effective exact-head approval without mutation"
+            argument :identifier, required: true, desc: "PR number, owner/repo#number, or URL"
+            option :expected_head, type: :string, required: true, desc: "Exact accepted head SHA"
+            option :review_id, type: :integer, required: true, desc: "Review ID from the approval receipt"
+
+            def call(identifier:, expected_head:, review_id:, **options)
+              result = lifecycle(options).approval(identifier, expected_head: expected_head, review_id: review_id)
+              render_evidence(options, header: "Formal approval verified", **result.to_h)
+            rescue Ace::Git::Error, ArgumentError => e
+              render_failure(options, e)
+              raise Ace::Support::Cli::Error.new(e.message)
+            end
+          end
+
           # `ace-git pr merge ID --expected-head SHA --method squash|merge|rebase`
           class Merge < BaseCommand
             desc "Merge with provider-side expected-head enforcement; no default method"

data/lib/ace/git/cli.rb

@@ -53,7 +53,7 @@ module Ace
         ["diff", "Show filtered git diff output"],
         ["status", "Show repository status and PR context"],
         ["branch", "Show current branch information"],
-        ["pr", "Forge-neutral pull request lifecycle: show, create, update, ready, merge"],
+        ["pr", "Forge-neutral pull request lifecycle: show, create, update, ready, approve, approval, merge"],
         ["service merge", "Fixed receiver-owned exact-head merge envelope"],
         ["service create", "Fixed receiver-owned draft PR creation"],
         ["service update", "Fixed receiver-owned draft PR update"],
@@ -74,6 +74,8 @@ module Ace
       register "pr create", Commands::Pr::Create.new
       register "pr update", Commands::Pr::Update.new
       register "pr ready", Commands::Pr::Ready.new
+      register "pr approve", Commands::Pr::Approve.new
+      register "pr approval", Commands::Pr::Approval.new
       register "pr merge", Commands::Pr::Merge.new
       register "service merge", Commands::ServiceMerge.new
       %w[create update ready].each do |operation|

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

@@ -142,6 +142,21 @@ module Ace
           )
         end
 
+        def approve(identifier, expected_head:, body_file:, correlation:)
+          body = load_body(body_file, limit: 64 * 1024 + 1)
+          reference = parse_identifier(identifier)
+          provider = provider_for(resolve_server_for(reference))
+          provider.approve_pull_request(number: reference.number, expected_head: expected_head,
+            body: body, correlation: correlation)
+        end
+
+        def approval(identifier, expected_head:, review_id:)
+          reference = parse_identifier(identifier)
+          provider = provider_for(resolve_server_for(reference))
+          provider.pull_request_approval(number: reference.number, expected_head: expected_head,
+            review_id: review_id)
+        end
+
         def post_review_comment(identifier, expected_head:, body:, correlation:)
           reference = parse_identifier(identifier)
           provider = provider_for(resolve_server_for(reference))
@@ -344,11 +359,11 @@ module Ace
           Ace::Git::Providers.for(server, timeout: @timeout, runner: @runner)
         end
 
-        def load_body(path)
+        def load_body(path, limit: nil)
           raise ArgumentError, "--body-file is required" unless path
           raise ArgumentError, "Body file not found: #{path}" unless File.file?(path)
 
-          File.read(path)
+          File.read(path, limit)
         rescue SystemCallError => e
           raise ArgumentError, "Cannot read body file #{path}: #{e.message}"
         end

data/lib/ace/git/providers/base.rb

@@ -168,6 +168,16 @@ module Ace
           raise NotImplementedError, "Providers must implement #{self.class}#repository_file"
         end
 
+        # Formal approval is distinct from comments. Unsupported adapters refuse;
+        # they must never project an approval as a comment or switch identity.
+        def approve_pull_request(number:, expected_head:, body:, correlation:)
+          raise ProviderUnsupportedCapabilityError, "Formal approval is unsupported by #{self.class}"
+        end
+
+        def pull_request_approval(number:, expected_head:, review_id:)
+          raise ProviderUnsupportedCapabilityError, "Formal approval evidence is unsupported by #{self.class}"
+        end
+
         # Create a top-level PR comment. `correlation` is a stable session key
         # embedded in the body so a retry can find exactly one prior send.
         # A possible post-send transport failure raises ProviderUnknownOutcomeError.

data/lib/ace/git/providers/evidence.rb

@@ -48,6 +48,13 @@ module Ace
       :idempotency
     )
 
+    # Effective formal review, verified against the current provider state.
+    ProviderApprovalReceipt = Data.define(
+      :provider, :server_name, :repository_url, :pr_number, :pr_url, :head_sha,
+      :reviewer_id, :reviewer, :review_id, :review_url, :state, :effective, :official,
+      :correlation, :evidence_sha256, :idempotency
+    )
+
     # Normalized repository evidence.
     ProviderRepository = Data.define(:server_name, :full_name, :default_branch, :url)
 

data/lib/ace/git/providers/formal_approval.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require "digest"
+require "tmpdir"
+require "etc"
+require_relative "evidence"
+require_relative "../atoms/server_url"
+
+module Ace
+  module Git
+    module Providers
+      # Shared policy for formal review evidence. Provider packages supply the
+      # authenticated I/O ports; no credentials or delivery state live here.
+      class FormalApproval
+        SHA = /\A[0-9a-f]{40}\z/
+        CORRELATION = /\A[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}\z/
+        MARKER = /\n\n<!-- ace-approval:([a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}) sha256:([0-9a-f]{64}) -->\z/
+
+        def initialize(provider:, request:, list:, official: false, pending_reuse: false)
+          @provider, @request, @list, @official = provider, request, list, official
+          @pending_reuse = pending_reuse
+        end
+
+        def approve(number:, expected_head:, body:, correlation:)
+          validate_input!(number, expected_head)
+          unless body.is_a?(String) && body.dup.force_encoding(Encoding::UTF_8).valid_encoding? && !body.strip.empty? &&
+              body.bytesize <= 64 * 1024 && !body.include?("\0") && !body.include?("<!-- ace-approval:") &&
+              correlation.is_a?(String) && correlation.match?(CORRELATION)
+            raise ArgumentError, "Approval requires a nonempty UTF-8 report (maximum 64KiB) and valid correlation"
+          end
+          body = body.dup.force_encoding(Encoding::UTF_8)
+          digest = Digest::SHA256.hexdigest(body)
+          sent_body = "#{body}\n\n<!-- ace-approval:#{correlation} sha256:#{digest} -->"
+          # Same existing per-session flock family as comment publication,
+          # with a digest filename so caller text never forms a filesystem path.
+          # All correlations for this PR share the lock: a provider may reuse
+          # an actor's pending review instead of creating a distinct object.
+          scope = [@provider.server.provider, Atoms::ServerUrl.normalize(@provider.server.url), number]
+          key = Digest::SHA256.hexdigest(scope.join("\0"))
+          File.open(File.join(Etc.systmpdir, "ace-review-session-approval-#{Process.uid}-#{key}.lock"),
+            File::CREAT | File::RDWR | File::NOFOLLOW, 0600) do |lock|
+            unless lock.stat.file? && lock.stat.uid == Process.uid && (lock.stat.mode & 0777) == 0600
+              raise ConfigError, "Unsafe approval session lock"
+            end
+            lock.flock(File::LOCK_EX)
+            pr = current!(number, expected_head)
+            actor = identity!(@request.call(:get, :actor, nil))
+            deny_author!(pr, actor)
+            rows = reviews!(number)
+            matches = rows.select { |row| row.fetch("body").include?("<!-- ace-approval:#{correlation} ") }
+            raise ProviderConflictingMatchesError, "Ambiguous approval correlation" if matches.length > 1
+            existing = matches.first
+            row!(existing) if existing
+            if existing && (existing["body"] != sent_body || existing["commit_id"] != expected_head ||
+                identity!(existing["user"]) != actor)
+              raise ProviderConflictingMatchesError, "Approval correlation is already bound to different evidence"
+            end
+            # A provider may reuse its current pending object on direct create.
+            # Only an exact known, comment-free pending review is resumable, and
+            # only when the adapter proves explicit commit preservation on reuse.
+            owned_pending = rows.select do |row|
+              row["state"] == "PENDING" && row["user"].is_a?(Hash) && row["user"]["id"] == actor.first
+            end
+            unrelated = owned_pending.any? { |row| !existing || row["id"] != existing["id"] }
+            if unrelated
+              raise ProviderConflictingMatchesError,
+                "Authenticated reviewer has an unrelated pending review; no publication performed"
+            end
+            recovering = existing && existing["state"] == "PENDING"
+            if recovering && (!@pending_reuse || existing["comments_count"] != 0 ||
+                existing["dismissed"] || existing["stale"])
+              raise ProviderUnsupportedCapabilityError,
+                "This pending review cannot be safely completed with its accepted commit/content; pending is preserved"
+            end
+            mutated = false
+            disposition = existing ? :existing : :created
+            begin
+              current!(number, expected_head)
+              if !existing || recovering
+                pending_id = existing && existing["id"]
+                mutated = true
+                # Direct approval keeps the explicit reviewed commit. Never
+                # use a later pending-submit endpoint with implicit current HEAD.
+                existing = @request.call(:post, "pulls/#{number}/reviews",
+                  {"body" => sent_body, "commit_id" => expected_head, "event" => "APPROVE"})
+                row!(existing)
+                if pending_id && existing["id"] != pending_id
+                  raise ProviderUnknownOutcomeError, "Pending review identity changed during direct approval"
+                end
+              end
+              verifying = true
+              receipt(number: number, expected_head: expected_head, review_id: existing.fetch("id"),
+                disposition: disposition, expected_body: sent_body, actor: actor)
+            rescue Error => error
+              definitive_refusal = error.is_a?(ProviderAuthenticationError) ||
+                error.is_a?(ProviderUnsupportedCapabilityError)
+              raise unless mutated && (verifying || !definitive_refusal)
+
+              raise ProviderUnknownOutcomeError,
+                "Approval outcome unknown for #{@provider.server.name}/#{number}, head #{expected_head}, " \
+                "correlation #{correlation}: #{error.class.name.split('::').last}; reconcile before repeating"
+            end
+          end
+        rescue SystemCallError
+          raise ConfigError, "Cannot acquire the private approval session lock"
+        end
+
+        def read(number:, expected_head:, review_id:)
+          validate_input!(number, expected_head)
+          unless review_id.is_a?(Integer) && review_id.positive?
+            raise ArgumentError, "Approval review ID must be a positive integer"
+          end
+          receipt(number: number, expected_head: expected_head, review_id: review_id, disposition: :existing)
+        end
+
+        private
+
+        def validate_input!(number, head)
+          unless number.is_a?(Integer) && number.positive? && head.is_a?(String) && head.match?(SHA)
+            raise ArgumentError, "Approval requires a positive PR number and full lowercase head SHA"
+          end
+        end
+
+        def current!(number, head)
+          pr = @provider.pull_request(number: number)
+          unless pr.number == number && pr.server_name == @provider.server.name &&
+              pr.head_sha == head && pr.state == :open && pr.draft == false &&
+              Atoms::ServerUrl.match?(pr.base_repository_url, @provider.server.url)
+            raise ProviderExpectedHeadConflictError,
+              "Approval requires the selected open, ready PR at the expected head"
+          end
+          pr
+        end
+
+        def identity!(user)
+          unless user.is_a?(Hash) && user["id"].is_a?(Integer) && user["id"].positive? &&
+              user["login"].is_a?(String) && !user["login"].empty?
+            raise ProviderMalformedOutputError, "Malformed authenticated review identity"
+          end
+          [user["id"], user["login"]]
+        end
+
+        def deny_author!(pr, actor)
+          unless pr.author.is_a?(String) && !pr.author.empty?
+            raise ProviderMalformedOutputError, "PR author is unverified"
+          end
+          if pr.author.casecmp?(actor.last)
+            raise ProviderAuthenticationError, "PR author cannot approve own pull request"
+          end
+        end
+
+        def row!(row)
+          unless row.is_a?(Hash) && row["id"].is_a?(Integer) && row["id"].positive? &&
+              row["body"].is_a?(String) && row["state"].is_a?(String) &&
+              row["commit_id"].is_a?(String) && row["commit_id"].match?(SHA)
+            raise ProviderMalformedOutputError, "Malformed formal review evidence"
+          end
+          identity!(row["user"])
+          row
+        end
+
+        def reviews!(number)
+          rows = @list.call("pulls/#{number}/reviews")
+          raise ProviderMalformedOutputError, "Formal reviews are not a list" unless rows.is_a?(Array)
+          rows.each do |row|
+            unless row.is_a?(Hash) && row["id"].is_a?(Integer) && row["id"].positive? &&
+                row["body"].is_a?(String) && row["state"].is_a?(String)
+              raise ProviderMalformedOutputError, "Malformed formal review list entry"
+            end
+          end
+          if rows.map { |row| row["id"] }.uniq.length != rows.length
+            raise ProviderMalformedOutputError, "Duplicate formal review IDs"
+          end
+          rows
+        end
+
+        def receipt(number:, expected_head:, review_id:, disposition:, expected_body: nil, actor: nil)
+          pr = current!(number, expected_head)
+          rows = reviews!(number)
+          row = rows.find { |entry| entry["id"] == review_id }
+          raise ProviderIdentityMismatchError, "Formal approval was not found" unless row
+          row!(row)
+          actual_actor = identity!(row["user"])
+          deny_author!(pr, actual_actor)
+          marker = row["body"].match(MARKER)
+          content = marker && row["body"][0...marker.begin(0)]
+          latest = rows.select do |entry|
+            next false unless entry["user"].is_a?(Hash) && entry["user"]["id"] == actual_actor.first
+            next false unless %w[APPROVED CHANGES_REQUESTED REQUEST_CHANGES DISMISSED].include?(entry["state"])
+
+            row!(entry)
+            unless identity!(entry["user"]) == actual_actor
+              raise ProviderIdentityMismatchError, "Inconsistent identity in relevant formal review history"
+            end
+            true
+          end.max_by { |entry| entry["id"] }
+          unless marker && !content.strip.empty? && content.bytesize <= 64 * 1024 &&
+              Digest::SHA256.hexdigest(content) == marker[2] &&
+              row["state"] == "APPROVED" && row["commit_id"] == expected_head &&
+              !row["dismissed"] && !row["stale"] && (!@official || row["official"] == true) &&
+              (!latest || latest["id"] == row["id"]) && (!expected_body || row["body"] == expected_body) &&
+              (!actor || actor == actual_actor) && row["html_url"].is_a?(String) &&
+              row["html_url"].start_with?("#{pr.url}#")
+            raise ProviderIdentityMismatchError, "Review is not the effective exact-head formal approval"
+          end
+          current!(number, expected_head)
+          ProviderApprovalReceipt.new(provider: @provider.server.provider, server_name: @provider.server.name,
+            repository_url: @provider.server.url, pr_number: number, pr_url: pr.url,
+            head_sha: expected_head, reviewer_id: actual_actor.first, reviewer: actual_actor.last,
+            review_id: row["id"], review_url: row["html_url"], state: :approved, effective: true,
+            official: @official ? row["official"] : nil,
+            correlation: marker[1], evidence_sha256: marker[2], idempotency: disposition)
+        end
+      end
+    end
+  end
+end

data/lib/ace/git/version.rb

@@ -2,6 +2,6 @@
 
 module Ace
   module Git
-    VERSION = "0.30.0"
+    VERSION = "0.31.0"
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: ace-git
 version: !ruby/object:Gem::Version
-  version: 0.30.0
+  version: 0.31.0
 platform: ruby
 authors:
 - Michal Czyz
 bindir: exe
 cert_chain: []
-date: 2026-10-08 00:00:00.000000000 Z
+date: 2026-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ace-support-config
@@ -186,6 +186,7 @@ files:
 - lib/ace/git/providers.rb
 - lib/ace/git/providers/base.rb
 - lib/ace/git/providers/evidence.rb
+- lib/ace/git/providers/formal_approval.rb
 - lib/ace/git/resolved_server.rb
 - lib/ace/git/server_registry.rb
 - lib/ace/git/version.rb