forgedock 1.1.7 → 1.1.9

package/commands/optimize.md

@@ -10,7 +10,7 @@ install: extras
 
 Proactively analyze the current repository and generate `.forgedock/scripts/` entries from `forge.yaml → learned:`, git commit history, and pipeline annotations — without waiting for a correction event. This is the proactive half of the learning loop; reactive capture happens in `/work-on` Phase 1D.
 
-**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
+**Agent model policy**: `model: "{DEFAULT_MODEL}"` — resolved from forge.yaml `agents.default_model`, else "sonnet" (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 **NEVER use plan mode (EnterPlanMode).**
 
 ---
@@ -401,6 +401,589 @@ Run /work-on on a few issues to let the pipeline capture corrections, then re-ru
 
 ---
 
+## Phase 5: Promotion Loop (Tier-A and Tier-B)
+
+<!-- Added: forge#1739 -->
+
+**Purpose**: Scan the Forge Ledger for validated finding patterns that have recurred ≥3 times and promote them — either as a Tier-A mechanizable check script in `gate.d/` or as a Tier-B prose entry in `devdocs/learned-rules/{domain}.md`. Both promotion paths open as a PR for human review. Checks are never silently auto-enforced.
+
+**Skip if**: `--dry-run` flag is set (print what would be promoted without creating PRs).
+
+**Skip if**: The Forge Ledger CLI (`forge recall`) is not available — log a note and continue.
+
+### 5A: Query the Ledger for promotion candidates
+
+```bash
+# forge recall requires the Forge Ledger from #1732 to be indexed.
+# If not available, skip Phase 5 with a note.
+if ! command -v forge >/dev/null 2>&1; then
+  echo "Phase 5: forge CLI not found — skipping promotion loop."
+  echo "  Install: https://github.com/RapierCraftStudios/forgedock#forge-ledger"
+  return 0 2>/dev/null || exit 0
+fi
+
+# Query for patterns with ≥3 validated occurrences (never unvalidated or false-positive)
+# Output: one JSON object per line with fields: slug, domain, count, type, summary, citations[]
+PROMOTION_CANDIDATES=$(forge recall \
+  --filter validated \
+  --min-count 3 \
+  --output jsonl \
+  --repo "$GH_REPO" \
+  2>/dev/null || echo '')
+
+if [ -z "$PROMOTION_CANDIDATES" ]; then
+  echo "Phase 5: No patterns with ≥3 validated occurrences found — nothing to promote."
+  return 0 2>/dev/null || exit 0
+fi
+
+CANDIDATE_COUNT=$(echo "$PROMOTION_CANDIDATES" | grep -c '"slug"' 2>/dev/null || echo 0)
+echo "Phase 5: Found $CANDIDATE_COUNT promotion candidate(s)"
+```
+
+### 5B: Classify each candidate as Tier-A or Tier-B
+
+For each candidate pattern, classify it:
+
+| Tier | Condition | Promotion target |
+|------|-----------|-----------------|
+| **Tier-A** | Pattern is mechanically grep-detectable in a diff (literal string, regex, or structural property) AND can be expressed as a bash check returning the standard `SLUG \| SEVERITY \| FILE \| MESSAGE` format | Draft gate.d script → PR |
+| **Tier-B** | Pattern requires LLM reasoning to detect (code semantics, logic flow, cross-file reasoning) OR the fix depends on project-specific context that can't be encoded in a grep | Draft learned-rules.md entry → PR |
+
+```bash
+TIER_A_PROMOTIONS=()
+TIER_B_PROMOTIONS=()
+
+while IFS= read -r candidate; do
+  [ -z "$candidate" ] && continue
+  SLUG=$(echo "$candidate" | jq -r '.slug // ""' 2>/dev/null)
+  DOMAIN=$(echo "$candidate" | jq -r '.domain // "GENERAL"' 2>/dev/null)
+  COUNT=$(echo "$candidate" | jq -r '.count // 0' 2>/dev/null)
+  TYPE=$(echo "$candidate" | jq -r '.type // "prose"' 2>/dev/null)   # "mechanical" or "prose"
+  SUMMARY=$(echo "$candidate" | jq -r '.summary // ""' 2>/dev/null)
+  CITATIONS=$(echo "$candidate" | jq -r '[.citations[] | "#" + tostring] | join(", ")' 2>/dev/null)
+
+  [ -z "$SLUG" ] && continue
+
+  if [ "$TYPE" = "mechanical" ]; then
+    TIER_A_PROMOTIONS+=("$candidate")
+    echo "  Tier-A candidate: $SLUG (domain=$DOMAIN, count=$COUNT, citations=$CITATIONS)"
+  else
+    TIER_B_PROMOTIONS+=("$candidate")
+    echo "  Tier-B candidate: $SLUG (domain=$DOMAIN, count=$COUNT, citations=$CITATIONS)"
+  fi
+done <<< "$PROMOTION_CANDIDATES"
+```
+
+### 5C: Draft Tier-A gate.d scripts
+
+For each Tier-A candidate, draft a gate.d script and open it as a PR:
+
+```bash
+GATE_D_DIR="$SCRIPTS_DIR/gate.d"
+mkdir -p "$GATE_D_DIR"
+
+for candidate in "${TIER_A_PROMOTIONS[@]}"; do
+  SLUG=$(echo "$candidate" | jq -r '.slug' 2>/dev/null)
+  DOMAIN=$(echo "$candidate" | jq -r '.domain // "GENERAL"' 2>/dev/null)
+  SUMMARY=$(echo "$candidate" | jq -r '.summary' 2>/dev/null)
+  PATTERN=$(echo "$candidate" | jq -r '.pattern // ""' 2>/dev/null)   # grep-ready pattern string
+  CITATIONS=$(echo "$candidate" | jq -r '[.citations[] | "#" + tostring] | join(", ")' 2>/dev/null)
+  COUNT=$(echo "$candidate" | jq -r '.count' 2>/dev/null)
+  SEVERITY=$(echo "$candidate" | jq -r '.severity // "HIGH"' 2>/dev/null)
+
+  SCRIPT_PATH="$GATE_D_DIR/${SLUG}.sh"
+
+  # Skip if already promoted (idempotent)
+  if [ -f "$SCRIPT_PATH" ] && [ "$DRY_RUN" != "true" ]; then
+    echo "  Tier-A: $SLUG — already exists at $SCRIPT_PATH, skipping"
+    continue
+  fi
+
+  if [ "$DRY_RUN" = "true" ]; then
+    echo "  [DRY RUN] Would create gate.d/${SLUG}.sh (domain=$DOMAIN, citations=$CITATIONS)"
+    continue
+  fi
+
+  # Generate the gate.d script
+  cat > "$SCRIPT_PATH" << GATE_SCRIPT_EOF
+#!/usr/bin/env bash
+# gate.d/${SLUG}.sh — auto-generated by /optimize Phase 5
+# Domain: ${DOMAIN}
+# Pattern: ${SUMMARY}
+# Evidence: ${COUNT} validated occurrences — ${CITATIONS}
+# Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+#
+# CONTRACT:
+#   \$1 = absolute path to unified diff (git diff HEAD)
+#   \$2 = absolute path to worktree root
+#   stdout = findings lines: SLUG | SEVERITY | FILE | MESSAGE
+#   exit 0 = pass, exit 1 = findings, exit 2 = inapplicable
+#   30s timeout enforced by quality-gate (fail-closed)
+#
+# EDIT THIS SCRIPT: the pattern below was auto-generated. Review and test
+# it against real diffs before the PR is merged.
+
+set -euo pipefail
+
+DIFF_PATH="\${1:-}"
+WORKTREE="\${2:-}"
+FOUND=0
+
+if [ -z "\$DIFF_PATH" ] || [ ! -f "\$DIFF_PATH" ]; then
+  exit 2  # inapplicable — no diff provided
+fi
+
+# Check for the pattern in added lines of the diff
+# TODO: refine this pattern based on the specific defect class
+PATTERN='${PATTERN}'
+if [ -z "\$PATTERN" ]; then
+  exit 2  # no pattern configured — mark inapplicable until author fills it in
+fi
+
+while IFS= read -r line; do
+  [ -z "\$line" ] && continue
+  FILE=\$(echo "\$line" | grep -oP '(?<=\+\+\+ b/).*' || true)
+done < <(grep '^+++ b/' "\$DIFF_PATH" 2>/dev/null)
+
+# Scan added lines for the pattern
+MATCHES=\$(grep -nP "^\+" "\$DIFF_PATH" 2>/dev/null | grep -v "^+++" | grep -P "\$PATTERN" 2>/dev/null || true)
+
+if [ -n "\$MATCHES" ]; then
+  while IFS= read -r match; do
+    [ -z "\$match" ] && continue
+    echo "GATD-${SLUG} | ${SEVERITY} | (diff) | ${SUMMARY} — pattern matched in added lines. Citations: ${CITATIONS}"
+    FOUND=1
+  done <<< "\$MATCHES"
+fi
+
+exit \$FOUND
+GATE_SCRIPT_EOF
+  chmod +x "$SCRIPT_PATH"
+  echo "  Tier-A: Created gate.d/${SLUG}.sh (citations=$CITATIONS)"
+done
+```
+
+After drafting all Tier-A scripts, open a single PR with all new gate.d scripts:
+
+```bash
+if [ "${#TIER_A_PROMOTIONS[@]}" -gt 0 ] && [ "$DRY_RUN" != "true" ]; then
+  PROMO_BRANCH="feat/gate-d-promotion-$(date -u +%Y%m%d)"
+  git -C "$REPO_PATH" checkout -b "$PROMO_BRANCH" "origin/${STAGING_BRANCH:-staging}" 2>/dev/null || \
+    git -C "$REPO_PATH" checkout "$PROMO_BRANCH" 2>/dev/null
+  git -C "$REPO_PATH" add "$GATE_D_DIR"
+  git -C "$REPO_PATH" diff --cached --quiet || \
+    git -C "$REPO_PATH" commit -s -m "feat(gate.d): promote ${#TIER_A_PROMOTIONS[@]} learned check(s) from Ledger patterns"
+  git -C "$REPO_PATH" push -u origin "$PROMO_BRANCH"
+
+  CITATIONS_BODY=""
+  for candidate in "${TIER_A_PROMOTIONS[@]}"; do
+    SLUG=$(echo "$candidate" | jq -r '.slug' 2>/dev/null)
+    SUMMARY=$(echo "$candidate" | jq -r '.summary' 2>/dev/null)
+    COUNT=$(echo "$candidate" | jq -r '.count' 2>/dev/null)
+    CITS=$(echo "$candidate" | jq -r '[.citations[] | "#" + tostring] | join(", ")' 2>/dev/null)
+    CITATIONS_BODY="${CITATIONS_BODY}
+- **\`${SLUG}\`**: ${SUMMARY} — ${COUNT} validated occurrences (${CITS})"
+  done
+
+  gh pr create -R "$GH_REPO" \
+    --base "${STAGING_BRANCH:-staging}" \
+    --head "$PROMO_BRANCH" \
+    --title "feat(gate.d): promote ${#TIER_A_PROMOTIONS[@]} learned check(s) from recurring patterns" \
+    --body "$(cat <<PR_BODY_EOF
+## Summary
+
+This PR was generated by \`/optimize\` Phase 5. It promotes ${#TIER_A_PROMOTIONS[@]} recurring pattern(s) from the Forge Ledger into deterministic gate.d check scripts.
+
+Each promoted script represents a defect class that appeared ≥3 times in validated findings for this codebase. Once merged, the check runs pre-commit on every future PR.
+
+## Promoted checks
+${CITATIONS_BODY}
+
+## Review notes
+
+**Please review each gate.d script carefully before merging.**
+
+- Verify the grep pattern matches the intended defect class
+- Test against a real diff that should fire (and one that should not)
+- The pattern comment in each script links to the source finding issues
+- Edit the \`PATTERN\` variable in the script if the auto-generated pattern needs refinement
+- If a promoted check is incorrect, close this PR and file a rule-contest issue
+
+## gate.d contract
+
+Each script receives:
+- \$1 = path to unified diff
+- \$2 = path to worktree root
+- exits 0 (pass), 1 (findings on stdout), or 2 (inapplicable)
+- 30-second timeout enforced by quality-gate (fail-closed on timeout)
+
+---
+Generated by: \`/optimize\` Phase 5 — pattern promotion loop
+PR_BODY_EOF
+)"
+  echo "Phase 5: Opened Tier-A promotion PR on branch $PROMO_BRANCH"
+fi
+```
+
+### 5D: Draft Tier-B learned-rules.md entries
+
+For each Tier-B candidate, append a prose entry to `devdocs/learned-rules/{domain}.md` and open a PR:
+
+```bash
+LEARNED_RULES_DIR="$REPO_PATH/devdocs/learned-rules"
+mkdir -p "$LEARNED_RULES_DIR"
+
+TIER_B_ENTRIES=""
+for candidate in "${TIER_B_PROMOTIONS[@]}"; do
+  SLUG=$(echo "$candidate" | jq -r '.slug' 2>/dev/null)
+  DOMAIN=$(echo "$candidate" | jq -r '.domain // "GENERAL"' 2>/dev/null)
+  SUMMARY=$(echo "$candidate" | jq -r '.summary' 2>/dev/null)
+  COUNT=$(echo "$candidate" | jq -r '.count' 2>/dev/null)
+  CITATIONS=$(echo "$candidate" | jq -r '[.citations[] | "#" + tostring] | join(", ")' 2>/dev/null)
+  SEVERITY=$(echo "$candidate" | jq -r '.severity // "MEDIUM"' 2>/dev/null)
+  RULES_FILE="$LEARNED_RULES_DIR/${DOMAIN}.md"
+
+  if [ "$DRY_RUN" = "true" ]; then
+    echo "  [DRY RUN] Would append to devdocs/learned-rules/${DOMAIN}.md — rule: $SLUG"
+    continue
+  fi
+
+  # Create file with header if it doesn't exist
+  if [ ! -f "$RULES_FILE" ]; then
+    cat > "$RULES_FILE" << RULES_HEADER_EOF
+# Learned Rules — ${DOMAIN} Domain
+
+This file contains Tier-B prose rules promoted by \`/optimize\` from recurring validated findings.
+These rules are injected into the quality gate's ${DOMAIN} domain scan to guide LLM-assisted checks.
+
+Each rule carries citations to the source findings that justified its promotion.
+Rules are removed when evidence is refuted (two sustained contests → promotion issue reopened).
+
+<!-- FORGE:LEARNED_RULES domain=${DOMAIN} -->
+RULES_HEADER_EOF
+    echo "  Tier-B: Created $RULES_FILE"
+  fi
+
+  # Check if rule already exists (idempotent by slug)
+  if grep -q "<!-- rule:${SLUG} -->" "$RULES_FILE" 2>/dev/null; then
+    echo "  Tier-B: $SLUG already present in ${DOMAIN}.md — skipping"
+    continue
+  fi
+
+  # Append the rule entry
+  cat >> "$RULES_FILE" << RULE_EOF
+
+## ${SLUG} <!-- rule:${SLUG} -->
+
+**Severity**: ${SEVERITY}
+**Pattern type**: Tier-B (prose — requires reasoning to detect)
+**Validated occurrences**: ${COUNT}
+**Citations**: ${CITATIONS}
+**Promoted**: $(date -u +%Y-%m-%dT%H:%M:%SZ)
+
+${SUMMARY}
+
+**What to check**: When reviewing ${DOMAIN} domain changes, flag any instance matching this pattern as \`SHELL-LEARNED-${SLUG} | ${SEVERITY} | {file} | {description}\`.
+
+**Refutation**: If this rule produces a false finding, file a rule-contest issue with the blocked diff attached. One sustained contest → rule demoted to advisory. Two sustained contests → this rule entry is removed and the promotion issue is reopened.
+
+---
+RULE_EOF
+  TIER_B_ENTRIES="${TIER_B_ENTRIES} devdocs/learned-rules/${DOMAIN}.md"
+  echo "  Tier-B: Appended rule $SLUG to devdocs/learned-rules/${DOMAIN}.md (citations=$CITATIONS)"
+done
+
+# Open PR for Tier-B entries
+if [ -n "$TIER_B_ENTRIES" ] && [ "$DRY_RUN" != "true" ]; then
+  TIER_B_BRANCH="feat/learned-rules-promotion-$(date -u +%Y%m%d)"
+  git -C "$REPO_PATH" checkout -b "$TIER_B_BRANCH" "origin/${STAGING_BRANCH:-staging}" 2>/dev/null || \
+    git -C "$REPO_PATH" checkout "$TIER_B_BRANCH" 2>/dev/null
+  # Stage only learned-rules files changed in this run
+  for f in $TIER_B_ENTRIES; do
+    git -C "$REPO_PATH" add "$f" 2>/dev/null || true
+  done
+  git -C "$REPO_PATH" diff --cached --quiet || \
+    git -C "$REPO_PATH" commit -s -m "feat(learned-rules): promote ${#TIER_B_PROMOTIONS[@]} Tier-B prose rule(s) from Ledger patterns"
+  git -C "$REPO_PATH" push -u origin "$TIER_B_BRANCH"
+
+  gh pr create -R "$GH_REPO" \
+    --base "${STAGING_BRANCH:-staging}" \
+    --head "$TIER_B_BRANCH" \
+    --title "feat(learned-rules): promote ${#TIER_B_PROMOTIONS[@]} Tier-B prose rule(s) from recurring patterns" \
+    --body "$(cat <<TIER_B_PR_EOF
+## Summary
+
+This PR was generated by \`/optimize\` Phase 5. It adds ${#TIER_B_PROMOTIONS[@]} prose rule(s) to \`devdocs/learned-rules/\` from recurring Ledger patterns.
+
+These are **Tier-B** rules — defect classes that cannot be caught by a mechanical grep but recur in LLM-assisted gate scans. Once merged, the relevant domain scan in \`/quality-gate\` will inject these rules as additional context (~200 tokens per domain).
+
+## Review notes
+
+- Verify each rule accurately describes the defect class and doesn't over-generalize
+- Rules carry evidence citations — check that the cited findings actually justify the rule
+- A builder can contest a rule by filing a rule-contest issue with the blocked diff
+- Rules are injected as Tier-B guidance, not as mechanical blockers
+
+---
+Generated by: \`/optimize\` Phase 5 — pattern promotion loop
+TIER_B_PR_EOF
+)"
+  echo "Phase 5: Opened Tier-B learned-rules promotion PR on branch $TIER_B_BRANCH"
+fi
+```
+
+### 5E: Phase 5 summary
+
+```bash
+echo ""
+echo "--- Phase 5: Promotion Loop Summary ---"
+if [ "$DRY_RUN" = "true" ]; then
+  echo "  Mode: DRY RUN — no PRs opened, no files written"
+  echo "  Tier-A candidates: ${#TIER_A_PROMOTIONS[@]}"
+  echo "  Tier-B candidates: ${#TIER_B_PROMOTIONS[@]}"
+else
+  echo "  Tier-A gate.d scripts promoted: ${#TIER_A_PROMOTIONS[@]}"
+  echo "  Tier-B learned-rules entries promoted: ${#TIER_B_PROMOTIONS[@]}"
+  echo ""
+  echo "  Each promotion lands as a PR for human review before enforcement."
+  echo "  Demotion is automatic on evidence; promotion requires a human."
+fi
+```
+
+---
+
+## Phase 6: Contribution Path (Outbound Exchange)
+
+<!-- Added: forge#1746 -->
+
+**Purpose**: When a promoted learned rule (from Phase 5) generalizes beyond this repo — no repo paths, no project-specific identifiers in the card body — offer to contribute it to a subscribed exchange repo so other ForgeDock installations can benefit. This is the outbound half of the pattern exchange loop.
+
+**CRITICAL: Never auto-publish.** All outbound actions require explicit human approval. The contribution path opens a PR DRAFT and stops — a human must review and approve before anything leaves this repo's private context.
+
+**Skip if**: `--dry-run` flag is set.
+**Skip if**: No exchange repo is configured in `forge.yaml → pattern_feeds.feeds` (check `contributing_to` field or any feed with `slug` marked as canonical exchange target).
+**Skip if**: No promoted patterns exist from Phase 5 (nothing to contribute).
+
+### 6A: Identify generalizable patterns
+
+Scan Phase 5 promotion output for candidates that pass ALL three generalization tests:
+
+**Test 1 — No repo paths**: Card body must not contain absolute paths, repo-specific directories, or project identifiers.
+
+```bash
+# Extract promoted card bodies from Phase 5 TIER_A_PROMOTIONS and TIER_B_PROMOTIONS
+GENERALIZABLE_CANDIDATES=()
+
+for SLUG in "${TIER_A_PROMOTIONS[@]}" "${TIER_B_PROMOTIONS[@]}"; do
+  # Read card body from gate.d/ or devdocs/learned-rules/ (where Phase 5 wrote it)
+  CARD_BODY=""
+  if [ -f "${WORKTREE_PATH}/.forgedock/gate.d/${SLUG}.sh" ]; then
+    CARD_BODY=$(cat "${WORKTREE_PATH}/.forgedock/gate.d/${SLUG}.sh" 2>/dev/null)
+  elif [ -f "${WORKTREE_PATH}/devdocs/learned-rules/${SLUG}.md" ]; then
+    CARD_BODY=$(cat "${WORKTREE_PATH}/devdocs/learned-rules/${SLUG}.md" 2>/dev/null)
+  fi
+
+  [ -z "$CARD_BODY" ] && continue
+
+  # Test 1: no absolute paths (e.g. /home/, /app/, /srv/, /opt/)
+  if echo "$CARD_BODY" | grep -qE '^[[:space:]]*(path|dir|file).*\/home\/|\/app\/|\/srv\/|\/opt\/'; then
+    echo "6A: SKIP $SLUG — contains absolute path references (not generalizable)"
+    continue
+  fi
+
+  # Test 2: no project-specific identifiers
+  PROJECT_NAME=$(yq '.project.name // ""' "$FORGE_YAML" 2>/dev/null || echo '')
+  PROJECT_REPO=$(yq '.project.repo // ""' "$FORGE_YAML" 2>/dev/null || echo '')
+  if [ -n "$PROJECT_NAME" ] && echo "$CARD_BODY" | grep -qi "$PROJECT_NAME"; then
+    echo "6A: SKIP $SLUG — contains project name '$PROJECT_NAME' (not generalizable)"
+    continue
+  fi
+  if [ -n "$PROJECT_REPO" ] && echo "$CARD_BODY" | grep -qi "$PROJECT_REPO"; then
+    echo "6A: SKIP $SLUG — contains repo name '$PROJECT_REPO' (not generalizable)"
+    continue
+  fi
+
+  # Test 3: has stack tags (required for exchange repo schema)
+  # (stack tags are set during Phase 5 promotion from ledger metadata)
+  STACK_TAGS=$(forge recall --slug "$SLUG" --field stacks 2>/dev/null || echo '')
+  if [ -z "$STACK_TAGS" ]; then
+    echo "6A: SKIP $SLUG — no stack tags found (required for exchange schema)"
+    continue
+  fi
+
+  echo "6A: CANDIDATE $SLUG — passes generalization tests"
+  GENERALIZABLE_CANDIDATES+=("$SLUG")
+done
+
+if [ "${#GENERALIZABLE_CANDIDATES[@]}" -eq 0 ]; then
+  echo "Phase 6: No generalizable candidates found — skipping contribution path."
+  return 0 2>/dev/null || exit 0
+fi
+
+echo "Phase 6: ${#GENERALIZABLE_CANDIDATES[@]} generalizable candidate(s): ${GENERALIZABLE_CANDIDATES[*]}"
+```
+
+### 6B: Resolve exchange target repo
+
+Read the first configured feed as the contribution target. If no feed is configured, skip.
+
+```bash
+EXCHANGE_REPO=$(yq '.pattern_feeds.feeds[0].repo // ""' "$FORGE_YAML" 2>/dev/null || echo '')
+EXCHANGE_PATH=$(yq '.pattern_feeds.feeds[0].path // "cards"' "$FORGE_YAML" 2>/dev/null || echo 'cards')
+
+if [ -z "$EXCHANGE_REPO" ]; then
+  echo "Phase 6: No exchange repo configured in forge.yaml → pattern_feeds.feeds — skipping."
+  return 0 2>/dev/null || exit 0
+fi
+
+# Verify the exchange repo is accessible
+if ! gh repo view "$EXCHANGE_REPO" >/dev/null 2>&1; then
+  echo "Phase 6: Exchange repo $EXCHANGE_REPO is not accessible — skipping."
+  return 0 2>/dev/null || exit 0
+fi
+
+echo "Phase 6: Contribution target → $EXCHANGE_REPO ($EXCHANGE_PATH/)"
+```
+
+### 6C: Draft contribution PR (HUMAN APPROVAL REQUIRED)
+
+For each generalizable candidate, build a card file following the exchange repo schema (`{stack}/{pattern-slug}.md`) and open a **DRAFT PR** on the exchange repo. The pipeline STOPS here — a human must review the card and approve the PR before anything is merged or published.
+
+**Human approval gate**: This step opens a DRAFT PR and posts a GitHub comment on the current issue with the link. No auto-merge. No CI trigger that merges automatically. The draft status ensures the exchange repo maintainer (a human) reviews and approves the outbound content before it becomes public knowledge.
+
+```bash
+for SLUG in "${GENERALIZABLE_CANDIDATES[@]}"; do
+  # Build exchange card from ledger metadata
+  STACK_TAGS=$(forge recall --slug "$SLUG" --field stacks 2>/dev/null || echo 'generic')
+  PREVENTION_RULE=$(forge recall --slug "$SLUG" --field prevention 2>/dev/null || echo '')
+  ROOT_CAUSE_SHAPE=$(forge recall --slug "$SLUG" --field root_cause_shape 2>/dev/null || echo '')
+  SUMMARY=$(forge recall --slug "$SLUG" --field summary 2>/dev/null || echo '')
+  GATE_TEMPLATE=$(forge recall --slug "$SLUG" --field gate_template 2>/dev/null || echo '')
+
+  # Determine card path: use first stack tag as directory
+  PRIMARY_STACK=$(echo "$STACK_TAGS" | tr ',' '\n' | head -1 | tr -d ' "[]')
+  CARD_PATH="${EXCHANGE_PATH}/${PRIMARY_STACK}/${SLUG}.md"
+
+  # Build card body following exchange repo schema
+  CARD_BODY="# Pattern: ${SLUG}
+
+## Stacks
+${STACK_TAGS}
+
+## Root Cause Shape
+${ROOT_CAUSE_SHAPE:-Unknown — see prevention rule below.}
+
+## Prevention Rule
+${PREVENTION_RULE:-No prevention rule captured.}
+
+## Summary
+${SUMMARY}
+"
+
+  # Append gate.d check template if present (optional field)
+  if [ -n "$GATE_TEMPLATE" ]; then
+    CARD_BODY="${CARD_BODY}
+## gate.d Check Template
+
+\`\`\`bash
+${GATE_TEMPLATE}
+\`\`\`
+"
+  fi
+
+  # NOTE: Only run this block if $DRY_RUN is false
+  if [ "$DRY_RUN" = "true" ]; then
+    echo "DRY RUN: Would draft contribution PR for $SLUG → $EXCHANGE_REPO:$CARD_PATH"
+    continue
+  fi
+
+  # Create contribution branch and draft PR on the exchange repo
+  CONTRIB_BRANCH="contrib/${SLUG}-$(date +%Y%m%d)"
+
+  # Write card to a temp file for gh pr creation (requires a clone of the exchange repo)
+  # NOTE: This requires the exchange repo to be cloned locally. If it is not, skip with a note.
+  EXCHANGE_LOCAL=$(yq '.pattern_feeds.feeds[0].local_path // ""' "$FORGE_YAML" 2>/dev/null || echo '')
+
+  if [ -z "$EXCHANGE_LOCAL" ] || [ ! -d "$EXCHANGE_LOCAL" ]; then
+    echo "Phase 6: SKIP $SLUG — exchange repo not cloned locally."
+    echo "  To contribute: clone $EXCHANGE_REPO, set pattern_feeds.feeds[0].local_path in forge.yaml, re-run /optimize."
+    continue
+  fi
+
+  # Create branch in exchange repo
+  git -C "$EXCHANGE_LOCAL" fetch origin 2>/dev/null
+  git -C "$EXCHANGE_LOCAL" checkout -b "$CONTRIB_BRANCH" origin/main 2>/dev/null || {
+    echo "Phase 6: SKIP $SLUG — could not create branch $CONTRIB_BRANCH in $EXCHANGE_LOCAL"
+    continue
+  }
+
+  # Write card file
+  mkdir -p "$EXCHANGE_LOCAL/${EXCHANGE_PATH}/${PRIMARY_STACK}"
+  echo "$CARD_BODY" > "$EXCHANGE_LOCAL/${EXCHANGE_PATH}/${PRIMARY_STACK}/${SLUG}.md"
+  git -C "$EXCHANGE_LOCAL" add "${EXCHANGE_PATH}/${PRIMARY_STACK}/${SLUG}.md"
+  git -C "$EXCHANGE_LOCAL" commit -s -m "feat(cards): add ${SLUG} pattern (${PRIMARY_STACK})" 2>/dev/null
+
+  # Push and open DRAFT PR — human approval required before merge
+  git -C "$EXCHANGE_LOCAL" push origin "$CONTRIB_BRANCH" 2>/dev/null && \
+  DRAFT_PR_URL=$(gh pr create \
+    -R "$EXCHANGE_REPO" \
+    --base main \
+    --head "$CONTRIB_BRANCH" \
+    --draft \
+    --title "feat(cards): contribute ${SLUG} pattern" \
+    --body "$(cat <<CONTRIB_PR_EOF
+## Pattern Contribution: \`${SLUG}\`
+
+This is an **automated draft** generated by \`/optimize\` Phase 6 on $(date -u +%Y-%m-%d).
+
+**HUMAN REVIEW REQUIRED before this PR is merged or published.**
+
+The card was automatically identified as generalizable (no repo paths, no project identifiers, has stack tags). However, automatic generalization detection is heuristic — please verify:
+
+- [ ] Card body contains no proprietary information, internal system names, or project-specific paths
+- [ ] Prevention rule is accurate and actionable for other teams using the same stack
+- [ ] Stack tags (\`${STACK_TAGS}\`) are correct
+- [ ] Root cause shape describes the bug class, not a specific incident
+
+## Card preview
+
+\`\`\`markdown
+${CARD_BODY}
+\`\`\`
+
+---
+Generated by: \`/optimize\` Phase 6 — contribution path
+Source repo: $(yq '.project.owner + "/" + .project.repo' "$FORGE_YAML" 2>/dev/null || echo 'unknown')
+**This draft will not auto-merge. A human must approve and merge.**
+CONTRIB_PR_EOF
+)" 2>/dev/null) || true
+
+  if [ -n "$DRAFT_PR_URL" ]; then
+    echo "Phase 6: Draft contribution PR opened for $SLUG → $DRAFT_PR_URL"
+    echo "  ACTION REQUIRED: Review the card, verify no proprietary content, then approve and merge."
+  else
+    echo "Phase 6: WARN — could not open draft PR for $SLUG. Push the branch manually."
+  fi
+done
+```
+
+### 6D: Phase 6 summary
+
+```bash
+echo ""
+echo "--- Phase 6: Contribution Path Summary ---"
+if [ "$DRY_RUN" = "true" ]; then
+  echo "  Mode: DRY RUN — no PRs opened"
+  echo "  Generalizable candidates: ${#GENERALIZABLE_CANDIDATES[@]}"
+else
+  echo "  Exchange target: $EXCHANGE_REPO"
+  echo "  Candidates evaluated: ${#GENERALIZABLE_CANDIDATES[@]}"
+  echo "  IMPORTANT: All contribution PRs are DRAFTS — human approval required before merge."
+fi
+```
+
+---
+
 ## Idempotency Guarantee
 
 Running `/optimize` twice produces the same output. Specifically:
@@ -408,5 +991,7 @@ Running `/optimize` twice produces the same output. Specifically:
 - `registry.json` is always overwritten with current analysis results
 - Generated timestamps in scripts and registry will update on each run (this is expected)
 - Content of scripts changes only if the underlying patterns change
+- Phase 5 is idempotent: existing gate.d scripts and learned-rules entries are detected by slug and skipped (not duplicated)
+- Phase 6 is idempotent: a card slug already present in the exchange repo is detected and skipped (no duplicate PR)
 
 To verify: run `/optimize` twice and compare outputs — the only differences should be the `generated_at` timestamps.

package/commands/orchestrate/config.md

@@ -1,5 +1,5 @@
 ---
-install: internal
+install: core
 ---
 <!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
 <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
@@ -22,7 +22,9 @@ You are the top-level orchestrator. Your job is to take a batch of issues, plan
 
 **You have access to ALL tools** — Agent tool (critical), Task tool, Skill tool, Bash, everything. Use the Agent tool aggressively to parallelize work.
 
-**Agent model policy**: `model: "haiku"`, `effort: low` (mechanical — dispatch bookkeeping, lane routing, classification). Fallback: `model: "sonnet"` if rate-limited. User can override with `--model <name>`. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
+**Agent model policy**: `model: "haiku"`, `effort: low` (mechanical — dispatch bookkeeping, lane routing, classification). Fallback: `model: "sonnet"` if rate-limited. User can override with `--model <name>`. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154. **Distinct from the spawned `/work-on` sub-agents** (Phase 4, per-issue and review-finding sweep): those resolve via `model: "{SUBAGENT_MODEL}"` — forge.yaml `agents.subagent_model`, else `agents.default_model`, else `"sonnet"` — not this dispatcher's own `haiku` policy.
+
+**Hard exclusion — already enforced by this design, not left to convention**: this `haiku`/`effort: low` tier applies ONLY to the orchestrator's own mechanical bookkeeping (dispatch, lane routing, classification) — never to the spawned `/work-on` sub-agents, which always run at `{SUBAGENT_MODEL}` (standard tier, sonnet by default). Every reasoning-heavy `/work-on` sub-phase file (`investigate.md`, `build/architect.md`, `build/implement.md`, `review.md`) carries its own "Agent model policy" line pinned to `{DEFAULT_MODEL}`/standard tier — see `work-on.md`'s `FORGE:MODEL_TIER_NOTE` for the canonical explanation of why these are never downtiered, and forge#1827 for the explicit correction against adding a `model: "haiku"` claim to any file where mechanical bits are interleaved with reasoning-heavy content. Do not introduce a second, competing deterministic-step-to-cheap-model config — this per-file tiering plus the dispatcher/sub-agent split above is the single source of truth for which steps may use a cheaper model.
 **NEVER use plan mode (EnterPlanMode).**
 
 <!-- FORGE:SPEC_LOADED — orchestrate.md loaded and active. Agent is bound by HARD RULES above. -->
@@ -44,9 +46,17 @@ STAGING_BRANCH=$(yq '.branches.staging' "$CONFIG_FILE")
 DEFAULT_BRANCH=$(yq '.branches.default' "$CONFIG_FILE")
 # Build satellite repo map from repos.satellites list
 # Each satellite: { prefix, repo, staging_branch }
+
+# Narration verbosity for Step 4B's per-completion status updates (phase-4-execution.md item 8).
+# "terse" (default when unset): one-line status per completion — matches today's existing
+# behavior, so leaving pipeline.narration unset is a no-op. "verbose": adds a running
+# per-completion recap table. Never affects the Step 6B consolidated report, which always
+# renders full tables once at the end regardless of this value.
+NARRATION_MODE=$(yq '.pipeline.narration // "terse"' "$CONFIG_FILE" 2>/dev/null || echo "terse")
+[ "$NARRATION_MODE" = "null" ] && NARRATION_MODE="terse"
 ```
 
-All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{PROJECT_NAME}`, `{STAGING_BRANCH}`, and `{DEFAULT_BRANCH}` references below are populated from `forge.yaml`.
+All `{GH_REPO}`, `{GH_FLAG}`, `{REPO_PATH}`, `{PROJECT_NAME}`, `{STAGING_BRANCH}`, `{DEFAULT_BRANCH}`, and `{NARRATION_MODE}` references below are populated from `forge.yaml`.
 
 ---