forgedock 1.1.11 → 1.3.0

package/commands/adopt.md

@@ -1,6 +1,6 @@
 ---
 description: Bootstrap an existing repo for ForgeDock — triage open issues, apply labels, suggest a starter milestone, and identify first /work-on candidates
-argument-hint: [--dry-run | --limit <N> | --milestone | --no-milestone]
+argument-hint: "[--dry-run | --limit <N> | --milestone | --no-milestone]"
 install: extras
 ---
 

package/commands/analytics.md

@@ -684,13 +684,11 @@ Fill in historical values from the Phase 0 history snapshots. Leave cells blank
 
 **Only after user confirms.** If "adjust" — modify list. If they pick specific ones — only create those.
 
-For each approved action:
+For each approved action, route creation through the `/issue` create-hook's programmatic invocation contract (see `commands/issue.md` → Programmatic Invocation Contract) so dedup and mandatory-section validation run on every finding:
 
 ```bash
-gh issue create \
-  --title "{type}: {action title}" \
-  --label "{priority},{category_label}" \
-  --body "$(cat <<'BODY_EOF'
+ANALYTICS_BODY_FILE=$(mktemp)
+cat > "$ANALYTICS_BODY_FILE" <<'BODY_EOF'
 ## Problem
 
 {1-3 sentences: what the analytics data shows is wrong or suboptimal, with specific numbers.}
@@ -727,10 +725,15 @@ Identified in analytics audit on {DATE}.
 
 {Technical steps}
 BODY_EOF
-)"
 ```
 
-**Label mapping**: SEO → `seo`, UX → `ux,frontend`, Performance → `performance,infra`, Bug → `bug`. Priority: `P0`-`P3`.
+```
+Skill(skill="issue", args="--title \"{type}: {action title}\" --body-file \"$ANALYTICS_BODY_FILE\" --label \"{priority}\" --label \"{category_label_1}\" --label \"{category_label_2}\"")
+```
+
+`{priority}`, `{category_label_1}`, and `{category_label_2}` are each passed as their own `--label` flag — `/issue`'s programmatic mode does not comma-split a single `--label` value. Resolve `{category_label_1}`/`{category_label_2}` from the label mapping below: split each mapping's comma-separated value into one label per placeholder. When a category maps to only one label, omit the `--label "{category_label_2}"` flag entirely (do not pass an empty string).
+
+**Label mapping**: SEO → `seo` (single label), UX → `ux` + `frontend` (two labels), Performance → `performance` + `infra` (two labels), Bug → `bug` (single label). Priority: `P0`-`P3`.
 
 If an open milestone fits, offer to assign issues to it.
 

package/commands/audit-agents.md

@@ -1,6 +1,6 @@
 ---
 description: Audit agent outputs from an orchestration run — timeline analysis, stall detection, active vs idle time breakdown
-argument-hint: [session-id | latest | <agent-id>]
+argument-hint: "[session-id | latest | <agent-id>]"
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
@@ -427,6 +427,8 @@ This step posts a structured `<!-- FORGE:AUDIT-AGENTS -->` summary comment to th
 
 **Step 4E.1 — Locate or create the tracking issue**:
 
