Merge pull request #3 from SuPuHe/feature/unified-agent-workflow

chore: unify agent review workflow

Author: kapustazh

.agent/AGENTS.md

@@ -13,6 +13,23 @@ infrastructure, data, and model agent working in this repository.
 If instructions conflict, stop and surface the conflict. Do not silently choose
 the most convenient interpretation.
 
+## Tool neutrality
+
+- Shared policy must remain independent of agent vendor, model, operating
+  system, and editor.
+- Codex, Claude, Antigravity, Cursor, or another capable agent may implement or
+  review a change.
+- Tool-specific repository files must be thin adapters pointing to the
+  canonical `AGENTS.md` and `.agent/` documents. Do not copy policy into them.
+- Personal prompts, permissions, model choices, and machine-specific commands
+  belong in ignored local files.
+- A gate reviewer must use a fresh read-only session, must not be the
+  implementation agent, and must identify its tool and platform-reported model
+  in the verdict. Record `not exposed by platform` when no model identifier is
+  available.
+- Different tools may perform Gate A and Gate B. Both must use the canonical
+  prompts and required verdict format.
+
 ## Before making changes
 
 - Read the task, acceptance criteria, relevant code, and related documentation.
@@ -84,15 +101,17 @@ blocker for the user.
 Follow `.agent/MILESTONE_IMPLEMENTATION_LOOP.md` exactly.
 
 - Review Gate A is a fresh, independent review of the complete workspace change
-  before the draft pull request is created. It evaluates the diff against the target
-  base branch (`develop`), covering acceptance criteria, correctness, edge cases,
-  security, and test coverage.
+  before the draft pull request is created. It evaluates the staged candidate
+  tree against the exact target base SHA, covering acceptance criteria,
+  correctness, edge cases, security, and test coverage.
 - Review Gate B is a second fresh, independent review after the draft PR exists
   and required CI is green. Gate B is bound to the exact PR head commit SHA and verifies
   PR readiness, diff integrity, and check results.
 - The implementation agent must not act as its own independent reviewer. Reviewers
   must be invoked in an independent session using `.agent/review-prompts/implementation-review.md`
   for Gate A and `.agent/review-prompts/draft-pr-review.md` for Gate B.
+- No specific review vendor or model is mandatory unless a milestone explicitly
+  requires one. Missing reviewer tool or reviewed Git identity is a failure.
 - Do not reuse or resume the Gate A session for Gate B.
 - Any content change after Gate A invalidates Gate A.
 - Any commit after Gate B invalidates Gate B.

.agent/MILESTONE_IMPLEMENTATION_LOOP.md

@@ -44,12 +44,15 @@ objective, testable acceptance criteria.
    ```bash
    git checkout develop
    git pull origin develop
-   git checkout -b milestone/<id>-<name>
+   git checkout -b feature/<name>
    ```
+   Use `fix/<name>` or `milestone/<id>-<name>` when appropriate.
 2. Make the smallest coherent change satisfying the milestone.
 3. Add or update tests and documentation alongside code.
 4. Inspect the full workspace diff (`git status`, `git diff`, untracked files)
    for scope drift, generated files, secrets, and unrelated edits.
+5. Stage only the complete intended candidate. Leave no intended change
+   unstaged or untracked before Gate A.
 
 The implementation may remain uncommitted through Gate A. Do not push a branch
 or create a PR yet.
@@ -71,10 +74,26 @@ Exit gate: All applicable local checks pass for the current workspace content.
 
 ## Phase 4 - Review Gate A: workspace implementation review
 
-Run an independent review session using `.agent/review-prompts/implementation-review.md`.
+Refresh the base, then copy the two printed SHAs into the review evidence:
+
+```bash
+git fetch origin develop
+git rev-parse origin/develop
+git write-tree
+git diff --cached <recorded-base-sha>
+```
+
+`<recorded-base-sha>` is the immutable output from `git rev-parse
+origin/develop`, not the mutable remote-tracking ref itself.
+
+Run a fresh, read-only independent review session using
+`.agent/review-prompts/implementation-review.md`. Any capable review tool may be
+used. Record its tool and platform-reported model name.
+If the platform does not expose a model identifier, record
+`not exposed by platform`.
 
 The reviewer evaluates:
