forgedock 1.27.0 → 1.29.0

package/scripts/fixtures/symbol-move-ts/gen_big.mjs

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+// SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+// SPDX-License-Identifier: AGPL-3.0-or-later
+//
+// gen_big.mjs <repo dir>: writes the TypeScript refactor:split fixture used by scripts/symbol-move-ts.test.sh
+// (forge#4212): src/big.ts (~700 lines: exported consts, non-exported helpers each used only by its exported
+// function, interfaces, classes, async functions, kept code that uses moved names, a relative import), src/util.ts
+// and a node:test suite in test/big.test.ts (one skipped test). Specifiers carry the .ts extension so Node runs
+// the sources with type stripping.
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+const root = process.argv[2];
+if (!root) { process.stderr.write("usage: gen_big.mjs <dir>\n"); process.exit(2); }
+const N = 20;
+const pad = (i) => String(i).padStart(2, "0");
+const out = [];
+out.push("// SPDX-License-Identifier: MIT", "// big.ts: a hotspot module for the split fixture.", "",
+  'import { clamp, type Unit } from "./util.ts";', "");
+for (let i = 0; i < N; i++) out.push(`export const LIMIT_${pad(i)} = ${100 + i};`);
+out.push("");
+for (let i = 0; i < N; i++) {
+  out.push(`// scale step ${i}`, `function _scale_${pad(i)}(x: number): number {`, `  const factor = ${i + 1};`, "  return x * factor;", "}", "");
+  out.push(`/** compute ${i}: scaled and clamped. */`, `export function compute_${pad(i)}(x: number): number {`, `  const scaled = _scale_${pad(i)}(x);`,
+    `  return clamp(scaled, 0, LIMIT_${pad(i)});`, "}", "");
+}
+for (let i = 0; i < N; i++) {
+  out.push(`export interface Item_${pad(i)} {`, "  id: number;", "  unit: Unit;", "}", "");
+  out.push(`export class Store_${pad(i)} {`, `  items: Item_${pad(i)}[] = [];`, `  add(item: Item_${pad(i)}): number {`, "    this.items.push(item);",
+    `    return compute_${pad(i)}(item.id);`, "  }", "", "  size(): number {", "    return this.items.length;", "  }", "}", "");
+}
+for (let i = 0; i < N; i++) {
+  out.push(`export async function fetch_${pad(i)}(x: number): Promise<number> {`, "  await Promise.resolve();", `  return compute_${pad(i)}(x) + 1;`, "}", "");
+}
+out.push("// kept code that uses moved names", "export function summary(): number {", "  return compute_00(1) + LIMIT_01 + new Store_02().size();", "}", "",
+  "function _shared(x: number): number {", "  return x + 1;", "}", "", "export function kept_total(x: number): number {", "  return _shared(x) * 2;", "}", "",
+  "export function ping(n: number): number {", "  return n <= 0 ? 0 : pong(n - 1);", "}", "", "export function pong(n: number): number {", "  return n <= 0 ? 1 : ping(n - 1);", "}");
+
+const test = [
+  'import { test } from "node:test";', 'import assert from "node:assert/strict";',
+  'import { compute_03, LIMIT_05, Store_04, fetch_06, summary, kept_total, ping } from "../src/big.ts";', "",
+  'test("compute clamps", () => { assert.equal(compute_03(1000), 103); assert.equal(compute_03(2), 8); });',
+  'test("limits", () => { assert.equal(LIMIT_05, 105); });',
+  'test("store", () => { const s = new Store_04(); assert.equal(s.add({ id: 2, unit: "m" }), 10); assert.equal(s.size(), 1); });',
+  'test("fetch", async () => { assert.equal(await fetch_06(1), 8); });',
+  'test("kept", () => { assert.equal(summary(), 1 + 101 + 0); assert.equal(kept_total(1), 4); assert.equal(ping(3), 1); });',
+  'test("later", { skip: "not yet" }, () => {});', "",
+];
+
+mkdirSync(path.join(root, "src"), { recursive: true });
+mkdirSync(path.join(root, "test"), { recursive: true });
+writeFileSync(path.join(root, "src/big.ts"), out.join("\n") + "\n");
+writeFileSync(path.join(root, "src/util.ts"),
+  'export type Unit = "m" | "s";\n\nexport function clamp(x: number, lo: number, hi: number): number {\n  return Math.min(hi, Math.max(lo, x));\n}\n');
+writeFileSync(path.join(root, "test/big.test.ts"), test.join("\n"));
+writeFileSync(path.join(root, "package.json"), '{ "name": "split-fixture", "private": true, "type": "module" }\n');

