agex-cli 0.27.0__tar.gz → 0.28.0__tar.gz

agex_cli-0.28.0/.devague/frames/devex-now-turns-a-push-into-continuous-pr-manageme.json

@@ -0,0 +1,259 @@
+{
+  "slug": "devex-now-turns-a-push-into-continuous-pr-manageme",
+  "title": "devex now turns a push into continuous PR management: when you push commits to a branch that already has an open PR, devex automatically enters the same review-readiness wait a new PR gets (the ~3-minute poll), so follow-up commits get triaged without a manual step \u2014 and a push to a branch with no PR stays an ordinary push.",
+  "schema_version": 1,
+  "status": "exported",
+  "created": "2026-05-29T11:17:22Z",
+  "updated": "2026-05-29T11:31:35Z",
+  "claims": [
+    {
+      "id": "c1",
+      "kind": "announcement",
+      "text": "devex now turns a push into continuous PR management: when you push commits to a branch that already has an open PR, devex automatically enters the same review-readiness wait a new PR gets (the ~3-minute poll), so follow-up commits get triaged without a manual step \u2014 and a push to a branch with no PR stays an ordinary push.",
+      "origin": "user",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h4",
+          "text": "Shipped behavior is exactly: push current branch; if it has an open PR, enter the new-PR-style ~180s readiness wait and render the delta; else plain push + a notice.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [
+        {
+          "id": "q3",
+          "text": "Does the command also 'git commit' (commit-push) or only 'git push' already-committed work? The user is unsure ('commit-pushing / just pushing').",
+          "resolved": true,
+          "blocking": false
+        }
+      ],
+      "links": []
+    },
+    {
+      "id": "c2",
+      "kind": "audience",
+      "text": "An agent (or human via an agent) running devex inside a repo mid-PR, who has just committed follow-up changes on a branch that already has an open PR and wants CI/review feedback picked up automatically.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h5",
+          "text": "The primary caller is an agent in an automated PR loop; the command needs no interactive input to choose the managed-vs-plain path.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c3",
+      "kind": "after_state",
+      "text": "Pushing follow-up commits to a branch with an open PR automatically enters the same review-readiness wait a new PR gets (~3-minute poll), with no separate manual 'pr await' / 'pr read --wait' step.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h6",
+          "text": "Post-push triage takes zero extra commands: the wait + delta render are part of the single 'devex push' invocation.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [
+        {
+          "id": "q2",
+          "text": "Is the wait blocking the agent session (like --delayed-read) or detached (like --detached-await/await --detach)? Continuous management argues for detached + later --check.",
+          "resolved": true,
+          "blocking": false
+        }
+      ],
+      "links": []
+    },
+    {
+      "id": "c4",
+      "kind": "before_state",
+      "text": "Today there is no push command. After pushing, the agent must remember to manually run 'pr await' / 'pr read --wait' to re-enter triage \u2014 easy to forget, so continuous PR management silently breaks.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h7",
+          "text": "Verified today: 'devex pr' has no push subcommand and no top-level push exists; re-entering triage requires a manual 'pr await' / 'pr read --wait'.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c5",
+      "kind": "why_it_matters",
+      "text": "Continuous PR management: every push, like every new PR, deterministically lands the agent back in the triage loop instead of leaving fresh CI/Sonar/review feedback unwatched.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h8",
+          "text": "Determinism: identical branch/PR state always routes to the same path (managed vs plain); no backend or branch auto-detection.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c6",
+      "kind": "success_signal",
+      "text": "After a push on a PR branch, the agent ends up holding the post-push review delta (CI + Sonar + threads) without issuing a second command.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h9",
+          "text": "Observable: one 'devex push' on a PR branch ends with the post-push CI/Sonar/threads delta on stdout, exit code reflecting the quality gate.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c7",
+      "kind": "boundary",
+      "text": "Not a general git porcelain: the push path is the minimum to land commits on the remote; devex does not grow into a git front-end (no rebase/merge/stash/branch management).",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h10",
+          "text": "Scope cap: the only git mutation devex performs is 'git push' of the current branch \u2014 no rebase/merge/stash/branch/commit.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c8",
+      "kind": "non_goal",
+      "text": "When the branch has no open PR, devex does NOT open one \u2014 that stays an explicit 'pr open'. The push case with no PR is out of the PR-management path.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c9",
+      "kind": "requirement",
+      "text": "The command must detect whether the current branch has an open PR (via gh) BEFORE deciding whether to enter the wait \u2014 the PR-management path is gated on PR existence, never auto-detected away from the user's branch.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h1",
+          "text": "Open-PR detection is a single 'gh pr view --json' style call on the current branch; no PR => exit 0 with a plain-push (or notice) path, never an error.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c10",
+      "kind": "requirement",
+      "text": "The default post-push wait is ~180s (3 minutes), matching 'pr open --delayed-read' (pr read --wait 180), not pr await's 1800s default \u2014 overridable via a flag.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h2",
+          "text": "The 180s default is exposed as an overridable flag (e.g. --max-wait) and documented as matching the new-PR delayed read.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c11",
+      "kind": "decision",
+      "text": "The command lives under the existing 'pr' namespace as 'devex pr push' (continuous PR management is a pr concern), rather than a top-level 'devex push'.",
+      "origin": "llm",
+      "status": "rejected",
+      "honesty_conditions": [],
+      "hard_questions": [
+        {
+          "id": "q1",
+          "text": "risk: Naming as 'pr push' is odd when no PR exists (you'd 'pr push' a branch that has no PR) \u2014 top-level 'devex push' may read better for the plain-push case.",
+          "resolved": true,
+          "blocking": false
+        }
+      ],
+      "links": []
+    },
+    {
+      "id": "c12",
+      "kind": "assumption",
+      "text": "It reuses the existing readiness machinery \u2014 pr await --detach/--check and/or pr read --wait \u2014 rather than introducing a second poller implementation.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c13",
+      "kind": "requirement",
+      "text": "Performing 'git push' of the current branch is a NEW class of side effect for devex (push-only; no commit); it requires an explicit carve-out added to design-invariant #4, alongside the existing pr-namespace network/sleep exceptions.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [
+        {
+          "id": "h3",
+          "text": "design-invariant #4 in CLAUDE.md is amended to name 'git push' as an allowed side effect of 'devex push', with the same explicitness as the existing gh/sleep carve-out \u2014 otherwise the feature violates a non-negotiable invariant.",
+          "status": "confirmed"
+        }
+      ],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c14",
+      "kind": "decision",
+      "text": "Top-level 'devex push' (not 'devex pr push'): reads naturally for the no-PR 'just push' case and conditionally enters PR management when an open PR exists.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c15",
+      "kind": "decision",
+      "text": "Push-only: pushes already-committed work; devex does NOT stage or commit. Commit-push is out of scope for v0.1.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    },
+    {
+      "id": "c16",
+      "kind": "decision",
+      "text": "After-push wait is BLOCKING ~180s (mirrors 'pr open --delayed-read' = 'pr read --wait 180'), not detached; --max-wait overrides. Resolves q2.",
+      "origin": "llm",
+      "status": "confirmed",
+      "honesty_conditions": [],
+      "hard_questions": [],
+      "links": []
+    }
+  ],
+  "open_vagueness": [
+    {
+      "id": "v1",
+      "text": "RESOLVED (push-only, c15): commit-push (stage+commit) is out of scope for v0.1; 'devex push' strictly pushes already-committed work.",
+      "kind": "out_of_scope",
+      "claim_id": "c15"
+    }
+  ]
+}