-- Complete workspace diff against `develop`;
+- Complete staged candidate tree against the recorded `develop` SHA;
 - Acceptance criteria coverage;
 - Edge cases, error handling, regressions;
 - Security, secrets, and licensing;
@@ -89,26 +108,28 @@ Gate decision:
 On `FAIL`, resolve every blocking finding, rerun local validation, and repeat Gate A
 in a fresh session.
 
-Exit gate: Gate A returns an explicit `VERDICT: PASS`.
+Exit gate: Gate A returns an explicit `VERDICT: PASS` containing reviewer tool,
+model, base SHA, and candidate tree SHA.
 
 ## Phase 5 - Commit and create draft pull request
 
 Only after Gate A passes:
 
-1. Stage only the reviewed milestone files and inspect the staged diff.
-2. Commit the reviewed change.
-3. Push the branch to origin:
+1. Confirm `git write-tree` still equals the reviewed candidate tree SHA.
+2. Commit the reviewed staged change without modifying its content.
+3. Confirm `git rev-parse "HEAD^{tree}"` equals the reviewed candidate tree SHA.
+4. Push the branch to origin:
    ```bash
-   git push -u origin milestone/<id>-<name>
+   git push -u origin HEAD
    ```
-4. Create a **draft** pull request against `develop`.
-5. Fill out `.github/PULL_REQUEST_TEMPLATE.md` with:
+5. Create a **draft** pull request against `develop`.
+6. Fill out `.github/PULL_REQUEST_TEMPLATE.md` with:
    - Milestone outcome & scope;
    - Acceptance criteria checklist;
    - Risk assessment;
    - Validation evidence;
    - Review Gate A verdict and reviewer evidence.
-6. Keep the pull request in draft state.
+7. Keep the pull request in draft state.
 
 Exit gate: The draft PR is created against `develop` with complete Gate A evidence.
 
@@ -129,11 +150,16 @@ Exit gate: All required status checks are green for the exact PR head commit.
 Gate B runs in an independent reviewer session after CI passes, evaluating the draft PR
 using `.agent/review-prompts/draft-pr-review.md`.
 
+Gate B may use any capable review tool, including a different tool from Gate A.
+It must run in a fresh read-only session and record its tool and
+platform-reported model, or `not exposed by platform`.
+
 The reviewer independently inspects:
 - PR title, description, and diff against `develop`;
 - Commits and file changes;
 - Required CI status and check logs;
 - Gate A evidence and resolution of earlier findings;
+- Equality of the PR head tree and Gate A candidate tree;
 - Merge readiness and residual risks.
 
 On `FAIL`, return to Phase 2. Any content change requires rerunning Phases 3 through 7.

.agent/milestones/M0_UNIFIED_AGENT_WORKFLOW.md

