iterative-works/iw-cli

Watch

Fork 0

phase-commit: --items splits commas inside bullet strings, mangling commit body #337

New issue

Closed

opened 2026-04-07 20:12:54 +00:00 by mprihoda · 2 comments

mprihoda commented

2026-04-07 20:12:54 +00:00

(Migrated from github.com)

Problem

./iw phase-commit --items "<bullet 1>,<bullet 2>,..." splits the --items value on every comma, including commas that appear inside a single bullet's text. This produces a mangled commit body where one logical bullet is broken into multiple half-sentences.

Reproduction

./iw phase-commit \
  --title "Date nodes + external/calendar conventions + task_add extension" \
  --items "Domain constants DateNodeType, TracksLinkType, ExternalReferenceNodeType in graph/domain/JournalGraphTypes.scala","JournalService.dateNodeFor lookup-or-create returning DateNodeResolution enum"

Expected commit body:

- Domain constants DateNodeType, TracksLinkType, ExternalReferenceNodeType in graph/domain/JournalGraphTypes.scala
- JournalService.dateNodeFor lookup-or-create returning DateNodeResolution enum

Actual commit body (from iterative-works/procedures commit 1dea03bb):

- Domain constants DateNodeType
- TracksLinkType
- ExternalReferenceNodeType in graph/domain/JournalGraphTypes.scala
- JournalService.dateNodeFor lookup-or-create returning DateNodeResolution enum
- ...

The first bullet got split into three because the parser treated every comma as a separator.

Root cause hypothesis

--items is presumably parsed by a naive string.split(","). This is unsafe whenever a bullet contains a comma — which is common in technical writing (lists of class names, qualified types, etc.).

Fix options

Repeatable flag — accept --items multiple times, one bullet per occurrence: --items "first" --items "second". CLI-idiomatic, no quoting tricks needed.
Different separator — accept a separator that is unlikely to appear in commit text (e.g. ;; or \n). Documented but ugly.
Quoted-CSV parsing — properly handle quoted strings with embedded commas inside the comma-separated list. More complex; user has to remember nested quoting rules.

Option 1 is the cleanest and matches how most CLI tools handle list-valued flags (gh pr create --label foo --label bar).

Impact

Cosmetic but visible: every multi-bullet phase commit produced by the agile workflow's ag-implement orchestration with bullets containing commas will have a mangled commit body. PR descriptions are unaffected (they are generated separately), but git log views are noisy.

Workaround until fixed

Avoid commas inside individual bullets when calling phase-commit --items, or invoke git commit directly.

## Problem `./iw phase-commit --items "<bullet 1>,<bullet 2>,..."` splits the `--items` value on every comma, including commas that appear *inside* a single bullet's text. This produces a mangled commit body where one logical bullet is broken into multiple half-sentences. ## Reproduction ```bash ./iw phase-commit \ --title "Date nodes + external/calendar conventions + task_add extension" \ --items "Domain constants DateNodeType, TracksLinkType, ExternalReferenceNodeType in graph/domain/JournalGraphTypes.scala","JournalService.dateNodeFor lookup-or-create returning DateNodeResolution enum" ``` Expected commit body: ``` - Domain constants DateNodeType, TracksLinkType, ExternalReferenceNodeType in graph/domain/JournalGraphTypes.scala - JournalService.dateNodeFor lookup-or-create returning DateNodeResolution enum ``` Actual commit body (from `iterative-works/procedures` commit `1dea03bb`): ``` - Domain constants DateNodeType - TracksLinkType - ExternalReferenceNodeType in graph/domain/JournalGraphTypes.scala - JournalService.dateNodeFor lookup-or-create returning DateNodeResolution enum - ... ``` The first bullet got split into three because the parser treated *every* comma as a separator. ## Root cause hypothesis `--items` is presumably parsed by a naive `string.split(",")`. This is unsafe whenever a bullet contains a comma — which is common in technical writing (lists of class names, qualified types, etc.). ## Fix options 1. **Repeatable flag** — accept `--items` multiple times, one bullet per occurrence: `--items "first" --items "second"`. CLI-idiomatic, no quoting tricks needed. 2. **Different separator** — accept a separator that is unlikely to appear in commit text (e.g. `;;` or `\n`). Documented but ugly. 3. **Quoted-CSV parsing** — properly handle quoted strings with embedded commas inside the comma-separated list. More complex; user has to remember nested quoting rules. Option 1 is the cleanest and matches how most CLI tools handle list-valued flags (`gh pr create --label foo --label bar`). ## Impact Cosmetic but visible: every multi-bullet phase commit produced by the agile workflow's `ag-implement` orchestration with bullets containing commas will have a mangled commit body. PR descriptions are unaffected (they are generated separately), but `git log` views are noisy. ## Workaround until fixed Avoid commas inside individual bullets when calling `phase-commit --items`, or invoke `git commit` directly.