agex_cli-0.28.0/.devague/plans/devex-now-turns-a-push-into-continuous-pr-manageme.json

@@ -0,0 +1,216 @@
+{
+  "slug": "devex-now-turns-a-push-into-continuous-pr-manageme",
+  "title": "devex now turns a push into continuous PR management: when you push commits to a branch that already has an open PR, devex automatically enters the same review-readiness wait a new PR gets (the ~3-minute poll), so follow-up commits get triaged without a manual step \u2014 and a push to a branch with no PR stays an ordinary push.",
+  "frame_slug": "devex-now-turns-a-push-into-continuous-pr-manageme",
+  "schema_version": 1,
+  "status": "exported",
+  "created": "2026-05-29T11:35:28Z",
+  "updated": "2026-05-29T11:52:00Z",
+  "targets": [
+    {
+      "id": "c1",
+      "kind": "announcement",
+      "text": "devex now turns a push into continuous PR management: when you push commits to a branch that already has an open PR, devex automatically enters the same review-readiness wait a new PR gets (the ~3-minute poll), so follow-up commits get triaged without a manual step \u2014 and a push to a branch with no PR stays an ordinary push."
+    },
+    {
+      "id": "h4",
+      "kind": "honesty",
+      "text": "Shipped behavior is exactly: push current branch; if it has an open PR, enter the new-PR-style ~180s readiness wait and render the delta; else plain push + a notice."
+    },
+    {
+      "id": "c2",
+      "kind": "audience",
+      "text": "An agent (or human via an agent) running devex inside a repo mid-PR, who has just committed follow-up changes on a branch that already has an open PR and wants CI/review feedback picked up automatically."
+    },
+    {
+      "id": "h5",
+      "kind": "honesty",
+      "text": "The primary caller is an agent in an automated PR loop; the command needs no interactive input to choose the managed-vs-plain path."
+    },
+    {
+      "id": "c3",
+      "kind": "after_state",
+      "text": "Pushing follow-up commits to a branch with an open PR automatically enters the same review-readiness wait a new PR gets (~3-minute poll), with no separate manual 'pr await' / 'pr read --wait' step."
+    },
+    {
+      "id": "h6",
+      "kind": "honesty",
+      "text": "Post-push triage takes zero extra commands: the wait + delta render are part of the single 'devex push' invocation."
+    },
+    {
+      "id": "c4",
+      "kind": "before_state",
+      "text": "Today there is no push command. After pushing, the agent must remember to manually run 'pr await' / 'pr read --wait' to re-enter triage \u2014 easy to forget, so continuous PR management silently breaks."
+    },
+    {
+      "id": "h7",
+      "kind": "honesty",
+      "text": "Verified today: 'devex pr' has no push subcommand and no top-level push exists; re-entering triage requires a manual 'pr await' / 'pr read --wait'."
+    },
+    {
+      "id": "c5",
+      "kind": "why_it_matters",
+      "text": "Continuous PR management: every push, like every new PR, deterministically lands the agent back in the triage loop instead of leaving fresh CI/Sonar/review feedback unwatched."
+    },
+    {
+      "id": "h8",
+      "kind": "honesty",
+      "text": "Determinism: identical branch/PR state always routes to the same path (managed vs plain); no backend or branch auto-detection."
+    },
+    {
+      "id": "c6",
+      "kind": "success_signal",
+      "text": "After a push on a PR branch, the agent ends up holding the post-push review delta (CI + Sonar + threads) without issuing a second command."
+    },
+    {
+      "id": "h9",
+      "kind": "honesty",
+      "text": "Observable: one 'devex push' on a PR branch ends with the post-push CI/Sonar/threads delta on stdout, exit code reflecting the quality gate."
+    },
+    {
+      "id": "c7",
+      "kind": "boundary",
+      "text": "Not a general git porcelain: the push path is the minimum to land commits on the remote; devex does not grow into a git front-end (no rebase/merge/stash/branch management)."
+    },
+    {
+      "id": "h10",
+      "kind": "honesty",
+      "text": "Scope cap: the only git mutation devex performs is 'git push' of the current branch \u2014 no rebase/merge/stash/branch/commit."
+    },
+    {
+      "id": "c9",
+      "kind": "requirement",
+      "text": "The command must detect whether the current branch has an open PR (via gh) BEFORE deciding whether to enter the wait \u2014 the PR-management path is gated on PR existence, never auto-detected away from the user's branch."
+    },
+    {
+      "id": "h1",
+      "kind": "honesty",
+      "text": "Open-PR detection is a single 'gh pr view --json' style call on the current branch; no PR => exit 0 with a plain-push (or notice) path, never an error."
+    },
+    {
+      "id": "c10",
+      "kind": "requirement",
+      "text": "The default post-push wait is ~180s (3 minutes), matching 'pr open --delayed-read' (pr read --wait 180), not pr await's 1800s default \u2014 overridable via a flag."
+    },
+    {
+      "id": "h2",
+      "kind": "honesty",
+      "text": "The 180s default is exposed as an overridable flag (e.g. --max-wait) and documented as matching the new-PR delayed read."
+    },
+    {
+      "id": "c13",
+      "kind": "requirement",
+      "text": "Performing 'git push' of the current branch is a NEW class of side effect for devex (push-only; no commit); it requires an explicit carve-out added to design-invariant #4, alongside the existing pr-namespace network/sleep exceptions."
+    },
+    {
+      "id": "h3",
+      "kind": "honesty",
+      "text": "design-invariant #4 in CLAUDE.md is amended to name 'git push' as an allowed side effect of 'devex push', with the same explicitness as the existing gh/sleep carve-out \u2014 otherwise the feature violates a non-negotiable invariant."
+    }
+  ],
+  "tasks": [
+    {
+      "id": "t1",
+      "summary": "core/github.py: add git_push() and current_branch_pr() primitives (push-only; single gh pr view for PR detection)",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "git_push() runs exactly 'git push' of the current branch and nothing else (no commit/rebase/merge/stash/branch); unit test mocks the subprocess, asserts the git argv, and asserts a push failure surfaces as a raised/non-zero error.",
+        "current_branch_pr() returns the open PR number for the current branch via a single 'gh pr view --json' call, or None when there is no PR \u2014 never raises on the no-PR case; unit test mocks gh for both branches."
+      ],
+      "deps": [],
+      "covers": [
+        "c9",
+        "h1",
+        "c7",
+        "h10",
+        "c13"
+      ]
+    },
+    {
+      "id": "t2",
+      "summary": "docs: amend design-invariant #4 in CLAUDE.md to allow 'git push' as a 'devex push' side effect",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "design-invariant #4 in CLAUDE.md names 'git push' (push-only) as an allowed side effect of 'devex push', listed alongside the existing pr-namespace gh/sleep carve-outs; the side-effects list and the prose are mutually consistent (no other invariant weakened)."
+      ],
+      "deps": [],
+      "covers": [
+        "c13",
+        "h3"
+      ]
+    },
+    {
+      "id": "t3",
+      "summary": "commands/push/: devex push command \u2014 git_push, detect open PR, route to blocking ~180s wait+delta (PR exists) or plain push + notice (no PR)",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "With an open PR on the current branch, 'devex push' calls git_push then enters the existing pr read/await wait (default 180s) and renders the CI/Sonar/threads delta in ONE invocation; integration test (gh+git mocked) asserts no second command and the delta on stdout.",
+        "With no open PR, 'devex push' calls git_push then prints the deterministic 'no PR on this branch \u2014 open one with devex pr open' notice and exits 0; test asserts exit 0, the notice text, and that NO wait occurs.",
+        "Routing is deterministic on (current branch, PR-exists) with no backend/branch auto-detection \u2014 same inputs always select the same path (test).",
+        "On the managed path the exit code reflects the post-wait quality gate (non-zero on gate ERROR / unresolved threads), mirroring pr await (test)."
+      ],
+      "deps": [
+        "t1"
+      ],
+      "covers": [
+        "c1",
+        "h4",
+        "c3",
+        "h6",
+        "c5",
+        "h8",
+        "c6",
+        "h9"
+      ]
+    },
+    {
+      "id": "t4",
+      "summary": "cli.py: register top-level 'devex push' subcommand with --max-wait (default 180) and --agent",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "'devex --help' lists 'push'; 'devex push --help' shows --max-wait (default 180) and --agent; parsing dispatches to the push command entry (test).",
+        "--max-wait overrides the 180s default and is threaded into the wait; the default equals pr open --delayed-read's 180 (test asserts the value reaches the wait call).",
+        "The command takes no interactive input \u2014 all inputs arrive via argv/flags; runs non-interactively to completion (test)."
+      ],
+      "deps": [
+        "t3"
+      ],
+      "covers": [
+        "c4",
+        "h7",
+        "c10",
+        "h2",
+        "c2",
+        "h5"
+      ]
+    },
+    {
+      "id": "t5",
+      "summary": "commands/push/assets/backends/{claude-code,codex,copilot,acp}.yaml: per-backend next-step phrasing for the no-PR notice and the post-wait delta",
+      "origin": "llm",
+      "status": "confirmed",
+      "acceptance_criteria": [
+        "All four backends have a push asset with deterministic next-step phrasing for both the no-PR notice and the post-wait delta; test asserts all four load and render with no StrictUndefined errors (all-backends rule)."
+      ],
+      "deps": [
+        "t3"
+      ],
+      "covers": [
+        "c2",
+        "h5"
+      ]
+    }
+  ],
+  "risks": [
+    {
+      "id": "r1",
+      "text": "Reusing pr read/await's wait+delta from the new command (t3) may need a shared helper extracted out of commands/pr/scripts if the logic isn't cleanly importable \u2014 could widen t3's file scope into commands/pr.",
+      "kind": "unknown_nonblocking",
+      "task_id": "t3"
+    }
+  ]
+}