+Creation (first-use only — the `gh issue list` existence check below still gates whether creation runs at all) is routed through the `/issue` create-hook's programmatic invocation contract (see `commands/issue.md` → Programmatic Invocation Contract):
+
 ```bash
 # Ensure the label exists before using it (gh issue create fails with GraphQL error if label is absent).
 # Color and description match the canonical ForgeDock label manifest (bin/labels.json).
@@ -441,11 +443,32 @@ TRACKING_ISSUE=$(gh issue list -R {FORGE_REPO} \
 
 if [ -z "$TRACKING_ISSUE" ]; then
   # Create the tracking issue on first use
-  TRACKING_ISSUE=$(gh issue create -R {FORGE_REPO} \
-    --title "Orchestration Metrics — Running Log" \
-    --label "orchestration-metrics" \
-    --body "This issue is a running log of persisted \`/audit-agents\` summaries. Each comment contains one session's efficiency metrics. Do not close this issue — \`/pipeline-health\` Phase 2K queries it to aggregate orchestration efficiency trends." \
-    --json number --jq '.number')
+  TRACKING_BODY_FILE=$(mktemp)
+  cat > "$TRACKING_BODY_FILE" <<'EOF'
+## Problem
+
+No `orchestration-metrics` tracking issue exists yet — this is the first `/audit-agents --persist` run for this repo.
+
+## Affected Files
+
+N/A — this is a running log issue, not a code change.
+
+## Acceptance Criteria
+
+- [ ] This issue stays open indefinitely as a running log of persisted `/audit-agents` summaries
+
+## Context
+
+This issue is a running log of persisted `/audit-agents` summaries. Each comment contains one session's efficiency metrics. Do not close this issue — `/pipeline-health` Phase 2K queries it to aggregate orchestration efficiency trends.
+EOF
+
+  Skill(skill="issue", args="--title \"Orchestration Metrics — Running Log\" --body-file \"$TRACKING_BODY_FILE\" --label \"orchestration-metrics\"")
+
+  # /issue's programmatic mode does not print a structured return value — re-query
+  # by label to recover the newly created issue number.
+  TRACKING_ISSUE=$(gh issue list -R {FORGE_REPO} \
+    --state open --label "orchestration-metrics" --limit 1 \
+    --json number --jq '.[0].number' 2>/dev/null)
   echo "Created orchestration-metrics tracking issue #$TRACKING_ISSUE"
 fi
 ```

package/commands/audit.md

@@ -287,29 +287,13 @@ Create a detailed, actionable issue in the **Forge repository**.
 
 ### 4B: Create the issue
 
-**Before creating, run the deterministic dedup check:** <!-- Added: forge#1335 -->
+Creation is routed through the `/issue` create-hook's programmatic invocation contract (see `commands/issue.md` → Programmatic Invocation Contract). `/issue` runs its own Phase 2D deterministic dedup check (`scripts/issue-dedup.sh`, same script and exit-code semantics this file used to run manually) before creating — a separate manual pre-check here is redundant and has been removed. `/issue`'s dedup STOP is authoritative: on exit 1 (near-duplicate) or exit 2 (usage error) it stops before creation and the audit tool should treat that as "skip creation, comment on the existing issue with new evidence instead" (see `commands/issue.md` Phase 2D).
 
 ```bash
 AUDIT_TITLE="fix(pipeline): {one-line description of what the pipeline missed}"
-DEDUP_RESULT=$(scripts/issue-dedup.sh "$AUDIT_TITLE" -R {FORGE_REPO} 2>&1)
-DEDUP_EXIT=$?
-if [ "$DEDUP_EXIT" -eq 1 ]; then
-  echo "DEDUP: Audit finding near-duplicate — $DEDUP_RESULT"
-  echo "Skipping creation. Comment on the existing issue with new evidence instead."
-  # Do NOT call gh issue create for this audit finding
-elif [ "$DEDUP_EXIT" -eq 2 ]; then
-  echo "DEDUP: Usage error — $DEDUP_RESULT"
-  # Do NOT call gh issue create for this audit finding — fix the invocation and retry
-fi
-```
-
-Only call `gh issue create` when the dedup script exits 0:
 
-```bash
-gh issue create -R {FORGE_REPO} \
-  --title "fix(pipeline): {one-line description of what the pipeline missed}" \
-  --label "{LABELS}" \
-  --body "$(cat <<'EOF'
+AUDIT_BODY_FILE=$(mktemp)
+cat > "$AUDIT_BODY_FILE" <<'EOF'
 ## Problem
 
 {2-3 sentences: what production issue or implementation failure occurred and what pipeline phase failed to prevent it.}
@@ -397,9 +381,14 @@ gh issue list -R {FORGE_REPO} --state all --limit 30 --json number,title \
 
 {Include results here with links}
 EOF
-)"
 ```
 