package/scripts/fixtures/test-map/go/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: ci
+on:
+  pull_request:
+    paths:
+      - '**.go'
+      - 'go.mod'
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: golangci-lint run ./...
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - name: test
+        run: |
+          go mod download
+          go test ./...
+      - name: docs
+        run: ./scripts/check-docs

package/scripts/fixtures/test-map/go/Makefile

@@ -0,0 +1,5 @@
+build:
+	go build ./...
+
+test:
+	go test ./...

package/scripts/fixtures/test-map/go/README.md

@@ -0,0 +1 @@
+fixture

package/scripts/fixtures/test-map/go/go.mod

@@ -0,0 +1,3 @@
+module example.com/fixture
+
+go 1.22

package/scripts/fixtures/test-map/go/internal/util/util.go

@@ -0,0 +1,3 @@
+package util
+
+func Double(n int) int { return n * 2 }

package/scripts/fixtures/test-map/go/main.go

@@ -0,0 +1,3 @@
+package main
+
+func main() {}

package/scripts/fixtures/test-map/node/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "fixture-node",
+  "private": true,
+  "workspaces": ["packages/*"],
+  "scripts": {
+    "build": "tsc -p .",
+    "test": "vitest run",
+    "lint": "eslint ."
+  }
+}

package/scripts/fixtures/test-map/node/packages/ui/package.json

@@ -0,0 +1,4 @@
+{
+  "name": "@fixture/ui",
+  "scripts": { "test": "vitest run", "typecheck": "tsc --noEmit" }
+}

package/scripts/fixtures/test-map/node/packages/ui/src/button.tsx

@@ -0,0 +1 @@
+export const Button = () => null;

package/scripts/fixtures/test-map/node/pnpm-lock.yaml

@@ -0,0 +1 @@
+lockfileVersion: '9.0'

package/scripts/fixtures/test-map/node/src/a.ts

@@ -0,0 +1 @@
+export const a = 1;

package/scripts/fixtures/test-map/node/vitest.config.ts

@@ -0,0 +1 @@
+export default {};

package/scripts/fixtures/test-map/python/pkg/mod.py

@@ -0,0 +1,2 @@
+def add(a, b):
+    return a + b

package/scripts/fixtures/test-map/python/pyproject.toml

@@ -0,0 +1,9 @@
+[project]
+name = "fixture-python"
+version = "0.0.0"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100

package/scripts/fixtures/test-map/python/tests/test_mod.py

@@ -0,0 +1,5 @@
+from pkg.mod import add
+
+
+def test_add():
+    assert add(1, 2) == 3

package/scripts/fixtures/test-map/python/uv.lock

@@ -0,0 +1 @@
+version = 1

package/scripts/forge-root.test.sh

@@ -341,7 +341,7 @@ hr_check_stub review-pr "$HR_CLASSIFY" DERIVE_MILESTONE_SCRIPT derive-finding-mi
 hr_check_stub review-pr "$HR_CLASSIFY" PRIORITY_SCRIPT severity-to-priority.sh
 hr_check_stub review-prepare "$HR_PREPARE" CODE_INDEX_SCRIPT code-index.sh
 hr_check_stub review-pr "$HR_CLASSIFY" DEDUP_SCRIPT issue-dedup.sh
-hr_check_block issue "$ROOT/commands/issue.md" DEDUP_SCRIPT issue-dedup.sh
+hr_check_stub issue "$ROOT/commands/issue.md" ISSUE_CREATE_SCRIPT issue-create.sh
 stub_block "$HR_CLASSIFY" DERIVE_MILESTONE_SCRIPT > "$T/hr_dm.sh"
 stub_block "$HR_CLASSIFY" PRIORITY_SCRIPT > "$T/hr_pr.sh"
 # no bare cwd-relative helper call in either review spec

package/scripts/hotspots.sh