{agex_cli-0.27.0 → agex_cli-0.28.0}/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.28.0] - 2026-05-29
+
+### Added
+
+- `devex push` — a top-level command that pushes the current branch, then enters continuous PR management: if the branch has an open PR it runs the same gate-aware readiness wait `pr await` does (default 180s, `--max-wait` overrides) and renders the CI/SonarCloud/threads delta in one invocation; with no open PR it does a plain push and prints a deterministic notice pointing at `pr open`. Push-only (never stages or commits). Per-backend next-step phrasing for all four backends.
+
+### Changed
+
+- design-invariant #4 now names `git push` (push-only) as an allowed side effect of `devex push`, alongside the existing pr-namespace gh/sleep carve-outs.
+- `core/github.py` gains `git_push()` and `current_branch_pr()` helpers.
+
 ## [0.27.0] - 2026-05-29
 
 ### Added

{agex_cli-0.27.0 → agex_cli-0.28.0}/CLAUDE.md

@@ -19,7 +19,7 @@ Read the spec before any non-trivial change — the design invariants below are
 1. **Zero LLM calls inside devex.** All output is deterministic markdown from Jinja templates + Python.
 2. **Markdown is the only output format.** No `--json` flag.
 3. **`--agent <backend>` is required** on backend-sensitive commands. The CLI never auto-detects.
