@mmerterden/multi-agent-pipeline 14.2.1 → 15.0.0

package/pipeline/commands/multi-agent/sync/SKILL.md

@@ -59,8 +59,8 @@ Run every step automatically:
 ```
 Step 1: PLATFORM    Detect macOS / Linux / Windows (Git Bash / WSL); export PLATFORM env
 Step 1.5: DETECT    Compare timestamps, find stale targets
-Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 49 sub-command skills)
-Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + 44 specs as refs + 8 agent TOML)
+Step 2: COPILOT     Claude Code -> Copilot CLI (instructions + 51 sub-command skills)
+Step 2b: CODEX      Claude Code -> Codex CLI (1 router skill + 51 specs as refs + 8 agent TOML)
 Step 3: REPO        Claude Code -> pipeline repo (genericized, personal data scrub, bash -n on all sh)
 Step 3c: PLUGINS    pipeline shared/external -> multi-agent-plugins marketplace (rebuild knowledge/,
                      bump changed plugins' patch version, commit + push the plugins repo)
@@ -127,13 +127,13 @@ If nothing is stale → report "All targets up to date" and stop.
    - `~/.claude/CLAUDE.md`, `~/.claude/rules/`, `~/.claude/knowledge/`
    - `~/.claude/scripts/`  -  EXCEPT `pre-commit-check.sh`, `agent-guard.sh`, `agent-guard.py`, and `build-stack-plugins.mjs` (generic, synced)
    - `~/.claude/settings.json`
-   - **Any `~/.claude/commands/multi-agent/*.md` whose frontmatter has `local-only: true`** - these are user/repo-specific alias wrappers that delegate to a private marketplace plugin (e.g. corporate `ai-ios-engineering-toolkit` skills exposed as `multi-agent:<name>`). Syncing them would leak the private plugin/skill names into the public pipeline. Filter before copy: skip every source file containing `local-only: true`, and after copy assert none reached `pipeline/commands/`.
+   - **Any `~/.claude/commands/multi-agent/*.md` whose frontmatter has `local-only: true`** - these are user/repo-specific alias wrappers that delegate to a private marketplace plugin (e.g. corporate `ai-ios-toolkit` skills exposed as `multi-agent:<name>`). Syncing them would leak the private plugin/skill names into the public pipeline. Filter before copy: skip every source file containing `local-only: true`, and after copy assert none reached `pipeline/commands/`.
      ```bash
      # backstop: no local-only wrapper may exist in the synced target
      grep -rl "^local-only: true" ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
        && { echo "ABORT: local-only wrapper leaked into pipeline/commands"; exit 1; } || true
      # backstop: no corporate marketplace/skill reference in the synced tree
-     grep -rniE "ai-ios-engineering-toolkit:(create-ui-component|evolve-ui-component|fix-bug|branch-and-pr|backlog|code-connect|figma-utility|resource-utility|component-wiki|component-docs|figma-setup)" \
+     grep -rniE "ai-ios(-engineering)?-toolkit:(create-ui-component|evolve-ui-component|fix-bug|branch-and-pr|backlog|code-connect|figma-utility|resource-utility|component-wiki|component-docs|figma-setup)" \
        ~/multi-agent-pipeline/pipeline/commands/ 2>/dev/null \
        && { echo "ABORT: corporate reference leaked into pipeline/commands"; exit 1; } || true
      ```
@@ -176,7 +176,7 @@ If nothing is stale → report "All targets up to date" and stop.
 Unlike the Copilot step, this one does **not** hand-copy files. The Codex tree is a
 *transform* of the Claude tree, not a mirror of it, and the transform is real work:
 
-- the 43 sub-command specs become reference files, because Codex silently truncates
+- the 51 sub-command specs become reference files, because Codex silently truncates
   its skills block (see `cross-cli-contract.md` 2.6 for the measurement)
 - every `$HOME/.claude/...` reference to a CLI-owned tree is retargeted, with
   `agents/<persona>.md` becoming `.toml` and the dispatcher becoming the router skill
@@ -233,13 +233,20 @@ node "$HOME/multi-agent-pipeline/pipeline/scripts/build-stack-plugins.mjs" --dry
 
 # 2. Apply: rebuild each stack plugin's knowledge/ from shared/external,
 #    regenerate plugin.json skills[], bump the patch version of any plugin
-#    whose skill set changed. Cross-stack skills -> ai-common-engineering-toolkit;
+#    whose skill set changed. Cross-stack skills -> ai-common-toolkit;
 #    Apple/Xcode-only skills -> iOS plugin only.
 node "$HOME/multi-agent-pipeline/pipeline/scripts/build-stack-plugins.mjs"
 ```
 
 **Version-based management:** the generator bumps a plugin's `version` (patch) only when its skill set actually changed. Idempotent - a no-op run bumps nothing. Consumers pick up new versions via `/multi-agent:update` (which runs `claude marketplace update multi-agent-plugins`).
 
+**Help + README freshness (mandatory when the generator reported any change):**
+
+1. Every plugin ships a `tools/help` skill that renders its catalog LIVE from `plugin.json`, so it needs no per-skill edits - but verify each changed plugin still registers it (`grep -c "./skills/tools/help" plugins/<name>/.claude-plugin/plugin.json` = 1) and that a new plugin gets one before publish.
+2. Plugin README tables sync through `python3 tools/bump.py <plugin> --set <version>`; run `python3 tools/bump.py --check` and treat DRIFT as a blocker.
+3. `python3 tools/validate.py` must be clean (it also enforces the CHANGELOG heading for every bumped version - write the entry, do not backdate).
+4. When the pipeline's command surface changed in the same sync (new/renamed `/multi-agent:*` commands), confirm `commands/multi-agent/help/SKILL.md` and both pipeline READMEs (`README.md`, `README.tr.md`) were updated in Step 3 before pushing here.
+
 **Publish (only if the generator reported bumps):**
 
 ```bash
@@ -484,21 +491,21 @@ When invoked with the `release` argument:
 > Codex takes the Step 2b path instead; see that section.
 
 This runs on the Claude <-> Copilot axis. Codex is NOT synced here: it receives the
-same 43 specs as reference files rather than as peer skills, via Step 2b -  see
+same 51 specs as reference files rather than as peer skills, via Step 2b -  see
 `cross-cli-contract.md` 2.6 for why the parity axis differs per host.
 
 | Claude Code | Copilot CLI |
 |-------------|-------------|
 | `~/.claude/commands/multi-agent/{cmd}/SKILL.md` | `~/.copilot/skills/multi-agent-{cmd}/SKILL.md` |
 
-**49 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
+**51 commands are synced** (canonical inventory  -  must match `cross-cli-contract.md` section 1; drift = contract violation):
 
 ```
-analysis, analysis-resolve, autopilot, build-optimize, channels, create-jira, design-check, dev,
+analysis, analysis-resolve, autopilot, build-optimize, channels, complaint-analysis, create-jira, design-check, dev,
 dev-autopilot, dev-local, dev-local-autopilot, diff-explain, forget, garbage-collect,
 help, ios-coding-standard, issue, jira, kill, language, local,
-local-autopilot, log, manual-test, prune-logs, purge, refactor, resume, review, review-issue, review-jira,
-routines, save, scan, search, setup, ship, stack, status, store-ready, sync, test, test-accessibility,
+local-autopilot, log, manual-test, prune-logs, prune-prompts, purge, refactor, resume, review, review-issue, review-jira,
+routines, save, scan, search, setup, resume-local, stack, status, store-ready, sync, test, test-accessibility,
 test-dark-mode, test-dynamic-type, test-screenshots, testflight-validation, uninstall, update
 ```
 

package/pipeline/commands/multi-agent/testflight-validation/SKILL.md

@@ -40,7 +40,7 @@ Unchanged from before the merge, on the iOS path:
 |---|---|---|
 | **1. Static** | `ios_app_store_audit` (18 rules, real ITMS codes) | an `.xcarchive` |
 | **2. Authoritative** | `ios_testflight_validate` → `altool --validate-app` | an `.ipa` + credentials |
-| **3. Policy** | `app-store-review` skill vs repo source | repo checkout |
+| **3. Policy** | `ai-ios-toolkit:app-store-review` skill vs repo source | repo checkout |
 
 A skipped gate is never folded into the pass count, and the run never uploads. The
 report lands in `~/StoreChecks/ios-<repo>-<branch>-<timestamp>/report.md`.

package/pipeline/commands/multi-agent/uninstall/SKILL.md

@@ -28,6 +28,8 @@ Tokens in the OS credential store are NEVER removed by either mode.
 - `~/.claude/CLAUDE.md` (user customisations)
 - `~/.claude/rules/` (user-owned; installed write-if-missing, never overwritten)
 - User content OUTSIDE the `<!-- multi-agent-pipeline:begin/end -->` markers (`copilot-instructions.md`)
+- Local-only alias wrappers (`local-only: true` frontmatter) under `commands/multi-agent/` (user-authored, exist nowhere else)
+- User-authored skill dirs and agent files (only pipeline-shipped names are removed)
 
 Settings (`multi-agent-preferences.json`) and the log root (`~/.claude/logs/multi-agent/`) are kept by default and removed only when the user picks full cleanup (`--all-data`).
 

package/pipeline/commands/multi-agent/update/SKILL.md

@@ -101,7 +101,7 @@ Update the pipeline in one command. Existing preferences are preserved; only ski
 ```
 Current: v3.6.0
   -> git pull origin main
-  -> node install.js --all (44 commands, 50 scripts, 291 skills)
+  -> node install.js --all (50 commands, 80 scripts, 203 skills)
   -> migrate-prefs.mjs (0 changes  -  already v2.1.0)
 
 ✓ Updated: v3.6.0 → v3.7.0

package/pipeline/lib/extract-conventions.sh

@@ -140,9 +140,31 @@ run_find() {
   if [ "${#roots[@]}" -eq 0 ]; then
     return 0
   fi
+  # No explicit -print anywhere in this expression means find falls back to
+  # its own implicit print on the WHOLE expression - which fires for every
+  # true branch of the -prune OR-chain too, including the pruned directories
+  # themselves (their contents are still correctly skipped; the dir path
+  # itself was not). An explicit -print, implicit-AND'd onto the caller's own
+  # criteria as the OR-chain's last branch, only fires on that branch.
   find "${roots[@]}" \
     "${SKIP_PRUNE_ARGS[@]}" \
-    "$@" 2>/dev/null || true
+    "$@" -print 2>/dev/null || true
+}
+
+# Count how many of the newline-separated paths in $1 contain a line matching
+# grep pattern $2. `xargs grep -l` here used to word-split on whitespace by
+# default, so any path with a space in it was silently mis-scanned as several
+# nonexistent partial paths (a false-negative on real matches, not an error -
+# stderr was already redirected to /dev/null). Reading line-by-line handles
+# that correctly since each line is one whole path regardless of embedded
+# spaces.
+count_grep_hits() {
+  local list="$1" pattern="$2" n=0 f
+  while IFS= read -r f; do
+    [ -z "$f" ] && continue
+    grep -lq "$pattern" "$f" 2>/dev/null && n=$((n + 1))
+  done <<< "$list"
+  printf '%s' "$n"
 }
 
 # ---- confidence classifier ----------------------------------------------------
@@ -849,8 +871,15 @@ bucket_localization_key() {
   case "$PLATFORM" in
     ios)
       local strings_files xcstrings_files
-      strings_files=$(find "$REPO_PATH" -name 'Localizable.strings' "${SKIP_PRUNE_ARGS[@]}" -o -name 'Localizable.strings' -type f -print 2>/dev/null | head -5 || true)
-      xcstrings_files=$(find "$REPO_PATH" -name 'Localizable.xcstrings' -type f 2>/dev/null | head -3 || true)
+      # An earlier version ANDed -name onto the FRONT of the prune chain
+      # (`-name X SKIP_PRUNE_ARGS...`), which requires every -prune branch to
+      # ALSO be named "Localizable.strings" - a directory prune can never
+      # satisfy that, so no prune ever fired and the search walked into
+      # Pods/.build/node_modules looking for vendored copies. Prunes must
+      # stay their own independent OR-chain, ahead of (not ANDed with) the
+      # real search criteria. The xcstrings search had no prune chain at all.
+      strings_files=$(find "$REPO_PATH" "${SKIP_PRUNE_ARGS[@]}" -name 'Localizable.strings' -type f -print 2>/dev/null | head -5 || true)
+      xcstrings_files=$(find "$REPO_PATH" "${SKIP_PRUNE_ARGS[@]}" -name 'Localizable.xcstrings' -type f -print 2>/dev/null | head -3 || true)
       if [ -n "$strings_files" ]; then
         keys=$(printf '%s\n' "$strings_files" | while IFS= read -r f; do
           [ -n "$f" ] && grep -hEo '^"[^"]+"' "$f" 2>/dev/null | tr -d '"'
@@ -918,9 +947,9 @@ bucket_di_registration() {
       fi
       files=$(run_find -type f -name '*.swift' 2>/dev/null || true)
       if [ -n "$files" ]; then
-        resolver_count=$(printf '%s\n' "$files" | xargs grep -l 'Resolver.register' 2>/dev/null | wc -l | tr -d ' ' || echo 0)
-        factory_count=$(printf '%s\n' "$files" | xargs grep -l '@Injected\|Container.shared' 2>/dev/null | wc -l | tr -d ' ' || echo 0)
-        swinject_count=$(printf '%s\n' "$files" | xargs grep -l 'Swinject\|Container()' 2>/dev/null | wc -l | tr -d ' ' || echo 0)
+        resolver_count=$(count_grep_hits "$files" 'Resolver.register')
+        factory_count=$(count_grep_hits "$files" '@Injected\|Container.shared')
+        swinject_count=$(count_grep_hits "$files" 'Swinject\|Container()')
       fi
       manual_count=${manual_count:-0}; resolver_count=${resolver_count:-0}; factory_count=${factory_count:-0}; swinject_count=${swinject_count:-0}
 
@@ -941,9 +970,9 @@ bucket_di_registration() {
       files=$(run_find -type f -name '*.kt' 2>/dev/null || true)
       if [ -z "$files" ]; then empty_bucket; return; fi
       local hilt_count koin_count dagger_count
-      hilt_count=$(printf '%s\n' "$files" | xargs grep -l '@Module\|@InstallIn\|@HiltViewModel' 2>/dev/null | wc -l | tr -d ' ' || echo 0)
-      koin_count=$(printf '%s\n' "$files" | xargs grep -l 'koinViewModel\|module {' 2>/dev/null | wc -l | tr -d ' ' || echo 0)
-      dagger_count=$(printf '%s\n' "$files" | xargs grep -l '@Component\|@Subcomponent' 2>/dev/null | wc -l | tr -d ' ' || echo 0)
+      hilt_count=$(count_grep_hits "$files" '@Module\|@InstallIn\|@HiltViewModel')
+      koin_count=$(count_grep_hits "$files" 'koinViewModel\|module {')
+      dagger_count=$(count_grep_hits "$files" '@Component\|@Subcomponent')
       hilt_count=${hilt_count:-0}; koin_count=${koin_count:-0}; dagger_count=${dagger_count:-0}
       if [ "$hilt_count" -ge "$koin_count" ] && [ "$hilt_count" -ge "$dagger_count" ] && [ "$hilt_count" -gt 0 ]; then
         emit_bucket "Hilt" "@Module @InstallIn(SingletonComponent::class)" "$(confidence_for "$hilt_count")" "[]" '["Koin","Dagger"]'
@@ -959,9 +988,9 @@ bucket_di_registration() {
       files=$(run_find -type f -name '*.py' 2>/dev/null || true)
       if [ -z "$files" ]; then empty_bucket; return; fi
       local depends_count dishka_count di_count
-      depends_count=$(printf '%s\n' "$files" | xargs grep -l 'Depends(' 2>/dev/null | wc -l | tr -d ' ' || echo 0)
-      dishka_count=$(printf '%s\n' "$files" | xargs grep -l 'dishka' 2>/dev/null | wc -l | tr -d ' ' || echo 0)
-      di_count=$(printf '%s\n' "$files" | xargs grep -l 'dependency_injector' 2>/dev/null | wc -l | tr -d ' ' || echo 0)
+      depends_count=$(count_grep_hits "$files" 'Depends(')
+      dishka_count=$(count_grep_hits "$files" 'dishka')
+      di_count=$(count_grep_hits "$files" 'dependency_injector')
       depends_count=${depends_count:-0}; dishka_count=${dishka_count:-0}; di_count=${di_count:-0}
       if [ "$depends_count" -ge "$dishka_count" ] && [ "$depends_count" -ge "$di_count" ] && [ "$depends_count" -gt 0 ]; then
         emit_bucket "FastAPI Depends" "def handler(svc: FooService = Depends(get_service))" "$(confidence_for "$depends_count")" "[]" '["dishka","dependency_injector"]'
@@ -977,9 +1006,9 @@ bucket_di_registration() {
       files=$(run_find -type f \( -name '*.tsx' -o -name '*.ts' \) 2>/dev/null || true)
       if [ -z "$files" ]; then empty_bucket; return; fi
       local context_count zustand_count hook_count
-      context_count=$(printf '%s\n' "$files" | xargs grep -l 'createContext\|\.Provider' 2>/dev/null | wc -l | tr -d ' ' || echo 0)
-      zustand_count=$(printf '%s\n' "$files" | xargs grep -l "from 'zustand'\|from \"zustand\"" 2>/dev/null | wc -l | tr -d ' ' || echo 0)
-      hook_count=$(printf '%s\n' "$files" | xargs grep -l 'export function use[A-Z]' 2>/dev/null | wc -l | tr -d ' ' || echo 0)
+      context_count=$(count_grep_hits "$files" 'createContext\|\.Provider')
+      zustand_count=$(count_grep_hits "$files" "from 'zustand'\\|from \"zustand\"")
+      hook_count=$(count_grep_hits "$files" 'export function use[A-Z]')
       context_count=${context_count:-0}; zustand_count=${zustand_count:-0}; hook_count=${hook_count:-0}
       if [ "$context_count" -ge "$zustand_count" ] && [ "$context_count" -ge "$hook_count" ] && [ "$context_count" -gt 0 ]; then
         emit_bucket "React Context Provider" "const FooContext = createContext<Foo>(...)" "$(confidence_for "$context_count")" "[]" '["zustand","custom-hook-factory"]'

package/pipeline/lib/fetch-figma-annotations.sh

@@ -124,10 +124,17 @@ trap 'rm -rf "$TMPDIR_A"' EXIT INT TERM
 # curl one /nodes batch (token via -K config so it never lands in argv).
 curl_nodes() {
   local out="$1" ids="$2" code
+  # curl already writes "000" via -w on a total connection failure (and
+  # still exits non-zero for it, which the inner `|| echo "000"` used to
+  # catch too - so `code` became the literal string "000000", never
+  # matching a plain "000" comparison anywhere downstream). `|| true` keeps
+  # a failing curl from tripping any caller's `set -e` without re-printing
+  # into $code; `:-000` only fills in when curl fails before -w ever runs.
   code=$(curl -sS -o "$out" -w '%{http_code}' \
             --max-time "$HTTP_TIMEOUT" --connect-timeout 5 \
             -K <(printf 'header = "X-Figma-Token: %s"\n' "$FIGMA_TOKEN") \
-            "$FIGMA_API/files/$FILE_KEY/nodes?ids=$ids" || echo "000")
+            "$FIGMA_API/files/$FILE_KEY/nodes?ids=$ids") || true
+  code="${code:-000}"
   printf '%s' "$code"
 }
 

package/pipeline/lib/fetch-fortify.sh

@@ -202,18 +202,33 @@ fortify_get() {
   return 1
 }
 
-VERSION_JSON=$(fortify_get "projectVersions/$VERSION_ID" || true)
-case "$VERSION_JSON" in
-  HTTP_AUTH_FAILED|*HTTP_4*)
-    echo "ERR: Fortify auth failed (Bearer + FortifyToken both rejected)" >&2
-    exit 3 ;;
-esac
+# Check fortify_get's actual exit status, not a string pattern over its
+# output - the old `case ... HTTP_AUTH_FAILED|*HTTP_4*)` only recognized
+# auth failures and 4xx. A dropped connection, timeout, or 5xx made
+# fortify_get return "...\nHTTP_000"/"...\nHTTP_5xx", which matched neither
+# arm, so the case fell through, VERSION_JSON stayed unparseable garbage,
+# and the Python block below silently treated that as "0 issues found" -
+# the security gate passing precisely when it couldn't check anything.
+if ! VERSION_JSON=$(fortify_get "projectVersions/$VERSION_ID"); then
+  echo "ERR: Fortify fetch failed for projectVersions/$VERSION_ID: ${VERSION_JSON:-no response}" >&2
+  exit 3
+fi
 
 ISSUES_JSON=""
 if [ -n "$ISSUE_ID" ]; then
-  ISSUES_JSON=$(fortify_get "projectVersions/$VERSION_ID/issues?q=issueInstanceId:\"$ISSUE_ID\"&limit=20" || true)
+  if ! ISSUES_JSON=$(fortify_get "projectVersions/$VERSION_ID/issues?q=issueInstanceId:\"$ISSUE_ID\"&limit=20"); then
+    echo "ERR: Fortify issues fetch failed for issue $ISSUE_ID: ${ISSUES_JSON:-no response}" >&2
+    exit 3
+  fi
 else
-  ISSUES_JSON=$(fortify_get "projectVersions/$VERSION_ID/issues?limit=200&filter=ANALYSIS%3D%3DNotAnIssue,ANALYSIS%3D%3DFalsePositive&filterset=Critical%2CHigh" || true)
+  # filter=ANALYSIS!=NotAnIssue,ANALYSIS!=FalsePositive (%21%3D is `!=`) is
+  # meant to EXCLUDE suppressed findings. It was encoded as %3D%3D (`==`),
+  # which instead selected only suppressed findings - the opposite of the
+  # gate's intent whenever SSC honors the filter.
+  if ! ISSUES_JSON=$(fortify_get "projectVersions/$VERSION_ID/issues?limit=200&filter=ANALYSIS%21%3DNotAnIssue,ANALYSIS%21%3DFalsePositive&filterset=Critical%2CHigh"); then
+    echo "ERR: Fortify issues fetch failed for version $VERSION_ID: ${ISSUES_JSON:-no response}" >&2
+    exit 3
+  fi
 fi
 
 # Issue details are fetched per-issue lazily  -  only for the first 10 to keep

package/pipeline/lib/figma-screenshot.sh

@@ -180,10 +180,20 @@ curl_figma() {
   for attempt in 1 2 3; do
     # Token header goes through a curl config via process substitution so it
     # never appears in argv (argv is visible to ps).
+    # curl already writes "000" via -w on a total connection failure (and
+    # still exits non-zero for it, which the inner `|| echo "000"` used to
+    # catch too - so `code` became the literal string "000000", matching
+    # neither the `000)` retry branch below nor handle_http_code's "000)
+    # network timeout" case, just the generic catch-all). `|| true` on its
+    # own line keeps `set -e` from aborting on curl's exit status without
+    # re-printing anything into $code; the `:-000` fallback only fires for
+    # the rarer case where curl fails before -w ever runs and $code is
+    # genuinely empty.
     code=$(curl -sS -o "$out" -w '%{http_code}' \
               --max-time "$HTTP_TIMEOUT" --connect-timeout 5 \
               -K <(printf 'header = "X-Figma-Token: %s"\n' "$FIGMA_TOKEN") \
-              "$url" || echo "000")
+              "$url") || true
+    code="${code:-000}"
     case "$code" in
       2*) printf '%s' "$code"; return 0 ;;
       401|403) printf '%s' "$code"; return 0 ;;

package/pipeline/lib/issue-fetcher.sh

@@ -12,7 +12,15 @@
 #     "title":      "...",
 #     "type":       "Bug" | "Task" | "Story" | "Issue",
 #     "status":     "...",
-#     "description":"...",                          // raw body (truncated to 4000 chars)
+#     "description":"...",                          // raw body (truncated to 4000 chars); this
+#                                                     // issue's OWN description  -  never auto-substituted
+#     "parentKey":         "PROJ-1" | null,          // jira only; set when own description is empty
+#                                                     // AND a parent link exists (single hop, no chasing
+#                                                     // the parent's parent)
+#     "parentDescription": "..." | null,             // jira only; the parent's description (truncated
+#                                                     // 4000 chars), only when own is empty and parent
+#                                                     // has content  -  a CANDIDATE, not applied automatically;
+#                                                     // the caller must confirm before using it as "description"
 #     "url":        "https://...",
 #     "host":       "jira.example.com" | "github.com",
 #     "owner":      "org" (gh) | null,
@@ -21,11 +29,17 @@
 #     "maturity": {
 #        "score":     0..100,
 #        "blockers":  ["status_closed", "description_empty"],
-#        "warnings":  ["short_description", "no_repro_steps"],
+#        "warnings":  ["short_description", "no_repro_steps", "description_empty_parent_available"],
 #        "summary":   "Description boş  -  pipeline başlatılamaz." (human-readable, tr|en)
 #     }
 #   }
 #
+# "description_empty_parent_available": own description is empty but parentDescription is
+# non-empty. This is a WARNING, not a blocker  -  the caller must ask the user (or, in
+# autopilot, auto-accept per the same "warnings auto-continue" rule) whether to proceed
+# using parentDescription as the working description. See jira/SKILL.md's maturity
+# section for the exact question wording.
+#
 # Required env:
 #   ACCOUNT_JIRA_TOKEN_KEY    keychain service name (optional)
 #   ACCOUNT_JIRA_HOST         e.g. jira.example.com    (optional)
@@ -51,8 +65,16 @@ detect_kind() {
   case "$in" in
     *atlassian.net/browse/*|*jira*/browse/*|http*://*/browse/*) echo "jira-url"; return ;;
     *github.com/*/issues/*) echo "gh-url"; return ;;
-    [A-Z]*-[0-9]*) echo "jira-id"; return ;;
   esac
+  # A bare Jira key is PROJECT-NUMBER, anchored end-to-end. The case glob this
+  # replaced ([A-Z]*-[0-9]*) matches whenever that shape appears ANYWHERE in a
+  # longer string (case patterns match the whole string, but `*` is greedy
+  # enough to swallow surrounding words) - "Add iOS-16 support" contains
+  # "S-16" and satisfied it, silently misrouting a free-text task description
+  # into a Jira lookup instead of the freetext path below.
+  if [[ "$in" =~ ^[A-Z][A-Z0-9]*-[0-9]+$ ]]; then
+    echo "jira-id"; return
+  fi
   # Bare issue number ("316" or "#316") must resolve BEFORE the repo#N glob:
   # `*\#[0-9]*` also matches "#316" with an empty repo prefix, which used to
   # misroute it to gh-short and build https://github.com/<owner>//issues/316.
@@ -140,7 +162,7 @@ fetch_jira() {
     return 1
   fi
   curl -sf -K <(jira_auth_cfg "$token") \
-    "https://$JIRA_HOST/rest/api/2/issue/$key?fields=summary,status,issuetype,description,priority,resolution,fixVersions" \
+    "https://$JIRA_HOST/rest/api/2/issue/$key?fields=summary,status,issuetype,description,priority,resolution,fixVersions,parent" \
     || { echo "ERR: Jira fetch failed for $key" >&2; return 1; }
 }
 
@@ -197,6 +219,8 @@ descriptor = {
     "resolution":  resolution or None,
     "fixVersions": fix_versions,
     "description": desc,
+    "parentKey":   fields.get("parentKey") or None,
+    "parentDescription": fields.get("parentDescription") or None,
     "host":        fields.get("host") or None,
     "url":         fields.get("url") or None,
     "owner":       fields.get("owner") or None,
@@ -213,6 +237,9 @@ title = (descriptor.get("title") or "").strip()
 status = (descriptor.get("status") or "").lower()
 itype = (descriptor.get("type") or "").lower()
 
+parent_desc = (descriptor.get("parentDescription") or "").strip()
+parent_key = descriptor.get("parentKey") or ""
+
 blockers, warnings = [], []
 closed = {"done","closed","cancelled","canceled","resolved"}
 if status in closed:
@@ -221,7 +248,14 @@ if status in closed:
 if resolution:
     blockers.append("already_resolved")
 if not desc.strip():
-    blockers.append("description_empty")
+    # A parent with actual content is a candidate, not an auto-fix  -  surface it
+    # as a warning so the caller asks the user before substituting it in (or,
+    # under autopilot, auto-accepts per the same "warnings auto-continue" rule).
+    # No parent / an equally-empty parent keeps the hard blocker as before.
+    if parent_desc:
+        warnings.append("description_empty_parent_available")
+    else:
+        blockers.append("description_empty")
 elif len(desc.strip()) < 80:
     warnings.append("short_description")
 if len(title) < 10:
@@ -239,6 +273,7 @@ labels_tr = {
     "status_closed":         "Issue kapalı veya iptal edilmiş",
     "already_resolved":      "Issue zaten resolved/merged ({})".format(resolution or " - "),
     "description_empty":     "Açıklama boş",
+    "description_empty_parent_available":"Açıklama boş ama parent'ta ({}) içerik var  -  oradan devam edilsin mi?".format(parent_key or " - "),
     "short_description":     "Açıklama çok kısa (<80 karakter)",
     "short_title":           "Başlık çok kısa (<10 karakter)",
     "no_repro_steps":        "Bug için repro adımları yok",
@@ -248,6 +283,7 @@ labels_en = {
     "status_closed":         "Issue is closed/cancelled",
     "already_resolved":      "Issue already resolved/merged ({})".format(resolution or " - "),
     "description_empty":     "Description is empty",
+    "description_empty_parent_available":"Description is empty but the parent ({}) has content  -  continue from there?".format(parent_key or " - "),
     "short_description":     "Description too short (<80 chars)",
     "short_title":           "Title too short (<10 chars)",
     "no_repro_steps":        "Bug missing reproduction steps",
@@ -309,21 +345,52 @@ description = (f.get("description") or "")
 priority    = _name(f.get("priority"))
 resolution  = _name(f.get("resolution"))
 fixversions = ",".join((v or {}).get("name", "") for v in (f.get("fixVersions") or []))
-parts = [title, itype, status, description, priority, resolution, fixversions]
+parentkey   = (f.get("parent") or {}).get("key", "") or ""
+parts = [title, itype, status, description, priority, resolution, fixversions, parentkey]
 parts = [v.replace("\x1f", " ") for v in parts]
 sys.stdout.write("\x1f".join(parts))
 ')
-      IFS=$'\x1f' read -r -d '' title itype status description priority resolution fixversions <<< "$parsed" || true
+      IFS=$'\x1f' read -r -d '' title itype status description priority resolution fixversions parentkey <<< "$parsed" || true
+      # `<<<` appends a trailing newline to its input; `read -d ''` has no
+      # delimiter to stop on, so that newline folds into whichever field
+      # comes last  -  now parentkey. Strip it, or a genuinely-empty parent
+      # (no fallback needed) or a real key gets a stray \n appended, which
+      # breaks the parent lookup's URL and misreports parentKey in output.
+      parentkey="${parentkey%$'\n'}"
     else
       title="(unfetched)"; itype="Task"; status="Unknown"; description=""
-      priority=""; resolution=""; fixversions=""
+      priority=""; resolution=""; fixversions=""; parentkey=""
+    fi
+    # Development sub-tasks are frequently filed with an empty description while
+    # the real requirements live on the parent (story/epic). Single hop only  -
+    # if the parent is also empty/unreachable, description stays empty and
+    # description_empty blocks below, same as before this existed. This fetcher
+    # only surfaces the parent's description as a CANDIDATE (parentDescription)
+    # - it never substitutes it into "description" itself. Whether to actually
+    # use it is a decision for the caller to put in front of the user (or
+    # auto-accept under autopilot), same as any other maturity warning.
+    parentdesc=""
+    if [ -z "$(printf '%s' "$description" | tr -d '[:space:]')" ] && [ -n "${parentkey:-}" ]; then
+      praw=$(fetch_jira "$parentkey") || praw=""
+      if [ -n "$praw" ]; then
+        pdesc=$(printf '%s' "$praw" | python3 -c '
+import json, sys
+d = json.load(sys.stdin)
+f = d.get("fields", {}) or {}
+sys.stdout.write((f.get("description") or "").replace("\x1f", " "))
+')
+        if [ -n "$(printf '%s' "$pdesc" | tr -d '[:space:]')" ]; then
+          parentdesc="$pdesc"
+        fi
+      fi
     fi
     branch=$(branch_for "$KEY" "$itype" "$title")
     emit_descriptor \
       "kind=jira" "key=$KEY" "title=$title" "type=$itype" "status=$status" \
       "description=$description" "host=$JIRA_HOST" \
       "url=https://$JIRA_HOST/browse/$KEY" "branchHint=$branch" \
-      "priority=$priority" "resolution=$resolution" "fixVersions=$fixversions"
+      "priority=$priority" "resolution=$resolution" "fixVersions=$fixversions" \
+      "parentKey=$parentkey" "parentDescription=$parentdesc"
     ;;
 
   jira-url)
@@ -335,7 +402,7 @@ sys.stdout.write("\x1f".join(parts))
   gh-url)
     OWNER=$(printf '%s' "$INPUT" | sed -E 's#https?://github.com/##; s#/.*##')
     REPO=$(printf '%s' "$INPUT" | sed -E 's#https?://github.com/[^/]+/##; s#/.*##')
-    NUM=$(printf '%s' "$INPUT" | sed -E 's#.*/issues/##; s#[/?].*##')
+    NUM=$(printf '%s' "$INPUT" | sed -E 's#.*/issues/##; s#[/?#].*##')
     raw=$(fetch_github "$OWNER" "$REPO" "$NUM") || raw=""
     if [ -n "$raw" ]; then
       # Single python3 pass  -  see jira-id branch for rationale on the

