forgedock 1.7.1 → 1.8.0

package/commands/audit-agents.md

@@ -167,9 +167,21 @@ def parse_agent(filepath, agent_id):
     skill_invocations = []  # unique (ts, skill) pairs
     skill_set = set()
     tool_counts = defaultdict(int)
-    resume_count = 0
     first_ts = last_ts = None
     end_turn_points = []
+    event_timestamps = []
+    operator_resume_cycles = 0
+    pending_end_turn = False
+
+    def is_terminal_skill(skill):
+        return skill.lower() in {'close', 'work-on/close', 'work-on:close'}
+
+    def is_terminal_text(text):
+        text = text.lower()
+        return any(marker in text for marker in (
+            'verdict: invalid', 'status: invalid', 'state: invalid',
+            'status: merged', 'state: merged', 'status: closed', 'state: closed',
+        ))
 
     for line in lines:
         data = json.loads(line)
@@ -181,11 +193,18 @@ def parse_agent(filepath, agent_id):
         if first_ts is None:
             first_ts = ts
         last_ts = ts
+        event_timestamps.append(ts)
 
         msg = data.get('message', {})
         stop_reason = msg.get('stop_reason', '')
         content = msg.get('content', [])
 
+        # A user turn after an assistant end_turn is an operator-style resume,
+        # even when the transcript is appended rather than replayed.
+        if data.get('type') == 'user' and pending_end_turn:
+            operator_resume_cycles += 1
+            pending_end_turn = False
+
         if stop_reason == 'end_turn':
             # Find the text content of this end_turn message
             text = ''
@@ -194,7 +213,15 @@ def parse_agent(filepath, agent_id):
                     if c.get('type') == 'text':
                         text = c.get('text', '')[:100]
                         break
-            end_turn_points.append({'ts': ts, 'text': text})
+            terminal = is_terminal_text(text) or any(
+                is_terminal_skill(si['skill']) for si in skill_invocations
+            )
+            end_turn_points.append({
+                'ts': ts,
+                'text': text,
+                'terminal': terminal,
+            })
+            pending_end_turn = not terminal
 
         if isinstance(content, list):
             for c in content:
@@ -217,17 +244,6 @@ def parse_agent(filepath, agent_id):
                             # Duplicate = resume replay
                             pass
 
-        # Detect resume points: user messages that contain resume instructions
-        if data.get('type') == 'user':
-            if isinstance(content, str) and any(kw in content.lower() for kw in ['continue', 'resume', 'you need to']):
-                resume_count += 1
-            elif isinstance(content, list):
-                for c in content:
-                    if c.get('type') == 'text':
-                        t = c.get('text', '').lower()
-                        if any(kw in t for kw in ['continue the', 'resume', 'you need to continue']):
-                            resume_count += 1
-
     # Count duplicate skill timestamps to detect resume replays
     all_skill_timestamps = []
     for line in lines:
@@ -244,7 +260,8 @@ def parse_agent(filepath, agent_id):
     for t in all_skill_timestamps:
         ts_counts[t] += 1
     max_replays = max(ts_counts.values()) if ts_counts else 1
-    resume_cycles = max_replays - 1  # first occurrence is original, rest are replays
+    replay_resume_cycles = max_replays - 1  # first occurrence is original, rest are replays
+    resume_cycles = replay_resume_cycles + operator_resume_cycles
 
     # Build phase timeline from unique skill invocations.
     # Stall detection: a gap is a TRUE STALL only when it is >120s AND contains zero
@@ -276,7 +293,17 @@ def parse_agent(filepath, agent_id):
         gap_sec = (si['ts'] - prev_ts).total_seconds()
         # Any tool_use event inside the gap window means the agent was active
         has_tool_use_in_gap = any(prev_ts < t <= si['ts'] for t in all_tool_use_ts)