+```
+Skill(skill="issue", args="--title \"$AUDIT_TITLE\" --body-file \"$AUDIT_BODY_FILE\" --label \"{LABEL_1}\" --label \"{LABEL_2}\" --label \"{LABEL_3}\"")
+```
+
+`{LABELS}` from the table in 4A (e.g. `P1,audit-finding,bug`) is split into one `--label` flag per label (`{LABEL_1}`, `{LABEL_2}`, `{LABEL_3}`) — `/issue`'s programmatic mode does not comma-split a single `--label` value. If `/issue` stops on dedup (near-duplicate or usage error, per the note above), do not fall back to a raw `gh issue create` — comment on the existing issue with the new evidence instead.
+
 ---
 
 ## Phase 5: Cross-Reference and Enrich

package/commands/autopilot.md

@@ -1,6 +1,6 @@
 ---
 description: Autonomous deploy loop — runs until zero open issues remain. Detects pipeline state and resumes from any position. Fully autonomous after invocation.
-argument-hint: [--dry-run | --recon-only]
+argument-hint: "[--dry-run | --recon-only]"
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
@@ -149,19 +149,25 @@ if [ -z "$OPS_ISSUE_NUMBER" ]; then
       --description "Autopilot ops issue — rolling FORGE:AUTOPILOT_CYCLE annotations. Managed by /autopilot." \
       --color "0075CA" \
       $GH_FLAG 2>/dev/null || true
-    OPS_ISSUE_NUMBER=$(gh issue create $GH_FLAG \
-      --title "ops: autopilot cycle log" \
-      --label "$AUTOPILOT_OPS_LABEL" \
-      --body "$(cat <<'OPS_EOF'
+    OPS_BODY_TMPFILE=$(mktemp)
+    trap 'rm -f "$OPS_BODY_TMPFILE"' EXIT
+    cat > "$OPS_BODY_TMPFILE" <<'OPS_EOF'
 ## Autopilot Ops Issue
 
 This issue is the rolling log for `/autopilot` cycle annotations. Each cycle appends a `<!-- FORGE:AUTOPILOT_CYCLE -->` comment with its metrics and phase-completion markers. Cycle N+1 reads the latest comment for baseline deltas and resume state.
 
 **Do not close this issue manually.** It is managed by `/autopilot`.
 OPS_EOF
-)" \
-      --json number \
-      --jq '.number' 2>/dev/null || echo '')
+    # Route through the /issue create-hook (canonical dedup + body validation) instead of
+    # a raw `gh issue create`. See commands/issue.md Programmatic Invocation Contract.
+    Skill(skill="issue", args="--title \"ops: autopilot cycle log\" --body-file \"$OPS_BODY_TMPFILE\" --label \"$AUTOPILOT_OPS_LABEL\"")
+    rm -f "$OPS_BODY_TMPFILE"
+    trap - EXIT
+    OPS_ISSUE_NUMBER=$(gh issue list $GH_FLAG \
+      --state open \
+      --search "ops: autopilot cycle log" \
+      --json number,title \
+      --jq '.[] | select(.title == "ops: autopilot cycle log") | .number' 2>/dev/null | head -1)
     echo "Autopilot: ops issue created: #$OPS_ISSUE_NUMBER"
   else
     echo "[DRY-RUN] Would create ops issue with label '$AUTOPILOT_OPS_LABEL'"
@@ -545,36 +551,10 @@ fi
 
 ### 1E: Create issues from recon findings
 
-For each finding (recurring CI failures, critical stale issue patterns):
+For each finding (recurring CI failures, critical stale issue patterns), route creation through the `/issue` create-hook — its Phase 2D runs the same deterministic `scripts/issue-dedup.sh` + LLM-fallback dedup this step used to run inline, and its Phase 3F runs the same mandatory-section repair this step used to run inline post-creation. Do not duplicate either check here.
 