-4. **Side effects only in** `gamify`, `gamify --uninstall`, `hook write`, `pr open`, `pr reply`, `pr review`, `pr read` (journal writes), `pr await` (journal + `--detach` marker writes under `.devex/data/pr/<pr>/` and the detached poller subprocess), and first-run `.devex/` init. Everything else is read-only. The `devex pr` namespace allows scoped network I/O (via `gh`), bounded `--wait` sleep, and — for `pr await --detach` — a detached background process that pays that sleep outside the agent session; a deliberate carve-out from the no-network/no-sleep invariants.
+4. **Side effects only in** `gamify`, `gamify --uninstall`, `hook write`, `pr open`, `pr reply`, `pr review`, `pr read` (journal writes), `pr await` (journal + `--detach` marker writes under `.devex/data/pr/<pr>/` and the detached poller subprocess), `push` (see below), and first-run `.devex/` init. Everything else is read-only. The `devex pr` namespace allows scoped network I/O (via `gh`), bounded `--wait` sleep, and — for `pr await --detach` — a detached background process that pays that sleep outside the agent session; a deliberate carve-out from the no-network/no-sleep invariants. `devex push` performs a `git push` of the current branch (push-only — it never stages or commits); a deliberate carve-out from the no-mutation invariant, introducing `git push` as a new allowed side-effect class.
 5. **"Unsupported" is success** — exit 0 with a markdown notice that links to the issue tracker, not a non-zero exit.
 6. **Skills are authored by the agent, not shipped by devex.** `devex learn <topic>` teaches; `devex explain <topic>` describes; devex never writes a user skill file on the agent's behalf in v0.1.
 