@@ -0,0 +1,43 @@
+# M0: Unified agent workflow
+
+## Outcome
+
+Every contributor follows one repository workflow while remaining free to use
+Codex, Claude, Antigravity, Cursor, or another capable agent.
+
+## Acceptance criteria
+
+- `AGENTS.md` and `.agent/` remain the only canonical shared policy.
+- Tool-specific files point to canonical policy instead of copying it.
+- Personal agent configuration is ignored.
+- Gate A records reviewer, available model identity, exact base SHA, and
+  candidate tree SHA.
+- Gate B records reviewer, available model identity, exact PR head SHA, and
+  equality with the Gate A candidate tree after required CI.
+- Pull requests run a minimal `Agent policy` status check.
+- Feature work targets `develop`; humans retain merge authority.
+
+## Scope
+
+In scope: shared policy, portable Git evidence, review prompts, PR evidence
+fields, Antigravity adapter, ignore rules, and minimal policy CI.
+
+Out of scope: product implementation, selecting a mandatory review provider,
+Windows-only automation, branch-protection mutation, and merging existing
+`agents-setup` or Claude adapter branches.
+
+## Validation
+
+- Inspect complete diff against the recorded immutable `develop` base SHA.
+- Confirm Markdown links and referenced paths exist.
+- Confirm only intended files are staged.
+- Run the policy workflow checks locally where practical.
+- Run independent Gate A before commit and Gate B after draft PR checks.
+
+## Risks and rollback
+
+Risk: a tool may not auto-load `AGENTS.md`. Thin adapters handle known tools;
+the PR template and human review expose missing gate evidence.
+
+Rollback: revert this documentation-only commit. No runtime or data migration
+exists.

.agent/review-prompts/draft-pr-review.md

@@ -13,7 +13,9 @@ This must be a fresh review. Do not rely on memory or a resumed Gate A session.
 - Verify draft pull request number, base branch (`develop`), head branch, and head SHA.
 - Read the PR description, full GitHub PR diff, commits, required status checks,
   and Review Gate A evidence.
-- Confirm all evidence refers to the exact current PR head SHA.
+- Confirm CI and Gate B evidence refer to the exact current PR head SHA.
+- Gate A evidence is bound to its base SHA and candidate tree SHA. Verify the
+  current PR head tree equals the Gate A candidate tree before accepting it.
 
 ## Required analysis
 
@@ -24,7 +26,7 @@ Independently evaluate:
 - Whether CI covers changed behavior and all required checks are green;
 - Whether documentation, config, and migration paths are complete;
 - Whether the PR description provides sufficient detail for human review;
-- Whether any commit made after Gate A invalidates its conclusions;
+- Whether the current PR head tree and base still match Gate A evidence;
 - Whether the PR is safe to mark ready for human review (not whether it should be merged).
 
 ## Verdict standard
@@ -36,9 +38,13 @@ Use this exact structure:
 
 ```text
 VERDICT: PASS | FAIL
+REVIEWER_TOOL: <tool or agent system>
+REVIEWER_MODEL: <exact model name, or not exposed by platform>
 PR: <number and URL>
 REVIEWED_HEAD: <full SHA>
-REVIEWED_BASE: develop
+REVIEWED_HEAD_TREE: <full `HEAD^{tree}` SHA>
+REVIEWED_BASE: develop (<exact base SHA>)
+GATE_A_TREE: <candidate tree SHA; must equal REVIEWED_HEAD_TREE>
 
 BLOCKING_FINDINGS:
 - <severity> <file:line or subsystem> - <problem, impact, and required fix>

.agent/review-prompts/implementation-review.md

@@ -8,8 +8,9 @@ Do not attempt to fix a finding yourself. Report findings and return the require
 
 - Read the repository `AGENTS.md` and `.agent/AGENTS.md`.
 - Target base branch: `develop` (or designated milestone base).
-- Review the complete workspace diff against the base, including committed,
-  staged, unstaged, and untracked files.
+- Review the complete staged candidate tree against the recorded base SHA.
+- Verify `git status` contains no intended unstaged or untracked change omitted
+  from the candidate.
 - Read the milestone acceptance criteria, requirements, and relevant docs.
 
 ## Required analysis
@@ -33,8 +34,11 @@ Use this exact structure:
 
 ```text
 VERDICT: PASS | FAIL
-REVIEWED_TARGET: <branch or commit SHA>
-REVIEWED_BASE: develop (<base SHA>)
+REVIEWER_TOOL: <tool or agent system>
+REVIEWER_MODEL: <exact model name, or not exposed by platform>
+REVIEWED_TARGET: <branch>
+REVIEWED_BASE: develop (<exact base SHA>)
+REVIEWED_TREE: <exact candidate tree SHA>
 
 BLOCKING_FINDINGS:
 - <severity> <file:line or subsystem> - <problem, impact, and required fix>