-        is_stall = gap_sec > 120 and not has_tool_use_in_gap
+        # An incomplete end_turn in this gap is accounted for separately below,
+        # so the same wall-clock wait is never counted twice.
+        has_incomplete_end_turn_in_gap = any(
+            not p['terminal'] and prev_ts < p['ts'] <= si['ts']
+            for p in end_turn_points
+        )
+        is_stall = (
+            gap_sec > 120
+            and not has_tool_use_in_gap
+            and not has_incomplete_end_turn_in_gap
+        )
         phases.append({
             'ts': si['ts'],
             'skill': si['skill'],
@@ -286,9 +313,27 @@ def parse_agent(filepath, agent_id):
         })
         prev_ts = si['ts']
 
-    total_sec = (last_ts - first_ts).total_seconds() if first_ts and last_ts else 0
-    stall_sec = sum(p['gap_from_prev_sec'] for p in phases if p['is_stall'])
+    # An end_turn before a terminal phase is a stall even with no idle gap. Its
+    # wait is measured until the next transcript event; a terminal transcript
+    # has no following event, so give it the detector's 120-second floor.
+    incomplete_end_turns = [p for p in end_turn_points if not p['terminal']]
+    for point in incomplete_end_turns:
+        next_ts = next((t for t in event_timestamps if t > point['ts']), None)
+        point['stall_sec'] = (next_ts - point['ts']).total_seconds() if next_ts else 120
+        point['is_stall'] = True
+
+    observed_total_sec = (last_ts - first_ts).total_seconds() if first_ts and last_ts else 0
+    unobserved_stall_sec = sum(
+        p['stall_sec'] for p in incomplete_end_turns if p['ts'] == last_ts
+    )
+    total_sec = observed_total_sec + unobserved_stall_sec
+    phase_stall_sec = sum(p['gap_from_prev_sec'] for p in phases if p['is_stall'])
+    end_turn_stall_sec = sum(p['stall_sec'] for p in incomplete_end_turns)
+    stall_sec = phase_stall_sec + end_turn_stall_sec
     active_sec = total_sec - stall_sec
+    reached_terminal_state_unaided = (
+        any(p['terminal'] for p in end_turn_points) and resume_cycles == 0
+    )
 
     return {
         'agent_id': agent_id,
@@ -304,6 +349,8 @@ def parse_agent(filepath, agent_id):
         'phases': phases,
         'end_turn_points': end_turn_points,
         'resume_cycles': resume_cycles,
+        'operator_resume_cycles': operator_resume_cycles,
+        'reached_terminal_state_unaided': reached_terminal_state_unaided,
         'skill_count': len(skill_invocations),
     }
 ```
@@ -346,7 +393,8 @@ For each agent, display:
 ```
 ## Agent: #{ISSUE_NUMBER} — {ISSUE_TITLE}
 **Duration**: {total_min} min (active: {active_min} min, idle: {stall_min} min — {idle_pct}% idle)
-**Resume cycles**: {resume_cycles} (agent stopped and was resumed {resume_cycles} times)
+**Resume cycles**: {resume_cycles} (replay: {replay_resume_cycles}, injected user turn: {operator_resume_cycles})
+**Terminal state**: {"reached unaided" if reached_terminal_state_unaided else "required intervention or did not reach terminal state"}
 **JSONL lines**: {lines} | **Tool calls**: Bash:{N} Read:{N} Edit:{N} Skill:{N}
 
 ### Phase Timeline
