gitflow-cli 2.1.0

跨平台 Git 工程化工作流编排框架:统一封装 GitHub / GitLab / GitCode 三大平台,配合 AI Agent Skills,覆盖从需求到发布的完整工程循环。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
# gf-workflow — Reference

Operations reference for the `gf-workflow` orchestrator. Main execution flow: see `SKILL.md`.

## Contract Operations API

### Create Contract

```bash
gf workflow create --title "<issue_title>" --mode <full|fast>
# 输出分配的 ID 与合同路径,例如:
# ✅ Workflow 已创建: wf-2026-08-08-002
#    合同: .cache/workflows/active/wf-2026-08-08-002.json
```

ID 由 CLI 自动分配(Issue #142):扫描 `active/` 与 `archive/` 全部月份目录取当日
最大序号的下一个空位,并用 O_EXCL 原子写入——归档后序号不复用,并发创建不产生
同名合同。**不要手写 `WORKFLOW_ID` 或按 active 数量计数**(旧逻辑已废弃)。

### Update Contract (on Phase completion)

```bash
COMPLETED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
jq --arg phase "$PHASE_NUM" \
   --arg status "complete" \
   --arg completed_at "$COMPLETED_AT" \
   --argjson evidence "$EVIDENCE_JSON" \
  '.phases[$phase].status = $status | .phases[$phase].completed_at = $completed_at | .phases[$phase].evidence = $evidence | .updated_at = $completed_at' \
  ".cache/workflows/active/${WORKFLOW_ID}.json" > "${WORKFLOW_ID}.tmp" \
  && mv "${WORKFLOW_ID}.tmp" ".cache/workflows/active/${WORKFLOW_ID}.json"
```

### Advance to Next Phase (after gate passes)

```bash
jq --arg next "$((PHASE_NUM + 1))" \
   --arg started_at "$COMPLETED_AT" \
  '.current_phase = ($next | tonumber) | .phases[$next].status = "in_progress" | .phases[$next].started_at = $started_at | .updated_at = $started_at' \
  ".cache/workflows/active/${WORKFLOW_ID}.json" > "${WORKFLOW_ID}.tmp" \
  && mv "${WORKFLOW_ID}.tmp" ".cache/workflows/active/${WORKFLOW_ID}.json"
```

### Read Contract

```bash
jq '.current_phase, .phases | to_entries[] | select(.value.status == "in_progress") | .key' \
  ".cache/workflows/active/${WORKFLOW_ID}.json"
```

## Cross-Session Recovery

Workflows may be interrupted at any Phase. New sessions recover via contract + plan doc.

```
New Session Starts
    ↓
1. List .cache/workflows/active/*.json → find workflow with status != "complete"
2. Read current_phase and evidence
3. Load context based on mode and current_phase:
   • Phase 1: No doc needed (start fresh)
   • Phase 2: Read design_doc_path; check mode for Phase 1 exemptions
   • Phase 3: Read spec_path (plan document); check mode for fast skip; also reload `change_surface`/`security_check`/`regression_check` evidence (Issue #344) and `diff_review_status`/`diff_review_path` (Issue #397) alongside `branch`/`worktree_path` — do not re-ask an answered change-surface question; rerun the cheap diff render if resuming before delivery, since HEAD may have changed
   • Phase 4: Read pr_url + review reports and any generated local `diff_review_path`; use get_phase4_steps(mode) to determine remaining steps
4. Resume from current_phase, follow auto-trigger rules
```

**Key principles:** Contract = state machine. Plan doc = execution manual. Design doc = requirement source. All state in contract and documents, no external dependencies.

## Multi-Workflow Concurrency

```
.cache/workflows/
├── active/
│   ├── wf-2026-07-09-001.json  ← feat: TOON
│   └── wf-2026-07-09-002.json  ← fix: pr merge
└── archive/
    └── 2026-07/
        └── wf-2026-07-08-001.json
```

Each workflow uses its own worktree, branch, and contract file — no interference.

### Worktree Path Convention

All worktrees are created at a fixed location within the project: `.worktree/<branch-name>`

- **Path pattern:** `.worktree/feat/<issue-number>-<short-description>`
- **Branch naming:** `feat/<issue-number>-<short-description>` (e.g., `feat/146-worktree-path`)
- **Gitignore:** `.worktree/` is included in `.gitignore`
- **Benefits:**
  - Worktrees remain within the project directory for easy discovery and cleanup
  - Predictable paths for Phase 4 Branch Finish automation
  - No orphaned worktrees in parent directories

**Example:**
```bash
# Phase 3 Step 1: preflight, then create worktree
git status --porcelain                      # classify before forking (see below)
git worktree add .worktree/feat/146-worktree-path -b feat/146-worktree-path main

# Carry this workflow's Phase 1/2 documents INTO the worktree, then commit on the
# feature branch (structure-preserving and portable — macOS has no `cp --parents`)
WORKTREE_PATH=".worktree/feat/146-worktree-path"
for f in docs/superpowers/specs/146-x-design.md docs/superpowers/plans/146-x.md; do
  mkdir -p "$WORKTREE_PATH/$(dirname "$f")"
  cp "$f" "$WORKTREE_PATH/$f"
done

# Backstop: assert every contract-referenced document really landed in the worktree
for f in docs/superpowers/specs/146-x-design.md docs/superpowers/plans/146-x.md; do
  test -f "$WORKTREE_PATH/$f" || { echo "ABORT: $f missing in worktree"; exit 1; }
done

# Symlink shared directories (workflow contracts + Claude config).
# Depth is computed, not hardcoded: worktree_path can be multi-segment
# (branch names follow feat/<issue-number>-<short-description>, so
# .worktree/<branch-name> is routinely 2+ segments deep). See "Why the
# Symlink Depth Is Computed, Not Hardcoded" below for the formula and
# the empirical proof.
segs=$(awk -F/ '{print NF}' <<< "$WORKTREE_PATH")
ups_cache=$((segs + 1))   # .cache/workflows 软链文件位于 .cache/ 下,多一级
ups_claude=$segs          # .claude 软链文件直接位于 $WORKTREE_PATH 下
rel_cache=$(printf '../%.0s' $(seq 1 "$ups_cache"))
rel_claude=$(printf '../%.0s' $(seq 1 "$ups_claude"))
mkdir -p "$WORKTREE_PATH/.cache"
ln -s "${rel_cache}.cache/workflows" "$WORKTREE_PATH/.cache/workflows"
ln -s "${rel_claude}.claude" "$WORKTREE_PATH/.claude"

# Existence self-check — a dangling symlink still passes `test -e`, so verify
# the *resolved target* is a real directory. A failure here means the depth
# formula or worktree_path itself is wrong, not that the contract is missing.
test -d "$WORKTREE_PATH/.cache/workflows" || {
  echo "ABORT: .cache/workflows symlink depth miscalculated — worktree_path=$WORKTREE_PATH segs=$segs ups_cache=$ups_cache"
  echo "Expected to resolve to repo-root .cache/workflows but did not."
  exit 1
}
test -d "$WORKTREE_PATH/.claude" || {
  echo "ABORT: .claude symlink depth miscalculated — worktree_path=$WORKTREE_PATH segs=$segs ups_claude=$ups_claude"
  echo "Expected to resolve to repo-root .claude but did not."
  exit 1
}

# Exclude them from git tracking — writes to the COMMON git dir's info/exclude
# (verified: worktrees do NOT have a per-worktree info/exclude; this file is shared
# by the main tree + all worktrees of this local clone), so it protects every
# worktree, not just this one, without touching the project's own .gitignore.
EXCLUDE_FILE="$(cd "$WORKTREE_PATH" && git rev-parse --git-common-dir)/info/exclude"
grep -qxF '.cache/workflows' "$EXCLUDE_FILE" || echo '.cache/workflows' >> "$EXCLUDE_FILE"
grep -qxF '.claude' "$EXCLUDE_FILE" || echo '.claude' >> "$EXCLUDE_FILE"

cd "$WORKTREE_PATH"
git add docs && git commit -m "docs(workflow): wf-2026-08-30-001 Phase 1-2 artifacts"
cd -
# Only now remove the main-tree copies, so the eventual merge cannot be blocked
rm docs/superpowers/specs/146-x-design.md docs/superpowers/plans/146-x.md

# Phase 4 Branch Finish: Remove worktree
git worktree remove "$WORKTREE_PATH"
```

### Worktree Preflight (Phase 3 Step 1)

`git worktree add` checks out a **committed** state. Anything uncommitted in the main
working tree stays behind — including this workflow's own Phase 1/2 documents, which the
contract references by path. The contract itself survives (it is symlinked), so without a
preflight the executor is handed a `spec_path` that does not exist in its working directory
and plans against a document it cannot read.

Run this before `git worktree add`. `git status --porcelain` empty ⇒ record
`worktree_preflight = "clean"` and proceed.

| Bucket | Match | Action |
|---|---|---|
| **A — workflow artifacts** | paths equal to contract `design_doc_path`, `spec_path`, `ticket_refs[]` | ✋ PAUSE and ask before committing (see below) |
| **B — unrelated dirty files** | everything else reported by `git status` | ✋ PAUSE and ask |
| **C — ignored** | covered by `.gitignore` (`.cache/`, `.worktree/`, `target/`) | Nothing to do (`git status` already omits them) |

**Bucket A requires explicit commit permission too** — per project policy, nothing is
committed without the user's go-ahead, and Phase 1/2 design docs are no exception just
because the workflow itself produced them. `git worktree add` only forks a **committed**
state, so these docs must be committed for the executor to see them — but the commit
itself still needs a yes. Before committing, show the paths and ask:

```
即将把以下设计文档提交到 feature 分支 <branch>,worktree 才能读取到它们:
  <bucket A paths>
是否提交?
  1) 提交    2) 中止(不创建 worktree,回 Phase 2 处理)
```

Choice 2 ⇒ do not run `git worktree add`; leave the contract in Phase 3 for resume.
Choice 1 ⇒ commit to the feature branch, never to `base_branch`: entering Phase 3 must
not leave commits on a shared branch as a side effect.

**Why the main-tree copies must be removed after committing.** Verified behaviour: if the
untracked originals stay, the later merge fails with
`untracked working tree files would be overwritten by merge … Aborting`. Removing them
after the worktree commit is safe because the content is preserved in git and comes back on
merge. Remove only after asserting the commit succeeded.

**Bucket B is never auto-committed and never deleted** — it is somebody else's work. Offer
exactly these four options, and record the choice in `worktree_preflight`:

```
主工作区有与本工作流无关的改动:
  <paths from git status --porcelain>

它们不会进入 worktree。请选择:
  1) 单独提交    2) git stash    3) 留在主工作区继续    4) 中止
```

Choice 3 ⇒ `worktree_preflight = "user_left_dirty"` and list the paths in
`unresolved_dirty_paths`, so Phase 4 and any later reader knows what was deliberately
abandoned in the main tree. Choice 2 ⇒ `"user_stashed"`. Choice 4 ⇒ `"aborted"`, keep
the contract in Phase 3 for resume.

A non-empty bucket A that the user approved and that was committed ⇒ `"artifacts_carried"`.
A non-empty bucket A that the user declined to commit ⇒ `"aborted"`, same as Bucket B
choice 4 — the contract stays in Phase 3 for resume.

**Every execution mode must run this preflight.** Modes ① and ② let the *executor* create
the worktree, so the orchestrator cannot rely on having checked the tree itself — the
handoff text must carry these steps verbatim. See `Phase 3 Execution Modes` below.

### Change-Surface Detection (Phase 3 Step 3, Issue #344)

Phase 3 Step 3 决定是否阻断式运行 `gf-security-check` / `gf-regression`,判定依据是 Step 1 已经记录的 `base_branch`——**不重新猜测 base ref**,直接复用:

```bash
diff_files="$(git diff --name-only "$base_branch"...HEAD)"
```

(`gf-quality` 的 Gate 3 曾经因为用 `${BASE_REF:-origin/main}` 猜测 base ref,在 GitLab/GitCode 默认分支不是 `main` 时解析失败;这里直接吃 Phase 3 Step 1 的既有产出,不重蹈覆辙。)

两条独立规则,各自判定,互不影响:

| 检查 | 触发路径模式 |
|---|---|
| `gf-security-check` | `Cargo.toml`、`Cargo.lock`、`**/Cargo.toml`(workspace 内任意 crate)、`deny.toml` |
| `gf-regression` | `apps/cli/src/**`、`crates/core/src/**`、`crates/github/src/**`、`crates/gitlab/src/**`、`crates/gitcode/src/**` |

都不命中(例如纯文档/spec/skill 文本改动)→ `change_surface = "docs_only"`,两项检查都记 `not_triggered`,不实际调用任何一个 skill。

**为什么必须在 Step 3(旧 Step 3 交付选择之前)而不是 Phase 4:** local_merge 路径下,旧的 Step 3(现 Step 4)会立刻把分支合并进 `base_branch`。如果检查放在 Phase 4(交付之后),发现问题时代码已经进了 `base_branch`,"阻断式"就名不副实了——所以必须卡在合并动作发生之前。

### Conditional Diff Review (Phase 3 Step 4, Issue #397)

`skills/gf-workflow/SKILL.md` → Phase 3 Step 4 defines the trigger and the
scan/render commands. It runs before the delivery choice so both PR and local
merge paths use the same `base_branch...HEAD` diff. The generated JSON/HTML
live in the main worktree's ignored `.cache/diff-review/<workflow_id>.*`, which
survives removal of the feature worktree. Record `diff_review_status` even when
not triggered or when rendering fails; record `diff_review_path` only on
success. This local file path belongs in the workflow summary, not in a remote
Issue/PR comment.

### Why the Symlink Depth Is Computed, Not Hardcoded

A relative symlink resolves starting from the directory that *contains* the
symlink file, not from `worktree_path` itself. `$WORKTREE_PATH/.cache/workflows`
lives inside `$WORKTREE_PATH/.cache/`, **one segment deeper** than
`$WORKTREE_PATH` — but `$WORKTREE_PATH/.claude` lives directly at
`$WORKTREE_PATH`, with no extra segment. The two symlinks therefore need two
different `../` counts:

```
ups_cache  = (number of "/"-separated segments in worktree_path) + 1
ups_claude = (number of "/"-separated segments in worktree_path)
```

An earlier version of this formula used `ups_cache`'s value for both
symlinks, which left `.claude` dangling (it resolved one level above the
repo root) — see Issue #353.

**Verified empirically** (not inferred from documentation) with real
`mkdir` + `ln -s`:

| `worktree_path` | segments | `ups_cache` | `ups_claude` |
|---|---|---|---|
| `.worktree/foo` (single-segment) | 2 | 3 | 2 |
| `.worktree/feat/89-desc` (branch name contains `/`, per the `feat/<issue-number>-<short-description>` convention) | 3 | 4 | 3 |

The old hardcoded `../../` (2 levels) was wrong even for the single-segment
case it was presumably written for — it only reaches `.worktree/`, one level
short of the repo root, in every case. A branch name containing `/` (the
routine case, not an edge case — see the naming convention above) simply
made the shortfall larger and easier to hit. The `ups_cache`/`ups_claude`
split is correct for both symlinks, and the post-creation
`test -d "$WORKTREE_PATH/.cache/workflows"` / `test -d "$WORKTREE_PATH/.claude"`
checks catch any future regression of either formula by refusing to proceed
silently — a dangling symlink otherwise looks identical to a missing
contract to every downstream reader (see Issue #322's real-world report:
this exact ambiguity cost significant debugging time downstream).

### Why These Symlinks Must Never Reach the Main Branch

`.cache/workflows` and `.claude` inside a worktree are relative symlinks
(e.g. `../../../.cache/workflows`, `../../.claude` for a two-segment
`worktree_path` — see `ups_cache`/`ups_claude` above). If either is ever committed, `git ls-files -s`
shows a `120000` (symlink) mode entry for that path. A clone made from a commit carrying
that entry re-creates the symlink pointing at `../../<name>` **relative to that clone's own
location** — which, outside the original working tree that produced it, resolves to a
directory that does not exist or belongs to something else entirely.

**Verified real-world impact (Issue #318):** in the downstream project
`iproost/proxy/api-src`, `.cache/workflows` and `.claude/.claude` had been committed as
symlinks (commit `e7f4254`, swept in by an unrelated broad `git add`). Resolved from that
repo's root, `.cache/workflows -> ../../.cache/workflows` landed **outside the repository**,
in a directory shared by other checkouts. Every subsequent gf-workflow contract read/write in
that project actually happened against that external shared path — including a case where a
background research fork and the main session concurrently touched the same contract file and
cross-wrote each other's Phase 3/4 progress.

**Why `info/exclude` fixes this at the source, not just in this repo.** A linked worktree has
no `info/exclude` of its own: `git rev-parse --git-common-dir` from inside any worktree
resolves to the *main* repository's `.git`, and `info/exclude` always lives there — confirmed
by writing to it from a worktree and observing `git status` change in a sibling worktree and
the main tree alike. So the one write performed right after `ln -s` (see the example above)
protects the main tree and every worktree this clone will ever create, permanently, without
depending on that project's own `.gitignore` ever mentioning `.cache/` or `.claude/` — which is
exactly the gap that let `e7f4254` happen upstream.

**Belt and suspenders.** `info/exclude` only stops *new* accidental adds; it does nothing for
a symlink that is already staged in a commit about to leave `branch` (rebase, cherry-pick,
`git commit -a` racing the exclude write, etc.). That is why Phase 3 Step 4 in `SKILL.md` also
scans the diff immediately before delivery:

```bash
git diff --summary "$BASE_BRANCH"...HEAD | grep 'create mode 120000'
```

A hit means some commit on `branch` added a symlink that `base_branch` doesn't have. Treat it
as a hard stop: show the path(s), and let the user choose to drop the offending commit/entry
or explicitly confirm it is an intentional, unrelated symlink before delivery proceeds.

## Lifecycle Management

| Status | Location | Retention | Cleanup |
|--------|----------|-----------|---------|
| active | `.cache/workflows/active/` | In progress | Move to archive on completion |
| archive | `.cache/workflows/archive/YYYY-MM/` | 90 days | `gitflow workflow cleanup --older-than 90` |

## CLI Integration

```bash
gitflow workflow create --title "<issue_title>" --mode <full|fast>  # 创建合同(自动分配当日不重复 ID)
gitflow workflow list                      # List active workflows
gitflow workflow status <workflow_id>      # View contract details
gitflow workflow archive <workflow_id>     # Archive completed workflow(目标已存在时拒绝覆盖)
gitflow workflow cleanup --older-than 90   # Clean up expired archives
```

## Branch Finish Operations

Phase 4 Step 4 commands. All operations are local-only (no push).

### Detect PR Merge Status

```bash
gf pr view  # parse "merged" field from output
```

### Execute Branch Cleanup (after user confirmation)

```bash
# Return to main working tree
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

# Switch to base branch and update
git checkout "$BASE_BRANCH"
git pull origin "$BASE_BRANCH"

# Delete feature branch (safe: refuses if unmerged)
git branch -d "$FEATURE_BRANCH"

# Remove worktree
git worktree remove "$WORKTREE_PATH"
git worktree prune

# Clean stale remote tracking refs
git fetch --prune origin
```

### Skip Conditions

| Condition | Action |
|-----------|--------|
| `base_branch` empty/missing | Skip entire Branch Finish |
| `worktree_path` empty | Skip worktree removal, still attempt branch delete |
| PR not merged | Skip all cleanup, set `branch_cleaned = false` |
| `git branch -d` fails | Warn, preserve branch, continue to archive |
| User declines confirmation | Set `branch_cleaned = false`, continue to archive |

## Dual-Source Skill Resolution (Issue #141)

gf-workflow runs on ONE external skill source: `superpowers` or `mattpocock/skills`.
SKILL.md phase steps use role aliases; actual names resolve from the tables below.
**This section is the single point of maintenance** — upstream renames are fixed here only.

### Sentinels (shared authoritative definition)

Mirrored by the Rust constants in `apps/cli/src/commands/skills.rs`
(`SUPERPOWERS_PLUGIN_PREFIX` / `MATTPOCOCK_PLUGIN_PREFIX` /
`SUPERPOWERS_BARE_SENTINELS` / `MATTPOCOCK_BARE_SENTINELS`) used by install-time
Step 0. Change both sides together.

| Source | Model-invoked sentinel | User-invoked sentinel |
|---|---|---|
| superpowers | `superpowers:brainstorming`, or bare `brainstorming` + `writing-plans` | — |
| mattpocock | `mattpocock-skills:grilling`, or bare `grilling` | `to-spec` |

Model-invoked sentinels must appear in the session available-skills list. User-invoked
sentinels normally do not appear there because their frontmatter sets
`disable-model-invocation: true`; locate them only under skill roots declared by the
environment and verify both the frontmatter `name` and that flag. They also count if the
session explicitly exposes them. A partial hit counts as absent; report each missing
sentinel.

### Detection & Recording

- Mechanism: at Bootstrap, BEFORE the contract exists, introspect the session
  available-skills list for model-invoked sentinels. For explicit user-invoked sentinels,
  inspect only the environment-declared skill roots; this scoped lookup is authoritative
  because those skills are intentionally hidden from model invocation. All other
  filesystem probing remains diagnostics-only.
- Both present → ask the user which source this workflow uses (no default priority).
- Neither present → ask: continue inline (`skill_source: "inline"`) or abort (no contract).
- Record after contract creation:

```bash
jq --arg src "<superpowers|mattpocock|inline>" \
   '.skill_source = $src | .updated_at = (now | todate)' \
   ".cache/workflows/active/${WORKFLOW_ID}.json" > tmp && mv tmp ".cache/workflows/active/${WORKFLOW_ID}.json"
```

- Resume: reuse `skill_source` from the contract; re-verify sentinels are still present;
  if vanished, re-run the neither-present prompt.

### Dual-Source Mapping Table

| Role alias | superpowers | mattpocock | Invocation form |
|---|---|---|---|
| Clarification | `brainstorming` | `grilling` | model-invoked / model-invoked |
| Spec | (merged into brainstorming design doc) | ✋ `/to-spec` (local-only) | — / user-invoked |
| Issue resolution | Reuse a verified open Issue; otherwise `gf-issue-create` | Same; `/to-spec` stays local-only | gf CLI |
| Issue review | `gf-issue-review` | `gf-issue-review` (unchanged) | gf CLI |
| Planning | `writing-plans` | ✋ `/to-tickets` | model-invoked / user-invoked |
| Quality gate | `gf-quality` | `gf-quality` (unchanged) | gf CLI |
| Execution engine | `subagent-driven-development` (same-session) / `executing-plans` (new window) — per GO gate | ✋ `/implement` per ticket (internal `/tdd` mandatory) | per mode / user-invoked |
| Execution review | SDD built-in two-stage review | `code-review` (driven inside `/implement`) | — |
| Delivery review | `gf-review` | `gf-review` (unchanged; no extra code-review pass) | gf skill |
| Triage (full mode) | `gf-issue-triage` | `gf-issue-triage` (unchanged; mattpocock `triage` NOT adopted) | gf skill |
| Pipeline analysis | `gf-pipeline-analyzer` — optional, asked at Phase 4 entry, default yes (all modes) | (unchanged) | gf skill |

### Source Branch Semantics

**Invariants (both sources):** four-phase state machine, three gates, contract evidence
semantics, all `gf-*` steps, mandatory TDD + code review, mode matrix (full/standard/fast).

**mattpocock path:**

- **Prerequisite:** `docs/agents/issue-tracker.md` exists (`setup-mat-pocock-skills`
  output). Missing → ask the user: run `setup-mat-pocock-skills` now (one-time) or abort.
- **Phase 1:** `grilling` (auto) → ✋ PAUSE prompting:

  > 请运行 `/to-spec`:综合当前对话撰写 spec,写入本地文件
  > `docs/specs/<workflow-id>-spec.md`。**只写本地,不发布 tracker、不打标签。**

  Verify the local spec exists afterwards. **Fallback** (constraint failed / skill refused):
  the orchestrator writes the design doc itself from the grilling record, bypassing `to-spec`.
  Then reuse the verified open Issue if one covers the task; otherwise
  `gf-issue-create` creates one. `/to-spec` never publishes to the tracker.
  `gf-issue-review` reviews the resolved Issue. Evidence: `issue_url`,
  `comment_id`, `design_doc_path`.
- **Phase 2:** ✋ PAUSE prompting `/to-tickets` with the Phase 1 spec reference.
  `to-tickets` publishes tickets per the configured tracker (local `.scratch/<feature>/issues/`
  files or real tracker issues) and includes its own breakdown quiz. Its rule "do NOT close
  or modify any parent issue" is compatible with gf-workflow. Orchestrator records
  `ticket_refs` (paths/URLs) and sets `spec_path` = the Phase 1 spec file. Gate 2→3
  presents the ticket list + blocking edges.
- **Phase 3:** worktree per chosen execution mode; per ticket in dependency order
  (frontier): ✋ PAUSE → user runs `/implement` (internal `/tdd` + `/code-review` + commit);
  suggest `/clear` between tickets (context recovery via contract + ticket files).
  `gf-pr-create` with `Closes #<issue>`, then `make test`.
- **Phase 4:** identical to superpowers ([pipeline ∥ triage[full] ∥ gf-review] →
  dogfooding[full] → Branch Finish → archive). `code-review` already ran inside `/implement`.
- **Evidence mapping:** `design_doc_path` ← local spec file; `spec_path` ← same spec file
  (what `to-tickets` consumed); `ticket_refs` ← ticket paths/URLs.

**inline source (both absent, user chose to continue):** orchestrator performs each phase
inline — self-interview, self-written design doc/plan, TDD loop with a review subagent.
Evidence fields follow the superpowers shape. Degraded but explicit.

### Phase 3 Execution Modes (GO gate)

Gate 2→3 = plan approval + execution-mode choice. Same-session execution left the default
menu (SDD objection: approving a plan ≠ authorizing hours of autonomous subagent fan-out;
same-session SDD hijacks the conversation once started).

| Mode | Description | Availability |
|---|---|---|
| ① Manual new window ⭐default | Print opening guidance: worktree path (or creation command) + contract recovery command (`gf workflow status <id>` + plan doc path) + **Worktree Preflight steps verbatim**; new window creates branch/worktree itself and runs `executing-plans` (superpowers) or per-ticket `/implement` (mattpocock); user reports back, orchestrator verifies evidence | both sources |
| ② Same-session | Current behavior: orchestrator creates worktree and drives the engine inline | explicit request only |

**Why no background-executor mode:** an earlier mode dispatching a harness-isolated,
non-interactive executor (`isolation: worktree` + `run_in_background`) was removed after
Issue #325 confirmed two structural defects that cannot be fixed by documentation alone:
(1) such an isolated executor's git operations are hard-restricted to its own
harness-managed worktree — it cannot target `.worktree/<branch-name>`; (2) that
harness-managed worktree forks from `origin/<default-branch>`, not from the orchestrator's
`base_branch`, so any resulting branch would silently miss `base_branch`-only commits.
See `specs/gf-workflow-mode1-removal-design.md` for the investigation.

Quality compensation: `executing-plans` (light path) lacks per-task review → gates
compensate (`make test` before PR + Phase 4 `gf-review`). SDD carries per-task review built in.

### Phase 3 Execution Error Classification (Issue #336)

`skills/gf-workflow/SKILL.md`'s top-level Error Handling table covers orchestrator-level
failures (missing contract, gate check failed). It does not cover failures that occur
**during Phase 3 execution** (the implementation engine actually running build/test/lint
commands, merging, or queuing a merge). This table fills that gap.

**Two categories were adapted, not ported verbatim, from `smallnest/goal-workflow`'s
`loop-it` skill** — this repo's semantics differ:

- `merge_conflict`: Phase 3 Step 4's local-merge path already aborts and hands back to the
  user on conflict (`git merge --abort`, branch/worktree untouched). The table below keeps
  that behavior — zero automatic retries — rather than inventing a new auto-resolve loop.
- `ci`: Phase 3 Step 6 queues the merge (`gf pr merge --auto`) against a specific SHA that
  has already passed checks. Pushing a new commit to that branch after queuing does **not**
  get carried into the queued check (verified empirically) — so `ci` failures can never be
  "fixed" by pushing more commits onto the queued branch. A fix requires a fresh commit and
  a fresh queue entry, which restarts at Step 2, not a retry of Step 6.

| Category | Trigger | Recovery | Retry Cap |
|---|---|---|---|
| `build` | Compile/build failure | Fix code, rebuild | 3 |
| `test` | Test failure | Fix code or test, rerun | 3 |
| `lint` | `cargo clippy` / `cargo fmt` (or per-language equivalent) failure | Fix, rerun `make lint` | 3 |
| `merge_conflict` | `git merge` conflict (Phase 3 Step 4, local-merge path) | `git merge --abort`; leave `branch`/worktree untouched; escalate to user immediately — no automatic retry. User resolves manually, then Step 4 is re-run as a fresh attempt (not counted against this cap) | 0 |
| `ci` | Required check fails after the merge queue (Phase 3 Step 6, PR path) | Never push a new commit to the already-queued branch. `gf` has no re-run command for an existing pipeline run — ✋ PAUSE and ask the user to rule out flakiness via the platform's own re-run action (e.g. GitHub Actions "Re-run failed jobs", or that platform's native CLI); if it still fails, a real fix requires a new commit + a fresh queue entry — that restarts at Step 2, it is not a retry of Step 6 | 1 (one user-triggered same-SHA re-run only) |
| `auth` | `gf auth status` failure / API 401/403 | No retry — escalate to user immediately (`auth login` is a human action) | 0 |
| `rate_limit` | API 429 / platform throttling | No retry — escalate to user immediately (waiting or rotating credentials is a human decision) | 0 |
| `network` | Transient network error (timeout, connection reset) | Retry with backoff | 3 |
| `issue_unclear` | Execution engine hits a requirement ambiguity it cannot resolve | Not a retryable error — pause and ask the user for clarification; never guess. Each clarification round is a fresh attempt, not counted against a retry cap | 0 |
| `unknown` | Uncategorized error | Capture the full error, retry once conservatively; escalate if it recurs | 1 |

**Escalation contract.** When a category's retry cap is reached (or immediately, for the
four 0-cap categories — `merge_conflict`, `auth`, `rate_limit`, `issue_unclear`): stop
retrying automatically, show the user the error category, every recovery attempt tried so
far with its outcome, and the retry count, then wait for the user's decision (continue /
change strategy / abort the task). Never silently give up and never silently switch
delivery mode (e.g. falling back from local-merge to PR) as a substitute for asking.