-**Deduplication check first** — deterministic script, then LLM fallback (canonical path from `issue.md §2D`):
 ```bash
-# Authoritative deterministic check — uses token overlap algorithm (see scripts/issue-dedup.sh)
-DEDUP_RESULT=$(scripts/issue-dedup.sh "{finding_title}" "$GH_FLAG" 2>&1)
-DEDUP_EXIT=$?
-
-if [ "$DEDUP_EXIT" -eq 1 ]; then
-  echo "Near-duplicate detected: $DEDUP_RESULT"
-  echo "Existing issue found — skipping creation for this finding."
-  # STOP here for this finding — do not fall through to gh issue create
-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
-fi
-
-# If script exits 0 (no match), also run LLM-side semantic search as a secondary pass
-if [ "$DEDUP_EXIT" -eq 0 ]; then
-  gh issue list $GH_FLAG --state open --limit 20 --search "{key_terms_from_finding}" \
-    --json number,title,labels \
-    --jq '.[] | "#\(.number) [\(.labels | map(.name) | join(","))] \(.title)"' 2>/dev/null || true
-  # LLM: if the secondary pass finds a semantic duplicate, treat it as DEDUP_EXIT=1 and skip
-fi
-```
-
-For new findings that have no existing open duplicate (DEDUP_EXIT=0 and no LLM match):
-```bash
-if [ "$DRY_RUN" = "false" ] && [ "${DEDUP_EXIT:-0}" -eq 0 ]; then
+if [ "$DRY_RUN" = "false" ]; then
   # Write body to a temp file to avoid heredoc shell-expansion and injection issues
   BODY_TMPFILE=$(mktemp /tmp/autopilot-issue-body-XXXXXX.md)
   trap 'rm -f "$BODY_TMPFILE"' EXIT
@@ -609,47 +589,28 @@ ISSUE_BODY_EOF
   # Substitute the cycle timestamp (not inside heredoc to avoid expansion-in-template issues)
   sed -i "s|{CYCLE_TIMESTAMP}|$(date -u +%Y-%m-%dT%H:%M:%SZ)|g" "$BODY_TMPFILE"
 
-  NEW_NUMBER=$(gh issue create $GH_FLAG \
-    --title "fix: {finding_description}" \
-    --label "P2,bug" \
-    --body-file "$BODY_TMPFILE" \
-    --json number --jq '.number' 2>/dev/null)
+  FINDING_TITLE="fix: {finding_description}"
+
+  # Route through the /issue create-hook (canonical dedup + body validation) instead of
+  # a raw `gh issue create`. If /issue finds a near-duplicate, it reports it and does not
+  # create — NEW_NUMBER will come back empty from the lookup below.
+  Skill(skill="issue", args="--title \"$FINDING_TITLE\" --body-file \"$BODY_TMPFILE\" --label P2 --label bug")
 
   rm -f "$BODY_TMPFILE"
   trap - EXIT
 
-  # §4C.5: Body validation/repair — ensure mandatory pipeline sections are present
-  # (canonical pattern from issue.md §4C.5 — never fails/blocks, only repairs)
-  if [ -n "$NEW_NUMBER" ]; then
-    CREATED_BODY=$(gh issue view "$NEW_NUMBER" $GH_FLAG --json body --jq '.body' 2>/dev/null || echo '')
-    MISSING_SECTIONS=""
-    echo "$CREATED_BODY" | grep -q "^## Problem" || MISSING_SECTIONS="$MISSING_SECTIONS PROBLEM"
-    echo "$CREATED_BODY" | grep -q "^## Affected Files" || MISSING_SECTIONS="$MISSING_SECTIONS AFFECTED_FILES"
-    echo "$CREATED_BODY" | grep -q "^## Acceptance Criteria" || MISSING_SECTIONS="$MISSING_SECTIONS ACCEPTANCE_CRITERIA"
-
-    if [ -n "$MISSING_SECTIONS" ]; then
-      echo "WARNING: Issue #$NEW_NUMBER body is missing sections:$MISSING_SECTIONS — adding placeholders"
-      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
+  NEW_NUMBER=$(gh issue list $GH_FLAG \
+    --state open \
+    --search "$FINDING_TITLE" \
+    --json number,title \
+    --jq --arg t "$FINDING_TITLE" '.[] | select(.title == $t) | .number' 2>/dev/null | head -1)
 
-- [ ] Fix confirmed during investigation."
-      REPAIRED_BODY="${CREATED_BODY}${APPEND_TEXT}"
-      gh issue edit "$NEW_NUMBER" $GH_FLAG --body "$REPAIRED_BODY"
-      echo "Body repaired — added:$MISSING_SECTIONS"
-    else
-      echo "Body validation passed for #$NEW_NUMBER — all mandatory sections present"
-    fi
+  if [ -n "$NEW_NUMBER" ]; then
+    echo "Created: #$NEW_NUMBER"
+  else
+    echo "No new issue created for finding (likely deduped by /issue) — skipping"
   fi
-elif [ "$DRY_RUN" = "true" ]; then
+else
   echo "[DRY-RUN] Would create issue: fix: {finding_description}"
 fi
 ```
