forgedock 1.1.11 → 1.2.0

package/commands/issue.md

@@ -1,6 +1,6 @@
 ---
 description: Create a well-structured GitHub issue that the pipeline can consume reliably
-argument-hint: [description of the problem or feature]
+argument-hint: "[description of the problem or feature] [--dry-run] | --title \"...\" --body-file <path> --label \"...\" [--milestone \"...\"] [--dry-run]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -11,11 +11,206 @@ argument-hint: [description of the problem or feature]
 
 You create GitHub issues with the exact structure the `/work-on` pipeline expects. Every issue you create must give the investigation agent enough context to find the right files on the first pass — no vague descriptions, no missing domains, no ambiguous scope.
 
+`/issue` is the structured create-hook for issue creation across the pipeline — it enforces the canonical template, reads code before drafting, runs dedup, and validates mandatory sections. Because those checks are deterministic, `/issue` **creates the issue by default once they pass** — it does not wait for a human to approve the draft. Pass `--dry-run` to review the draft without creating anything (see Argument Parsing below).
+
+`/issue` also accepts a **programmatic invocation form** for callers that have already composed a title, body, labels, and (optionally) a milestone — e.g. `Skill(skill="issue", args="--title \"fix: ...\" --body-file /tmp/body.md --label bug --label P2")`. This form skips the free-text parsing (Phase 1) and LLM drafting (Phase 3) entirely, but still runs the same dedup and body-validation correctness gates as the interactive path. See **Programmatic Invocation Contract** below.
+
 **Agent model policy**: `model: "{DEFAULT_MODEL}"` — resolved from forge.yaml `agents.default_model`, else "sonnet" (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 **NEVER use plan mode (EnterPlanMode).**
 
 ---
 
+## Argument Parsing
+
+| Flag | Effect |
+|------|--------|
+| (none) | Default — read code, dedup, draft, validate, then create the issue immediately. No pre-create confirmation prompt. |
+| `--dry-run` | Draft and validate as normal, but STOP before `gh issue create` — print the draft (or batch draft table) for human review instead of creating it |
+| `--title "..."` | **Activates programmatic mode.** Supplies the final issue title directly — skips Phase 1 (parse) and Phase 3 (draft) entirely. See Programmatic Invocation Contract below. |
+| `--body "..."` | Supplies the final issue body directly (programmatic mode only). Mutually exclusive with `--body-file`. |
+| `--body-file <path>` | Supplies the final issue body by reading it from a file (programmatic mode only). Mutually exclusive with `--body`. |
+| `--label "..."` | Adds one label. Repeatable (`--label bug --label P2`) — labels accumulate. Programmatic mode only. |
+| `--milestone "..."` | Supplies the milestone title directly, skipping the Phase 2E milestone lookup. Programmatic mode only, optional. |
+
+```bash
+DRY_RUN=false
+PROGRAMMATIC_TITLE=""
+PROGRAMMATIC_BODY=""
+PROGRAMMATIC_BODY_FILE=""
+PROGRAMMATIC_LABELS=()
+PROGRAMMATIC_MILESTONE=""
+
+# Positional/flag parsing. $ARGUMENTS is a single opaque string (the invoking
+# agent's raw args, e.g. from `Skill(skill="issue", args="--title \"fix: ...\" ...")`)
+# — it is NOT pre-tokenized by any harness, and a naive `ARGS=($ARGUMENTS)` would
+# word-split on whitespace without honoring embedded quote characters (a literal
+# `"` inside the string is not shell syntax at this point), fragmenting any
+# multi-word `--title`/`--body` value (forge#2094).
+#
+# Do NOT tokenize via `eval "set -- $ARGUMENTS"`. An earlier fix for #2094 used
+# exactly that — it is quote-aware, but `eval` re-parses and EXECUTES the full
+# substituted string as shell code: any unescaped `$(...)`, backtick, `;`, `|`,
+# or `&&` embedded in a caller-supplied title/body value runs as a command
+# during parsing, not just as text. `/issue` is invoked programmatically by
+# other automation (audit tools, /work-on decomposition, review-finding
+# creation — see commands/work-on.md, commands/review-pr.md,
+# commands/review-pr-staging.md, commands/test-gate.md) with less-trusted
+# strings, so this is a real call-site injection surface, not a theoretical one.
+#
+# Use `xargs` instead: it applies the same quote/backslash-aware word-splitting
+# a shell command line would (so `--title "fix: billing crash"` still yields
+# ONE token), but — unlike `eval` — it never expands `$(...)`, never expands
+# backticks, and never executes anything. NUL-delimit the output (`printf
+# '%s\0'` / `xargs -n1 ... -0`) so tokens containing embedded newlines still
+# round-trip correctly through `mapfile -d ''`.
+#
+# `mapfile -d ''` requires bash >= 4.4 — consistent with the minimum this
+# pipeline already assumes elsewhere (e.g. `resolve_script()`'s tier-dispatch
+# in work-on.md), so this is not a new constraint.
+#
+# Do NOT silence xargs's exit status with `2>/dev/null`: xargs has a
+# platform-dependent max single-argument length (POSIX guarantees at least
+# 4096 bytes; Linux/macOS observed limits are far higher but not unbounded).
+# A token exceeding that ceiling makes xargs fail loudly — suppressing stderr
+# would turn that into a silent truncation instead, which is worse than the
+# word-splitting bug this whole block exists to fix. `--title`/`--body` are
+# short by convention; `--body-file` (the mechanism every current caller
+# actually uses for large content — see commands/work-on.md,
+# commands/review-pr.md, commands/review-pr-staging.md, commands/test-gate.md,
+# commands/validate.md) is unaffected, since only the file *path* passes
+# through this tokenizer, not the file's contents.
+#
+# `mapfile -d '' -t ARGS < <(cmd)` cannot observe `cmd`'s exit status —
+# process substitution runs in a detached subshell, and mapfile's own exit
+# status only reflects whether the read succeeded, not the upstream command
+# (verified: `mapfile -d '' -t A < <(false; printf 'x\0')` exits 0). Route
+# through a temp file instead so the real xargs exit status is captured.
+ARGS_TMP=$(mktemp)
+if ! printf '%s' "$ARGUMENTS" | xargs -n1 printf '%s\0' > "$ARGS_TMP"; then
+  echo "ERROR: failed to tokenize \$ARGUMENTS — a single token may exceed xargs's max argument length. Use --body-file for large content instead of inline --body." >&2
+  rm -f "$ARGS_TMP"
+  exit 1
+fi
+mapfile -d '' -t ARGS < "$ARGS_TMP"
+rm -f "$ARGS_TMP"
+
+# Flag-mode gate: only run the flag-parsing loop (and its hard-error on
+# unrecognized --flags below) when at least one token EXACTLY matches a
+# recognized flag. Free-text invocations (the "(none)" row above) are plain
+# English descriptions and may legitimately contain a "--something" substring
+# as part of the prose (e.g. "fix: crash when using --verbose flag") — those
+# must fall through untouched to Phase 1's free-text parser, not be treated
+# as a caller typo. Without this gate, the --*) error arm below would abort
+# on any free-text description that happens to mention a flag name. See
+# forge#2096 (loop content) for why unrecognized flags must fail loudly once
+# we ARE in flag mode.
+LOOKS_LIKE_FLAG_MODE=false
+for arg in "${ARGS[@]}"; do
+  case "$arg" in
+    --dry-run|--title|--body|--body-file|--label|--milestone)
+      LOOKS_LIKE_FLAG_MODE=true
+      break
+      ;;
+  esac
+done
+
+i=0
+while [ "$LOOKS_LIKE_FLAG_MODE" = "true" ] && [ $i -lt ${#ARGS[@]} ]; do
+  arg="${ARGS[$i]}"
+  case "$arg" in
+    --dry-run) DRY_RUN=true ;;
+    --title|--body|--body-file|--label|--milestone)
+      # Each of these flags requires a value token immediately after it. A flag
+      # with no following token (e.g. --title as the last argument) is a usage
+      # error, not an empty value — fail loudly instead of silently proceeding
+      # with PROGRAMMATIC_TITLE="" (which would otherwise mis-detect as
+      # non-programmatic mode and mask the caller's mistake).
+      if [ $((i+1)) -ge ${#ARGS[@]} ]; then
+        echo "ERROR: $arg requires a value"
+        exit 1
+      fi
+      i=$((i+1))
+      case "$arg" in
+        --title) PROGRAMMATIC_TITLE="${ARGS[$i]}" ;;
+        --body) PROGRAMMATIC_BODY="${ARGS[$i]}" ;;
+        --body-file) PROGRAMMATIC_BODY_FILE="${ARGS[$i]}" ;;
+        --label) PROGRAMMATIC_LABELS+=("${ARGS[$i]}") ;;
+        --milestone) PROGRAMMATIC_MILESTONE="${ARGS[$i]}" ;;
+      esac
+      ;;
+    --*)
+      # Unrecognized flag (e.g. a mistyped --titel instead of --title). Fail
+      # loudly instead of silently discarding it — a silently-ignored flag
+      # can fail open into the interactive/free-text path (PROGRAMMATIC_MODE
+      # stays false because PROGRAMMATIC_TITLE never gets set) with no
+      # diagnostic pointing at the caller's typo. See forge#2096.
+      #
+      # Deliberately NOT a bare `*)` catch-all: free-text invocations (the
+      # "(none)" row in the Argument Parsing table above, e.g. "the billing
+      # page crashes when credits hit zero") tokenize into plain words with
+      # no leading `--`, and those words are intentionally NOT flags — they
+      # are consumed later via $ARGUMENTS as a whole by Phase 1's free-text
+      # parser. Only tokens that look like a flag (start with `--`) but
+      # don't match a known one are a caller mistake worth failing loudly on.
+      echo "ERROR: unrecognized flag: $arg" >&2
+      exit 1
+      ;;
+  esac
+  i=$((i+1))
+done
+
+# PROGRAMMATIC_MODE is true iff --title was supplied. Every other structured flag
+# (--body/--body-file/--label/--milestone) is meaningless without a title and does
+# NOT, on its own, activate programmatic mode — this avoids a caller accidentally
+# triggering the skip-Phase-1/3 path with a partial/malformed flag set.
+if [ -n "$PROGRAMMATIC_TITLE" ]; then
+  PROGRAMMATIC_MODE=true
+else
+  PROGRAMMATIC_MODE=false
+fi
+```
+
+`--dry-run` never bypasses a correctness gate — the Phase 2D dedup STOP and the `--force` human-override rule (see Phase 2D) apply identically whether or not `--dry-run` is set, and identically in both interactive and programmatic mode.
+
+### Programmatic Invocation Contract
+
+For callers that have already composed a title, body, labels, and (optionally) a milestone — audit tools, `/work-on` decomposition, pipeline-health proposals, review-finding creation, and similar automation — pass `--title` to activate programmatic mode. This bypasses Phase 1 (free-text parsing) and Phase 3 (LLM drafting) entirely; Phase 2D (dedup) and body validation still run.
+
+**Required**: `--title "TEXT"` and exactly one of `--body "TEXT"` / `--body-file <path>`.
+**Optional**: `--label "NAME"` (repeatable, zero or more), `--milestone "TITLE"`, `--dry-run`.
+
+If `--title` is present but neither `--body` nor `--body-file` is supplied, or both are supplied, this is a usage error: print `ERROR: programmatic mode requires exactly one of --body or --body-file` and STOP — do not fall through to Phase 2D or Phase 4B.
+
+```bash
+if [ "$PROGRAMMATIC_MODE" = "true" ]; then
+  if [ -n "$PROGRAMMATIC_BODY" ] && [ -n "$PROGRAMMATIC_BODY_FILE" ]; then
+    echo "ERROR: programmatic mode requires exactly one of --body or --body-file (both given)"
+    exit 1
+  elif [ -z "$PROGRAMMATIC_BODY" ] && [ -z "$PROGRAMMATIC_BODY_FILE" ]; then
+    echo "ERROR: programmatic mode requires exactly one of --body or --body-file (neither given)"
+    exit 1
+  elif [ -n "$PROGRAMMATIC_BODY_FILE" ]; then
+    # Fail loudly on a missing/unreadable file — do NOT let a failed `cat` fall
+    # through as an empty $PROGRAMMATIC_BODY. An empty body would otherwise look
+    # like "no body given" to Phase 3F below, which would silently repair it
+    # with placeholder-only stub sections instead of surfacing the caller's
+    # file-path mistake as an error, same fail-loudly convention as the
+    # both/neither check directly above.
+    if [ ! -r "$PROGRAMMATIC_BODY_FILE" ]; then
+      echo "ERROR: --body-file '$PROGRAMMATIC_BODY_FILE' is missing or unreadable"
+      exit 1
+    fi
+    PROGRAMMATIC_BODY=$(cat "$PROGRAMMATIC_BODY_FILE")
+  fi
+fi
+```
+
+**Routing** (see also Phase 1's routing guard below): when `PROGRAMMATIC_MODE=true`, skip directly from here to **Phase 2D** using `{PROPOSED_TITLE}` = `$PROGRAMMATIC_TITLE` — Phase 1 (parse) and Phase 3 (draft) do not run. After Phase 2D passes, run **Phase 3F: Programmatic Pre-Create Validation** (below), then proceed to the unmodified Phase 4 (create). `{PRIORITY_LABEL},{CATEGORY_LABEL}` in Phase 4B is the comma-join of `PROGRAMMATIC_LABELS[@]`; the milestone flag is included iff `PROGRAMMATIC_MILESTONE` is non-empty.
+
+The free-text/interactive path (`PROGRAMMATIC_MODE=false`) is completely unaffected — it always proceeds through Phase 1 → Phase 2 → Phase 3 → Phase 4 exactly as before this contract was added.
+
+---
+
 ## Why This Exists
 
 Bad issues cause cascading pipeline failures. When an issue says "fix the docker mount" without specifying WHICH compose file, the investigator checks one file, misses the override, the builder writes an incomplete fix, the deploy fails, and a new audit issue gets filed about the original issue. One vague sentence costs 3+ agent runs. This command prevents that by enforcing structure at creation time.
@@ -24,6 +219,8 @@ Bad issues cause cascading pipeline failures. When an issue says "fix the docker
 
 ## Phase 1: Parse the Request
 
+**If `PROGRAMMATIC_MODE=true`** (see Programmatic Invocation Contract above): run **1A only** (repository resolution — `GH_REPO`/`GH_FLAG`/`REPO_PATH`/`STAGING_BRANCH` still come from `forge.yaml` and the multi-repo prefix table, never from a caller flag), then skip 1B/1C/1D (type/priority/category classification — the caller already supplied final `--label` values) and skip Phase 3 (drafting) entirely. Jump directly to Phase 2D using `{PROPOSED_TITLE}` = `$PROGRAMMATIC_TITLE`, then continue to Phase 3F (Programmatic Pre-Create Validation) and Phase 4 (create). Do not apply the free-text classification/drafting rules below — they apply only when `PROGRAMMATIC_MODE=false`.
+
 The user's input (`$ARGUMENTS`) can be:
 
 | Input Form | Example |
@@ -97,6 +294,8 @@ Pick ONE primary category label:
 
 **You MUST read code before writing the issue.** This is the critical difference between a good issue and a bad one. The investigation agent inherits YOUR file references — if you point to the wrong file, the entire pipeline goes sideways.
 
+**In programmatic mode, skip 2A/2B/2C (domain identification, code reading, affected-file enumeration)** — the caller already did its own domain-specific reading and drafting before invoking `/issue` with `--title`/`--body`/`--body-file`; re-deriving that here would duplicate work the caller has already done and risks second-guessing a caller with more direct context (e.g. an audit agent that already read the offending file). Continue to **2D** (dedup — still mandatory) and **2E** (skip — see below).
+
 ### 2A: Identify the domain
 
 Map the issue to its domain and key files. Domain structure comes from the project — check `forge.yaml → review.context` and the project's `CLAUDE.md` for project-specific domain maps.
@@ -173,6 +372,8 @@ If a duplicate exists:
 gh api repos/{GH_REPO}/milestones --jq '.[] | select(.state == "open") | "#\(.number) \(.title) (\(.open_issues) open)"'
 ```
 
