diff --git a/openspec/changes/agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18/.openspec.yaml b/openspec/changes/agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18/.openspec.yaml new file mode 100644 index 0000000..25345f4 --- /dev/null +++ b/openspec/changes/agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-04-22 diff --git a/openspec/changes/agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18/proposal.md b/openspec/changes/agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18/proposal.md new file mode 100644 index 0000000..313eca3 --- /dev/null +++ b/openspec/changes/agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18/proposal.md @@ -0,0 +1,11 @@ +## Why + +- TODO: describe the user/problem outcome this change addresses. + +## What Changes + +- TODO: summarize the intended behavior and scope. + +## Impact + +- TODO: call out risks, rollout notes, and affected surfaces. diff --git a/openspec/changes/agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18/specs/fix-agent-branch-start-template-parity/spec.md b/openspec/changes/agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18/specs/fix-agent-branch-start-template-parity/spec.md new file mode 100644 index 0000000..3e7c276 --- /dev/null +++ b/openspec/changes/agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18/specs/fix-agent-branch-start-template-parity/spec.md @@ -0,0 +1,14 @@ +## ADDED Requirements + +### Requirement: branch-start runtime preserves template bootstrap parity +The runtime `scripts/agent-branch-start.sh` SHALL preserve the same bootstrap behavior and user guidance as `templates/scripts/agent-branch-start.sh`. + +#### Scenario: OpenSpec bootstrap uses the CLI-owned path +- **WHEN** `scripts/agent-branch-start.sh` initializes OpenSpec workspaces in a new agent worktree +- **THEN** it invokes change and plan initialization through `gx internal run-shell ...` +- **AND** it does not rehydrate deprecated local helper copies into the worktree. + +#### Scenario: printed next steps match the supported CLI surface +- **WHEN** `scripts/agent-branch-start.sh` prints the post-start handoff instructions +- **THEN** it points users at `gx locks claim` +- **AND** it points users at `gx branch finish`. diff --git a/openspec/changes/agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18/tasks.md b/openspec/changes/agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18/tasks.md new file mode 100644 index 0000000..5cf65de --- /dev/null +++ b/openspec/changes/agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18/tasks.md @@ -0,0 +1,34 @@ +## 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-fix-agent-branch-start-template-parity-2026-04-22-11-18`; branch=`agent/codex/fix-agent-branch-start-template-parity-2026-04-22-11-18`; scope=`scripts/agent-branch-start.sh`; action=`restore runtime/template parity and verify existing parity coverage`. +- Copy prompt: Continue `agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18` on branch `agent/codex/fix-agent-branch-start-template-parity-2026-04-22-11-18`. Work inside the existing sandbox, review `openspec/changes/agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18/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/fix-agent-branch-start-template-parity-2026-04-22-11-18 --base main --via-pr --wait-for-merge --cleanup`. + +## 1. Specification + +- [x] 1.1 Finalize proposal scope and acceptance criteria for `agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18`. +- [x] 1.2 Define normative requirements in `specs/fix-agent-branch-start-template-parity/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. +- [x] 3.2 Run `openspec validate agent-codex-fix-agent-branch-start-template-parity-2026-04-22-11-18 --type change --strict`. +- [x] 3.3 Run `openspec validate --specs`. + +## 4. Cleanup (mandatory; run before claiming completion) + +- [ ] 4.1 Run the cleanup pipeline: `gx branch finish --branch agent/codex/fix-agent-branch-start-template-parity-2026-04-22-11-18 --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/scripts/agent-branch-start.sh b/scripts/agent-branch-start.sh index ef8cc11..c871372 100755 --- a/scripts/agent-branch-start.sh +++ b/scripts/agent-branch-start.sh @@ -7,6 +7,8 @@ BASE_BRANCH="" BASE_BRANCH_EXPLICIT=0 WORKTREE_ROOT_REL="" WORKTREE_ROOT_EXPLICIT=0 +NODE_BIN="${GUARDEX_NODE_BIN:-node}" +CLI_ENTRY="${GUARDEX_CLI_ENTRY:-}" OPENSPEC_AUTO_INIT_RAW="${GUARDEX_OPENSPEC_AUTO_INIT:-false}" OPENSPEC_PLAN_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_PLAN_SLUG:-}" OPENSPEC_CHANGE_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CHANGE_SLUG:-}" @@ -15,6 +17,23 @@ OPENSPEC_MASTERPLAN_LABEL_RAW="${GUARDEX_OPENSPEC_MASTERPLAN_LABEL-masterplan}" PRINT_NAME_ONLY=0 POSITIONAL_ARGS=() +run_guardex_cli() { + if [[ -n "$CLI_ENTRY" ]]; then + "$NODE_BIN" "$CLI_ENTRY" "$@" + return $? + fi + if command -v gx >/dev/null 2>&1; then + gx "$@" + return $? + fi + if command -v gitguardex >/dev/null 2>&1; then + gitguardex "$@" + return $? + fi + echo "[agent-branch-start] Guardex CLI entrypoint unavailable; rerun via gx." >&2 + return 127 +} + while [[ $# -gt 0 ]]; do case "$1" in --task) @@ -385,26 +404,14 @@ initialize_openspec_plan_workspace() { local worktree="$2" local plan_slug="$3" - hydrate_local_helper_in_worktree "$repo" "$worktree" "scripts/openspec/init-plan-workspace.sh" - if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then return 0 fi - local openspec_script="${worktree}/scripts/openspec/init-plan-workspace.sh" - if [[ ! -f "$openspec_script" ]]; then - echo "[agent-branch-start] OpenSpec init script is missing in sandbox worktree." >&2 - echo "[agent-branch-start] Run 'gx setup --target \"$repo\"' to repair templates, then retry." >&2 - return 1 - fi - if [[ ! -x "$openspec_script" ]]; then - chmod +x "$openspec_script" 2>/dev/null || true - fi - local init_output="" if ! init_output="$( cd "$worktree" - bash "scripts/openspec/init-plan-workspace.sh" "$plan_slug" 2>&1 + run_guardex_cli internal run-shell planInit "$plan_slug" 2>&1 )"; then printf '%s\n' "$init_output" >&2 echo "[agent-branch-start] OpenSpec workspace initialization failed for plan '${plan_slug}'." >&2 @@ -423,26 +430,14 @@ initialize_openspec_change_workspace() { local change_slug="$3" local capability_slug="$4" - hydrate_local_helper_in_worktree "$repo" "$worktree" "scripts/openspec/init-change-workspace.sh" - if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then return 0 fi - local openspec_script="${worktree}/scripts/openspec/init-change-workspace.sh" - if [[ ! -f "$openspec_script" ]]; then - echo "[agent-branch-start] OpenSpec change init script is missing in sandbox worktree." >&2 - echo "[agent-branch-start] Run 'gx setup --target \"$repo\"' to repair templates, then retry." >&2 - return 1 - fi - if [[ ! -x "$openspec_script" ]]; then - chmod +x "$openspec_script" 2>/dev/null || true - fi - local init_output="" if ! init_output="$( cd "$worktree" - bash "scripts/openspec/init-change-workspace.sh" "$change_slug" "$capability_slug" 2>&1 + run_guardex_cli internal run-shell changeInit "$change_slug" "$capability_slug" 2>&1 )"; then printf '%s\n' "$init_output" >&2 echo "[agent-branch-start] OpenSpec workspace initialization failed for change '${change_slug}'." >&2 @@ -592,7 +587,6 @@ if [[ -n "$auto_transfer_stash_ref" ]]; then fi fi -hydrate_local_helper_in_worktree "$repo_root" "$worktree_path" "scripts/codex-agent.sh" hydrate_dependency_dir_symlink_in_worktree "$repo_root" "$worktree_path" "node_modules" hydrate_dependency_dir_symlink_in_worktree "$repo_root" "$worktree_path" "apps/frontend/node_modules" hydrate_dependency_dir_symlink_in_worktree "$repo_root" "$worktree_path" "apps/backend/node_modules" @@ -609,6 +603,6 @@ echo "[agent-branch-start] OpenSpec change: openspec/changes/${openspec_change_s echo "[agent-branch-start] OpenSpec plan: openspec/plan/${openspec_plan_slug}" echo "[agent-branch-start] Next steps:" echo " cd \"${worktree_path}\"" -echo " python3 scripts/agent-file-locks.py claim --branch \"${branch_name}\" " +echo " gx locks claim --branch \"${branch_name}\" " echo " # implement + commit" -echo " bash scripts/agent-branch-finish.sh --branch \"${branch_name}\" --base ${BASE_BRANCH} --via-pr --wait-for-merge" +echo " gx branch finish --branch \"${branch_name}\" --base ${BASE_BRANCH} --via-pr --wait-for-merge"