package/pipeline/lib/md2confluence-v3.py

@@ -137,7 +137,7 @@ MERMAID_FENCE_OPEN_RE = re.compile(r"^```mermaid\s*$")
 def mermaid_macro(body: str) -> str:
     return (
         '<ac:structured-macro ac:name="mermaid">'
-        f'<ac:plain-text-body><![CDATA[\n{body}\n]]></ac:plain-text-body>'
+        f'<ac:plain-text-body><![CDATA[\n{cdata_escape(body)}\n]]></ac:plain-text-body>'
         '</ac:structured-macro>'
     )
 
@@ -205,6 +205,20 @@ def esc(s: str) -> str:
     return html.escape(s, quote=False)
 
 
+def cdata_escape(s: str) -> str:
+    """Make `s` safe to embed inside a CDATA section.
+
+    A code fence or Mermaid diagram can legitimately contain the literal
+    three-character sequence "]]>" (a real XML CDATA example, a shell case
+    pattern, ...), which is the CDATA terminator - embedding it unescaped
+    closes the section early and leaves the rest of the storage-format XML
+    unparsed as markup. Splitting it across a close/reopen pair is the
+    standard CDATA-in-CDATA escape: it renders identically, but is no longer
+    a literal terminator to the XML parser.
+    """
+    return s.replace("]]>", "]]]]><![CDATA[>")
+
+
 @dataclass
 class InlineContext:
     attachments_available: set[str]
@@ -388,7 +402,7 @@ def markdown_to_storage(
                 out.append(
                     '<ac:structured-macro ac:name="code">'
                     f'<ac:parameter ac:name="language">{esc(code_lang)}</ac:parameter>'
-                    f'<ac:plain-text-body><![CDATA[{body}]]></ac:plain-text-body>'
+                    f'<ac:plain-text-body><![CDATA[{cdata_escape(body)}]]></ac:plain-text-body>'
                     '</ac:structured-macro>'
                 )
             i += 1