@@ -376,15 +424,15 @@ For each agent, display:
 ```
 ## Wave Summary
 
-| Agent | Issue | Total | Active | Idle | Idle% | Resumes | Stall Points |
-|-------|-------|-------|--------|------|-------|---------|--------------|
-| afbc… | #14513 | 40m | 8m | 31m | 80% | 2 | investigate→build, context→architect |
-| a3b5… | #14508 | 23m | 23m | 0m | 0% | 0 | — |
-| adf5… | #14514 | 55m | 12m | 43m | 78% | 3 | investigate→build, context→architect, implement→validate |
+| Agent | Issue | Total | Active | Idle | Idle% | Resumes | Terminal unaided | Stall Points |
+|-------|-------|-------|--------|------|-------|---------|------------------|--------------|
+| afbc… | #14513 | 40m | 8m | 31m | 80% | 2 | no | investigate→build, context→architect |
+| a3b5… | #14508 | 23m | 23m | 0m | 0% | 0 | yes | — |
+| adf5… | #14514 | 55m | 12m | 43m | 78% | 3 | no | investigate→build, context→architect, implement→validate |
 
 **Wave efficiency**: {avg_idle_pct}% idle time across all agents
 **Longest stall**: {max_stall_min} min ({agent_id} between {phase_a} → {phase_b})
-**Clean agents**: {N} of {total} ran without stalls
+**Clean agents**: {N} of {total} ran without stalls or intervention
 ```
 
 ### Step 4C: Stall pattern analysis
@@ -416,6 +464,7 @@ Based on the data, output specific recommendations:
 
 - If idle% > 50% across wave → "Orchestrator polling too slow — agents spend more time waiting than working"
 - If resume_cycles > 0 for most agents → "Routing loop in work-on.md not continuing past phase boundaries"
+- If any agent did not reach a terminal state unaided → "Routing loop required operator intervention; inspect end_turn stops before declaring the wave clean"
 - If specific boundary stalls repeatedly → "Phase {X} returns text with end_turn instead of continuing loop — check work-on.md routing instructions"
 - If one agent ran clean but others didn't → "Compare clean agent (#XXXX) vs stalled agents — what differs?"
 
@@ -480,7 +529,7 @@ fi
 TOTAL_AGENTS=$(echo "${AGENT_DATA[@]}" | jq 'length')
 AVG_IDLE=$(echo "${AGENT_DATA[@]}" | jq '[.[].idle_pct] | add / length | . * 10 | round / 10')
 AVG_RESUMES=$(echo "${AGENT_DATA[@]}" | jq '[.[].resume_cycles] | add / length | . * 100 | round / 100')
-CLEAN_N=$(echo "${AGENT_DATA[@]}" | jq '[.[] | select(.idle_pct == 0 and .resume_cycles == 0)] | length')
+CLEAN_N=$(echo "${AGENT_DATA[@]}" | jq '[.[] | select(.idle_pct == 0 and .resume_cycles == 0 and .reached_terminal_state_unaided)] | length')
 
 # Top stall boundaries: aggregate gap_from_prev_sec > 120 entries by skill transition label
 # Format: "investigate→build(4), context→architect(3), implement→validate(2)"
@@ -541,4 +590,4 @@ This enables tracking whether orchestrator/prompt changes actually improved thro
 - **File format**: Agent outputs are JSONL (one JSON object per line). Each line has `type` (user/assistant), `timestamp`, `message` (with `content` array and optional `stop_reason`).
 - **Subagent files**: Located at `~/.claude/projects/{munged-project-path}/{sessionId}/subagents/agent-{agentId}.jsonl`. The munging rule: both `/` and `.` in the project path are replaced with `-` (e.g. `/home/user/projects/myapp` → `-home-user-projects-myapp`). There are no platform-specific temp paths or symlinks involved.
 - **Size filtering**: Only analyze files > 10 lines. Small files are helper/polling agents spawned by the orchestrator for status checks.
-- **Resume detection**: When an agent is resumed, the full conversation is replayed. Duplicate `(timestamp, skill_name)` pairs indicate replay cycles. `max(duplicates) - 1 = resume_cycles`.
+- **Resume detection**: Replay-dispatched resumes produce duplicate `(timestamp, skill_name)` pairs. SendMessage-style resumes append a user turn after an assistant `end_turn`. Both signals contribute to `resume_cycles`.

package/commands/autopilot.md

