edercnj/x-internal-ensure-epic-branch

Global Output Policy

• Language: English ONLY.
• Tone: Technical, Direct, and Concise.
• Efficiency: Remove all conversational fillers and greetings to save tokens.

🔒 INTERNAL SKILL Esta skill é invocada apenas por outras skills (orquestradores). NÃO é destinada a invocação direta pelo usuário. Callers principais: x-epic-create, x-epic-decompose, x-orchestrate-epic, x-implement-epic, x-epic-map (story-0049-0018, 0049-0021, 0049-0022). Sétima skill da convenção x-internal-* (após x-internal-update-status pilot 0049-0005, x-internal-write-report 0049-0006, x-internal-normalize-args 0049-0007, x-internal-load-story-context 0049-0011, x-internal-build-story-plan 0049-0012, x-internal-verify-story 0049-0014). Primeira skill na subdir internal/git/ — o subdir git/ agrupa operações git de orquestração (ensure de branches de épico; futuras skills de ensure de release branch, merge-back de hotfix, etc.).

Skill: x-internal-ensure-epic-branch

Purpose

Provide a single, idempotent entry point for the RULE-001 convention "one branch per epic (epic/<ID>), always exists, always pushed". The orchestrator skills that open an epic lifecycle step MUST call this skill at step 0 rather than issuing inline git checkout -b or git push -u origin commands; this eliminates three historical regressions:

1. Duplicate branches created in parallel invocations (two entry-points launched in the same wave both running git checkout -b).
2. Local-only branches that lagged origin for hours because the caller forgot to push (documented in EPIC-0033 post-mortem).
3. Divergent base commits between local and remote due to mixed --base flags across entry-points.

Responsibilities (single):

1. Validate --epic-id against the canonical 4-digit regex.
2. Resolve branch name → epic/<ID>.
3. Detect local existence (git rev-parse --verify).
4. Detect remote existence (git ls-remote origin).
5. Apply the 3-state decision:
   • new (neither) ⇒ delegate to Skill x-create-git-branch --push;
   • local-only ⇒ emit complementary git push -u origin;
   • local+remote ⇒ idempotent no-op.
6. Emit a single-line JSON envelope consumed by the caller.

This skill does NOT create branches directly — all branch creation goes through x-create-git-branch (story-0049-0001) to preserve the "one creation path" invariant of RULE-001.

Convention Anchors (x-internal-* 7th skill)

| Aspect | Value | Rationale | | :--- | :--- | :--- | | Path | internal/git/x-internal-ensure-epic-branch/ | internal/ prefix scopes visibility; git/ groups orchestration-level git ensure operations (distinct from internal/ops/ state mutation and internal/plan/ planning-phase carve-outs). | | Frontmatter visibility | internal | Generator filters from /help menu. | | Frontmatter user-invocable | false | Declarative complement to visibility: internal. | | Body marker | > 🔒 **INTERNAL SKILL** as first non-frontmatter content | Human-visible when browsing the repo. | | Allowed tools | Bash only | Minimal surface; delegates to x-create-git-branch via Skill tool when needed. | | Naming | x-internal-{subject}-{action} | subject = epic-branch; action = ensure. Mirrors Rule 04 skill taxonomy. |

Audit rule: Rule 22 (Lifecycle Integrity) validates every skill under internal/** satisfies all 6 anchors above. Violations fail the LifecycleIntegrityAuditTest.

Triggers

Bare-slash form is intentionally omitted — this skill is never invoked by a human typing /x-internal-ensure-epic-branch in chat. All invocations follow Rule 13 INLINE-SKILL pattern from a calling orchestrator:

Skill(skill: "x-internal-ensure-epic-branch",
      args: "--epic-id 0049")

Skill(skill: "x-internal-ensure-epic-branch",
      args: "--epic-id 0050 --base main --push true")

Parameters

| Parameter | Required | Default | Description | | :--- | :--- | :--- | :--- | | --epic-id <XXXX> | M | — | 4-digit numeric epic identifier. Must match ^\d{4}$. | | --base <branch> | O | develop | Base branch for the delegated creation. Must exist locally. | | --push <true\|false> | O | true | When true, guarantees the branch is present on origin. When false, creation is local-only and the remote-check step is skipped. |

Response Contract

Successful invocations emit a single-line JSON object on stdout:

| Field | Type | Always Present | Description | | :--- | :--- | :--- | :--- | | branchName | String | yes | Resolved branch name (epic/<ID>). | | baseSha | String(40) | yes | SHA of --base at the moment the skill ran (captured for audit). | | created | Boolean | yes | true when the branch was created in this invocation (delegation to x-create-git-branch succeeded). | | alreadyExisted | Boolean | yes | true when the branch already existed locally before this invocation. | | pushedNow | Boolean | yes | true when this invocation issued the git push -u origin <branch> (either through x-create-git-branch --push or the complementary-push branch). |

Invariant: exactly one of (created, alreadyExisted) is true. pushedNow is independent; it can be true with either.

Exit Codes

| Code | Name | Condition | Message Format | | :--- | :--- | :--- | :--- | | 0 | SUCCESS | Ensure completed (created, no-op, or complementary push) | — | | 1 | INVALID_EPIC_ID | --epic-id missing or fails ^\d{4}$ | Epic ID must be 4 digits | | 2 | BASE_NOT_FOUND | --base does not resolve locally | Base branch '<name>' not found | | 3 | DELEGATION_FAILED | x-create-git-branch returned non-zero | x-create-git-branch failed with exit <code>: <stderr> | | 4 | PUSH_FAILED | Complementary git push returned non-zero | Push to origin failed: <stderr> |

Exit codes 1 and 2 mirror the story's Section 5.3 error-code table. Codes 3 and 4 surface child-process failures without swallowing stderr.

Workflow

Step 1 — Argument parsing and --epic-id validation

EPIC_ID=""
BASE_BRANCH="develop"
PUSH="true"

while [ $# -gt 0 ]; do
  case "$1" in
    --epic-id) EPIC_ID="$2"; shift 2 ;;
    --base)    BASE_BRANCH="$2"; shift 2 ;;
    --push)    PUSH="$2"; shift 2 ;;
    *) echo "ERROR: unknown flag: $1" >&2; exit 64 ;;
  esac
done

if ! printf '%s' "$EPIC_ID" | grep -Eq '^[0-9]{4}$'; then
  echo "INVALID_EPIC_ID — Epic ID must be 4 digits" >&2
  exit 1
fi

The 4-digit regex matches the story's Section 5.1 validation rule. The skill intentionally does NOT accept a feat/ / epic/ prefix in --epic-id — the caller supplies the raw number; prefix composition is the skill's responsibility.

Step 2 — Base branch existence check

if ! git rev-parse --verify --quiet "$BASE_BRANCH" >/dev/null; then
  echo "BASE_NOT_FOUND — Base branch '$BASE_BRANCH' not found" >&2
  exit 2
fi
BASE_SHA=$(git rev-parse --verify "$BASE_BRANCH")

Exits early before touching any network operation. Matches x-create-git-branch Step 3 semantics.

Step 3 — Compute target branch name

BRANCH_NAME="epic/${EPIC_ID}"

Hard-coded prefix — the RULE-001 convention has exactly one form. No configurability is intentional; variance breaks the "one branch per epic" audit trail.

Step 4 — Local existence detection

ALREADY_EXISTED="false"
if git rev-parse --verify --quiet "$BRANCH_NAME" >/dev/null; then
  ALREADY_EXISTED="true"
fi

A local branch is authoritative over remote — the epic lifecycle runs N times on a developer workstation between pushes. The skill trusts the local state and only reconciles to remote when --push=true.

Step 5 — Remote existence detection (skipped when --push=false)

REMOTE_EXISTS="false"
if [ "$PUSH" = "true" ]; then
  if git ls-remote --exit-code --heads origin "$BRANCH_NAME" >/dev/null 2>&1; then
    REMOTE_EXISTS="true"
  fi
fi

When --push=false, the remote check is skipped and the complementary-push branch becomes unreachable. The skill still emits pushedNow=false in that case; the caller owns the downstream decision (e.g., a dry-run mode may want local-only).

Step 6 — Three-state decision and execution

CREATED="false"
PUSHED_NOW="false"

if [ "$ALREADY_EXISTED" = "true" ] && [ "$REMOTE_EXISTS" = "true" ]; then
  # State A — idempotent no-op
  :
elif [ "$ALREADY_EXISTED" = "true" ] && [ "$REMOTE_EXISTS" = "false" ] && [ "$PUSH" = "true" ]; then
  # State B — complementary push
  if ! git push -u origin "$BRANCH_NAME" 2>/tmp/epic-branch-ensure.push.err; then
    echo "PUSH_FAILED — Push to origin failed" >&2
    cat /tmp/epic-branch-ensure.push.err >&2
    exit 4
  fi
  PUSHED_NOW="true"
elif [ "$ALREADY_EXISTED" = "false" ]; then
  # State C — delegate creation to x-create-git-branch
  #
  # Invocation shape (Rule 13 INLINE-SKILL):
  #
  #   Skill(skill: "x-create-git-branch",
  #         args: "--name epic/<ID> --base <BASE_BRANCH> [--push]")
  #
  # The calling orchestrator forwards --push=true/false verbatim. A
  # successful invocation populates baseSha, created=true, pushed=<push>
  # on the x-create-git-branch response; this skill re-exports those as
  # created=true, pushedNow=<push>.
  echo "DELEGATE_TO_X_GIT_BRANCH — name=$BRANCH_NAME base=$BASE_BRANCH push=$PUSH" >&2
  # The orchestrator layer performs the actual Skill(...) call and
  # captures the result; see the full protocol for the end-to-end
  # envelope translation.
  CREATED="true"
  if [ "$PUSH" = "true" ]; then
    PUSHED_NOW="true"
  fi
fi

State A, B, and C are mutually exclusive. The caller can distinguish them post-hoc by inspecting (created, alreadyExisted, pushedNow).

Step 7 — Emit structured response

printf '{"branchName":"%s","baseSha":"%s","created":%s,"alreadyExisted":%s,"pushedNow":%s}\n' \
  "$BRANCH_NAME" "$BASE_SHA" "$CREATED" "$ALREADY_EXISTED" "$PUSHED_NOW"

Single-line JSON keeps parsing cost at O(1) for the caller, which is typically the very first step of an epic entry-point — any overhead here is paid N times per day on a developer workstation.

Examples

Example 1 — New epic, branch absent locally and remotely

Skill(skill: "x-internal-ensure-epic-branch",
      args: "--epic-id 0050")

Expected stdout:

{"branchName":"epic/0050","baseSha":"<sha>","created":true,"alreadyExisted":false,"pushedNow":true}

Exit: 0. Matches Section 7 Gherkin scenario "Criar branch nova quando epic é novo".

Example 2 — Idempotent no-op, branch present locally + remotely

Skill(skill: "x-internal-ensure-epic-branch",
      args: "--epic-id 0049")

Expected stdout:

{"branchName":"epic/0049","baseSha":"<sha>","created":false,"alreadyExisted":true,"pushedNow":false}

Exit: 0. Matches "Idempotência — branch já existe local + remoto".

Example 3 — Complementary push, local-only branch

# Branch created manually earlier; never pushed.
Skill(skill: "x-internal-ensure-epic-branch",
      args: "--epic-id 0049 --push true")

Expected stdout:

{"branchName":"epic/0049","baseSha":"<sha>","created":false,"alreadyExisted":true,"pushedNow":true}

Exit: 0. Matches "Push complementar — branch local mas não remota".

Example 4 — Custom base

Skill(skill: "x-internal-ensure-epic-branch",
      args: "--epic-id 0051 --base main")

Expected stdout:

{"branchName":"epic/0051","baseSha":"<sha>","created":true,"alreadyExisted":false,"pushedNow":true}

Exit: 0.

Example 5 — Missing base branch

Skill(skill: "x-internal-ensure-epic-branch",
      args: "--epic-id 0052 --base mybase")

Expected stderr:

BASE_NOT_FOUND — Base branch 'mybase' not found

Exit: 2. Matches "Erro — base inexistente".

Example 6 — Malformed epic-id

Skill(skill: "x-internal-ensure-epic-branch",
      args: "--epic-id 49")

Expected stderr:

INVALID_EPIC_ID — Epic ID must be 4 digits

Exit: 1. Matches "Boundary — epic-id mal formado".

Example 7 — Local-only flow (--push false)

Skill(skill: "x-internal-ensure-epic-branch",
      args: "--epic-id 0053 --push false")

Expected stdout:

{"branchName":"epic/0053","baseSha":"<sha>","created":true,"alreadyExisted":false,"pushedNow":false}

Exit: 0. The skill never issues a network operation; suitable for offline dry-runs.

Error Handling

| Scenario | Action | | :--- | :--- | | --epic-id missing or fails regex | Exit 1 (INVALID_EPIC_ID); stderr carries the offending value. | | --base absent locally | Exit 2 (BASE_NOT_FOUND); suggest git fetch origin. | | x-create-git-branch delegation fails (State C) | Exit 3 (DELEGATION_FAILED); stderr carries x-create-git-branch stderr verbatim. | | git push fails in State B | Exit 4 (PUSH_FAILED); stderr carries git push stderr verbatim. | | git ls-remote times out or auth fails | Exit 4 (PUSH_FAILED); remote-check failure is treated as a push-side failure. | | Unknown flag | Exit 64 (sysexits EX_USAGE); print usage: banner. | | git absent on PATH | Exit 127 with git is required; abort before any state mutation. |

All exits preserve set -e / trap-free semantics: no temp files are written in the happy path, and the complementary-push temp file at /tmp/epic-branch-ensure.push.err is overwritten on the next invocation (no accumulation).

Idempotency Contract

The skill satisfies RULE-002 idempotency over the full 3-state matrix:

| State before | First call | Second call | | :--- | :--- | :--- | | Branch absent (local + remote) | created=true, alreadyExisted=false, pushedNow=true | created=false, alreadyExisted=true, pushedNow=false | | Branch local, not remote | created=false, alreadyExisted=true, pushedNow=true | created=false, alreadyExisted=true, pushedNow=false | | Branch local + remote | created=false, alreadyExisted=true, pushedNow=false | created=false, alreadyExisted=true, pushedNow=false |

Two concurrent invocations of the same --epic-id serialize on the git process lock; the later caller always observes the earlier caller's result as "already exists". No flock is required — git's own .git/index.lock provides the critical-section guarantee at the granularity we need.

Performance Contract (story Section 3.5)

| Operation | Budget | | :--- | :--- | | State A (idempotent no-op; no network) | < 1s (two git rev-parse calls + ls-remote) | | State B (complementary push) | < 3s (ls-remote + single push round-trip) | | State C (delegate to x-create-git-branch) | < 3s (branch create + push; matches x-create-git-branch budget) |

The "< 1s" ceiling for idempotency is the dominant case in a multi-entry-point workflow: x-implement-epic followed by x-orchestrate-epic followed by x-epic-map on the same epic will trigger State A three times; the aggregate overhead must stay sub-3s.

Testing

The story ships the following acceptance test scenarios, which are the reference contract every downstream caller (0049-0018, 0049-0021, 0049-0022) can rely on:

1. Happy path (State C) — branch absent both sides; assert created=true, alreadyExisted=false, pushedNow=true; assert the ref exists locally (git rev-parse) and on origin (git ls-remote).
2. Idempotency (State A) — second invocation of the same epic ID yields created=false, alreadyExisted=true, pushedNow=false; file tree unchanged; .git/packed-refs unchanged.
3. Complementary push (State B) — pre-create local branch without pushing, then invoke skill; assert pushedNow=true; origin ref now present.
4. --push false — assert no network call; pushedNow=false regardless of remote state.
5. BASE_NOT_FOUND — pass --base unknown; exit 2; message contains BASE_NOT_FOUND.
6. INVALID_EPIC_ID — pass --epic-id 49; exit 1; message contains INVALID_EPIC_ID.

No Java production code is introduced by this story; the SKILL.md is the deliverable. Golden-file smoke tests are covered upstream by the generator's existing skill-inventory goldens — this skill, being visibility: internal, does NOT appear in the /help menu or in .claude/README.md, so no golden-file updates are required.

Generator Filter Contract

The ia-dev-env generator MUST exclude skills with visibility: internal from:

1. The .claude/README.md skill-inventory table.
2. The /help menu listing surfaced by Claude Code.
3. User-facing autocomplete in the chat input.

Internal skills ARE still copied into .claude/skills/ (flat layout) so Skill(skill: "x-internal-ensure-epic-branch") invocations from other skills resolve correctly. The invariant: user cannot see them; orchestrators can invoke them.

Telemetry

Internal skills DO NOT emit phase.start / phase.end markers — telemetry is produced by the invoking orchestrator (the phase wrapping the orchestrator's own step 0 is the correct aggregation boundary). Passive hooks still capture tool.call for the underlying Bash invocation.

Reference: Rule 13 (Skill Invocation Protocol), Rule 22 (Lifecycle Integrity Audit), ADR-0010 (Interactive Gates Convention — exempts internal skills from the 3-option menu contract).

Rule References

• RULE-001 (EPIC-0049) — Branch única por épico (epic/<ID>). This skill IS the canonical enforcement point.
• RULE-005 (EPIC-0049) — Thin orchestrator (UseCase pattern). Epic entry-points call this skill instead of inlining branch logic.
• RULE-006 (EPIC-0049) — x-internal-* convention. This is the seventh skill to follow the convention.
• Rule 09 (Branching Model) — epic/<ID> is a canonical prefix in the generic branch-name regex.
• Rule 13 (Skill Invocation Protocol) — INLINE-SKILL pattern used by all callers.
• Rule 22 (Lifecycle Integrity Audit) — validates the 6 convention anchors above.

Integration Notes

| Skill | Relationship | Context | | :--- | :--- | :--- | | x-create-git-branch | delegate (State C) | The only skill this one calls. Handles actual git branch + optional push. | | x-epic-create | caller (future — story-0049-0018) | Step 0 before writing epic metadata. | | x-epic-decompose | caller (future — story-0049-0018) | Step 0 before writing stories / IMPLEMENTATION-MAP. | | x-orchestrate-epic | caller (future — story-0049-0021) | Step 0 before per-story planning loop. | | x-implement-epic | caller (future — story-0049-0021) | Step 0 before Phase 0 preparation. | | x-epic-map | caller (future — story-0049-0022) | Step 0 before IMPLEMENTATION-MAP refresh. | | x-internal-update-status | peer (internal/ops/) | Independent — mutates execution-state; this skill mutates git refs. Never co-serialized. | | x-internal-normalize-args | peer (internal/ops/) | Future refactor may adopt it for flag parsing; current implementation uses inline Bash parsing for minimal surface. |

Downstream stories that depend on this skill: story-0049-0018 (epic-create / epic-decompose refactor), story-0049-0021 (epic-orchestrate / epic-implement refactor), story-0049-0022 (epic-map refactor).