mph commented

2026-09-01 12:17:53 +00:00

Owner

Merging #471 into this issue as a duplicate. Everything #471 held that this issue did not:

Second sighting — triaging IW-437, committing phase 2. ./iw phase-commit --items "A, and not B,C,D" wrote three bullets, not two. One sentence came out as:

- Type the createPullRequest error channel as ForgeCreateError so a duplicate
  is recognised by what the forge said
- not how the adapter phrased it

Third sighting — IW-476 phase 1 (recorded as that issue's LESSONS.md entry 11). Same shape; the commit message was repaired with git commit --amend.

Why it is easy to miss — the command reports success and echoes the resulting message, so the damage is visible only if the caller reads back the message field it printed.

Fix options, as a design choice rather than a one-liner — an escape syntax, a repeatable --item flag, or a different separator.

If the restriction is kept instead, it must at least be stated in the command's --help. #463 covers giving every command a --help that can guide an agent. Note that commands/phase-commit.scala:2 currently documents the flag as [--items ITEM1,ITEM2,...] and does not warn that the separator is a plain split.

Merging #471 into this issue as a duplicate. Everything #471 held that this issue did not: **Second sighting** — triaging IW-437, committing phase 2. `./iw phase-commit --items "A, and not B,C,D"` wrote three bullets, not two. One sentence came out as: - Type the createPullRequest error channel as ForgeCreateError so a duplicate is recognised by what the forge said - not how the adapter phrased it **Third sighting** — IW-476 phase 1 (recorded as that issue's LESSONS.md entry 11). Same shape; the commit message was repaired with `git commit --amend`. **Why it is easy to miss** — the command reports success and echoes the resulting message, so the damage is visible only if the caller reads back the `message` field it printed. **Fix options, as a design choice rather than a one-liner** — an escape syntax, a repeatable `--item` flag, or a different separator. **If the restriction is kept instead**, it must at least be stated in the command's `--help`. #463 covers giving every command a `--help` that can guide an agent. Note that `commands/phase-commit.scala:2` currently documents the flag as `[--items ITEM1,ITEM2,...]` and does not warn that the separator is a plain split.

mph referenced this issue

2026-09-01 12:17:57 +00:00

phase-commit --items has no way to carry a comma inside one item #471

mph referenced this issue from a commit

2026-09-01 15:35:00 +00:00

workflow: Triage lessons for IW-476

mph referenced this issue

2026-09-01 15:35:39 +00:00

IW-476: The herdr sidebar names a worktree by its key, and a rename sticks #498

mph referenced this issue from a commit

2026-09-01 15:36:36 +00:00

workflow: Triage lessons for IW-436

mph referenced this issue

2026-09-01 15:36:57 +00:00

IW-436: review-state CLI — fix five flag-parsing and update-semantics defects #499

mph referenced this issue from a commit

2026-09-02 06:22:12 +00:00

fix(phase-commit): give each --items occurrence its own bullet

mph referenced this issue

2026-09-02 06:22:57 +00:00

Squash the batch-implement blockers: nine fixes for the phase gate, the CI gate and the review-state card #501

mph commented

2026-09-02 20:55:14 +00:00

Owner

Fixed in PR #501 (merge d1eba9c4). --items is now repeatable: each occurrence is exactly one bullet and a comma inside a value is literal. The flag name is unchanged.

Two follow-ups, both outside this repo or this issue: the kanon workflow skills and the published iw-cli-ops skill still comma-join and must be regenerated; and a value beginning with two dashes is silently dropped by the parser guard, which wants its own issue.

Fixed in PR #501 (merge d1eba9c4). `--items` is now repeatable: each occurrence is exactly one bullet and a comma inside a value is literal. The flag name is unchanged. Two follow-ups, both outside this repo or this issue: the kanon workflow skills and the published `iw-cli-ops` skill still comma-join and must be regenerated; and a value beginning with two dashes is silently dropped by the parser guard, which wants its own issue.

mph closed this issue

2026-09-02 20:55:14 +00:00