@@ -1377,10 +1338,10 @@ if [ "${#RECON_ISSUES[@]:-0}" -gt 0 ] && [ -n "$OPS_ISSUE_NUMBER" ] && [ "$OPS_I
           --limit 1 --json number --jq '.[0].number // empty' 2>/dev/null || echo '')
 
         if [ -z "$EXISTING_META" ] && [ "$DRY_RUN" = "false" ]; then
-          gh issue create $GH_FLAG \
-            --title "meta: recurring autopilot finding — $FINDING_PATTERN" \
-            --label "priority:P2" \
-            --body "$(cat <<META_EOF
+          META_TITLE="meta: recurring autopilot finding — $FINDING_PATTERN"
+          META_BODY_TMPFILE=$(mktemp /tmp/autopilot-meta-body-XXXXXX.md)
+          trap 'rm -f "$META_BODY_TMPFILE"' EXIT
+          cat > "$META_BODY_TMPFILE" <<META_EOF
 ## Problem
 
 The following finding pattern has appeared in **3 or more consecutive /autopilot cycles**, indicating a systemic issue rather than a one-off occurrence.
@@ -1413,9 +1374,22 @@ Files to be identified during investigation.
 **Citing cycles**: ${CITING_CYCLES}
 **Detected by**: /autopilot Phase 4B recurrence detection
 META_EOF
-)" \
-            --json number --jq '"Created meta-issue #\(.number) for recurrent pattern: $ENV.FINDING_PATTERN"' \
-            2>/dev/null || echo "WARNING: Failed to create meta-issue for recurrence pattern: $FINDING_PATTERN"
+          # Route through the /issue create-hook (canonical dedup + body validation) instead
+          # of a raw `gh issue create`. The EXISTING_META search above already guards against
+          # re-creating for the same pattern; /issue's own dedup is an additional safety net.
+          Skill(skill="issue", args="--title \"$META_TITLE\" --body-file \"$META_BODY_TMPFILE\" --label priority:P2")
+          rm -f "$META_BODY_TMPFILE"
+          trap - EXIT
+          META_NEW_NUMBER=$(gh issue list $GH_FLAG \
+            --state open \
+            --search "$META_TITLE" \
+            --json number,title \
+            --jq --arg t "$META_TITLE" '.[] | select(.title == $t) | .number' 2>/dev/null | head -1)
+          if [ -n "$META_NEW_NUMBER" ]; then
+            echo "Created meta-issue #$META_NEW_NUMBER for recurrent pattern: $FINDING_PATTERN"
+          else
+            echo "WARNING: Could not confirm meta-issue creation for recurrence pattern: $FINDING_PATTERN"
+          fi
         elif [ -n "$EXISTING_META" ]; then
           echo "Recurrence meta-issue already exists (#$EXISTING_META) for pattern '$FINDING_PATTERN' — skipping"
         elif [ "$DRY_RUN" = "true" ]; then

package/commands/changelog.md

@@ -1,6 +1,6 @@
 ---
 description: Auto-generate release notes from merged PRs and FORGE:TRAJECTORY annotations — grouped by conventional commit type
-argument-hint: [v1.0.0..v1.1.0 | since:YYYY-MM-DD | last-N]
+argument-hint: "[v1.0.0..v1.1.0 | since:YYYY-MM-DD | last-N]"
 install: extras
 ---
 

package/commands/ci-audit.md

@@ -1,6 +1,6 @@
 ---
 description: Stack-aware CI gap detection — audits a project's GitHub Actions workflows against its declared tech stack and files issues for missing config validation checks
