From ef56336b2d05ec59de0c41697c6cd14f1531c550 Mon Sep 17 00:00:00 2001 From: NagyVikt Date: Fri, 8 May 2026 15:40:17 +0200 Subject: [PATCH] Route agent completion through Guardex finish Agents were seeing completion guidance as commit plus raw push plus ad hoc PR work, which can trip Codex policy approval for standalone network commands even though the repo has a Guardex finish flow for that lifecycle. This tightens the managed AGENTS policy and its setup regression so future installed guidance makes gx branch finish the explicit completion path. Constraint: Codex policy approval prompts can block standalone git push commands from agent sessions Rejected: Add more raw git push allowlist text | it preserves the fragmented path that caused the prompt Confidence: high Scope-risk: narrow Directive: Keep completion guidance centered on gx branch finish; do not reintroduce standalone git push or gh pr as the primary completion path Tested: rtk test node --test --test-name-pattern "install configures AGENTS managed policy block with GX contract wording" test/setup.test.js Tested: openspec validate agent-codex-codex-task-2026-05-08-15-30 --type change --strict Tested: openspec validate --specs Not-tested: full test/setup.test.js remains blocked by existing repo skill guard redirect and git worktree add --orphan environment failures Co-authored-by: OmX --- AGENTS.md | 2 +- .../.openspec.yaml | 2 ++ .../proposal.md | 14 ++++++++ .../spec.md | 9 +++++ .../tasks.md | 36 +++++++++++++++++++ templates/AGENTS.multiagent-safety.md | 2 +- test/setup.test.js | 3 +- 7 files changed, 65 insertions(+), 3 deletions(-) create mode 100644 openspec/changes/agent-codex-codex-task-2026-05-08-15-30/.openspec.yaml create mode 100644 openspec/changes/agent-codex-codex-task-2026-05-08-15-30/proposal.md create mode 100644 openspec/changes/agent-codex-codex-task-2026-05-08-15-30/specs/agent-codex-codex-task-2026-05-08-15-30/spec.md create mode 100644 openspec/changes/agent-codex-codex-task-2026-05-08-15-30/tasks.md diff --git a/AGENTS.md b/AGENTS.md index 09edc56..157ac67 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -648,7 +648,7 @@ Task is complete only when: If anything blocks, append a `BLOCKED:` note and stop. Do not half-finish. -OMX completion policy: when a task is done, the agent must commit the task changes, push the agent branch, and create/update a PR before considering the branch complete. +OMX completion policy: when a task is done, the agent must run `gx branch finish --branch "" --via-pr --wait-for-merge --cleanup` (or `gx finish --all`) instead of standalone `git push` / `gh pr` commands. The finish flow owns commit, push, PR creation/update, merge wait, and sandbox cleanup. ### Parallel safety diff --git a/openspec/changes/agent-codex-codex-task-2026-05-08-15-30/.openspec.yaml b/openspec/changes/agent-codex-codex-task-2026-05-08-15-30/.openspec.yaml new file mode 100644 index 0000000..054b8c0 --- /dev/null +++ b/openspec/changes/agent-codex-codex-task-2026-05-08-15-30/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-05-08 diff --git a/openspec/changes/agent-codex-codex-task-2026-05-08-15-30/proposal.md b/openspec/changes/agent-codex-codex-task-2026-05-08-15-30/proposal.md new file mode 100644 index 0000000..e236454 --- /dev/null +++ b/openspec/changes/agent-codex-codex-task-2026-05-08-15-30/proposal.md @@ -0,0 +1,14 @@ +## Why + +- Agents can interpret the completion contract as raw `git push` plus ad hoc PR operations, which triggers Codex policy approval prompts for publish steps even though Guardex already provides an approved finish flow. +- Completion guidance should make `gx branch finish ... --via-pr --wait-for-merge --cleanup` the explicit path so push, PR creation, merge wait, and cleanup happen under one repo-owned command. + +## What Changes + +- Update the managed AGENTS policy block and current repo AGENTS text to require the Guardex finish flow instead of standalone `git push` / `gh pr` commands. +- Update setup regression coverage so installed AGENTS guidance preserves this wording. + +## Impact + +- Affects agent-facing workflow guidance only; runtime finish behavior remains unchanged. +- Future `gx install` / `gx setup` managed-policy refreshes will keep agents on the Guardex finish path. diff --git a/openspec/changes/agent-codex-codex-task-2026-05-08-15-30/specs/agent-codex-codex-task-2026-05-08-15-30/spec.md b/openspec/changes/agent-codex-codex-task-2026-05-08-15-30/specs/agent-codex-codex-task-2026-05-08-15-30/spec.md new file mode 100644 index 0000000..e05e3ff --- /dev/null +++ b/openspec/changes/agent-codex-codex-task-2026-05-08-15-30/specs/agent-codex-codex-task-2026-05-08-15-30/spec.md @@ -0,0 +1,9 @@ +## ADDED Requirements + +### Requirement: Agent completion uses Guardex finish flow +Managed agent guidance SHALL instruct agents to complete work through `gx branch finish --branch "" --via-pr --wait-for-merge --cleanup` or `gx finish --all` instead of standalone `git push` / `gh pr` commands. + +#### Scenario: Completion policy avoids raw push prompts +- **WHEN** `gx install` writes the managed multi-agent policy block +- **THEN** the completion policy names the Guardex finish command as the required path +- **AND** the policy tells agents not to use standalone `git push` / `gh pr` commands for completion. diff --git a/openspec/changes/agent-codex-codex-task-2026-05-08-15-30/tasks.md b/openspec/changes/agent-codex-codex-task-2026-05-08-15-30/tasks.md new file mode 100644 index 0000000..b3c973f --- /dev/null +++ b/openspec/changes/agent-codex-codex-task-2026-05-08-15-30/tasks.md @@ -0,0 +1,36 @@ +## Definition of Done + +This change is complete only when **all** of the following are true: + +- Every checkbox below is checked. +- The agent branch reaches `MERGED` state on `origin` and the PR URL + state are recorded in the completion handoff. +- If any step blocks (test failure, conflict, ambiguous result), append a `BLOCKED:` line under section 4 explaining the blocker and **STOP**. Do not tick remaining cleanup boxes; do not silently skip the cleanup pipeline. + +## Handoff + +- Handoff: change=`agent-codex-codex-task-2026-05-08-15-30`; branch=`agent/codex/codex-task-2026-05-08-15-30`; scope=`TODO`; action=`continue this sandbox or finish cleanup after a usage-limit/manual takeover`. +- Copy prompt: Continue `agent-codex-codex-task-2026-05-08-15-30` on branch `agent/codex/codex-task-2026-05-08-15-30`. Work inside the existing sandbox, review `openspec/changes/agent-codex-codex-task-2026-05-08-15-30/tasks.md`, continue from the current state instead of creating a new sandbox, and when the work is done run `gx branch finish --branch agent/codex/codex-task-2026-05-08-15-30 --base main --via-pr --wait-for-merge --cleanup`. + +## 1. Specification + +- [x] 1.1 Finalize proposal scope and acceptance criteria for `agent-codex-codex-task-2026-05-08-15-30`. +- [x] 1.2 Define normative requirements in `specs/agent-codex-codex-task-2026-05-08-15-30/spec.md`. + +## 2. Implementation + +- [x] 2.1 Implement scoped behavior changes. +- [x] 2.2 Add/update focused regression coverage. + +## 3. Verification + +- [x] 3.1 Run targeted project verification commands. Evidence: `rtk test node --test --test-name-pattern "install configures AGENTS managed policy block with GX contract wording" test/setup.test.js` passed. +- [x] 3.2 Run `openspec validate agent-codex-codex-task-2026-05-08-15-30 --type change --strict`. Evidence: change is valid. +- [x] 3.3 Run `openspec validate --specs`. Evidence: exited 0 with "No items found to validate." + +Baseline note: full `rtk test node --test test/setup.test.js` still has 2 pre-existing failures: `repo skill guard blocks shell output redirect bypasses` and `setup refreshes initialized protected main through a sandbox and prunes it` (`git worktree add` lacks `--orphan` support in this environment). + +## 4. Cleanup (mandatory; run before claiming completion) + +- [ ] 4.1 Run the cleanup pipeline: `gx branch finish --branch agent/codex/codex-task-2026-05-08-15-30 --base main --via-pr --wait-for-merge --cleanup`. This handles commit -> push -> PR create -> merge wait -> worktree prune in one invocation. +- [ ] 4.2 Record the PR URL and final merge state (`MERGED`) in the completion handoff. +- [ ] 4.3 Confirm the sandbox worktree is gone (`git worktree list` no longer shows the agent path; `git branch -a` shows no surviving local/remote refs for the branch). diff --git a/templates/AGENTS.multiagent-safety.md b/templates/AGENTS.multiagent-safety.md index 9060f53..0af48dc 100644 --- a/templates/AGENTS.multiagent-safety.md +++ b/templates/AGENTS.multiagent-safety.md @@ -315,7 +315,7 @@ Task is complete only when: If anything blocks, append a `BLOCKED:` note and stop. Do not half-finish. -OMX completion policy: when a task is done, the agent must commit the task changes, push the agent branch, and create/update a PR before considering the branch complete. +OMX completion policy: when a task is done, the agent must run `gx branch finish --branch "" --via-pr --wait-for-merge --cleanup` (or `gx finish --all`) instead of standalone `git push` / `gh pr` commands. The finish flow owns commit, push, PR creation/update, merge wait, and sandbox cleanup. ### Parallel safety diff --git a/test/setup.test.js b/test/setup.test.js index 442c755..f51f7ca 100644 --- a/test/setup.test.js +++ b/test/setup.test.js @@ -868,8 +868,9 @@ test('install configures AGENTS managed policy block with GX contract wording', assert.match(agentsContent, /## Multi-Agent Execution Contract: Guardex \+ Colony/); assert.match( agentsContent, - /OMX completion policy: when a task is done, the agent must commit the task changes, push the agent branch, and create\/update a PR/, + /OMX completion policy: when a task is done, the agent must run `gx branch finish --branch "" --via-pr --wait-for-merge --cleanup`/, ); + assert.match(agentsContent, /instead of standalone `git push` \/ `gh pr` commands/); assert.match(agentsContent, /### Colony coordination loop/); assert.match(agentsContent, /### Token \/ context budget/); assert.match(agentsContent, /### Caveman style/);