/phase-4-proposals

user-invocable: false
install: extras

<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios --> <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

/pipeline-health — Phase 4: Generate Improvement Proposals

> **Skill names**: `{FORGE_SKILL_PREFIX}` is `forgedock:` (plugin install) or empty (`install.sh`), resolved once per run by `commands/work-on.md` § Skill Name Resolution. If the skill is not found under either name, STOP and report "skill not found" — never run the phase inline.

Phase 4: Generate Improvement Proposals

4A: Pattern recurrence analysis — check-promotion threshold <!-- Added: forge#1331 -->

Before the general improvement proposals, scan for `FORGE:PATTERN` tags in review-finding issues closed in the analysis window. When the same pattern slug appears on 3+ distinct issues, emit a check-promotion issue:

# Collect all review-finding issues closed in the window with FORGE:PATTERN annotations
# {GH_FLAG} and {GH_REPO} are resolved from forge.yaml (see Config Resolution at top of file)
PATTERN_ISSUES=$(gh issue list {GH_FLAG} \
  --label "review-finding" \
  --state closed \
  --search "FORGE:PATTERN" \
  --limit 100 \
  --json number,title,body,closedAt \
  --jq ".[] | select(.closedAt >= \"$SINCE\") | {number: .number, title: .title, body: .body}" 2>/dev/null || echo "[]")

# Extract pattern slugs from FORGE:PATTERN HTML comments in issue bodies
# Format in issue body: <!-- FORGE:PATTERN: {slug} -->
PATTERN_LIST=$(echo "$PATTERN_ISSUES" | jq -r '
  .body |
  scan("<!-- FORGE:PATTERN: ([^\\s>]+) -->") |
  .[0]
' 2>/dev/null | sort | uniq -c | sort -rn)

# For each pattern that appears 3+ times, emit a check-promotion issue
while IFS= read -r line; do
  COUNT=$(echo "$line" | awk '{print $1}')
  SLUG=$(echo "$line" | awk '{print $2}')
  [ -z "$SLUG" ] && continue
  [ "$COUNT" -lt 3 ] && continue

  # SECURITY: $SLUG is sourced from a <!-- FORGE:PATTERN: ([^\s>]+) --> tag inside
  # a review-finding issue body — untrusted, externally-influenced text. It is
  # interpolated below into a Skill(skill="{FORGE_SKILL_PREFIX}issue", args="...") string, and
  # commands/issue.md's Phase 1A resolves that string via `eval "set -- $ARGUMENTS"`.
  # Any shell metacharacter (quote, backtick, $, ;) in $SLUG would break out of the
  # intended --title token and be eval'd as shell. Whitelist-validate at the
  # extraction point — the only legitimate values are check-registry-safe
  # identifiers (also used to build a filename: scripts/check-registry/${SLUG}.sh).
  if ! echo "$SLUG" | grep -qE '^[A-Za-z0-9_-]+$'; then
    echo "WARNING: pattern slug '$SLUG' contains disallowed characters — skipping check-promotion for this pattern (unsafe for interpolation into a downstream eval sink)."
    continue
  fi

  # Check if a promotion issue already exists for this slug (avoid duplicates)
  EXISTING_PROMOTION=$(gh issue list {GH_FLAG} \
    --label "check-promotion" \
    --state open \
    --search "FORGE:PATTERN: $SLUG" \
    --limit 5 \
    --json number --jq '.[0].number' 2>/dev/null || echo "")

  if [ -n "$EXISTING_PROMOTION" ]; then
    echo "Check-promotion already open for pattern '$SLUG' as #${EXISTING_PROMOTION} — skipping."
    continue
  fi

  # Collect the source finding issue numbers for this pattern
  SOURCE_FINDINGS=$(echo "$PATTERN_ISSUES" | jq -r --arg slug "$SLUG" '
    select(.body | test("<!-- FORGE:PATTERN: " + $slug + " -->")) |
    "#\(.number)"
  ' 2>/dev/null | head -10 | tr '\n' ' ')

  # Route through the /issue programmatic create-hook (#2085) instead of a raw
  # `gh issue create` — gets Phase 2D dedup + Phase 3F body validation for free.
  # The hook's programmatic mode requires the body via --body-file, and expects
  # one repeatable --label flag per label (a single comma-joined --label value
  # would be treated as one malformed label name, not two labels).
  CHECK_BODY_FILE=$(mktemp)
  cat > "$CHECK_BODY_FILE" <<CHECK_EOF
## Problem

The review-finding pattern \`$SLUG\` has recurred ${COUNT} times in the analysis window ($(date -u +%Y-%m-%d) window). Each recurrence costs a full investigate→build→review→merge cycle. A static check catches this in milliseconds.

## Source Findings

${SOURCE_FINDINGS}

## Task

1. Read the source findings above to understand the defect class mechanically.
2. Write \`scripts/check-registry/${SLUG}.sh\` following the check contract in \`scripts/check-registry/README.md\`.
3. Add an entry to \`scripts/check-registry/manifest.json\` referencing the new script.
4. Verify the check: test it by reintroducing the defect pattern and confirm the gate blocks.
5. PR, review, merge — the check runs on all subsequent quality-gate invocations.

## Acceptance Criteria

- [ ] \`scripts/check-registry/${SLUG}.sh\` exists, exits 1 on match with correct output format
- [ ] Manifest entry added: \`{ "slug": "${SLUG}", "script": "...", "source_findings": [...], ... }\`
- [ ] Seeded repo test: reintroduce the \`$SLUG\` pattern → quality gate blocks with REGISTRY-${SLUG} finding
- [ ] Gate runtime increase ≤5s for the registered check batch
- [ ] No regression: a clean changeset (no pattern) → gate passes

## Pattern Tag

<!-- FORGE:PATTERN: ${SLUG} -->

<!-- AUTO-CREATED: pipeline-health Phase 4A — pattern recurrence threshold exceeded -->
CHECK_EOF

  Skill(skill="{FORGE_SKILL_PREFIX}issue", args="--title \"feat(quality-gate): promote pattern '$SLUG' to deterministic registry check (recurred ${COUNT}x)\" --body-file $CHECK_BODY_FILE --label check-promotion --label priority:P2")
  rm -f "$CHECK_BODY_FILE"
  echo "Created check-promotion issue for pattern '$SLUG' (recurred ${COUNT}x from: $SOURCE_FINDINGS)"
done <<< "$PATTERN_LIST"

**Recurrence threshold**: 3 occurrences in the analysis window. The threshold is intentionally low — the cost of a false positive is one extra check that rarely fires; the cost of a false negative is another full pipeline cycle for a defect that a grep already knows about.

---

4A