-argument-hint: [--repo <prefix>] [--dry-run]
+argument-hint: "[--repo <prefix>] [--dry-run]"
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
@@ -362,11 +362,15 @@ ${VERSION_NOTE}
             echo "$ISSUE_BODY"
             echo "Labels: bug,P2,audit-finding"
         else
-            CREATED_ISSUE=$(gh issue create $GH_FLAG \
-                --title "ci($tool): add structural config validation step to CI pipeline" \
-                --body "$ISSUE_BODY" \
-                --label "bug,P2,audit-finding" 2>&1)
-            echo "Created issue for $tool gap: $CREATED_ISSUE"
+            # Route creation through the /issue create-hook's programmatic invocation
+            # contract (see commands/issue.md -> Programmatic Invocation Contract) so
+            # dedup and mandatory-section validation run on every CI-gap finding.
+            # Written to a temp file (rather than passed inline via --body) because
+            # $ISSUE_BODY contains backticks and other shell metacharacters that would
+            # be unsafe to re-embed into a Skill args string.
+            CI_GAP_BODY_FILE=$(mktemp)
+            printf '%s' "$ISSUE_BODY" > "$CI_GAP_BODY_FILE"
+            Skill(skill="issue", args="--title \"ci($tool): add structural config validation step to CI pipeline\" --body-file \"$CI_GAP_BODY_FILE\" --label \"bug\" --label \"P2\" --label \"audit-finding\"")
         fi
     fi
 done
@@ -402,10 +406,15 @@ The project has a \`$tool\` validation step in CI, but it only runs in the deplo
     if [ "$DRY_RUN" = "true" ]; then
         echo "=== DRY RUN: Would create placement issue for $tool ==="
     else
-        gh issue create $GH_FLAG \
-            --title "ci($tool): move config validation to PR-time CI workflow" \
-            --body "$ISSUE_BODY" \
-            --label "bug,P3,audit-finding" 2>&1
+        # Route creation through the /issue create-hook's programmatic invocation
+        # contract (see commands/issue.md -> Programmatic Invocation Contract) so
+        # dedup and mandatory-section validation run on every finding. Written to a
+        # temp file (rather than passed inline via --body) because $ISSUE_BODY
+        # contains backticks and other shell metacharacters that would be unsafe to
+        # re-embed into a Skill args string.
+        CI_PLACEMENT_BODY_FILE=$(mktemp)
+        printf '%s' "$ISSUE_BODY" > "$CI_PLACEMENT_BODY_FILE"
+        Skill(skill="issue", args="--title \"ci($tool): move config validation to PR-time CI workflow\" --body-file \"$CI_PLACEMENT_BODY_FILE\" --label \"bug\" --label \"P3\" --label \"audit-finding\"")
     fi
 done
 ```

package/commands/cleanup.md

@@ -1,6 +1,6 @@
 ---
 description: Sweep closed issues for stale labels, missing workflow state, and Project board gaps — plus prune worktrees, branches, and milestones
-argument-hint: [labels | branches | milestones | board | orphans | all]
+argument-hint: "[labels | branches | milestones | board | orphans | all]"
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/compat-audit.md

@@ -1,6 +1,6 @@
 ---
 description: On-demand Claude Code compatibility and feature parity report — compares installed version against the breakpoints registry and lists affected ForgeDock features
-argument-hint: [--refresh]
+argument-hint: "[--refresh]"
 install: extras
 ---
 

package/commands/deploy-info.md

@@ -1,6 +1,6 @@
 ---
 description: Show what will deploy next — diff staging vs main with issue/PR summary, risk assessment, and deploy checklist
-argument-hint: [staging | milestone/{slug} | compare {branch}]
+argument-hint: "[staging | milestone/{slug} | compare {branch}]"
 install: extras
 ---
 

package/commands/deploy-pr.md

@@ -1,6 +1,6 @@
 ---
 description: Ship a branch to its deploy target — detect or create PR, fix CI, review, merge. Returns structured result for callers.