+**Skip in programmatic mode** — `$PROGRAMMATIC_MILESTONE` (if supplied) is used directly by Phase 4B; there is nothing to look up.
+
 ---
 
 ## Phase 3: Draft the Issue
@@ -349,14 +550,64 @@ Before creating, verify:
 5. **Override files included**: If `docker-compose.yml` is listed, `docker-compose.prod.yml` is too (if it exists). If a model is listed, its migration is too.
 6. **Priority matches severity**: P0 = prod down, P1 = significant user impact, P2 = minor, P3 = cosmetic
 
+**Skip this step entirely in programmatic mode** — the caller already composed and is responsible for the draft. Programmatic mode has its own validation gate instead: Phase 3F below.
+
+### 3F: Programmatic Pre-Create Validation (programmatic mode only, MANDATORY)
+
+**Skip if `PROGRAMMATIC_MODE=false`** — this step only runs for the `--title`-driven path; the free-text/interactive path uses 3E above instead.
+
+Runs after Phase 2D (dedup) passes and before Phase 4B (create). This reuses the exact same three mandatory-section check Phase 4C.5 performs post-creation — but applied here, pre-create, against the caller-supplied body, so a programmatic caller's issue is validated *before* it exists rather than repaired after the fact. Phase 4C.5 still runs afterward too (unchanged, for both modes) as an idempotent safety net — after this step it will find nothing to repair.
+
+```bash
+MISSING_SECTIONS=""
+echo "$PROGRAMMATIC_BODY" | grep -q "^## Problem" || MISSING_SECTIONS="$MISSING_SECTIONS PROBLEM"
+echo "$PROGRAMMATIC_BODY" | grep -q "^## Affected Files" || MISSING_SECTIONS="$MISSING_SECTIONS AFFECTED_FILES"
+echo "$PROGRAMMATIC_BODY" | grep -q "^## Acceptance Criteria" || MISSING_SECTIONS="$MISSING_SECTIONS ACCEPTANCE_CRITERIA"
+
+if [ -n "$MISSING_SECTIONS" ]; then
+  echo "WARNING: supplied --body is missing sections:$MISSING_SECTIONS — adding placeholders before creation"
+
+  APPEND_TEXT=""
+  echo "$MISSING_SECTIONS" | grep -q "PROBLEM" && APPEND_TEXT="$APPEND_TEXT
+## Problem
+
+Root cause unknown — investigation needed."
+
+  echo "$MISSING_SECTIONS" | grep -q "AFFECTED_FILES" && APPEND_TEXT="$APPEND_TEXT
+## Affected Files
+
+Files to be identified during investigation."
+
+  echo "$MISSING_SECTIONS" | grep -q "ACCEPTANCE_CRITERIA" && APPEND_TEXT="$APPEND_TEXT
+## Acceptance Criteria
+
+- [ ] Fix confirmed during investigation."
+
+  # Append missing sections to the supplied body (never replace — only extend),
+  # same non-blocking "repair, don't fail" semantics as Phase 4C.5.
+  PROGRAMMATIC_BODY="${PROGRAMMATIC_BODY}${APPEND_TEXT}"
+  echo "Body repaired in-memory before creation — added:$MISSING_SECTIONS"
+else
+  echo "Pre-create validation passed — all mandatory sections present"
+fi
+```
+
+**This step never fails or blocks** — identical to Phase 4C.5's contract. Missing sections cause an in-memory repair, not an error; `$PROGRAMMATIC_BODY` (now guaranteed to contain all three mandatory sections) is what Phase 4B creates the issue with, and what a `--dry-run` preview (Phase 4A) prints.
+
 ---
 
 ## Phase 4: Create the Issue
 