@@ -858,7 +858,7 @@ To approve: remove \`needs-human\` label from #${ISSUE_NUM} and re-run \`/autopi
         2>/dev/null || echo '')
       for N in $PRE_DISPATCH_ISSUES; do DISPATCHED_ISSUES+=("$N"); done
 
-      Skill("orchestrate", args="fast-lane")
+      Skill("orchestrate", args="fast-lane --auto")
 
       # Terminal-state verification after orchestrate (fallback path).
       # Re-query GitHub state for each pre-dispatch issue.
@@ -883,7 +883,7 @@ To approve: remove \`needs-human\` label from #${ISSUE_NUM} and re-run \`/autopi
     if [ "$FORGEDOCK_AVAILABLE" = "true" ]; then
       echo "[DRY-RUN] Would dispatch each fast-lane issue via: forgedock run-issue <issue> --lane staging"
     else
-      echo "[DRY-RUN] Would invoke: Skill(orchestrate, fast-lane)"
+      echo "[DRY-RUN] Would invoke: Skill(orchestrate, fast-lane --auto)"
     fi
   fi
 
@@ -1112,7 +1112,7 @@ To approve: remove \`needs-human\` label from #${ISSUE_NUM} and re-run \`/autopi
           2>/dev/null || echo '')
         for N in $MS_PRE_DISPATCH; do DISPATCHED_ISSUES+=("$N"); done
 
-        Skill("orchestrate", args="milestone $MS_SLUG")
+        Skill("orchestrate", args="milestone $MS_SLUG --auto")
 
         # Terminal-state verification after orchestrate fallback.
         echo "Verifying terminal state for $( echo "$MS_PRE_DISPATCH" | wc -w | tr -d ' ') dispatched milestone issue(s) (orchestrate path)..."
@@ -1136,7 +1136,7 @@ To approve: remove \`needs-human\` label from #${ISSUE_NUM} and re-run \`/autopi
       if [ "$FORGEDOCK_AVAILABLE" = "true" ]; then
         echo "[DRY-RUN] Would dispatch each milestone issue via: forgedock run-issue <issue> --lane milestone/$MS_SLUG"
       else
-        echo "[DRY-RUN] Would invoke: Skill(orchestrate, milestone $MS_SLUG)"
+        echo "[DRY-RUN] Would invoke: Skill(orchestrate, milestone $MS_SLUG --auto)"
       fi
     fi
   else

package/commands/cleanup.md

@@ -386,7 +386,7 @@ Eligibility is **default-batchable**: any open `review-finding` + a P3 priority
 ```bash
 # Find all open, unbatched P3 review findings. Excludes findings already
 # claimed by a batch ("batch" label), and applies the same extended safety
-# exclusions (security, billing, anti-bot, auth) as the other two batching
+# billing exclusion and security-class batching rules as the other two batching
 # sites, using the identical jq test() (Oniguruma) patterns so classification
 # cannot diverge between the three sweep locations. <!-- Changed: forge#1828 -->
 # NOTE: "priority:P3" is intentionally NOT in the --label filter — GH label filters are
@@ -423,10 +423,15 @@ UNBATCHED_P3=$(gh issue list {GH_FLAG} \
   --json number,title,body,labels,createdAt \
   --jq '.[] | select([.labels[].name] | any(test("^(priority:)?P3$")))
          | select(([.labels[].name] | any(. == "batch")) | not)
-         | select((.title | test("\\b(security|billing|anti-bot|auth|authentication|authorization|authn|authz)\\b"; "i")) | not)
+         | select((.title | test("\\b(billing|operator-only|manual action required|human action required)\\b"; "i")) | not)
          | (.body | gsub("(?m)^\\*\\*(?:Confidence\\*\\*: (?:CONFIRMED|LIKELY|POSSIBLE)|Severity\\*\\*: (?:CRITICAL|HIGH|MEDIUM|LOW|INFO)|Review comment\\*\\*: https?://\\S+)$"; "")) as $stripped_body
-         | select($stripped_body | test("## Problem[\\s\\S]{0,500}\\b(security|billing|anti-bot|auth|authentication|authorization|authn|authz)\\b"; "i") | not)
-         | select(([.labels[].name] | any(. == "security" or . == "billing" or . == "anti-bot" or . == "auth")) | not)')
+         | select($stripped_body | test("## Problem[\\s\\S]{0,500}\\b(billing|operator-only|manual action required|human action required)\\b"; "i") | not)
+         | select(([.labels[].name] | any(. == "billing" or . == "needs-human" or . == "blocked" or . == "operator-only")) | not)')
+
+# Classify each remaining finding with admission.mjs's classifyBatchSafety(). A
+# non-null, non-billing class may share a batch only with that exact class, has
+# a three-member cap, and requires a `live vector`/`defence-in-depth` verdict
+# beside every member in the generated batch body. <!-- Added: forge#2859 -->
 
 echo "Unbatched batchable P3 findings: $(echo "$UNBATCHED_P3" | jq -s 'length')"
 ```
@@ -515,7 +520,7 @@ echo "$DIR_ISSUES" | while IFS=: read -r dir issue_list; do
 done
 ```
 
-**Batch creation** uses the same template as `orchestrate.md Phase 1 → P3 Review-Finding Batching`, including its surface-area path sanitization (`tr -cd 'A-Za-z0-9._/-'` on the file/directory value before interpolating it into the batch issue's `--title`/`--body`). After creating the batch issue, add the `batch` label to each member issue to prevent re-batching on the next sweep.
+**Batch creation** uses the same template and bounded generation policy as `orchestrate.md Phase 1 → P3 Review-Finding Batching`, including its surface-area path sanitization (`tr -cd 'A-Za-z0-9._/-'` on the file/directory value before interpolating it into the batch issue's `--title`/`--body`). Compute every member's generation, exclude members above `orchestration.cascade.batch_max_generation` (default `2`), and record the retained maximum with `FORGE:BATCH_MAX_GENERATION`; list every generation-2-or-higher member in the body. After creating the batch issue, add the `batch` label to each member issue to prevent re-batching on the next sweep.
 
 ### Step 4B.4: Report
 

package/commands/issue.md

@@ -13,7 +13,7 @@ You create GitHub issues with the exact structure the `/work-on` pipeline expect
 
 `/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 \"$(mktemp)\" --label bug --label P2")` (the caller writes the body to that path before invoking). 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 — in particular, `--body-file` callers MUST use a `mktemp`-created path, never a fixed literal like `/tmp/body.md`; concurrent orchestrated agents share this host's `/tmp`, and a fixed path can be clobbered mid-flight by another agent (forge#2198).
+`/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 \"$BODY_FILE\" --label bug --label P2")` (the caller writes the body to that path before invoking). 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 — every `--body-file` caller must use an entity- and agent-scoped scratch path and include a unique integrity marker which `/issue` verifies after creation. This is required because a collision can substitute plausible but unrelated content, not just produce an obvious file error (forge#2843).
 
 **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).**
@@ -184,9 +184,20 @@ For callers that have already composed a title, body, labels, and (optionally) a
 
 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.
 
-**`--body-file` path requirement (MANDATORY for the caller)**: The path passed to `--body-file` MUST come from `mktemp` (e.g. `BODY_FILE="$(mktemp)"`), never a fixed literal such as `/tmp/body.md` or `/tmp/issue.json`. Concurrent orchestrated agents (`/orchestrate` dispatches up to `orchestration.max_concurrent` agents, default 12) share this host's `/tmp` — a fixed filename collides across agents, and a second agent's write to the same path can silently corrupt the first agent's staged content before it is read. `mktemp` gives every caller a collision-free path at effectively zero cost. This applies to every `--body-file` caller across the pipeline (`commands/work-on.md`, `commands/work-on/decompose.md`, `commands/review-pr*.md`, `commands/orchestrate/phase-1-resolve.md`, and all others) — all current callers already comply; this is the stated contract that keeps it that way (forge#2198).
+**`--body-file` integrity contract (MANDATORY for the caller)**: Do not use a generic name under shared `/tmp`, even with `mktemp`. Prefer the session scratchpad (or a repo-relative scratch directory) because a Windows-native `gh` may not resolve Git Bash `/tmp` as expected. Never hand-roll a temporary path or use a single-segment root path such as `/tmp_invbody_31076.txt`, which can require interactive deletion approval and hang unattended runs. Create the directory if needed, make the filename include the target issue or PR number and an agent-unique token, then let `mktemp` add its random suffix:
 
-**Fail-loud read ordering (the defensive mechanism against a clobbered body-file)**: `/issue` reads `$PROGRAMMATIC_BODY_FILE` exactly once, into memory, immediately below — it never re-reads the file later in the pipeline. This is deliberate: combined with a `mktemp`-unique path, it minimizes the window in which another process could overwrite the file between the caller's write and this read to effectively nil (no other agent has any reason to target a `mktemp`-generated path). If the file is missing or unreadable at read time, the check below fails loudly (`exit 1`) rather than silently proceeding with an empty or partial body — a clobbered/missing body-file is surfaced as an error, not pushed to GitHub.
+```bash
+SCRATCHPAD="${FORGE_SCRATCHPAD:-$PWD/.forge-scratch}"
+AGENT_TOKEN="${AGENT_ID:-${HOSTNAME:-agent}-$$}"
+mkdir -p "$SCRATCHPAD"
+BODY_MARKER="FORGE:BODY-INTEGRITY:${PR_NUMBER}_review_${AGENT_TOKEN}"
+BODY_FILE=$(mktemp "$SCRATCHPAD/${PR_NUMBER}_review_${AGENT_TOKEN}.XXXXXX.md")
+printf '%s\n<!-- %s -->\n' "$BODY" "$BODY_MARKER" > "$BODY_FILE"
+```
+
+The body MUST contain exactly one caller-chosen marker in the form `<!-- FORGE:BODY-INTEGRITY:<entity>_<role>_<agent-token> -->`. A unique path reduces collisions; it does not prove that the intended content reached GitHub. The caller must retain the marker until the write is verified. A collision can substitute plausible-looking content from another agent, so an eyeball check is not a sufficient backstop.
+
+**Fail-loud read and verification**: `/issue` reads `$PROGRAMMATIC_BODY_FILE` once into memory below. For `--body-file`, it also extracts the required marker and, after `gh issue create`, re-reads the created issue and requires that exact marker. Missing, unreadable, absent, or ambiguous markers are hard errors; do not create or report success with unverified content.
 
 ```bash
 if [ "$PROGRAMMATIC_MODE" = "true" ]; then
@@ -208,6 +219,12 @@ if [ "$PROGRAMMATIC_MODE" = "true" ]; then
       exit 1
     fi
     PROGRAMMATIC_BODY=$(cat "$PROGRAMMATIC_BODY_FILE")
+    mapfile -t PROGRAMMATIC_BODY_MARKERS < <(printf '%s' "$PROGRAMMATIC_BODY" | grep -oE '<!-- FORGE:BODY-INTEGRITY:[^>]+ -->')
+    if [ "${#PROGRAMMATIC_BODY_MARKERS[@]}" -ne 1 ]; then
+      echo "ERROR: --body-file must contain exactly one FORGE:BODY-INTEGRITY marker"
+      exit 1
+    fi
+    PROGRAMMATIC_BODY_MARKER="${PROGRAMMATIC_BODY_MARKERS[0]}"
   fi
 fi
 ```
@@ -354,11 +371,14 @@ DEDUP_EXIT=$?
 if [ "$DEDUP_EXIT" -eq 1 ]; then
   echo "Near-duplicate detected: $DEDUP_RESULT"
   echo "Existing issue found — do NOT create a new one."
-  # STOP here and report to user (see handling rules below)
+  DEDUP_NUMBER=$(printf '%s\n' "$DEDUP_RESULT" | grep -oE '#[0-9]+' | head -1 | tr -d '#')
+  [ -n "$DEDUP_NUMBER" ] || { echo "ERROR: dedup STOP returned no issue number." >&2; exit 2; }
+  echo "ISSUE_CREATE_RESULT:DEDUP number=${DEDUP_NUMBER}"
+  exit 1  # STOP here and report the explicit dedup result to the caller
 elif [ "$DEDUP_EXIT" -eq 2 ]; then
   echo "Dedup check usage error: $DEDUP_RESULT"
   echo "Do NOT proceed to issue creation — fix the invocation and retry."
-  # STOP here — do not fall through to gh issue create
+  exit 2  # STOP here — do not fall through to issue creation
 fi
 ```
 
@@ -639,57 +659,97 @@ Re-run without --dry-run to create this issue.
 
 ### 4B: Create the issue
 
-```bash
-gh issue create {GH_FLAG} \
-  --title "{TITLE}" \
-  --label "{PRIORITY_LABEL},{CATEGORY_LABEL}" \
-  --body "$(cat <<'ISSUE_EOF'
-{FULL_BODY}
-ISSUE_EOF
-)"
-```
+**Never use `gh issue create` for this step.** GitHub CLI can report success with
+empty output when GitHub rejects content creation with a secondary-rate-limit 403.
+Use `gh api --method POST`, which preserves that API failure, and require a unique
+token to survive a read-back before treating the issue as created. The token is
+generated by this caller, not inferred from a title search, so a similarly titled
+existing issue cannot be mistaken for the new one.
 
-If milestone was identified:
 ```bash
-gh issue create {GH_FLAG} \
-  --title "{TITLE}" \
-  --label "{PRIORITY_LABEL},{CATEGORY_LABEL}" \
-  --milestone "{MILESTONE_TITLE}" \
-  --body "$(cat <<'ISSUE_EOF'
-{FULL_BODY}
-ISSUE_EOF
-)"
+CREATE_TOKEN="forge-create-$(date -u +%Y%m%dT%H%M%SZ)-$$-$RANDOM"
+CREATE_BODY="${FULL_BODY}
+
+<!-- issue-create-token:${CREATE_TOKEN} -->"
+CREATE_RESPONSE=$(gh api "repos/${GH_REPO}/issues" --method POST \
+  -f title="{TITLE}" -f body="$CREATE_BODY" \
+  -f 'labels[]={PRIORITY_LABEL}' -f 'labels[]={CATEGORY_LABEL}') || {
+  echo "ERROR: GitHub rejected issue creation; no issue was created." >&2
+  exit 1
+}
+NEW_NUMBER=$(echo "$CREATE_RESPONSE" | jq -r '.number // empty')
+[ -n "$NEW_NUMBER" ] || { echo "ERROR: issue creation returned no issue number." >&2; exit 1; }
+CREATED_BODY=$(gh issue view "$NEW_NUMBER" {GH_FLAG} --json body --jq '.body') || exit 1
+printf '%s' "$CREATED_BODY" | grep -qF "issue-create-token:${CREATE_TOKEN}" || {
+  echo "ERROR: issue #${NEW_NUMBER} did not contain this create token; refusing to report success." >&2
+  exit 1
+}
+if [ -n "${MILESTONE_TITLE:-}" ]; then
+  [ "${DRY_RUN:-false}" != "true" ] || { echo "ERROR: refusing milestone edit during dry run." >&2; exit 1; }
+  gh issue edit "$NEW_NUMBER" {GH_FLAG} --milestone "$MILESTONE_TITLE" || exit 1
+fi
 ```
 
-**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.
+**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 verified REST-create path the interactive mode 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):
+`{PRIORITY_LABEL},{CATEGORY_LABEL}` in the interactive-mode template above stands for `PROGRAMMATIC_LABELS[@]`. REST API labels are passed as repeated `labels[]` fields, so labels remain distinct and zero labels need no field:
 
 ```bash
-LABEL_FLAG=()
+CREATE_TOKEN="forge-create-$(date -u +%Y%m%dT%H%M%SZ)-$$-$RANDOM"
+CREATE_BODY="${PROGRAMMATIC_BODY}
+
+<!-- issue-create-token:${CREATE_TOKEN} -->"
+API_LABELS=()
 for label in "${PROGRAMMATIC_LABELS[@]}"; do
-  LABEL_FLAG+=(--label "$label")
+  API_LABELS+=(-f "labels[]=$label")
 done
-
+CREATE_RESPONSE=$(gh api "repos/${GH_REPO}/issues" --method POST \
+  -f title="$PROGRAMMATIC_TITLE" -f body="$CREATE_BODY" "${API_LABELS[@]}") || exit 1
+NEW_NUMBER=$(echo "$CREATE_RESPONSE" | jq -r '.number // empty')
+[ -n "$NEW_NUMBER" ] || { echo "ERROR: issue creation returned no issue number." >&2; exit 1; }
+CREATED_BODY=$(gh issue view "$NEW_NUMBER" {GH_FLAG} --json body --jq '.body') || exit 1
+printf '%s' "$CREATED_BODY" | grep -qF "issue-create-token:${CREATE_TOKEN}" || {
+  echo "ERROR: issue #${NEW_NUMBER} did not contain this create token; refusing to report success." >&2
+  exit 1
+}
 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"
+  [ "${DRY_RUN:-false}" != "true" ] || { echo "ERROR: refusing milestone edit during dry run." >&2; exit 1; }
+  gh issue edit "$NEW_NUMBER" {GH_FLAG} --milestone "$PROGRAMMATIC_MILESTONE" || exit 1
 fi
 ```
 
 ### 4C: Post-creation verification
 
 ```bash
-# Verify the issue was created correctly
-ISSUE_URL=$(gh issue view {NEW_NUMBER} {GH_FLAG} --json url --jq '.url')
+# The mandatory create-token read-back in 4B is the success gate. This read
+# obtains report metadata only; it must not replace that gate with a title search.
+ISSUE_URL=$(gh issue view "$NEW_NUMBER" {GH_FLAG} --json url --jq '.url')
 LABELS=$(gh issue view {NEW_NUMBER} {GH_FLAG} --json labels --jq '[.labels[].name] | join(", ")')
 echo "Created: ${ISSUE_URL}"
 echo "Labels: ${LABELS}"
+echo "ISSUE_CREATE_RESULT:CREATED number=${NEW_NUMBER} url=${ISSUE_URL}"
+```
+
+**`--body-file` integrity read-back (MANDATORY)**: Immediately after every programmatic creation sourced from `--body-file`, re-read the issue body and assert the caller's exact marker is present. This is a hard error, not a warning: a missing marker means the write may have received another agent's plausible-looking body.
+
+```bash
+if [ -n "$PROGRAMMATIC_BODY_FILE" ]; then
+  CREATED_BODY=$(gh issue view {NEW_NUMBER} {GH_FLAG} --json body --jq '.body') || exit 1
+  if ! printf '%s' "$CREATED_BODY" | grep -Fqx "$PROGRAMMATIC_BODY_MARKER"; then
+    echo "ERROR: created issue body is missing expected integrity marker $PROGRAMMATIC_BODY_MARKER" >&2
+    exit 1
+  fi
+fi
 ```
 
+### Content-Creation Rule
+
+Apply the same fail-closed pattern to `gh issue comment`, `gh pr comment`, and
+`gh pr create`: use `gh api --method POST`, include a caller-generated token in
+the submitted body, capture the returned object ID/number, then GET that exact
+object and assert the token is present. Empty output, a missing ID, or a failed
+read-back is a hard error, never a successful no-op or a search-indexing retry.
+
 ### 4C.5: Body Validation (MANDATORY)
 
 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.