fix(gx): make OpenSpec scaffolding on-by-default and stop the silent-failure log (#549)

`gx branch start` claimed in its end-of-run log that the OpenSpec
change workspace was created at openspec/changes/<slug>, but the
directory was never materialized unless the user happened to have
GUARDEX_OPENSPEC_AUTO_INIT=true in their environment. Reproduced three
times this session: PRs #546, #547, #548 all required manual scaffold
creation despite the log claim.

Root cause: templates/scripts/agent-branch-start.sh line 12 defaulted
the env raw to "false", which short-circuited initialize_openspec_*_workspace
at line 655 / 629; but the trailing log lines 901-911 only checked
$OPENSPEC_SKIP_CHANGE (tier-driven), not $OPENSPEC_AUTO_INIT, so the
log lied.

This change:
- Flips the default to "true" so scaffolding happens by default,
  matching the project's own CLAUDE.md OpenSpec-first contract and the
  tier table that describes T2/T3 as creating "full change workspace".
- Rewrites the end-of-run log block so each branch distinguishes three
  states: auto-init disabled, tier-skipped, scaffolded-at-path. The log
  can no longer claim a workspace exists when the helper exited early.

Verified in-session: with the fix applied, a default-invocation
`bash scripts/agent-branch-start.sh --tier T2 ...` (no env var)
materializes proposal.md, tasks.md, .openspec.yaml, and specs/<n>/spec.md
under the new worktree. Negative path with GUARDEX_OPENSPEC_AUTO_INIT=false
prints "OpenSpec change: skipped (GUARDEX_OPENSPEC_AUTO_INIT disabled)".

Only templates/scripts/agent-branch-start.sh is edited; scripts/agent-branch-start.sh
is a symlink to it (PR #548) and inherits the fix transparently.

OpenSpec change at
openspec/changes/agent-claude-fix-openspec-scaffold-silent-failure-2026-05-11-12-12/.

Co-authored-by: NagyVikt <nagy.viktordp@gmail.com>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: 3 people

openspec/changes/agent-claude-fix-openspec-scaffold-silent-failure-2026-05-11-12-12/proposal.md

@@ -0,0 +1,53 @@
+# Proposal: enable OpenSpec scaffolding by default in `gx branch start` and stop the silent-failure log
+
+## Problem
+
+`gx branch start` claims to scaffold the OpenSpec change workspace in its end-of-run log:
+
+```
+[agent-branch-start] OpenSpec change: openspec/changes/<slug>
+```
+
+But the directory is not created. Reproduced three times this session (PRs #546, #547, #548) — every agent worktree I started had to be manually populated with `proposal.md`/`tasks.md`/`spec.md` despite the log claiming the scaffold was in place.
+
+### Root cause
+
+Two coupled bugs in `templates/scripts/agent-branch-start.sh`:
+
+1. **Default disables scaffolding.** Line 12 reads `OPENSPEC_AUTO_INIT_RAW="${GUARDEX_OPENSPEC_AUTO_INIT:-false}"`. The default is `false`, so the helper `initialize_openspec_change_workspace()` (line 649) hits its guard at line 655 (`if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]] || [[ "$OPENSPEC_SKIP_CHANGE" -eq 1 ]]; then return 0; fi`) and exits without creating anything. The same gate disables `initialize_openspec_plan_workspace()` at line 629.
+
+2. **Log lines do not check the guard.** Lines 901–911 print "OpenSpec change: openspec/changes/<slug>" only checking `$OPENSPEC_SKIP_CHANGE` (the tier-driven skip), not `$OPENSPEC_AUTO_INIT`. So when AUTO_INIT is 0, the function returns early without printing anything, but the final log still announces the scaffold path as if it had been created.
+
+This contradicts the project's own contract in `CLAUDE.md` (the "Workflow (OpenSpec-first)" section: *"For every repo change (feature, fix, refactor, chore, test, config, docs), create/update an OpenSpec change in `openspec/changes/**` before editing code."*) and contradicts the tier table that describes T2/T3 as creating "full change workspace (`proposal.md`, `tasks.md`, `specs/.../spec.md`)".
+
+## Approach
+
+Two small changes, both in `templates/scripts/agent-branch-start.sh` (the runtime-canonical copy; `scripts/agent-branch-start.sh` is a symlink to it as of PR #548).
+
+1. **Flip the default** at line 12 from `:-false` to `:-true`. Scaffolding is on by default. The downstream `run_guardex_cli internal run-shell changeInit ...` path works correctly — proven in-session by setting `GUARDEX_OPENSPEC_AUTO_INIT=true` once and seeing `proposal.md`, `tasks.md`, `.openspec.yaml`, and `specs/<name>/spec.md` materialize at the worktree's `openspec/changes/<slug>/` path.
+
+2. **Make the end-of-run log honest** at lines 901–911. Each branch of the log now checks `$OPENSPEC_AUTO_INIT` first; if 0, the log says `skipped (GUARDEX_OPENSPEC_AUTO_INIT disabled)`; if 1, it falls through to the existing tier-skip / scaffolded-path branches.
+
+### Out of scope
+
+- Tier policy (T0 skips, T1 minimal, T2/T3 full) — unchanged.
+- The `initialize_openspec_change_workspace()` function body — unchanged.
+- The scaffolding pipeline downstream (`run-shell changeInit`) — unchanged.
+- `scripts/agent-branch-start.sh` — already a symlink to the file we edit (PR #548).
+
+## Rationale
+
+- The OpenSpec contract in `CLAUDE.md` requires a change workspace for every PR. The current default forces every contributor to either set `GUARDEX_OPENSPEC_AUTO_INIT=true` in their environment or manually scaffold by hand — neither is documented. The default should match the contract.
+- The downstream pipeline works as soon as the flag is on — verified empirically before committing this fix.
+- A misleading log is worse than no log; the new log accurately reports the three real states (auto-init disabled, tier-skipped, scaffolded).
+
+## Compatibility
+
+- Anyone currently relying on the `false` default for some reason (none observed in this repo) can restore it explicitly with `export GUARDEX_OPENSPEC_AUTO_INIT=false`. The negative-path log line clearly tells them what state they're in.
+- T0 tier (`gx branch start --tier T0 ...`) still creates no scaffold — `$OPENSPEC_SKIP_CHANGE=1` short-circuits the function regardless of `$OPENSPEC_AUTO_INIT`.
+- No CLI surface change. No new flag. No new env var.
+
+## Risks
+
+- Existing CI or fast-iteration scripts that called `bash scripts/agent-branch-start.sh ...` without setting the env var will now create `openspec/changes/<slug>/` directories that they previously didn't. The directories are scoped to the new agent worktree (under `.omc/agent-worktrees/.../openspec/changes/<slug>/`), so they don't pollute the primary checkout. The blast radius is limited to "extra files in throwaway worktrees that get pruned anyway."
+- `git status` inside fresh agent worktrees will show one extra directory tracked by the change. This is the intended behavior — those files are the change docs the contract requires.

openspec/changes/agent-claude-fix-openspec-scaffold-silent-failure-2026-05-11-12-12/specs/gitguardex-agent-lifecycle/spec.md

@@ -0,0 +1,50 @@
+# Spec Delta: gitguardex-agent-lifecycle
+
+## ADDED Requirements
+
+### Requirement: `gx branch start` MUST scaffold the OpenSpec change workspace by default
+
+When `gx branch start` is invoked without an explicit `GUARDEX_OPENSPEC_AUTO_INIT` setting, and the resolved tier is `T1`, `T2`, or `T3`, the script MUST create the change workspace at `<worktree>/openspec/changes/<slug>/` with the tier-appropriate scaffold (`.openspec.yaml`, `proposal.md`, `tasks.md`, and for `T2`/`T3` also `specs/<capability>/spec.md`). The user MUST NOT have to set an environment variable for the workspace to materialize.
+
+#### Scenario: Default invocation creates the change workspace
+
+- **GIVEN** a fresh agent worktree being created via `gx branch start --tier T2 "<task>" "<agent>"`
+- **AND** `GUARDEX_OPENSPEC_AUTO_INIT` is not set in the environment
+- **WHEN** the script completes successfully
+- **THEN** `<worktree>/openspec/changes/<slug>/proposal.md` exists
+- **AND** `<worktree>/openspec/changes/<slug>/tasks.md` exists
+- **AND** `<worktree>/openspec/changes/<slug>/.openspec.yaml` exists
+- **AND** `<worktree>/openspec/changes/<slug>/specs/<capability>/spec.md` exists
+
+#### Scenario: `--tier T0` still skips scaffolding regardless of the default
+
+- **GIVEN** `gx branch start --tier T0 "<task>" "<agent>"`
+- **WHEN** the script completes
+- **THEN** no `openspec/changes/<slug>/` directory is created
+- **AND** the end-of-run log says `OpenSpec change: skipped by tier T0`
+
+#### Scenario: Explicit opt-out via env var
+
+- **GIVEN** `GUARDEX_OPENSPEC_AUTO_INIT=false` is exported in the environment
+- **WHEN** `gx branch start --tier T2 ...` runs
+- **THEN** no `openspec/changes/<slug>/` directory is created
+- **AND** the end-of-run log says `OpenSpec change: skipped (GUARDEX_OPENSPEC_AUTO_INIT disabled)`
+
+### Requirement: `gx branch start` end-of-run log MUST accurately reflect scaffold state
+
+The trailing log block in `templates/scripts/agent-branch-start.sh` MUST distinguish three cases for both the change and plan workspaces: `auto-init disabled`, `tier-skipped`, and `created at <path>`. The log MUST NOT claim a workspace was created when the corresponding `initialize_openspec_*_workspace` helper exited early.
+
+#### Scenario: Log honesty when auto-init is disabled
+
+- **GIVEN** `GUARDEX_OPENSPEC_AUTO_INIT=false` is set
+- **WHEN** `gx branch start --tier T2` runs
+- **THEN** the end-of-run log does NOT contain `OpenSpec change: openspec/changes/<slug>`
+- **AND** the log contains `OpenSpec change: skipped (GUARDEX_OPENSPEC_AUTO_INIT disabled)`
+- **AND** the log contains `OpenSpec plan: skipped (GUARDEX_OPENSPEC_AUTO_INIT disabled)`
+
+#### Scenario: Log honesty when tier skips the change workspace
+
+- **GIVEN** auto-init is enabled (default) and the tier is `T0`
+- **WHEN** `gx branch start --tier T0 ...` runs
+- **THEN** the log contains `OpenSpec change: skipped by tier T0`
+- **AND** the log contains `OpenSpec plan: skipped by tier T0`

openspec/changes/agent-claude-fix-openspec-scaffold-silent-failure-2026-05-11-12-12/tasks.md

@@ -0,0 +1,25 @@
+# Tasks
+
+## 1. Spec
+
+- [x] 1.1 Capture problem + approach in `proposal.md`.
+- [x] 1.2 Add ADDED requirements + scenarios to `specs/gitguardex-agent-lifecycle/spec.md`.
+
+## 2. Implementation
+
+- [x] 2.1 `templates/scripts/agent-branch-start.sh`: flip `OPENSPEC_AUTO_INIT_RAW` default from `false` to `true` (line 12).
+- [x] 2.2 `templates/scripts/agent-branch-start.sh`: rewrite end-of-run OpenSpec log block (lines 901–911) so each branch checks `$OPENSPEC_AUTO_INIT` first and prints `skipped (GUARDEX_OPENSPEC_AUTO_INIT disabled)` when the flag is off.
+
+## 3. Verification
+
+- [x] 3.1 `bash -n` clean on the edited script.
+- [x] 3.2 Positive probe: `bash scripts/agent-branch-start.sh --tier T2 --no-transfer "<task>" "<agent>"` without setting the env var creates `openspec/changes/<slug>/{proposal.md,tasks.md,.openspec.yaml,specs/<name>/spec.md}` in the new worktree.
+- [x] 3.3 Symlink check: confirm `scripts/agent-branch-start.sh` (symlink → `templates/...`) sees the fix transparently.
+- [x] 3.4 Negative probe: `GUARDEX_OPENSPEC_AUTO_INIT=false bash scripts/agent-branch-start.sh ...` exits without creating the scaffold and logs `OpenSpec change: skipped (GUARDEX_OPENSPEC_AUTO_INIT disabled)`.
+
+## 4. Cleanup
+
+- [ ] 4.1 Commit on `agent/claude/fix-openspec-scaffold-silent-failure-2026-05-11-12-12`.
+- [ ] 4.2 Push and open PR against `main`.
+- [ ] 4.3 PR merged (record URL + MERGED state).
+- [ ] 4.4 Sandbox worktree pruned via `gx branch finish --cleanup`.

templates/scripts/agent-branch-start.sh

@@ -9,7 +9,7 @@ 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_AUTO_INIT_RAW="${GUARDEX_OPENSPEC_AUTO_INIT:-true}"
 OPENSPEC_PLAN_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_PLAN_SLUG:-}"
 OPENSPEC_CHANGE_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CHANGE_SLUG:-}"
 OPENSPEC_CAPABILITY_SLUG_OVERRIDE="${GUARDEX_OPENSPEC_CAPABILITY_SLUG:-}"
@@ -899,12 +899,16 @@ fi
 echo "[agent-branch-start] Created branch: ${branch_name}"
 echo "[agent-branch-start] Worktree: ${worktree_path}"
 echo "[agent-branch-start] OpenSpec tier: ${OPENSPEC_TIER}"
-if [[ "$OPENSPEC_SKIP_CHANGE" -eq 1 ]]; then
+if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
+  echo "[agent-branch-start] OpenSpec change: skipped (GUARDEX_OPENSPEC_AUTO_INIT disabled)"
+elif [[ "$OPENSPEC_SKIP_CHANGE" -eq 1 ]]; then
   echo "[agent-branch-start] OpenSpec change: skipped by tier ${OPENSPEC_TIER}"
 else
   echo "[agent-branch-start] OpenSpec change: openspec/changes/${openspec_change_slug}"
 fi
-if [[ "$OPENSPEC_SKIP_PLAN" -eq 1 ]]; then
+if [[ "$OPENSPEC_AUTO_INIT" -ne 1 ]]; then
+  echo "[agent-branch-start] OpenSpec plan: skipped (GUARDEX_OPENSPEC_AUTO_INIT disabled)"
+elif [[ "$OPENSPEC_SKIP_PLAN" -eq 1 ]]; then
   echo "[agent-branch-start] OpenSpec plan: skipped by tier ${OPENSPEC_TIER}"
 else
   echo "[agent-branch-start] OpenSpec plan: openspec/plan/${openspec_plan_slug}"