-### 4A: Present draft to user
+### 4A: Create by default, or stop for review with `--dry-run`
+
+Once Phase 2D (dedup) has passed with no blocking duplicate, and either Phase 3E (interactive draft validation) or Phase 3F (programmatic pre-create validation) has passed, proceed directly to Phase 4B and create the issue. **No pre-create confirmation prompt.** This is the default for both interactive and programmatic invocations — dedup and validation are the correctness gates, not a human approval step.
+
+In programmatic mode, `{title}` = `$PROGRAMMATIC_TITLE`, `{full issue body}` = `$PROGRAMMATIC_BODY` (post-3F, i.e. already section-repaired), `{priority}, {category}` = the joined `PROGRAMMATIC_LABELS[@]`, and `{milestone}` = `$PROGRAMMATIC_MILESTONE` (or "none" if empty) — no interactive drafting occurred, so the dry-run preview below simply echoes back what the caller supplied (plus any 3F repairs).
+
+**If `--dry-run` was passed** (see Argument Parsing): print the draft below and STOP. Do NOT run Phase 4B.
 
 ```
-## Issue Draft
+## Issue Draft (--dry-run — not created)
 
 **Repo**: {GH_REPO}
 **Title**: {title}
@@ -369,11 +620,9 @@ Before creating, verify:
 
 ---
 
-Create this issue? (yes / adjust / cancel)
+Re-run without --dry-run to create this issue.
 ```
 