@@ -0,0 +1,100 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# hotspots.sh — deterministic size and churn facts for named files (forge#4195). No LLM, no network: git + wc + jq,
+# yq (optional) only to read forge.yaml. Run from the repo root.
+#
+# Usage: hotspots.sh [--base <ref>] [--] <path>...
+# Config: forge.yaml maintenance.hotspot {enabled, file_lines, growth_lines, exclude_globs}; defaults true/2000/150/[]
+#   (also when forge.yaml or yq is missing).
+# Output (stdout, one JSON object):
+#   {"enabled","file_lines","growth_lines","files":[{path,lines,commits_90d,hotspot,over,excluded,base_lines,growth}]}
+# lines = `wc -l` of the working-tree file (0 when missing); commits_90d = `git rev-list --count --since=90.days HEAD`;
+# hotspot = lines × commits_90d; over = lines > file_lines; excluded = linguist-generated / linguist-vendored set by
+# .gitattributes, or a match of an exclude_glob (shell pattern, `*` crosses `/`). Without --base no blob is read and
+# base_lines/growth are null; with --base they are the line count at git merge-base(<ref>, HEAD) (0 when absent there)
+# and lines - base_lines. enabled:false prints files:[] and does no per-file work.
+# Exit: 0 ok | 2 usage or bad ref. bash 3.2 portable.
+set -uo pipefail
+
+die() { echo "hotspots: $*" >&2; exit 2; }
+command -v jq >/dev/null 2>&1 || die "jq is required"
+BASE=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --base) [ $# -ge 2 ] && [ -n "$2" ] || die "usage: hotspots.sh [--base <ref>] [--] <path>..."; BASE="$2"; shift 2 ;;
+    --) shift; break ;;
+    -*) die "unknown option: $1" ;;
+    *) break ;;
+  esac
+done
+
+# ---- config: maintenance.hotspot as JSON, {} when unreadable ----
+CFG='{}'
+if [ -f forge.yaml ] && command -v yq >/dev/null 2>&1; then
+  c=$(yq -o=json '.maintenance.hotspot // {}' forge.yaml 2>/dev/null) || c=""
+  printf '%s' "$c" | jq -e 'type == "object"' >/dev/null 2>&1 && CFG="$c"
+fi
+CFG=$(printf '%s' "$CFG" | jq -c '
+  def pos($d): if type == "number" and . > 0 then floor else $d end;
+  { enabled: (.enabled != false), file_lines: (.file_lines | pos(2000)), growth_lines: (.growth_lines | pos(150)),
+    exclude_globs: ([(.exclude_globs // [])[]? | strings]) }')
+ENABLED=$(printf '%s' "$CFG" | jq -r '.enabled')
+FILE_LINES=$(printf '%s' "$CFG" | jq -r '.file_lines')
+GROWTH_LINES=$(printf '%s' "$CFG" | jq -r '.growth_lines')
+head_json() { printf '%s' "$CFG" | jq -c --argjson files "$1" '{enabled, file_lines, growth_lines, files: $files}'; }
+[ "$ENABLED" = true ] || { head_json '[]'; exit 0; }
+
+MB=""
+if [ -n "$BASE" ]; then
+  git rev-parse --verify -q "$BASE^{commit}" >/dev/null || die "bad base ref: $BASE"
+  MB=$(git merge-base "$BASE" HEAD) || die "no merge base for $BASE and HEAD"
+fi
+HAS_HEAD=0; git rev-parse --verify -q "HEAD^{commit}" >/dev/null && HAS_HEAD=1
+GLOBS=$(printf '%s' "$CFG" | jq -r '.exclude_globs[]')
+
+T=$(mktemp -d "${TMPDIR:-/tmp}/hotspots.XXXXXX") || die "mktemp failed"
+trap 'rm -rf "$T"' EXIT
+: > "$T/rows"
+# one history walk per file, 8 at a time: wall time is the slowest batch, not the sum
+i=0
+for p in "$@"; do
+  i=$((i+1))
+  [ "$HAS_HEAD" = 1 ] && [ -n "${p#./}" ] && { git rev-list --count --since=90.days HEAD -- "${p#./}" > "$T/c.$i" 2>/dev/null & }
+  [ $((i % 8)) -eq 0 ] && wait
+done
+wait
+i=0
+for p in "$@"; do
+  i=$((i+1))
+  p=${p#./}
+  [ -n "$p" ] || continue
+  lines=0; [ -f "$p" ] && lines=$(wc -l < "$p" | tr -d ' ')
+  commits=$(cat "$T/c.$i" 2>/dev/null); case "$commits" in ''|*[!0-9]*) commits=0 ;; esac
+  excluded=false
+  if git check-attr linguist-generated linguist-vendored -- "$p" 2>/dev/null | grep -qE ': (set|true)$'; then excluded=true; fi
+  if [ "$excluded" = false ] && [ -n "$GLOBS" ]; then
+    while IFS= read -r g; do
+      [ -n "$g" ] || continue
+      # shellcheck disable=SC2254
+      case "$p" in $g) excluded=true; break ;; esac
+    done <<EOF
+$GLOBS
+EOF
+  fi
+  base_lines=null; growth=null
+  if [ -n "$MB" ]; then
+    base_lines=0
+    git cat-file -e "$MB:$p" 2>/dev/null && base_lines=$(git show "$MB:$p" | wc -l | tr -d ' ')
+    growth=$((lines - base_lines))
+  fi
+  printf '%s\t%s\t%s\t%s\t%s\t%s\n' "$p" "$lines" "$commits" "$excluded" "$base_lines" "$growth" >> "$T/rows"
+done
+
+FILES=$(jq -R -s -c --argjson fl "$FILE_LINES" '
+  [split("\n")[] | select(length > 0) | split("\t") |
+   { path: .[0], lines: (.[1] | tonumber), commits_90d: (.[2] | tonumber) } as $r |
+   $r + { hotspot: ($r.lines * $r.commits_90d), over: ($r.lines > $fl), excluded: (.[3] == "true"),
+          base_lines: (.[4] | fromjson), growth: (.[5] | fromjson) }]' < "$T/rows")
+head_json "$FILES"

package/scripts/hotspots.test.sh

@@ -0,0 +1,101 @@
+#!/usr/bin/env bash
+# hotspots.test.sh — cases for scripts/hotspots.sh (forge#4195).
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+set -uo pipefail
+S="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/hotspots.sh"
+PASS=0; FAILN=0
+TMP="$(mktemp -d "${TMPDIR:-/tmp}/hotspots-test.XXXXXX")"; trap 'rm -rf "$TMP"' EXIT
+ok() { PASS=$((PASS+1)); }
+bad() { FAILN=$((FAILN+1)); echo "FAIL: $1"; }
+eq() { if [ "$2" = "$3" ]; then ok; else bad "$1 (got: $2 want: $3)"; fi }
+q() { printf '%s' "$OUT" | jq -c "$1"; }
+HAVE_YQ=1; yq -o=json '.' - <<<'a: 1' 2>/dev/null | grep -q '"a"' || HAVE_YQ=0
+
+new_repo() {
+  rm -rf "$TMP/w"; mkdir -p "$TMP/w"; cd "$TMP/w" || exit 1
+  git init -q -b main; git config user.email t@example.com; git config user.name t; git config commit.gpgsign false
+}
+commit() { git add -A; git commit -qm "$1"; }
+lines() { i=0; : > "$1"; while [ $i -lt "$2" ]; do echo "l$i" >> "$1"; i=$((i+1)); done; }
+
+# ---- 1. exact lines, commits_90d, hotspot, over; old commits outside the window are not counted ----
+new_repo
+lines big.py 2100; GIT_COMMITTER_DATE="2000-01-01T00:00:00Z" GIT_AUTHOR_DATE="2000-01-01T00:00:00Z" commit old
+echo x >> big.py; commit c1
+echo y >> big.py; lines small.py 10; commit c2
+OUT="$(bash "$S" big.py ./small.py missing/gone.py)"; rc=$?
+eq "rc" "$rc" 0
+eq "defaults" "$(q '[.enabled,.file_lines,.growth_lines]')" '[true,2000,150]'
+eq "big facts" "$(q '.files[0]')" '{"path":"big.py","lines":2102,"commits_90d":2,"hotspot":4204,"over":true,"excluded":false,"base_lines":null,"growth":null}'
+eq "small facts (./ stripped)" "$(q '.files[1] | [.path,.lines,.commits_90d,.over]')" '["small.py",10,1,false]'
+eq "missing file" "$(q '.files[2] | [.path,.lines,.commits_90d,.over]')" '["missing/gone.py",0,0,false]'
+OUT="$(bash "$S")"; eq "no paths" "$(q '.files')" '[]'
+
+# ---- 2. --base growth: merge-base side, new file counts from 0 ----
+git checkout -q -b feat
+lines extra 200; cat extra >> big.py; lines fresh.py 30; commit grow
+OUT="$(bash "$S" --base main -- big.py fresh.py)"
+eq "growth" "$(q '.files[0] | [.base_lines,.growth,.lines]')" '[2102,200,2302]'
+eq "new file growth" "$(q '.files[1] | [.base_lines,.growth]')" '[0,30]'
+bash "$S" --base no-such-ref big.py >/dev/null 2>&1; eq "bad ref exit" "$?" 2
+bash "$S" --base >/dev/null 2>&1; eq "usage exit" "$?" 2
+bash "$S" --bogus x >/dev/null 2>&1; eq "unknown option exit" "$?" 2
+
+# ---- 3. exclusions: linguist-generated, linguist-vendored, forge.yaml globs ----
+mkdir -p gen vendor/lib dist
+lines gen/api.py 2500; lines vendor/lib/x.js 2500; lines dist/bundle.js 2500
+printf 'gen/** linguist-generated\nvendor/** linguist-vendored=true\n' > .gitattributes
+commit gen
+OUT="$(bash "$S" gen/api.py vendor/lib/x.js dist/bundle.js big.py)"
+eq "attr exclusions" "$(q '[.files[] | .excluded]')" '[true,true,false,false]'
+if [ "$HAVE_YQ" = 1 ]; then
+  printf 'maintenance:\n  hotspot:\n    file_lines: 100\n    growth_lines: 5\n    exclude_globs: ["dist/*", "*.lock"]\n' > forge.yaml
+  OUT="$(bash "$S" dist/bundle.js small.py big.py)"
+  eq "config thresholds" "$(q '[.file_lines,.growth_lines]')" '[100,5]'
+  eq "glob exclusion" "$(q '[.files[] | .excluded]')" '[true,false,false]'
+  eq "over uses configured file_lines" "$(q '[.files[] | .over]')" '[true,false,true]'
+  printf 'maintenance:\n  hotspot:\n    enabled: false\n' > forge.yaml
+  OUT="$(bash "$S" big.py)"
+  eq "opt-out" "$(q '[.enabled,.files]')" '[false,[]]'
+  printf 'maintenance:\n  hotspot:\n    file_lines: nope\n' > forge.yaml
+  OUT="$(bash "$S" big.py)"; eq "bad value falls back" "$(q '.file_lines')" 2000
+  rm -f forge.yaml
+else
+  echo "SKIP: forge.yaml cases need mikefarah yq v4"
+fi
+# yq missing: defaults, still exit 0
+mkdir -p "$TMP/noyq"; printf '#!/bin/sh\nexit 1\n' > "$TMP/noyq/yq"; chmod +x "$TMP/noyq/yq"
+printf 'maintenance:\n  hotspot:\n    file_lines: 100\n' > forge.yaml
+OUT="$(PATH="$TMP/noyq:$PATH" bash "$S" big.py)"; eq "yq unusable: defaults" "$(q '.file_lines')" 2000
+rm -f forge.yaml
+
+# ---- 4. 30k-commit repo: exact counts under 1 s, no blob reads, no network ----
+rm -rf "$TMP/big"; git init -q -b main "$TMP/big"; cd "$TMP/big" || exit 1
+now=$(date +%s)
+awk -v now="$now" 'BEGIN { for (i = 1; i <= 30000; i++) {
+  ts = (i > 27000) ? now - (30000 - i) * 60 : now - 200 * 86400 - (27000 - i) * 600
+  print "commit refs/heads/main"; print "mark :" i; print "committer t <t@e> " ts " +0000"; print "data 1"; print "x"
+  if (i > 1) print "from :" (i - 1)
+  f = (i % 10 == 0) ? "hot.py" : "other" (i % 50) ".txt"; c = "line " i
+  print "M 644 inline " f; print "data " length(c) + 1; print c; print "" } }' | git fast-import --quiet
+git checkout -q main
+mkdir -p "$TMP/bin"
+for t in gh curl wget npm npx pnpm yarn nc ssh; do printf '#!/bin/sh\necho "%s" >> "%s/net.log"\nexit 1\n' "$t" "$TMP" > "$TMP/bin/$t"; chmod +x "$TMP/bin/$t"; done
+best=""
+for _ in 1 2 3; do
+  start=$(date +%s%N 2>/dev/null)
+  OUT="$(PATH="$TMP/bin:$PATH" GIT_TRACE2_EVENT="$TMP/trace.json" bash "$S" hot.py other1.txt other2.txt other3.txt)"
+  end=$(date +%s%N 2>/dev/null)
+  case "$start$end" in *N*|"") best=0; break ;; esac
+  ms=$(( (end - start) / 1000000 )); if [ -z "$best" ] || [ "$ms" -lt "$best" ]; then best=$ms; fi
+done
+eq "30k exact commits" "$(q '[.files[] | .commits_90d]')" '[300,60,60,60]'
+eq "30k exact lines" "$(q '[.files[] | .lines]')" '[1,1,1,1]'
+if [ "$best" -lt 1000 ]; then ok; else bad "30k-commit run took ${best} ms (limit 1000)"; fi
+grep -q '"rev-list"' "$TMP/trace.json" && ok || bad "git trace not captured"
+if grep -qE '"(cat-file|show)"' "$TMP/trace.json"; then bad "blob read without --base"; else ok; fi
+if [ -e "$TMP/net.log" ]; then bad "network tool invoked: $(tr '\n' ' ' < "$TMP/net.log")"; else ok; fi
+
+echo "hotspots.test.sh: $PASS passed, $FAILN failed"
+[ "$FAILN" -eq 0 ]

package/scripts/issue-create.sh

@@ -0,0 +1,197 @@
+#!/usr/bin/env bash
+# issue-create.sh — deterministic /issue create path (forge#4164): parse, integrity check, dedup, section repair,
+# REST create with token read-back, milestone, project board. commands/issue.md calls it once.
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# Usage: issue-create.sh --title T (--body B | --body-file F) [--label L]... [--milestone M] [--exclude N,N]
+#                        [--dry-run] [--repo OWNER/NAME] [--config forge.yaml]
+#        issue-create.sh --args "<raw \$ARGUMENTS string>" [--repo ...] [--config ...]
+# --args is tokenized quote-aware by xargs (never eval: $(...), backticks, ; and | in caller text are never run, #2094).
+# Repo: --repo, else yq .project.owner/.project.repo of --config (default ${FORGE_CONFIG:-forge.yaml}).
+#
+# Output: exactly one stdout line per run
+#   ISSUE_CREATE_RESULT:CREATED number=N url=U   exit 0
+#   ISSUE_CREATE_RESULT:DRY_RUN                  exit 0 (draft printed, nothing created)
+#   ISSUE_CREATE_RESULT:DEDUP number=N           exit 1 (an open near-duplicate exists; nothing created)
+#   ISSUE_CREATE_RESULT:USAGE                    exit 2 (bad flags, body or integrity marker, dedup usage error)
+#   ISSUE_CREATE_RESULT:ERROR                    exit 3 (GitHub rejected the create or a read-back failed)
+# Diagnostics go to stderr. Bash 3.2 portable: no mapfile, no assoc arrays, no ${arr[@]} under set -u.
+set -o pipefail
+
+usage() { echo "ERROR: $*" >&2; echo "ISSUE_CREATE_RESULT:USAGE"; exit 2; }
+fail() { echo "ERROR: $*" >&2; echo "ISSUE_CREATE_RESULT:ERROR"; exit 3; }
+
+SELF_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TITLE=""; BODY=""; BODY_FILE=""; HAVE_BODY=false; MILESTONE=""; EXCLUDE=""; DRY_RUN=false
+REPO=""; CONFIG="${FORGE_CONFIG:-forge.yaml}"; RAW_ARGS=""; HAVE_RAW=false
+LABELS=()
+
+# --- tokenize --args (quote-aware, never executed) ---------------------------
+TOKENS=()
+take_tokens() { # tokenize $1 into TOKENS via a temp file so the real xargs exit status is seen
+  local tmp tok
+  case "$1" in *[![:space:]]*) ;; *) return 0 ;; esac
+  tmp=$(mktemp "${TMPDIR:-/tmp}/issue-create-args.XXXXXX") || usage "mktemp failed"
+  if ! printf '%s' "$1" | xargs -n1 printf '%s\0' > "$tmp"; then
+    rm -f "$tmp"
+    usage "failed to tokenize the arguments (unbalanced quote, or a token over xargs's limit; use --body-file for large content)"
+  fi
+  while IFS= read -r -d '' tok; do TOKENS+=("$tok"); done < "$tmp"
+  rm -f "$tmp"
+}
+
+# Outer argv: --args/--repo/--config, or the flags themselves.
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --args) [ $# -ge 2 ] || usage "--args requires a value"; RAW_ARGS="$2"; HAVE_RAW=true; shift 2 ;;
+    --repo) [ $# -ge 2 ] || usage "--repo requires a value"; REPO="$2"; shift 2 ;;
+    --config) [ $# -ge 2 ] || usage "--config requires a value"; CONFIG="$2"; shift 2 ;;
+    *) TOKENS+=("$1"); shift ;;
+  esac
+done
+[ "$HAVE_RAW" = true ] && take_tokens "$RAW_ARGS"
+
+# Flag mode only when a token is exactly a known flag: free text that mentions "--verbose" is not a flag typo.
+FLAG_MODE=false
+for t in ${TOKENS[@]+"${TOKENS[@]}"}; do
+  case "$t" in --dry-run|--greenfield|--spike|--title|--body|--body-file|--label|--milestone|--exclude) FLAG_MODE=true; break ;; esac
+done
+[ "$FLAG_MODE" = true ] || usage "no recognised flag: free-text /issue requests are drafted interactively (commands/issue.md), not by this script"
+
+i=0; n=${#TOKENS[@]}
+while [ "$i" -lt "$n" ]; do
+  arg="${TOKENS[$i]}"
+  case "$arg" in
+    --dry-run) DRY_RUN=true ;;
+    --greenfield) ;;   # interactive draft validation only (forge#4172); accepted, no effect on a programmatic create
+    --title|--body|--body-file|--label|--milestone|--exclude|--spike)
+      [ $((i + 1)) -lt "$n" ] || usage "$arg requires a value"
+      i=$((i + 1)); v="${TOKENS[$i]}"
+      case "$arg" in
+        --title) TITLE="$v" ;;
+        --body) BODY="$v"; HAVE_BODY=true ;;
+        --body-file) BODY_FILE="$v" ;;
+        --label) LABELS+=("$v") ;;
+        --milestone) MILESTONE="$v" ;;
+        --exclude) EXCLUDE="$v" ;;
+        --spike) ;;   # see --greenfield
+      esac ;;
+    --*) usage "unrecognized flag: $arg" ;;
+    *) ;;   # stray words are ignored, as in the spec's flag loop
+  esac
+  i=$((i + 1))
+done
+
+# --- body and integrity marker ------------------------------------------------
+[ -n "$TITLE" ] || usage "programmatic mode requires --title"
+if [ "$HAVE_BODY" = true ] && [ -n "$BODY_FILE" ]; then
+  usage "programmatic mode requires exactly one of --body or --body-file (both given)"
+elif [ "$HAVE_BODY" != true ] && [ -z "$BODY_FILE" ]; then
+  usage "programmatic mode requires exactly one of --body or --body-file (neither given)"
+fi
+MARKER=""
+if [ -n "$BODY_FILE" ]; then
+  [ -f "$BODY_FILE" ] && [ -r "$BODY_FILE" ] || usage "--body-file '$BODY_FILE' is missing or unreadable"
+  BODY=$(cat "$BODY_FILE") || usage "--body-file '$BODY_FILE' is missing or unreadable"
+  MARKERS=$(printf '%s' "$BODY" | grep -oE '<!-- FORGE:BODY-INTEGRITY:[^>]+ -->' || true)
+  count=0; [ -n "$MARKERS" ] && count=$(printf '%s\n' "$MARKERS" | wc -l | tr -d ' ')
+  [ "$count" -eq 1 ] || usage "--body-file must contain exactly one FORGE:BODY-INTEGRITY marker (found $count)"
+  MARKER="$MARKERS"
+fi
+
+# --- repository ----------------------------------------------------------------
+if [ -z "$REPO" ] && [ -f "$CONFIG" ] && command -v yq >/dev/null 2>&1; then
+  REPO=$(yq '.project.owner + "/" + .project.repo' "$CONFIG" 2>/dev/null | tr -d '"')
+fi
+case "$REPO" in ?*/?*) ;; *) usage "no target repository: pass --repo OWNER/NAME or a forge.yaml with project.owner/project.repo" ;; esac
+
+# --- dedup (helper resolved from this script's own install, never the cwd) ---
+DEDUP_SCRIPT="$SELF_DIR/issue-dedup.sh"
+[ -f "$DEDUP_SCRIPT" ] || fail "issue-dedup.sh not found next to issue-create.sh ($SELF_DIR)"
+DEDUP_ARGS=("$TITLE" -R "$REPO")
+[ -n "$EXCLUDE" ] && DEDUP_ARGS+=(--exclude "$EXCLUDE")
+DEDUP_RESULT=$(bash "$DEDUP_SCRIPT" "${DEDUP_ARGS[@]}" 2>&1); DEDUP_EXIT=$?
+if [ "$DEDUP_EXIT" -eq 1 ]; then
+  echo "Near-duplicate detected: $DEDUP_RESULT" >&2
+  DEDUP_NUMBER=$(printf '%s\n' "$DEDUP_RESULT" | grep -oE '#[0-9]+' | head -1 | tr -d '#')
+  [ -n "$DEDUP_NUMBER" ] || usage "dedup STOP returned no issue number"
+  echo "ISSUE_CREATE_RESULT:DEDUP number=${DEDUP_NUMBER}"
+  exit 1
+elif [ "$DEDUP_EXIT" -ne 0 ]; then
+  usage "dedup check usage error: $DEDUP_RESULT"
+fi
+
+# --- mandatory sections (repair, never block) ----------------------------------
+section_repair() { # body -> text to append for missing sections
+  local b="$1" add=""
+  printf '%s\n' "$b" | grep -q "^## Problem" || add="$add
+## Problem
+
+Root cause unknown — investigation needed."
+  printf '%s\n' "$b" | grep -q "^## Affected Files" || add="$add
+## Affected Files
+
+Files to be identified during investigation."
+  printf '%s\n' "$b" | grep -q "^## Acceptance Criteria" || add="$add
+## Acceptance Criteria
+
+- [ ] Fix confirmed during investigation."
+  printf '%s' "$add"
+}
+APPEND=$(section_repair "$BODY")
+if [ -n "$APPEND" ]; then
+  BODY="${BODY}${APPEND}"
+  echo "WARNING: body was missing mandatory sections; placeholders added before creation" >&2
+fi
+
+if [ "$DRY_RUN" = true ]; then
+  LABEL_TEXT=""; for l in ${LABELS[@]+"${LABELS[@]}"}; do LABEL_TEXT="${LABEL_TEXT:+$LABEL_TEXT, }$l"; done
+  printf '## Issue Draft (--dry-run — not created)\n\n**Repo**: %s\n**Title**: %s\n**Labels**: %s\n**Milestone**: %s\n\n---\n\n%s\n\n---\n\nRe-run without --dry-run to create this issue.\n' \
+    "$REPO" "$TITLE" "${LABEL_TEXT:-none}" "${MILESTONE:-none}" "$BODY" >&2
+  echo "ISSUE_CREATE_RESULT:DRY_RUN"
+  exit 0
+fi
+
+# --- REST create + create-token read-back (never gh issue create: it can swallow a 403) ---
+CREATE_TOKEN="forge-create-$(date -u +%Y%m%dT%H%M%SZ)-$$-$RANDOM"
+CREATE_BODY="${BODY}
+
+<!-- issue-create-token:${CREATE_TOKEN} -->"
+API_LABELS=()
+for l in ${LABELS[@]+"${LABELS[@]}"}; do API_LABELS+=(-f "labels[]=$l"); done
+CREATE_RESPONSE=$(gh api "repos/${REPO}/issues" --method POST -f title="$TITLE" -f body="$CREATE_BODY" ${API_LABELS[@]+"${API_LABELS[@]}"}) \
+  || fail "GitHub rejected issue creation; no issue was created."
+NEW_NUMBER=$(printf '%s' "$CREATE_RESPONSE" | jq -r '.number // empty' 2>/dev/null)
+case "$NEW_NUMBER" in ''|*[!0-9]*) fail "issue creation returned no issue number." ;; esac
+ISSUE_URL=$(printf '%s' "$CREATE_RESPONSE" | jq -r '.html_url // empty' 2>/dev/null)
+CREATED_BODY=$(gh issue view "$NEW_NUMBER" -R "$REPO" --json body --jq '.body') || fail "could not read back issue #${NEW_NUMBER}."
+printf '%s' "$CREATED_BODY" | grep -qF "issue-create-token:${CREATE_TOKEN}" \
+  || fail "issue #${NEW_NUMBER} did not contain this create token; refusing to report success."
+if [ -n "$MARKER" ] && ! printf '%s\n' "$CREATED_BODY" | grep -Fqx "$MARKER"; then
+  fail "created issue #${NEW_NUMBER} body is missing expected integrity marker $MARKER"
+fi
+
+if [ -n "$MILESTONE" ]; then
+  gh issue edit "$NEW_NUMBER" -R "$REPO" --milestone "$MILESTONE" >&2 || fail "could not set milestone '$MILESTONE' on #${NEW_NUMBER}."
+fi
+
+# Post-create safety net: GitHub or a transform may have altered the body; extend, never replace.
+APPEND=$(section_repair "$CREATED_BODY")
+if [ -n "$APPEND" ]; then
+  gh issue edit "$NEW_NUMBER" -R "$REPO" --body "${CREATED_BODY}${APPEND}" >&2 || echo "WARNING: could not append missing sections to #${NEW_NUMBER}" >&2
+fi
+
+# Project board (best effort), from forge.yaml project_board.
+if [ -f "$CONFIG" ] && command -v yq >/dev/null 2>&1; then
+  PROJECT_NUMBER=$(yq '.project_board.project_number // ""' "$CONFIG" 2>/dev/null | tr -d '"')
+  PROJECT_OWNER=$(yq '.project_board.owner // .project.owner' "$CONFIG" 2>/dev/null | tr -d '"')
+  if [ -n "$PROJECT_NUMBER" ] && [ "$PROJECT_NUMBER" != "null" ] && [ -n "$ISSUE_URL" ]; then
+    gh project item-add "$PROJECT_NUMBER" --owner "$PROJECT_OWNER" --url "$ISSUE_URL" >/dev/null 2>&1 || true
+  fi
+fi
+
+[ -n "$ISSUE_URL" ] || ISSUE_URL="https://github.com/${REPO}/issues/${NEW_NUMBER}"
+echo "Created: ${ISSUE_URL}" >&2
+echo "ISSUE_CREATE_RESULT:CREATED number=${NEW_NUMBER} url=${ISSUE_URL}"
+exit 0