### Worktree Location Convention (Issue #146)

All gf-workflow worktrees are created at a **fixed path**: `.worktree/<branch-name>`.

- Branch name format: `feat/<issue-number>-<short-description>`
- Full path example: `.worktree/feat/141-dual-skill-sources`
- `.worktree/` is in `.gitignore` → worktrees are automatically excluded from version control
- Phase 4 Branch Finish cleanup uses this predictable path for `git worktree remove`
- New-window executors create worktrees at this same location
## Workflow Recommendation (Issue #383)

At Bootstrap, make a short, reviewed JSON input with `title`, `summary` (at most 512 bytes), `labels`, and optional `userMode`; store it under ignored `.cache/workflows/`. Include only the task description and allowed issue labels. Do not include logs, environment variables, credentials, private URLs, or full repository content. Run `gf workflow recommend --input <path>` for deterministic advice. If the user explicitly opts into Jev and `GF_DECISION_PROVIDER=jev` is configured, add `--live`; otherwise no provider call occurs. A saved typed `DecisionResponse` can be replayed with `--response <path>` without a provider. The command emits `ruleMode`, optional `suggestedMode`, `effectiveMode`, `status`, `riskFlags`, and `candidatePhases`. See `docs/workflow-recommendation.md` for the schema and examples.

The command does not create a contract or change a gate. Use `effectiveMode` only as the rule or explicit user choice when creating the contract. Display model conflicts and low confidence for review; do not treat `suggestedMode`, `riskFlags`, or `suggestedSkills` as permission to run or skip steps. If the command is unavailable in an older `gf` binary, apply the deterministic Mode Auto-Detection table in `SKILL.md`.