-**Wait for user confirmation.** Do NOT create the issue without approval.
-
 ### 4B: Create the issue
 
 ```bash
@@ -398,6 +647,25 @@ ISSUE_EOF
 )"
 ```
 
+**Programmatic mode variable mapping**: `{TITLE}` = `$PROGRAMMATIC_TITLE`; `{FULL_BODY}` = `$PROGRAMMATIC_BODY` (post-Phase-3F); the milestone branch is used iff `$PROGRAMMATIC_MILESTONE` is non-empty, with `{MILESTONE_TITLE}` = `$PROGRAMMATIC_MILESTONE`. This is the same `gh issue create` call the interactive path uses — no new command surface, only a new source for the variables.
+
+`{PRIORITY_LABEL},{CATEGORY_LABEL}` in the interactive-mode template above stands for `PROGRAMMATIC_LABELS[@]`, but the actual `--label` flag(s) passed to `gh issue create` are built as one repeatable `--label` per array element — NOT a single comma-joined string. `gh issue create --label` itself comma-splits its argument, so joining `PROGRAMMATIC_LABELS[@]` with `,` and passing it as one value would incorrectly fragment any individual label that contains a literal comma (see forge#2097). `--label` is a repeatable flag — passing it multiple times accumulates labels without any join/split ambiguity. Zero labels is valid and must omit `--label` entirely (an empty `--label ""` would fail):
+
+```bash
+LABEL_FLAG=()
+for label in "${PROGRAMMATIC_LABELS[@]}"; do
+  LABEL_FLAG+=(--label "$label")
+done
+
+if [ -n "$PROGRAMMATIC_MILESTONE" ]; then
+  gh issue create {GH_FLAG} --title "$PROGRAMMATIC_TITLE" "${LABEL_FLAG[@]}" \
+    --milestone "$PROGRAMMATIC_MILESTONE" --body "$PROGRAMMATIC_BODY"
+else
+  gh issue create {GH_FLAG} --title "$PROGRAMMATIC_TITLE" "${LABEL_FLAG[@]}" \
+    --body "$PROGRAMMATIC_BODY"
+fi
+```
+
 ### 4C: Post-creation verification
 
 ```bash
@@ -412,6 +680,8 @@ echo "Labels: ${LABELS}"
 
 After creation, verify the issue body contains the three mandatory pipeline sections. If any are missing, add placeholder content so downstream pipeline agents have the correct scaffolding.
 
+**Runs for both interactive and programmatic invocations, unconditionally — do not skip this step for programmatic mode.** For programmatic callers this is expected to be a no-op: Phase 3F already validated and repaired `$PROGRAMMATIC_BODY` before creation, so `$CREATED_BODY` here should already contain all three sections. This step still runs as an idempotent safety net (e.g. if GitHub or an intermediate transform altered the body between 3F and creation).
+
 **This step never fails or blocks.** Missing sections cause a repair, not an error. Issues created with full structure pass through immediately.
 
 ```bash
@@ -481,13 +751,25 @@ fi
 
 If the user provides multiple issues to create (e.g., from an audit, analytics session, or decomposition):
 
-1. Draft ALL issues first
-2. Present them as a numbered list for review
-3. Create all after confirmation
-4. Report all created issue numbers
+1. Draft ALL issues first (each running its own dedup + validation pass, Phase 2D/3E)
+2. Create all of them by default — consistent with the single-issue default in Phase 4A. No pre-create confirmation prompt.
+3. If `--dry-run` was passed, present them as a numbered list instead of creating them (see table below) and STOP
+4. Report all created (or, under `--dry-run`, all drafted) issue numbers
+
+**Default (no `--dry-run`)**: create each drafted issue in order, then report:
+```
+## Batch Issues Created
+
+| # | Issue | Priority | Category | Deps |
+|---|-------|----------|----------|------|
+| 1 | #{N1} {title} | P2 | bug | — |
+| 2 | #{N2} {title} | P1 | feature | After #{N1} |
+| 3 | #{N3} {title} | P2 | refactor | — |
+```
 
+**With `--dry-run`**: print the batch draft table and stop before any `gh issue create` call:
 ```
-## Batch Issue Draft
+## Batch Issue Draft (--dry-run — not created)
 
 | # | Title | Priority | Category | Deps |
 |---|-------|----------|----------|------|
@@ -507,7 +789,7 @@ If the user provides multiple issues to create (e.g., from an audit, analytics s
 
 </details>
 
-Create all {N} issues? (yes / adjust #N / cancel)
+Re-run without --dry-run to create these {N} issues.
 ```
 
 ---
@@ -528,10 +810,11 @@ Create all {N} issues? (yes / adjust #N / cancel)
 
 ## Safety Rules
 
-1. **Always read code before creating an issue.** Never create an issue based solely on user description without verifying the files exist and the problem is plausible.
-2. **Always check for duplicates.** Creating duplicate issues wastes agent runs.
-3. **Always wait for user confirmation.** Never create issues without showing the draft first.
+1. **Always read code before creating an issue.** Never create an issue based solely on user description without verifying the files exist and the problem is plausible. (Programmatic mode: this responsibility shifts to the caller — the caller already read code before composing `--title`/`--body`; `/issue` does not re-verify file paths for programmatic invocations.)
+2. **Always check for duplicates.** Creating duplicate issues wastes agent runs — dedup (Phase 2D) runs identically for interactive and programmatic invocations; no flag bypasses it.
+3. **Default to non-interactive creation.** Once dedup (Phase 2D) and draft validation (Phase 3E, or Phase 3F for programmatic mode) pass, create the issue — do not wait for a human to approve the draft. Only pause for human review when `--dry-run` is explicitly passed.
 4. **Never fabricate file paths.** Every path in the issue body must be verified against the actual repo.
 5. **Never omit override/companion files.** If one compose file is affected, check the other. If one model is affected, check its migration.
 6. **Use conventional commit prefixes in titles.** The pipeline and changelog depend on them.
 7. **Default to P2.** Only use P0/P1 when the user explicitly indicates severity or the evidence clearly shows production impact.
+8. **`--title` is the sole programmatic-mode trigger.** `--body`/`--body-file`/`--label`/`--milestone` are meaningless without it and never activate programmatic mode on their own — this prevents an accidental partial flag set from silently skipping Phase 1/3.

package/commands/milestone.md

@@ -1,6 +1,6 @@
 ---
 description: Create, manage, and ship milestones — the top-level planning layer for feature development
-argument-hint: [create <name> | status | ship <slug> | sync <slug>]
+argument-hint: "[create <name> | status | ship <slug> | sync <slug>]"
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
@@ -168,17 +168,16 @@ Present the proposed issues to the user. Ask:
 
 **Issue body standard**: Use the **Pipeline Issue Template** from `issue.md` Phase 3D as the body structure for every issue created here. Do NOT use a bespoke inline template — the Pipeline Issue Template is the single canonical standard for all automated issue creation across the pipeline. The body content (Problem, Root Cause, Affected Files, Acceptance Criteria, Context, Dependencies) comes from the per-issue investigation in Step 4B. <!-- Added: forge#293 -->
 
+**Route creation through `/issue`'s programmatic invocation contract** (`commands/issue.md`, added #2085) instead of calling `gh issue create` directly — this gets dedup (Phase 2D) and mandatory-section body validation (Phase 3F) for free. <!-- Changed: forge#2086 — route through /issue create-hook -->
+
 For each approved issue, create it in the **correct repo** based on the scope analysis:
 
 ```bash
 # For default repo issues:
 # Body content derives from the Step 4B per-issue investigation.
 # Structure MUST match the Pipeline Issue Template in issue.md Phase 3D.
-gh issue create {GH_FLAG} \
-  --title "{fix|feat|refactor}: {issue_title}" \
-  --label "{type},{priority}" \
-  --milestone "{TITLE}" \
-  --body "$(cat <<'BODY_EOF'
+MILESTONE_ISSUE_BODY_FILE="$(mktemp)"
+cat > "$MILESTONE_ISSUE_BODY_FILE" <<'BODY_EOF'
 ## Problem
 
 {1-3 sentences: what needs to be built or fixed for this milestone. Specific — derived from Step 4B code read, not milestone description alone.}
@@ -209,15 +208,21 @@ Part of milestone: **{MILESTONE_TITLE}**
 
 {Either "None" or "Depends on #{ISSUE_NUMBER} — {reason}"}
 BODY_EOF
-)"
+```
+
+```
+ISSUE_SKILL_OUTPUT=$(Skill(skill="issue", args="--title \"{fix|feat|refactor}: {issue_title}\" --body-file \"${MILESTONE_ISSUE_BODY_FILE}\" --label \"{type}\" --label \"{priority}\" --milestone \"{TITLE}\""))
+```
 
+```bash
 # For satellite repo issues (MCP, n8n) — create in the satellite repo:
 # Note: GitHub milestones are per-repo, so satellite issues reference the milestone by name only
 # Body structure MUST match the Pipeline Issue Template in issue.md Phase 3D.
-gh issue create -R {SATELLITE_REPO} \
-  --title "{fix|feat|refactor}: {issue_title}" \
-  --label "{type},{priority}" \
-  --body "$(cat <<'BODY_EOF'
+# issue.md's Phase 1A resolves target repo from a "{satellite_prefix}: " prefix embedded in
+# the title text itself (not a --repo flag — the programmatic contract has none), so the
+# satellite prefix is prepended here exactly as issue.md's routing table documents it.
+SATELLITE_ISSUE_BODY_FILE="$(mktemp)"
+cat > "$SATELLITE_ISSUE_BODY_FILE" <<'BODY_EOF'
 ## Problem
 
 {1-3 sentences: what needs to be built or fixed in this satellite repo for the milestone.}
@@ -247,7 +252,24 @@ Part of cross-repo milestone: **{MILESTONE_TITLE}** (primary: {GH_REPO})
 
 {Either "None" or "Depends on #{ISSUE_NUMBER} — {reason}"}
 BODY_EOF
-)"
+```
+
+```
+ISSUE_SKILL_OUTPUT=$(Skill(skill="issue", args="--title \"{SATELLITE_PREFIX}: {fix|feat|refactor}: {issue_title}\" --body-file \"${SATELLITE_ISSUE_BODY_FILE}\" --label \"{type}\" --label \"{priority}\""))
+```
+
+**Extract each created issue number from the Skill output** (see `commands/issue.md` Phase 4C/4E — it echoes `Created: {url}` and reports `**#{NUMBER}**: {title}`) — repeat for both the default-repo and satellite-repo calls above:
+
+```bash
+NEW_ISSUE_NUMBER=$(echo "$ISSUE_SKILL_OUTPUT" | grep -oE 'issues/[0-9]+' | head -1 | grep -oE '[0-9]+')
+[ -z "$NEW_ISSUE_NUMBER" ] && NEW_ISSUE_NUMBER=$(echo "$ISSUE_SKILL_OUTPUT" | grep -oE '\*\*#[0-9]+\*\*' | head -1 | grep -oE '[0-9]+')
+
+if [ -z "$NEW_ISSUE_NUMBER" ]; then
+  echo "WARNING: /issue did not report a created issue number for '{issue_title}' — likely a Phase 2D dedup STOP (near-duplicate found) or a usage error. Do not add this issue to {created_issue_numbers} (Step 6B) or to any dependency reference in a later issue body — review the Skill output above."
+else
+  # Accumulate into {created_issue_numbers} for Step 6B project board sync
+  created_issue_numbers+=("$NEW_ISSUE_NUMBER")
+fi
 ```
 
 ### Step 6B: Add issues to Project board
@@ -445,9 +467,10 @@ else
             # Truncate AT_RISK to safe size for issue body (avoid shell quoting issues with large diffs)
             AT_RISK_SNIPPET=$(echo "$AT_RISK" | head -60 | sed "s/'/'\\\\''/g")
 
-            gh issue create {GH_FLAG} \
-              --title "fix(milestone): rebase conflict during hunk-loss audit for milestone/{slug}" \
-              --body "$(cat <<ISSUE_EOF
+            # Route through /issue's programmatic invocation contract (commands/issue.md, #2085)
+            # instead of calling gh issue create directly — gets dedup + body validation for free.
+            REBASE_ISSUE_BODY_FILE="$(mktemp)"
+            cat > "$REBASE_ISSUE_BODY_FILE" <<ISSUE_EOF
 ## Problem
 
 The pre-merge hunk-loss audit for milestone \`{slug}\` detected $AT_RISK_COUNT at-risk staging hunks, then attempted to rebase \`milestone/{slug}\` onto \`origin/{STAGING_BRANCH}\` to absorb them. The rebase conflicted and was aborted. Manual resolution is required before the milestone can ship.
@@ -488,10 +511,14 @@ Then re-run \`/milestone ship {slug}\`.
 
 <!-- AUTO-CREATED: hunk-loss audit rebase conflict -->
 ISSUE_EOF
-)" \
-              --label "bug" --label "priority:P0" --label "needs-human"
+```
 
-            echo "STOP: Rebase conflict. Created issue for manual resolution. Do NOT proceed to PR creation."
+```
+ISSUE_SKILL_OUTPUT=$(Skill(skill="issue", args="--title \"fix(milestone): rebase conflict during hunk-loss audit for milestone/{slug}\" --body-file \"${REBASE_ISSUE_BODY_FILE}\" --label \"bug\" --label \"priority:P0\" --label \"needs-human\""))
+```
+
+```bash
+            echo "STOP: Rebase conflict. Created issue for manual resolution (see /issue output above). Do NOT proceed to PR creation."
             echo "Run '/milestone ship {slug}' again after resolving the conflict."
             exit 1
         fi

package/commands/optimize.md

@@ -1,6 +1,6 @@
 ---
 description: Analyze this repo and generate per-repo adaptive scripts from learned patterns, git history, and existing configuration
-argument-hint: [--dry-run | --force | --no-registry]
+argument-hint: "[--dry-run | --force | --no-registry]"
 install: extras
 ---
 

package/commands/orchestrate/phase-1-resolve.md

@@ -106,12 +106,13 @@ BATCHABLE_P3=$(gh issue list {GH_FLAG} \
 - Form same-file clusters first; evaluate any remaining ungrouped findings for leaf-directory clustering. A finding is claimed by at most one batch.
 
 **Sanitize the surface-area path before interpolation (MANDATORY):** `{SURFACE_AREA}` is an affected-file path derived from an issue body, and git filenames can legally carry shell metacharacters (`` ` ``, `$()`, quotes). Restrict it to a validated `[A-Za-z0-9._/-]` charset before templating it into `--title` / `--body`, so an untrusted issue body cannot break the `gh` argument boundary. The same guard is applied at the mirror site in `phase-4-execution.md`. <!-- forge#1833, forge#1835 -->
+
+**Route batch issue creation through `/issue`'s programmatic invocation contract** (`commands/issue.md`, added #2085) instead of calling `gh issue create` directly — this gets dedup (Phase 2D) and mandatory-section body validation (Phase 3F) for free. <!-- Changed: forge#2086 — route through /issue create-hook -->
+
 ```bash
 SAFE_SURFACE_AREA=$(printf '%s' "{SURFACE_AREA}" | tr -cd 'A-Za-z0-9._/-')
-BATCH_ISSUE_NUM=$(gh issue create {GH_FLAG} \
-  --title "fix(batch): P3 review findings — ${SAFE_SURFACE_AREA} (batch #{BATCH_N})" \
-  --label "review-finding,priority:P3,batch" \
-  --body "$(cat <<'BATCH_EOF'
+BATCH_BODY_FILE="$(mktemp)"
+cat > "$BATCH_BODY_FILE" <<'BATCH_EOF'
 ## Problem
 
 Batch of P3 review findings in **{SURFACE_AREA}** (same file or leaf directory), grouped to reduce per-finding pipeline overhead.
@@ -135,7 +136,21 @@ Batch of P3 review findings in **{SURFACE_AREA}** (same file or leaf directory),
 
 <!-- FORGE:BATCHABLE -->
 BATCH_EOF
-)")
+```
+
+```
+ISSUE_SKILL_OUTPUT=$(Skill(skill="issue", args="--title \"fix(batch): P3 review findings — ${SAFE_SURFACE_AREA} (batch #{BATCH_N})\" --body-file \"${BATCH_BODY_FILE}\" --label \"review-finding\" --label \"priority:P3\" --label \"batch\""))
+```
+
+**Extract the created batch issue number from the Skill output** (see `commands/issue.md` Phase 4C/4E — it echoes `Created: {url}` and reports `**#{NUMBER}**: {title}`):
+
+```bash
+BATCH_ISSUE_NUM=$(echo "$ISSUE_SKILL_OUTPUT" | grep -oE 'issues/[0-9]+' | head -1 | grep -oE '[0-9]+')
+[ -z "$BATCH_ISSUE_NUM" ] && BATCH_ISSUE_NUM=$(echo "$ISSUE_SKILL_OUTPUT" | grep -oE '\*\*#[0-9]+\*\*' | head -1 | grep -oE '[0-9]+')
+
+if [ -z "$BATCH_ISSUE_NUM" ]; then
+  echo "WARNING: /issue did not report a created batch issue number — likely a Phase 2D dedup STOP (near-duplicate found) or a usage error. Do not replace member issues with a batch issue for this cluster; leave the members on the standard individual pipeline instead."
+fi
 ```
 
 **Replace member issues with the batch issue** in the resolved issue set. Member issues are NOT individually dispatched to `/work-on` — the batch issue is the single pipeline unit.

package/commands/orchestrate/phase-4-execution.md

@@ -266,7 +266,12 @@ Before building agent prompts, run `classify-lane.sh` for every issue in the cur
 ```bash
 # Requires classify-lane.sh to be available at ~/.claude/scripts/classify-lane.sh
 # (installed by `npx forgedock` — see bin/journey.mjs: forge()'s linkPipelineScripts() step)
-# Fallback: bash "$FORGE_HOME/scripts/classify-lane.sh" if ~/.claude/scripts/ is unavailable
+# NOTE: the actual invocations below (and in the review-finding sweep) hardcode this
+# ~/.claude path directly — there is no $FORGE_HOME-based fallback implemented, so this
+# call site is not exposed to the bare-unset-$FORGE_HOME → root-anchored-path footgun
+# that affected commands/review-pr.md (see forge#1984, forge#2035 audit). If
+# ~/.claude/scripts/ is genuinely unavailable, classify-lane.sh hard-fails per the
+# phantom-slug gate above — it does NOT fall through to a filesystem search.
 
 declare -A ISSUE_LANE
 declare -A ISSUE_PR_BASE

package/commands/orchestrate/phase-5-cleanup.md

@@ -39,9 +39,50 @@ Include the audit summary in the final report (Phase 6). Key metrics to surface:
 - **Resume cycles** — how many times agents had to be resumed
 - **Stall boundaries** — which phase transitions cause the most stalls
 
-### Step 5C: Report cleanup results
+### Step 5C: Close the coordination issue (claims board) <!-- Added: forge#2072 -->
 
-Include the cleanup summary in the final report (Phase 6). If cleanup found problems, call them out — they indicate agent pipeline failures that may need investigation.
+**Why this step exists**: Step 3D.1 (`phase-3-dependency.md`) creates a per-batch coordination issue (the claims board) and exports `FORGE_COORD_ISSUE`/`COORD_ISSUE_NUMBER`. Step 5A's `/cleanup` sweep only closes orphaned issues whose PR merged — the claims board has no PR of its own, so that heuristic never matches it. Without this step, one `automation`-labelled issue leaks per orchestration batch.
+
+**Run after Step 5B, before Step 5D.** No-ops cleanly if the claims board was never created this run (`COORD_ISSUE_NUMBER` unset/empty — e.g. Step 3D.1's `gh issue create` failed, or this batch never reached DAG construction). Tolerates GitHub API failures without aborting the rest of Phase 5 — the same tolerant-failure convention (`2>/dev/null || echo ...`, `|| true`) used throughout `phase-3-dependency.md`/`phase-4-execution.md`.
+
+```bash
+if [ -n "${COORD_ISSUE_NUMBER:-}" ]; then
+  # Detect any still-active (unreleased) claims — a claim posted with no matching
+  # CLAIM_RELEASED comment on the same coordination issue. Adapted from the query
+  # phase-4-execution.md's claims-board relaxation sweep uses (Step 4B item 4),
+  # simplified to holder-only (a flat string array) since Step 5C only needs
+  # holder names for the closure note — unlike phase-4-execution.md's version,
+  # which also captures each claim's `files` into an object alongside `holder`.
+  ACTIVE_CLAIMS=$(gh api repos/{GH_REPO}/issues/${COORD_ISSUE_NUMBER}/comments \
+    --jq '[.[] | select(.body | contains("<!-- FORGE:CLAIM -->")) |
+           select(.body | contains("<!-- FORGE:CLAIM_RELEASED -->") | not)] |
+          map(.body | capture("\\*\\*Holder\\*\\*: (?P<h>[^\\n]+)").h // "unknown")' 2>/dev/null || echo '[]')
+  ACTIVE_CLAIMS_COUNT=$(echo "$ACTIVE_CLAIMS" | jq 'length' 2>/dev/null || echo 0)
+
+  if [ "$ACTIVE_CLAIMS_COUNT" -gt 0 ] 2>/dev/null; then
+    ACTIVE_CLAIMS_NOTE="**Still-active claims at close time** (${ACTIVE_CLAIMS_COUNT}) — not blocking closure, listed for visibility:
+$(echo "$ACTIVE_CLAIMS" | jq -r '.[] | "- " + .' 2>/dev/null)"
+  else
+    ACTIVE_CLAIMS_NOTE="No active (unreleased) claims at close time."
+  fi
+
+  gh issue close "$COORD_ISSUE_NUMBER" -R {GH_REPO} --comment "Batch complete — closing claims board.
+
+${ACTIVE_CLAIMS_NOTE}
+
+Closed automatically by \`/orchestrate\` Phase 5 Step 5C." 2>/dev/null \
+    && echo "Closed coordination issue #${COORD_ISSUE_NUMBER}" \
+    || echo "WARNING: failed to close coordination issue #${COORD_ISSUE_NUMBER} — non-fatal, continuing Phase 5"
+else
+  echo "No coordination issue for this batch (FORGE_COORD_ISSUE unset) — Step 5C is a no-op"
+fi
+```
+
+**Idempotency**: `gh issue close` on an already-closed issue succeeds as a no-op (no error) — safe to re-run this step on a resumed/compacted session without an extra pre-check.
+
+### Step 5D: Report cleanup results
+
+Include the cleanup summary in the final report (Phase 6), including whether the coordination issue was closed this run (see Step 5C). If cleanup found problems, call them out — they indicate agent pipeline failures that may need investigation.
 
 ---