.agents/rules/repository-policy.md

@@ -0,0 +1,11 @@
+# OneShot repository policy
+
+Load and follow these canonical repository policies before planning, editing,
+reviewing, committing, pushing, or opening a pull request:
+
+@../../AGENTS.md
+@../../.agent/AGENTS.md
+@../../.agent/MILESTONE_IMPLEMENTATION_LOOP.md
+
+This file is an Antigravity adapter only. Personal rules belong in local
+ignored files and must not override repository policy.

.antigravity/README.md

@@ -1,17 +1,9 @@
-# Antigravity CLI Review Configuration
+# Antigravity adapter
 
-This directory contains configuration, prompts, and documentation for personal code review workflows using Antigravity CLI (gy).
+Antigravity loads `.agents/rules/repository-policy.md`, which points to the
+canonical repository policy and implementation loop.
 
-## Purpose
+Use the shared prompts in `.agent/review-prompts/` for Gate A and Gate B.
+Personal Antigravity configuration and review logs stay local.
 
-- Allows developers to run independent Review Gate A and Review Gate B evaluations using Antigravity CLI without conflicting with other team members' local review tooling.
-- Keeps personal Antigravity review logs and configurations decoupled from core repository policies.
-
-## Review Gates
-
-- **Gate A (Pre-PR Workspace Review)**:
-  Run in Antigravity CLI using .agent/review-prompts/implementation-review.md.
-  Evaluates workspace diff against develop before draft PR creation.
-- **Gate B (Post-PR Draft Review)**:
-  Run in Antigravity CLI using .agent/review-prompts/draft-pr-review.md.
-  Evaluates draft PR head commit, status checks, and diff against develop.
+Reference: https://www.antigravity.google/docs/rules-workflows/

.antigravity/review.md

@@ -18,12 +18,22 @@
    - Human review and approval.
 4. Agents must never merge pull requests. Final approval and merging is performed exclusively by the user.
 
+## Agent review evidence
+
+Canonical agent and review rules live in `AGENTS.md`, `.agent/AGENTS.md`, and
+`.agent/MILESTONE_IMPLEMENTATION_LOOP.md`. Pull requests record their required
+evidence through `.github/PULL_REQUEST_TEMPLATE.md`.
+
+GitHub status checks and branch protection enforce merge readiness. Local agent
+instructions alone are not enforcement.
+
 ## Required status checks
 
-As CI workflows are established in `.github/workflows/`, branch protection rules for `develop` and `main` must enforce:
-- Linting and static analysis;
-- Automated test suites;
-- Build / compilation checks.
+The initial required check for `develop` and `main` is:
+
+- `Agent policy`.
+
+Add lint, test, and build checks as executable project components appear.
 
 ## Protection rules
 

.github/BRANCH_POLICY.md

@@ -33,22 +33,27 @@
 
 ## Review Gate A - implementation
 
-- Reviewed head / commit:
-- Reviewer / model:
+- Reviewed base SHA:
+- Reviewed candidate tree SHA:
+- Reviewer tool:
+- Reviewer model:
 - Verdict:
 - Blocking findings resolved:
 - Evidence / review summary:
 
 ## Required CI
 
-- [ ] Lint and static analysis
-- [ ] Automated tests
-- [ ] Build validation
+- [ ] `Agent policy`
+- [ ] All project checks applicable to this change
+- [ ] No required check is missing, pending, skipped, or failing
 
 ## Review Gate B - draft PR
 
 - Reviewed PR head SHA:
-- Reviewer / model:
+- Reviewed PR head tree SHA:
+- Matching Gate A candidate tree SHA:
+- Reviewer tool:
+- Reviewer model:
 - Verdict:
 - Blocking findings resolved:
 - Evidence / review summary: