feat(epic): link branch to issue via createLinkedBranch instead of cross-ref comment

GitHub's GraphQL exposes a createLinkedBranch mutation that creates a
branch officially linked to an issue (the same link that powers the
'Development' sidebar in the issue UI). When a PR is opened from such
a branch, it is auto-linked to the issue — natively, in the proper
slot, no Closes-#N body keyword required.

Replace the ad-hoc 'Linked PR: #N' comment workaround with this
native mechanism:

- New helper create_linked_branch.sh: idempotent (reuses an existing
  ticket/<N>-* branch if any), generates a slug from the issue title,
  resolves the base SHA via git ls-remote, calls createLinkedBranch.
  Returns the branch name on stdout.
- epic_loop.sh: calls the helper after ensure_worktree, passes the
  branch name to spawn_agent and into the prompt.
- code-dev/AGENT.md: step 4 now does 'git fetch origin <branch>' +
  'git checkout <branch>' (no more 'checkout -b') — the agent works
  on the pre-created linked branch.
- process_tick_result.sh: drops the link_pr_to_ticket.sh call from
  the validated branch (no longer needed).
- link_pr_to_ticket.sh: deleted (obsolete).

Net effect: cleaner UX (PR appears in the issue's Development sidebar
with no extra noise in the comments stream).

Author: Viczei

.claude/agents/code-dev/AGENT.md

@@ -16,6 +16,7 @@ You execute one pre-specified ticket end-to-end : edit code, write/update tests,
 - **Base branch** (assigned by `/epic` ou `/code`) — toujours au format **remote-tracking ref** (`origin/<branch>`), déjà fetchée par l'orchestrateur :
   - `origin/alpha` (ou `origin/chore/ai-pipeline` pendant la phase de transition) si aucune dépendance ou toutes mergées
   - `origin/ticket/<parent-slug>` si le ticket dépend d'un autre encore en `In review` (stacked PR)
+- **Working branch** (assigned by `/epic`) — déjà créée sur GitHub par l'orchestrateur via `createLinkedBranch` GraphQL et **officiellement linkée à l'issue** (sidebar Development). La PR ouverte depuis cette branche y apparaîtra automatiquement — pas besoin de cross-reference comment.
 
 ## Workflow
 
@@ -27,10 +28,11 @@ You execute one pre-specified ticket end-to-end : edit code, write/update tests,
 
 3. **Status ticket** → **In progress** via `bash scripts/orchestration/set_ticket_status.sh <N> "In progress"`.
 
-4. **Branche** dans le worktree, à partir de la **base branch** reçue en input (déjà au format `origin/<x>` et déjà fetchée par l'orchestrateur — **ne pas re-fetcher**) :
+4. **Checkout la branche linkée pré-créée** (la `Working branch` reçue en input). **Ne pas créer une nouvelle branche** — la branche existe déjà sur GitHub, est linkée à l'issue, et c'est sur elle que tu dois pousser :
    - `cd <worktree>` (le worktree est en mode `--detach` sur la base)
-   - `git checkout -b ticket/<N>-<slug> <base-branch>` (ex: `git checkout -b ticket/123-foo origin/alpha`)
-   - Si `<base-branch>` n'est pas `origin/alpha` (ou `origin/chore/ai-pipeline` en phase de transition), on est en mode **stacked PR** — la PR sera ouverte avec `--base <base-branch-sans-prefix-origin>` (ex: `--base ticket/<parent-slug>`), GitHub retargettera vers `alpha` quand la PR parent sera mergée
+   - `git fetch origin <working-branch>`
+   - `git checkout <working-branch>` (PAS `checkout -b`)
+   - Si la **base branch** n'est pas `origin/alpha` (ou `origin/chore/ai-pipeline` en phase de transition), on est en mode **stacked PR** — la PR sera ouverte avec `--base <base-branch-sans-prefix-origin>` (ex: `--base ticket/<parent-slug>`), GitHub retargettera vers `alpha` quand la PR parent sera mergée
 
 4.5. **Sanity check stack docker** — vérifier que `packages/app/.env.local` existe et contient `COMPOSE_PROJECT_NAME=egapro-wt-*`. Si absent → `scripts/setup-worktree.sh <index> [<extras>]` (où `<extras>` vient du parsing de la section `## Requires services` du ticket). Si `/epic` ou `/code` a déjà lancé le setup, l'étape est un no-op.
 

scripts/orchestration/create_linked_branch.sh

@@ -0,0 +1,94 @@
+#!/usr/bin/env bash
+# create_linked_branch.sh <ticket_number> <base_branch>
+#
+# Creates a branch officially "linked" to the GitHub issue (i.e. it shows up
+# in the issue's sidebar "Development" section). The PR opened later from
+# this branch is then auto-linked to the issue too — no need for a manual
+# cross-reference comment, no dependency on the "Closes #N" body keyword
+# (which only fires when the PR targets the default branch).
+#
+# Idempotent: if a branch matching `ticket/<N>-*` already exists on origin,
+# it is reused and its name is returned. The linkedBranch GraphQL state is
+# *not* re-asserted in that case (re-running createLinkedBranch on an existing
+# linked ref would fail, and a stale branch from a prior cancelled run is
+# already linked).
+#
+# Stdout: the branch name (e.g. ticket/3313-annotate-indicators-af).
+# Stderr: progress + any error.
+#
+# Usage:
+#   create_linked_branch.sh 3313 origin/chore/ai-pipeline
+#   create_linked_branch.sh 3313 origin/ticket/3312-post-processing-wiki
+
+set -euo pipefail
+
+if [ $# -lt 2 ]; then
+    echo "Usage: $0 <ticket_number> <base_branch>" >&2
+    exit 2
+fi
+
+TICKET="$1"
+BASE="$2"
+
+# 1. Reuse existing branch if any (idempotent across re-runs)
+EXISTING=$(git ls-remote --heads origin "ticket/${TICKET}-*" 2>/dev/null \
+    | awk '{print $2}' | sed 's|refs/heads/||' | head -1)
+if [ -n "$EXISTING" ]; then
+    echo "[create_linked_branch] reusing existing branch: $EXISTING" >&2
+    echo "$EXISTING"
+    exit 0
+fi
+
+# 2. Compute the slug from the issue title
+TITLE=$(gh issue view "$TICKET" --json title --jq '.title')
+# Strip leading prefix like "T0 — " / "T1 - " / "[bug] " (best-effort)
+TITLE_TRIMMED=$(echo "$TITLE" | sed -E 's/^(T[0-9]+ *[—–-] *|\[[^]]+\] *)//')
+# Slugify: lowercase, ASCII-fold removes accents, non-alphanumeric → '-',
+# collapse runs of '-', trim leading/trailing '-', cap at 40 chars.
+SLUG=$(echo "$TITLE_TRIMMED" \
+    | iconv -f UTF-8 -t ASCII//TRANSLIT 2>/dev/null \
+    | tr '[:upper:]' '[:lower:]' \
+    | sed -E 's/[^a-z0-9]+/-/g; s/^-+//; s/-+$//' \
+    | head -c 40 \
+    | sed -E 's/-+$//')
+
+if [ -z "$SLUG" ]; then
+    SLUG="ticket"
+fi
+
+NAME="ticket/${TICKET}-${SLUG}"
+
+# 3. Resolve the base branch SHA. Accept either a remote-tracking ref
+# (origin/<x>) or a bare branch name (<x>).
+BASE_REF="${BASE#origin/}"
+OID=$(git ls-remote --heads origin "$BASE_REF" 2>/dev/null | awk '{print $1}' | head -1)
+if [ -z "$OID" ]; then
+    echo "[create_linked_branch] ERROR: cannot resolve SHA for base $BASE" >&2
+    exit 1
+fi
+
+# 4. Resolve the issue's GraphQL node ID
+ISSUE_ID=$(gh issue view "$TICKET" --json id --jq '.id')
+if [ -z "$ISSUE_ID" ]; then
+    echo "[create_linked_branch] ERROR: cannot resolve issue node id for #$TICKET" >&2
+    exit 1
+fi
+
+# 5. Create the linked branch
+echo "[create_linked_branch] creating $NAME from $BASE ($OID) linked to issue #$TICKET" >&2
+RESULT=$(gh api graphql -f query='
+mutation($issueId: ID!, $oid: GitObjectID!, $name: String!) {
+    createLinkedBranch(input: { issueId: $issueId, oid: $oid, name: $name }) {
+        linkedBranch { ref { name } }
+    }
+}' -f issueId="$ISSUE_ID" -f oid="$OID" -f name="$NAME" 2>&1)
+
+CREATED_NAME=$(echo "$RESULT" | jq -r '.data.createLinkedBranch.linkedBranch.ref.name // ""' 2>/dev/null || echo "")
+if [ -z "$CREATED_NAME" ]; then
+    echo "[create_linked_branch] ERROR: createLinkedBranch failed:" >&2
+    echo "$RESULT" >&2
+    exit 1
+fi
+
+echo "[create_linked_branch] linked branch created: $CREATED_NAME" >&2
+echo "$CREATED_NAME"

scripts/orchestration/epic_loop.sh

@@ -124,6 +124,7 @@ spawn_agent() {
     local BASE="$6"
     local WT_PATH="$7"
     local AGENT_LOG="$8"
+    local BRANCH="$9"
 
     local BUDGET="$BUDGET_SONNET"
     [ "$MODEL" = "opus" ] && BUDGET="$BUDGET_OPUS"
@@ -134,18 +135,25 @@ spawn_agent() {
 Worktree: ${WT_PATH}
 Worktree index: ${INDEX} (dev server port = ${PORT})
 Base branch: ${BASE}  (remote-tracking ref, déjà fetchée par l'orchestrateur)
+Working branch: ${BRANCH}  (déjà créée et linkée à l'issue via createLinkedBranch — pousse tes commits dessus)
 
 Suivre STRICTEMENT le workflow de .claude/agents/code-dev/AGENT.md.
 
 L'orchestrateur a déjà :
 - créé le worktree en mode --detach sur ${BASE}
 - lancé setup-worktree.sh ${INDEX} (pnpm install + stack docker + .env.local + migrations OK)
 - passé le ticket #${TICKET} en \"In progress\" sur le board
+- **créé la branche ${BRANCH}** sur GitHub, officiellement linkée à l'issue #${TICKET} (la PR que tu ouvriras y apparaîtra automatiquement dans la sidebar Development — pas besoin de comment cross-ref)
 
-Toi : depuis le worktree, créer la branche ticket/${TICKET}-<slug> à partir de
-${BASE} (remote-tracking ref, donc \`git checkout -b ticket/${TICKET}-<slug> ${BASE}\`,
-**pas besoin de re-fetch**), implémenter, créer la PR draft, faire les 4 + 2
-validators internes, itérer sur les RETRY, retourner le verdict final JSON.
+Toi : depuis le worktree, fetch et checkout la branche existante :
+\`\`\`bash
+cd ${WT_PATH}
+git fetch origin ${BRANCH}
+git checkout ${BRANCH}
+\`\`\`
+Puis implémenter, push tes commits sur ${BRANCH}, créer la PR draft (\`gh pr create --base ${BASE#origin/} --head ${BRANCH}\`), faire les 4 + 2 validators internes, itérer sur les RETRY, retourner le verdict final JSON.
+
+**Ne crée PAS une autre branche** (pas de \`checkout -b\`). La branche ${BRANCH} est déjà créée et linkée — utilise-la telle quelle.
 
 REGLES STRICTES (appliquer sans exception) :
 - **N'invoque AUCUN skill built-in** (fewer-permission-prompts, update-config,
@@ -258,12 +266,21 @@ while [ $TICK -lt $MAX_TICKS ]; do
             continue
         fi
 
+        # Create (or reuse) a branch linked to the issue. The PR opened from
+        # this branch will then be auto-attached in the issue's "Development"
+        # sidebar — no manual cross-ref comment needed.
+        BRANCH=$(bash "$SCRIPT_DIR/create_linked_branch.sh" "$TICKET" "$BASE" 2>/dev/null)
+        if [ -z "$BRANCH" ]; then
+            bash "$SCRIPT_DIR/log_event.sh" "$AID" LINKED_BRANCH_FAIL "ticket=$TICKET base=$BASE"
+            continue
+        fi
+
         AGENT_LOG="$TICK_DIR/tick_${TICK}_agent_${TICKET}.json"
         AGENT_FILES[$TICKET]="$AGENT_LOG"
 
-        bash "$SCRIPT_DIR/log_event.sh" "$AID" AGENT_SPAWN "ticket=$TICKET agent=$AGENT model=$MODEL index=$INDEX budget=$([ "$MODEL" = "opus" ] && echo "$BUDGET_OPUS" || echo "$BUDGET_SONNET")"
+        bash "$SCRIPT_DIR/log_event.sh" "$AID" AGENT_SPAWN "ticket=$TICKET agent=$AGENT model=$MODEL index=$INDEX branch=$BRANCH budget=$([ "$MODEL" = "opus" ] && echo "$BUDGET_OPUS" || echo "$BUDGET_SONNET")"
 
-        spawn_agent "$TICKET" "$AGENT" "$MODEL" "$INDEX" "$EPIC" "$BASE" "$WT_PATH" "$AGENT_LOG" &
+        spawn_agent "$TICKET" "$AGENT" "$MODEL" "$INDEX" "$EPIC" "$BASE" "$WT_PATH" "$AGENT_LOG" "$BRANCH" &
         PIDS+=($!)
     done
 

scripts/orchestration/link_pr_to_ticket.sh

@@ -105,15 +105,12 @@ jq -c '.results[]' "$RESULT_FILE" | while read -r result; do
 
     case "$STATUS" in
         validated)
-            # code-dev has set 'In review' and pr ready. Just reset attempt counter.
+            # code-dev has set 'In review' and pr ready. The PR is already
+            # linked to the issue via the linked-branch flow (createLinkedBranch
+            # called by epic_loop.sh before spawning the agent), so no manual
+            # cross-ref is needed. Just reset the attempt counter.
             clear_attempt_labels "$TICKET"
             invalidate_caches "$TICKET"
-            # Cross-reference the PR on the ticket (GitHub's native auto-link
-            # via Closes #N doesn't fire when the PR base isn't the default
-            # branch — typical of our stacked PR / transition-base runs).
-            if [ -n "$PR" ] && [ "$PR" != "null" ]; then
-                bash "$SCRIPT_DIR/link_pr_to_ticket.sh" "$TICKET" "$PR" || true
-            fi
             bash "$SCRIPT_DIR/log_event.sh" "$AID" VALIDATED "ticket=$TICKET pr=$PR"
             echo "  ✓ ticket #$TICKET validated (In review, PR ready)"
             N_VALIDATED=$((N_VALIDATED + 1))