-argument-hint: [source_branch | "staging" | "milestone/{slug}"] [--target TARGET] [--issue ISSUE_NUMBER] [--repo REPO] [--max-ci-iterations N] [--max-review-iterations N] [--dry-run]
+argument-hint: "[source_branch | \"staging\" | \"milestone/{slug}\"] [--target TARGET] [--issue ISSUE_NUMBER] [--repo REPO] [--max-ci-iterations N] [--max-review-iterations N] [--dry-run]"
 allowed-tools: Bash, Read, Grep, Glob, Skill
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/design-bench.md

@@ -1,6 +1,6 @@
 ---
 description: Run the ABC benchmark — reference URL → design-blind brief → render arms A/B/C → blind judge → scorecard with win-rates over n runs
-argument-hint: [<brief-name>|all] [--n <runs>] [--corpus-version <ver>]
+argument-hint: "[<brief-name>|all] [--n <runs>] [--corpus-version <ver>]"
 install: internal
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/design-render-critique-loop.md

@@ -1,6 +1,6 @@
 ---
 description: Render a design from its FORGE:DESIGN_SPEC, critique the rendered pixels against the perceptual negatives, and iterate until it passes or the budget is spent — the missing reward signal.
-argument-hint: [<issue-number>|<spec-path>] [--max-iters <n>] [--viewports desktop,mobile]
+argument-hint: "[<issue-number>|<spec-path>] [--max-iters <n>] [--viewports desktop,mobile]"
 install: internal
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->

package/commands/diagnose.md

@@ -1,6 +1,6 @@
 ---
 description: Trace a failed or stalled pipeline run — identify which FORGE annotation is missing or malformed, diagnose the failure point, and suggest specific remediation steps
-argument-hint: [issue number] [--repo prefix]
+argument-hint: "[issue number] [--repo prefix]"
 install: extras
 ---
 

package/commands/forge-stats.md

@@ -1,6 +1,6 @@
 ---
 description: Track command sizes, detect bloat, compare against baselines and thresholds
-argument-hint: [diff | baseline | full | cost]
+argument-hint: "[diff | baseline | full | cost]"
 install: internal
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
@@ -34,8 +34,8 @@ Commands are classified by role. Each role has a max line count — beyond this,
 |------|-----------|-----------|
 | Orchestrator (work-on, orchestrate, review-pr) | 800 | Delegates to sub-agents; needs full pipeline logic |
 | Agent catalog (review-pr-agents, review-pr-staging) | 1000 | Reference file read on demand, not fed whole to one agent |
-| Specialist (milestone, analytics, validate, etc.) | 400 | Single-purpose; Sonnet attention degrades past this |
-| Utility (cleanup, sync-ecosystem, forge-stats) | 250 | Simple tasks; should stay lean |
+| Specialist (milestone, analytics, sync-ecosystem, validate, etc.) | 400 | Single-purpose or multi-subcommand; Sonnet attention degrades past this |
+| Utility (cleanup, forge-stats) | 250 | Simple tasks; should stay lean |
 | Sub-file (quality-gate, pipeline-health) | 350 | Invoked by parent; shares context budget |
 
 **Current overages (v1.1.0 baseline):**
@@ -46,7 +46,8 @@ Commands are classified by role. Each role has a max line count — beyond this,
 - `review-pr.md`: 796 lines (threshold 800) — OK
 - `validate.md`: 97 lines (threshold 400) — OK (compressed from 679)
 - `orchestrate.md`: 654 lines (threshold 800) — OK
-- `analytics.md`: 590 lines (threshold 400) — **48% over**
+- `analytics.md`: 856 lines (threshold 400) — **114% over**
+- `sync-ecosystem.md`: 799 lines (threshold 400) — **99% over**
 
 ---
 