{agex_cli-0.27.0 → agex_cli-0.28.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agex-cli
-Version: 0.27.0
+Version: 0.28.0
 Summary: Agent-operated developer-experience CLI — deterministic per-backend markdown briefings for autonomous agents.
 Project-URL: Homepage, https://culture.dev/devex/
 Project-URL: Repository, https://github.com/agentculture/devex

agex_cli-0.28.0/docs/plans/2026-05-29-devex-now-turns-a-push-into-continuous-pr-manageme.md

@@ -0,0 +1,50 @@
+# Build Plan — devex now turns a push into continuous PR management: when you push commits to a branch that already has an open PR, devex automatically enters the same review-readiness wait a new PR gets (the ~3-minute poll), so follow-up commits get triaged without a manual step — and a push to a branch with no PR stays an ordinary push.
+
+slug: `devex-now-turns-a-push-into-continuous-pr-manageme` · status: `exported` · from frame: `devex-now-turns-a-push-into-continuous-pr-manageme`
+
+> devex now turns a push into continuous PR management: when you push commits to a branch that already has an open PR, devex automatically enters the same review-readiness wait a new PR gets (the ~3-minute poll), so follow-up commits get triaged without a manual step — and a push to a branch with no PR stays an ordinary push.
+
+## Tasks
+
+### t1 — core/github.py: add git_push() and current_branch_pr() primitives (push-only; single gh pr view for PR detection)
+
+- covers: c9, h1, c7, h10, c13
+- acceptance:
+  - git_push() runs exactly 'git push' of the current branch and nothing else (no commit/rebase/merge/stash/branch); unit test mocks the subprocess, asserts the git argv, and asserts a push failure surfaces as a raised/non-zero error.
+  - current_branch_pr() returns the open PR number for the current branch via a single 'gh pr view --json' call, or None when there is no PR — never raises on the no-PR case; unit test mocks gh for both branches.
+
+### t2 — docs: amend design-invariant #4 in CLAUDE.md to allow 'git push' as a 'devex push' side effect
+
+- covers: c13, h3
+- acceptance:
+  - design-invariant #4 in CLAUDE.md names 'git push' (push-only) as an allowed side effect of 'devex push', listed alongside the existing pr-namespace gh/sleep carve-outs; the side-effects list and the prose are mutually consistent (no other invariant weakened).
+
+### t3 — commands/push/: devex push command — git_push, detect open PR, route to blocking ~180s wait+delta (PR exists) or plain push + notice (no PR)
+
+- depends on: t1
+- covers: c1, h4, c3, h6, c5, h8, c6, h9
+- acceptance:
+  - With an open PR on the current branch, 'devex push' calls git_push then enters the existing pr read/await wait (default 180s) and renders the CI/Sonar/threads delta in ONE invocation; integration test (gh+git mocked) asserts no second command and the delta on stdout.
+  - With no open PR, 'devex push' calls git_push then prints the deterministic 'no PR on this branch — open one with devex pr open' notice and exits 0; test asserts exit 0, the notice text, and that NO wait occurs.
+  - Routing is deterministic on (current branch, PR-exists) with no backend/branch auto-detection — same inputs always select the same path (test).
+  - On the managed path the exit code reflects the post-wait quality gate (non-zero on gate ERROR / unresolved threads), mirroring pr await (test).
+
+### t4 — cli.py: register top-level 'devex push' subcommand with --max-wait (default 180) and --agent
+
+- depends on: t3
+- covers: c4, h7, c10, h2, c2, h5
+- acceptance:
+  - 'devex --help' lists 'push'; 'devex push --help' shows --max-wait (default 180) and --agent; parsing dispatches to the push command entry (test).
+  - --max-wait overrides the 180s default and is threaded into the wait; the default equals pr open --delayed-read's 180 (test asserts the value reaches the wait call).
+  - The command takes no interactive input — all inputs arrive via argv/flags; runs non-interactively to completion (test).
+
+### t5 — commands/push/assets/backends/{claude-code,codex,copilot,acp}.yaml: per-backend next-step phrasing for the no-PR notice and the post-wait delta
+
+- depends on: t3
+- covers: c2, h5
+- acceptance:
+  - All four backends have a push asset with deterministic next-step phrasing for both the no-PR notice and the post-wait delta; test asserts all four load and render with no StrictUndefined errors (all-backends rule).
+
+## Risks
+
+- [unknown_nonblocking] Reusing pr read/await's wait+delta from the new command (t3) may need a shared helper extracted out of commands/pr/scripts if the logic isn't cleanly importable — could widen t3's file scope into commands/pr. (task t3)

agex_cli-0.28.0/docs/specs/2026-05-29-devex-now-turns-a-push-into-continuous-pr-manageme.md

@@ -0,0 +1,67 @@
+# devex now turns a push into continuous PR management: when you push commits to a branch that already has an open PR, devex automatically enters the same review-readiness wait a new PR gets (the ~3-minute poll), so follow-up commits get triaged without a manual step — and a push to a branch with no PR stays an ordinary push.
+
+> devex now turns a push into continuous PR management: when you push commits to a branch that already has an open PR, devex automatically enters the same review-readiness wait a new PR gets (the ~3-minute poll), so follow-up commits get triaged without a manual step — and a push to a branch with no PR stays an ordinary push.
+
+## Audience
+
+- An agent (or human via an agent) running devex inside a repo mid-PR, who has just committed follow-up changes on a branch that already has an open PR and wants CI/review feedback picked up automatically.
+
+## Before → After
+
+- Before: Today there is no push command. After pushing, the agent must remember to manually run 'pr await' / 'pr read --wait' to re-enter triage — easy to forget, so continuous PR management silently breaks.
+- After: Pushing follow-up commits to a branch with an open PR automatically enters the same review-readiness wait a new PR gets (~3-minute poll), with no separate manual 'pr await' / 'pr read --wait' step.
+
+## Why it matters
+
+- Continuous PR management: every push, like every new PR, deterministically lands the agent back in the triage loop instead of leaving fresh CI/Sonar/review feedback unwatched.
+
+## Requirements
+
+- The command must detect whether the current branch has an open PR (via gh) BEFORE deciding whether to enter the wait — the PR-management path is gated on PR existence, never auto-detected away from the user's branch.
+  - honesty: Open-PR detection is a single 'gh pr view --json' style call on the current branch; no PR => exit 0 with a plain-push (or notice) path, never an error.
+- The default post-push wait is ~180s (3 minutes), matching 'pr open --delayed-read' (pr read --wait 180), not pr await's 1800s default — overridable via a flag.
+  - honesty: The 180s default is exposed as an overridable flag (e.g. --max-wait) and documented as matching the new-PR delayed read.
+- Performing 'git push' of the current branch is a NEW class of side effect for devex (push-only; no commit); it requires an explicit carve-out added to design-invariant #4, alongside the existing pr-namespace network/sleep exceptions.
+  - honesty: design-invariant #4 in CLAUDE.md is amended to name 'git push' as an allowed side effect of 'devex push', with the same explicitness as the existing gh/sleep carve-out — otherwise the feature violates a non-negotiable invariant.
+
+## Honesty conditions
+
+- Shipped behavior is exactly: push current branch; if it has an open PR, enter the new-PR-style ~180s readiness wait and render the delta; else plain push + a notice.
+- The primary caller is an agent in an automated PR loop; the command needs no interactive input to choose the managed-vs-plain path.
+- Post-push triage takes zero extra commands: the wait + delta render are part of the single 'devex push' invocation.
+- Verified today: 'devex pr' has no push subcommand and no top-level push exists; re-entering triage requires a manual 'pr await' / 'pr read --wait'.
+- Determinism: identical branch/PR state always routes to the same path (managed vs plain); no backend or branch auto-detection.
+- Observable: one 'devex push' on a PR branch ends with the post-push CI/Sonar/threads delta on stdout, exit code reflecting the quality gate.
+- Scope cap: the only git mutation devex performs is 'git push' of the current branch — no rebase/merge/stash/branch/commit.
+
+## Success signals
+
+- After a push on a PR branch, the agent ends up holding the post-push review delta (CI + Sonar + threads) without issuing a second command.
+
+## Scope / boundaries
+
+- Not a general git porcelain: the push path is the minimum to land commits on the remote; devex does not grow into a git front-end (no rebase/merge/stash/branch management).
+
+## Non-goals
+
+- When the branch has no open PR, devex does NOT open one — that stays an explicit 'pr open'. The push case with no PR is out of the PR-management path.
+
+## Assumptions
+
+- It reuses the existing readiness machinery — pr await --detach/--check and/or pr read --wait — rather than introducing a second poller implementation.
+
+## Decisions
+
+- Top-level 'devex push' (not 'devex pr push'): reads naturally for the no-PR 'just push' case and conditionally enters PR management when an open PR exists.
+- Push-only: pushes already-committed work; devex does NOT stage or commit. Commit-push is out of scope for v0.1.
+- After-push wait is BLOCKING ~180s (mirrors 'pr open --delayed-read' = 'pr read --wait 180'), not detached; --max-wait overrides. Resolves q2.
+
+## Hard questions
+
+- Does the command also 'git commit' (commit-push) or only 'git push' already-committed work? The user is unsure ('commit-pushing / just pushing').
+- Is the wait blocking the agent session (like --delayed-read) or detached (like --detached-await/await --detach)? Continuous management argues for detached + later --check.
+- risk: Naming as 'pr push' is odd when no PR exists (you'd 'pr push' a branch that has no PR) — top-level 'devex push' may read better for the plain-push case.
+
+## Open / follow-up
+
+- RESOLVED (push-only, c15): commit-push (stage+commit) is out of scope for v0.1; 'devex push' strictly pushes already-committed work.

{agex_cli-0.27.0 → agex_cli-0.28.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agex-cli"
-version = "0.27.0"
+version = "0.28.0"
 description = "Agent-operated developer-experience CLI — deterministic per-backend markdown briefings for autonomous agents."
 authors = [{name = "Ori Nachum"}]
 license = {text = "MIT"}