@@ -75,7 +76,7 @@ for cmd in commands/*.md; do
     case "$name" in
         work-on.md|orchestrate.md|review-pr.md) threshold=800 ;;
         review-pr-agents.md|review-pr-staging.md) threshold=1000 ;;
-        cleanup.md|sync-ecosystem.md|forge-stats.md) threshold=250 ;;
+        cleanup.md|forge-stats.md) threshold=250 ;;
         quality-gate.md|pipeline-health.md) threshold=350 ;;
         *) threshold=400 ;;
     esac

package/commands/forgedock-init.md

@@ -1,6 +1,6 @@
 ---
 description: AI-powered forge.yaml config generator — scans codebase, queries GitHub, auto-fills all optional sections from detection
-argument-hint: [--preserve | --interactive | --section <name>]
+argument-hint: "[--preserve | --interactive | --section <name>]"
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

package/commands/geo-audit.md

@@ -320,12 +320,10 @@ Show the user a structured report BEFORE creating issues:
 
 **Only after user confirms.** If "adjust" — modify. If specific ones — only create those.
 
-For each approved issue:
+For each approved issue, route creation through the `/issue` create-hook's programmatic invocation contract (see `commands/issue.md` → Programmatic Invocation Contract) so dedup and mandatory-section validation run on every finding:
 ```bash
-gh issue create \
-  --title "{fix|feat}: {concise description}" \
-  --label "{priority},{labels}" \
-  --body "$(cat <<'BODY_EOF'
+GEO_BODY_FILE=$(mktemp)
+cat > "$GEO_BODY_FILE" <<'BODY_EOF'
 ## Problem
 
 {1-3 sentences: what the GEO audit found is wrong or missing. Current state with specific numbers.}
@@ -359,9 +357,14 @@ Identified in GEO audit on {DATE}.
 
 {Concrete technical steps}
 BODY_EOF
-)"
 ```
 
+```
+Skill(skill="issue", args="--title \"{fix|feat}: {concise description}\" --body-file \"$GEO_BODY_FILE\" --label \"{priority}\" --label \"seo\" --label \"geo\"")
+```
+
+`{priority}`, `seo`, and `geo` are each passed as their own `--label` flag — `/issue`'s programmatic mode does not comma-split a single `--label` value. Every row in the Phase 3 table maps to the `seo,geo` label pair, so both are passed as separate literal `--label` flags rather than a single `{labels}` placeholder.
+
 If a `geo-ai-discoverability` milestone exists, assign issues to it:
 ```bash
 gh issue edit {NUMBER} --milestone "geo-ai-discoverability"

package/commands/incident-response.md

@@ -1,6 +1,6 @@
 ---
 description: Coordinate P0 incident response — hotfix validation, timeline reconstruction, and post-incident analysis
-argument-hint: [issue number | "active" | "postmortem {issue}"]
+argument-hint: "[issue number | \"active\" | \"postmortem {issue}\"]"
 install: extras
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
@@ -330,9 +330,10 @@ POSTMORTEM_EOF
 For each action item identified in the postmortem:
 
 ```bash
-gh issue create --title "{fix|feat|refactor}: {action item title}" \
-  --label "{type_label},P{priority}" \
-  --body "$(cat <<'BODY_EOF'
+ACTION_ITEM_TITLE="{fix|feat|refactor}: {action item title}"
+ACTION_ITEM_BODY_TMPFILE=$(mktemp)
+trap 'rm -f "$ACTION_ITEM_BODY_TMPFILE"' EXIT
+cat > "$ACTION_ITEM_BODY_TMPFILE" <<'BODY_EOF'
 ## Problem
 
 {What gap or vulnerability this action item addresses. What failure mode it prevents.}
@@ -361,7 +362,16 @@ See postmortem: #{INCIDENT_NUMBER} (comment)
 
 {Concrete next step}
 BODY_EOF
-)"
+# Route through the /issue create-hook (canonical dedup + body validation) instead of a raw
+# `gh issue create`.
+Skill(skill="issue", args="--title \"$ACTION_ITEM_TITLE\" --body-file \"$ACTION_ITEM_BODY_TMPFILE\" --label \"{type_label}\" --label \"P{priority}\"")
+rm -f "$ACTION_ITEM_BODY_TMPFILE"
+trap - EXIT
+ACTION_ITEM_NUMBER=$(gh issue list \
+  --state open \
+  --search "$ACTION_ITEM_TITLE" \
+  --json number,title \
+  --jq --arg t "$ACTION_ITEM_TITLE" '.[] | select(.title == $t) | .number' 2>/dev/null | head -1)
 ```
 
 ---