forgedock 1.8.1 → 1.8.3

package/scripts/wait-ci-green.sh

@@ -0,0 +1,98 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# wait-ci-green.sh — CI gate every autonomous merge must pass first.
+#
+# Usage: wait-ci-green.sh <pr-number> -R <owner/repo> [--timeout SECONDS] [--interval SECONDS]
+#
+# Waits until every check on the PR has finished, then decides. Fails closed: a merge may
+# proceed ONLY on exit 0. Field test: pipeline agents merged PRs to staging while checks were
+# pending or red (#3165 merged with the side-effect gate failing), because neither the specs nor
+# branch protection required green CI, and `gh pr merge --auto` only waits for *required* checks.
+#
+# Exit codes (one "CI_GATE: <RESULT>" line on stdout, details after it):
+#   0  PASS     every check is pass/skipping (or the repo reports no checks after the grace period
+#               and FORGE_CI_REQUIRE_CHECKS is not 1)
+#   1  FAIL     at least one check failed or was cancelled (listed)
+#   2  ERROR    bad usage, gh unreadable for too long, the PR head moved during the wait, or
+#               FORGE_CI_REQUIRE_CHECKS=1 and no checks were reported
+#   3  TIMEOUT  checks still pending when the timeout expired (listed)
+#
+# Every result also prints "CI_GATE_HEAD: <sha>" — the exact PR head the decision applies to. Callers
+# MUST merge with `--match-head-commit <that sha>` so a push after the gate cannot land unchecked.
+#
+# Env: FORGE_CI_TIMEOUT (default 540 — stays under the 10-minute Bash tool limit; on TIMEOUT the
+#      caller re-runs the gate, it does not raise the timeout), FORGE_CI_INTERVAL (default 20),
+#      FORGE_CI_NO_CHECKS_GRACE (default 120), FORGE_CI_SETTLE (default 45 — never PASS earlier than
+#      this after the wait starts, so workflows that register late are not missed),
+#      FORGE_CI_REQUIRE_CHECKS (default 0).
+# "No checks" passes only when GitHub Actions also reports no workflow runs for the head commit;
+# if runs exist but their checks have not appeared yet, the gate keeps waiting.
+set -uo pipefail
+
+PR=""; REPO=""
+TIMEOUT="${FORGE_CI_TIMEOUT:-540}"; INTERVAL="${FORGE_CI_INTERVAL:-20}"; SETTLE="${FORGE_CI_SETTLE:-45}"
+GRACE="${FORGE_CI_NO_CHECKS_GRACE:-120}"; REQUIRE="${FORGE_CI_REQUIRE_CHECKS:-0}"
+usage() { echo "CI_GATE: ERROR"; echo "CI_GATE_HEAD: unknown"; echo "usage: wait-ci-green.sh <pr> -R <owner/repo> [--timeout S] [--interval S]" >&2; exit 2; }
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -R) [ $# -ge 2 ] || usage; REPO="$2"; shift 2 ;;
+    -R*) REPO="${1#-R}"; REPO="${REPO# }"; shift ;;
+    --timeout) [ $# -ge 2 ] || usage; TIMEOUT="$2"; shift 2 ;;
+    --interval) [ $# -ge 2 ] || usage; INTERVAL="$2"; shift 2 ;;
+    -h|--help) sed -n '5,25p' "$0"; exit 0 ;;
+    *) [ -z "$PR" ] || usage; PR="$1"; shift ;;
+  esac
+done
+case "$PR" in ''|*[!0-9]*) usage ;; esac
+case "$REPO" in */*) ;; *) usage ;; esac
+for v in "$TIMEOUT" "$INTERVAL" "$GRACE" "$SETTLE"; do case "$v" in ''|*[!0-9]*) usage ;; esac; done
+[ "$INTERVAL" -ge 1 ] || INTERVAL=1
+
+emit() { echo "CI_GATE: $1"; echo "CI_GATE_HEAD: ${START_SHA:-unknown}"; }
+head_sha() { gh pr view "$PR" -R "$REPO" --json headRefOid --jq '.headRefOid' 2>/dev/null; }
+START_SHA="$(head_sha)"
+if [ -z "$START_SHA" ]; then START_SHA=""; emit ERROR; echo "cannot read PR #$PR head in $REPO"; exit 2; fi
+
+start=$(date +%s); errors=0
+while :; do
+  now=$(date +%s); elapsed=$((now - start))
+  if ! JSON="$(gh pr checks "$PR" -R "$REPO" --json name,bucket 2>/dev/null)" || ! printf '%s' "$JSON" | jq -e 'type=="array"' >/dev/null 2>&1; then
+    # gh pr checks exits non-zero both on outage and on "no checks reported"; tell them apart by output.
+    if printf '%s' "${JSON:-}" | jq -e 'type=="array"' >/dev/null 2>&1; then :; else
+      # Capture first: under pipefail, `gh ... | grep -q` fails whenever gh exits 1, which it
+      # does precisely in the "no checks reported" case this branch exists to detect.
+      NC_OUT="$(gh pr checks "$PR" -R "$REPO" 2>&1 || true)"
+      if printf '%s' "$NC_OUT" | grep -qi 'no checks reported'; then JSON='[]'
+      else
+        errors=$((errors + 1))
+        if [ "$errors" -ge 5 ]; then emit ERROR; echo "gh pr checks unreadable 5 times in a row"; exit 2; fi
+        sleep "$INTERVAL"; continue
+      fi
+    fi
+  fi
+  errors=0
+  cur="$(head_sha)"
+  if [ -n "$cur" ] && [ "$cur" != "$START_SHA" ]; then emit ERROR; echo "PR head moved during the wait ($START_SHA -> $cur); re-review the new head"; exit 2; fi
+  total=$(printf '%s' "$JSON" | jq 'length')
+  failed=$(printf '%s' "$JSON" | jq -r '.[] | select(.bucket=="fail" or .bucket=="cancel") | "  - \(.name) (\(.bucket))"')
+  pending=$(printf '%s' "$JSON" | jq -r '.[] | select(.bucket!="pass" and .bucket!="skipping" and .bucket!="fail" and .bucket!="cancel") | "  - \(.name) (\(.bucket))"')
+  if [ -n "$failed" ]; then emit FAIL; echo "PR #$PR head ${START_SHA:0:7}: failing checks:"; echo "$failed"; exit 1; fi
+  if [ "$total" -eq 0 ]; then
+    if [ "$elapsed" -ge "$GRACE" ]; then
+      RUNS=$(gh api "repos/$REPO/actions/runs?head_sha=$START_SHA&per_page=1" --jq '.total_count' 2>/dev/null || echo "")
+      if [ -n "$RUNS" ] && [ "$RUNS" != "0" ]; then
+        :  # workflow runs exist for this head but no checks are reported yet — keep waiting
+      elif [ "$REQUIRE" = "1" ]; then
+        emit ERROR; echo "no checks reported after ${GRACE}s and FORGE_CI_REQUIRE_CHECKS=1"; exit 2
+      else
+        emit PASS; echo "no checks reported for PR #$PR after ${GRACE}s and no workflow runs for its head (no CI on this branch)"; exit 0
+      fi
+    fi
+  elif [ -z "$pending" ] && [ "$elapsed" -ge "$SETTLE" ]; then
+    emit PASS; echo "PR #$PR head ${START_SHA:0:7}: $total checks passed or skipped"; exit 0
+  fi
+  if [ "$elapsed" -ge "$TIMEOUT" ]; then emit TIMEOUT; echo "PR #$PR: still pending after ${TIMEOUT}s:"; echo "$pending"; exit 3; fi
+  sleep "$INTERVAL"
+done

package/scripts/wait-ci-green.test.sh

@@ -0,0 +1,99 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+# wait-ci-green.test.sh — offline tests for scripts/wait-ci-green.sh (fake gh on PATH).
+# Usage: bash scripts/wait-ci-green.test.sh
+set -uo pipefail
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"; GATE="$HERE/wait-ci-green.sh"
+T=$(mktemp -d); trap 'rm -rf "$T"' EXIT
+PASS=0; FAILN=0
+expect() { [ "$2" = "$3" ] && PASS=$((PASS+1)) || { FAILN=$((FAILN+1)); echo "FAIL: $1 (got '$3' want '$2')"; }; }
+
+# Fake gh: `pr view --json headRefOid` prints line N of $T/sha (N = call count, last line repeats);
+# `pr checks --json` prints the N-th fixture $T/checks.N (last one repeats); "ERR" fixture = outage.
+mkdir -p "$T/bin"
+cat > "$T/bin/gh" <<'GH'
+#!/usr/bin/env bash
+D="$FAKE_DIR"
+if [ "$1 $2" = "pr view" ]; then
+  n=$(( $(cat "$D/sha.n" 2>/dev/null || echo 0) + 1 )); echo "$n" > "$D/sha.n"
+  total=$(wc -l < "$D/sha"); [ "$n" -gt "$total" ] && n=$total; sed -n "${n}p" "$D/sha"; exit 0
+fi
+if [ "$1" = "api" ]; then
+  case "$2" in *actions/runs*) cat "$D/runs" 2>/dev/null || echo 0; exit 0 ;; esac
+  exit 1
+fi
+if [ "$1 $2" = "pr checks" ]; then
+  case " $* " in *" --json "*) ;; *) [ -f "$D/nochecks" ] && { echo "no checks reported on the 'x' branch" >&2; exit 1; }; exit 1 ;; esac
+  n=$(( $(cat "$D/chk.n" 2>/dev/null || echo 0) + 1 )); echo "$n" > "$D/chk.n"
+  f="$D/checks.$n"; while [ ! -f "$f" ] && [ "$n" -gt 1 ]; do n=$((n-1)); f="$D/checks.$n"; done
+  c=$(cat "$f"); [ "$c" = "ERR" ] && { echo "HTTP 502" >&2; exit 1; }
+  [ "$c" = "NONE" ] && { echo "no checks reported on the 'x' branch" >&2; exit 1; }
+  echo "$c"; exit 0
+fi
+exit 1
+GH
+chmod +x "$T/bin/gh"
+
+run() { # run <case-dir> [gate args...] -> prints "rc|first line"
+  local d="$1"; shift
+  local out; out=$(FAKE_DIR="$d" PATH="$T/bin:$PATH" FORGE_CI_INTERVAL=1 FORGE_CI_NO_CHECKS_GRACE=1 FORGE_CI_SETTLE="${SETTLE:-0}" bash "$GATE" 7 -R o/r "$@" 2>/dev/null); local rc=$?
+  printf '%s|%s' "$rc" "$(printf '%s\n' "$out" | head -1)"
+}
+mk() { local d="$T/$1"; mkdir -p "$d"; printf 'abc1234\n' > "$d/sha"; shift; local i=1; for c in "$@"; do printf '%s' "$c" > "$d/checks.$i"; i=$((i+1)); done; echo "$d"; }
+
+P='[{"name":"a","bucket":"pass"},{"name":"b","bucket":"skipping"}]'
+expect "all pass/skipping" "0|CI_GATE: PASS" "$(run "$(mk pass "$P")")"
+expect "one failure" "1|CI_GATE: FAIL" "$(run "$(mk fail '[{"name":"a","bucket":"pass"},{"name":"b","bucket":"fail"}]')")"
+expect "cancelled counts as failure" "1|CI_GATE: FAIL" "$(run "$(mk cancel '[{"name":"a","bucket":"cancel"}]')")"
+expect "pending then pass" "0|CI_GATE: PASS" "$(run "$(mk pend '[{"name":"a","bucket":"pending"}]' "$P")")"
+expect "pending then fail" "1|CI_GATE: FAIL" "$(run "$(mk pendfail '[{"name":"a","bucket":"pending"}]' '[{"name":"a","bucket":"fail"}]')")"
+expect "pending past timeout" "3|CI_GATE: TIMEOUT" "$(run "$(mk slow '[{"name":"a","bucket":"pending"}]')" --timeout 2)"
+expect "fail wins over pending" "1|CI_GATE: FAIL" "$(run "$(mk mixed '[{"name":"a","bucket":"pending"},{"name":"b","bucket":"fail"}]')")"
+expect "transient outage then pass" "0|CI_GATE: PASS" "$(run "$(mk blip ERR "$P")")"
+expect "persistent outage" "2|CI_GATE: ERROR" "$(run "$(mk down ERR)" --timeout 60)"
+d=$(mk none NONE); touch "$d/nochecks"
+expect "no checks after grace passes" "0|CI_GATE: PASS" "$(run "$d")"
+expect "no checks + REQUIRE fails closed" "2|CI_GATE: ERROR" "$(FORGE_CI_REQUIRE_CHECKS=1 run "$d")"
+d=$(mk moved '[{"name":"a","bucket":"pending"}]' "$P"); printf 'abc1234\nabc1234\ndef5678\n' > "$d/sha"
+expect "head moved during wait" "2|CI_GATE: ERROR" "$(run "$d")"
+expect "bad pr number" "2|CI_GATE: ERROR" "$(FAKE_DIR="$T/pass" PATH="$T/bin:$PATH" bash "$GATE" abc -R o/r 2>/dev/null | head -1 | sed 's/^/2|/')"
+expect "missing repo" "2" "$(FAKE_DIR="$T/pass" PATH="$T/bin:$PATH" bash "$GATE" 7 >/dev/null 2>&1; echo $?)"
+
+d=$(mk runsnochecks NONE); touch "$d/nochecks"; echo 3 > "$d/runs"
+expect "no checks but workflow runs exist keeps waiting (timeout)" "3|CI_GATE: TIMEOUT" "$(run "$d" --timeout 3)"
+expect "pass is held until the settle period" "0|CI_GATE: PASS" "$(SETTLE=2 run "$(mk settle "$P")")"
+out=$(FAKE_DIR="$(mk headline "$P")" PATH="$T/bin:$PATH" FORGE_CI_INTERVAL=1 FORGE_CI_SETTLE=0 bash "$GATE" 7 -R o/r 2>/dev/null)
+expect "every result names the gated head" "CI_GATE_HEAD: abc1234" "$(printf '%s\n' "$out" | grep '^CI_GATE_HEAD:')"
+
+# Static guard: every autonomous `gh pr merge` command line in the pipeline specs must be preceded
+# (within 25 lines) by a CI gate result check. Prose/manual instructions are not command lines.
+for spec in commands/review-pr.md commands/work-on/review.md commands/work-on/remediate.md commands/recover-orphans.md commands/deploy-pr.md; do
+  bad=$(awk '
+    { line[NR]=$0 }
+    /^[[:space:]]*(MERGE_RESULT=\$\()?gh pr merge / {
+      ok=0; for (i=NR-1; i>0 && i>=NR-25; i--) if (line[i] ~ /CI_GATE_RC/) { ok=1; break }
+      if (!ok) print FILENAME ":" NR
+    }' "$HERE/../$spec")
+  expect "every autonomous merge in $spec is CI-gated" "" "$bad"
+done
+# Every autonomous merge pins the gated head (forge#3187): no merge line may omit --match-head-commit.
+for spec in commands/review-pr.md commands/work-on/review.md commands/work-on/remediate.md commands/recover-orphans.md commands/deploy-pr.md; do
+  unpinned=$(grep -nE '^[[:space:]]*(MERGE_RESULT=\$\(|MERGE_OUTPUT=\$\()?gh pr merge ' "$HERE/../$spec" | grep -v -- '--match-head-commit')
+  expect "every autonomous merge in $spec pins the gated head" "" "$unpinned"
+done
+# The gate's own default timeout stays under the 10-minute Bash tool limit (forge#3189).
+expect "default gate timeout fits one Bash call" "540" "$(sed -n 's/.*TIMEOUT="\${FORGE_CI_TIMEOUT:-\([0-9]*\)}".*/\1/p' "$GATE")"
+
+# The /work-on router never merges: every merge lives in a CI-gated phase.
+if grep -qE '^[[:space:]]*(MERGE_RESULT=\$\()?gh pr merge ' "$HERE/../commands/work-on.md"; then FAILN=$((FAILN+1)); echo "FAIL: work-on.md router contains a merge command"; else PASS=$((PASS+1)); fi
+
+# Reviewed-head guard: review-pr Phase 8 must refuse to merge a head other than the reviewed commit,
+# and the work-on callers must route "stale review" to a re-review, never a manual merge.
+grep -qF '${GATED_HEAD#"$REVIEWED_SHORT"}' "$HERE/../commands/review-pr.md" && PASS=$((PASS+1)) || { FAILN=$((FAILN+1)); echo "FAIL: review-pr Phase 8 lacks reviewed-head guard"; }
+for f in commands/work-on/review.md; do
+  grep -q 'stale review' "$HERE/../$f" && PASS=$((PASS+1)) || { FAILN=$((FAILN+1)); echo "FAIL: $f does not route stale review"; }
+done
+
+echo "wait-ci-green tests: pass=$PASS fail=$FAILN"
+[ "$FAILN" -eq 0 ]

package/commands/work-on-monolithic.md

@@ -1,326 +0,0 @@
----
-description: "[BENCHMARK] Monolithic work-on — single-prompt pipeline with no Skill sub-phase boundaries"
-argument-hint: "[issue number]"
-install: internal
----
-<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
-<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
-
-# /work-on-monolithic — Full Issue Pipeline (Single Prompt)
-
-**Input**: $ARGUMENTS
-
-Orchestrator for the full issue lifecycle: investigate → build → review → merge → close. GitHub issues are the persistent context layer — read existing comments before starting, write structured reports back, use `workflow:*` labels to track state.
-
-**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).**
-
-> **Relationship to `/work-on` (canonical path)**: This file is a `[BENCHMARK]` reference variant. It documents the same inline-execution model that `/work-on` Phase 3 and `work-on/build.md` use as their **default** for STANDARD/fast-lane issues — all build sub-phases (context → architect → implement → validate) run inline in the current context window with no `Skill()` sub-agent spawns. The difference is that this file omits the worktree lifecycle, `FORGE:CONTRACT` posting, and the Spawn-Decision exception path for large builds. Use `/work-on` for production runs; use this file for baseline benchmarking or when comparing single-prompt token cost against the modular path. See `work-on/build.md` (Canonical Build Path section) for the reconciled build topology. <!-- Added: forge#1276 -->
-**NEVER use the Agent tool** — this spec executes all phases inline as a single monolithic prompt. The Agent tool would spawn a subprocess outside this context, breaking the single-prompt contract and losing all accumulated pipeline state.
-
-<!-- FORGE:SPEC_LOADED — work-on-monolithic.md loaded and active. Agent is bound by this spec. -->
-
-### Compaction Resilience
-
-1. Write state to GitHub after EVERY significant step
-2. Re-read GitHub state at the START of each phase (don't rely on in-memory context)
-3. After compaction: re-read issue (body + comments + labels) to reconstruct state
-4. Key principle: A NEW session running this command should pick up where the last left off by reading GitHub state alone
-
----
-
-## Pipeline Rules
-
-- **NEVER merge to main.** PRs target `staging` (fast lane) or `milestone/{slug}` (feature lane).
-- **`Closes #N` does not auto-close for non-default-branch PRs.** You MUST explicitly `gh issue close`.
-- **Review findings are NOT merge blockers.** They become separate issues.
-
----
-
-## Project Configuration
-
-Read `forge.yaml` from the repository root. If missing, tell the user to run `npx forgedock init` and stop.
-
-Resolve the following variables from `forge.yaml` before running any pipeline phase:
-
-| Variable | Source in forge.yaml | Description |
-|----------|----------------------|-------------|
-| `GH_REPO` | `project.owner` + `project.repo` | Full GitHub repo identifier (`owner/repo`) |
-| `REPO_PATH` | `paths.root` | Absolute path to the local repository |
-| `STAGING_BRANCH` | `branches.staging` | Branch for fast-lane PRs (no milestone) |
-| `WORKTREE_BASE` | `paths.worktree_base` | Directory where git worktrees are created |
-| `GH_FLAG` | _(empty for default repo; `-R owner/repo` for satellites)_ | Extra flag for `gh` CLI satellite repo calls |
-
-**Multi-repo routing** (optional): If `forge.yaml` contains a `repos.satellites` list, build the prefix routing table from it. Each satellite entry has `prefix`, `repo`, `staging_branch`, and `local_path`. Issues without a prefix route to the default `GH_REPO`. Satellite repos have no staging — their fast-lane PRs go to their configured `staging_branch` (typically `main`).
-
-If no `repos.satellites` section exists, only the primary repo is available — all issues route to `GH_REPO`.
-
----
-
-## Phase 0: Resolve Issue & Load Context
-
-### 0A: Parse input
-Extract project prefix and issue number.
-
-### 0B: Load issue + existing context
-```bash
-gh issue view {NUMBER} {GH_FLAG} --json number,title,body,labels,state,comments,milestone
-gh api repos/{GH_REPO}/issues/{NUMBER}/comments --jq '.[] | {id: .id, author: .user.login, body: .body}'
-```
-
-**Check**: state (closed → STOP), terminal labels (`workflow:merged`/`workflow:invalid` → STOP), existing agent comments (`FORGE:INVESTIGATOR`, `FORGE:CONTRACT`, `FORGE:BUILDER`, `FORGE:TRAJECTORY`), parent tracker status.
-
-**Determine resume point**: No comments → Phase 1. Investigation exists + ready-to-build → Phase 3. Builder:COMPLETE + no PR → Phase 4. Builder without :COMPLETE (partial/interrupted build) + no PR → Phase 3 (partial-build cleanup). Builder + PR open → Phase 5. PR merged + issue open → close issue.
-
-**Classify lane**: Milestone → feature lane (`milestone/{slug}`). No milestone → fast lane (`staging`).
-
-**Source branch for review-findings**: Parse `**Code branch**: \`{branch}\`` from body. Branch from there, not main.
-
-### 0C: Sync to Project board
-Add issue to project, set Status=In Progress, Lane, Component, Priority, Workflow=Investigating.
-
----
-
-## Phase 1: Investigation
-
-**Skip if**: `<!-- FORGE:INVESTIGATOR -->` exists with `<!-- INVESTIGATION:COMPLETE -->`.
-
-### 1A: Set label
-```bash
-gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:investigating"
-gh issue edit {NUMBER} {GH_FLAG} --remove-label "workflow:ready-to-build,workflow:building,workflow:in-review" 2>/dev/null || true
-```
-
-### 1B: Investigate the issue
-
-Mission: Validate whether the issue is real. Assume description is wrong until proven otherwise.
-
-**Domain file hints** (start search here):
-
-Configure domain-to-file mappings for your project in `forge.yaml → review.key_paths`. The table below shows the standard layout — override any entry that doesn't match your codebase:
-
-| Domain | Default key files (override via forge.yaml) |
-|--------|---------------------------------------------|
-| BILLING | `routers/billing.py`, `core/pricing.py`, `services/payment_service.py` |
-| WORKER | `worker/main.py`, `worker/queues.py`, `worker/tasks.py` |
-| AUTH | `core/auth.py`, `routers/auth.py`, `dependencies.py` |
-| DATABASE | `infra/migrations/`, `models/`, `db/` |
-| FRONTEND | `web/src/app/`, `web/src/components/`, `web/src/lib/` |
-| AI | `services/ai_client.py`, `routers/ai.py` |
-| INFRA | `.github/workflows/`, `docker-compose.yml`, `infra/traefik/` |
-
-If `forge.yaml → review.key_paths` is present, use those mappings instead of the defaults above.
-
-**Steps**: Check right branch → read domain files → verify claims → git blame → determine root cause → identify affected files → validate proposed fixes against full system stack.
-
-**Fix-Approach Validation**: If issue proposes a fix, don't adopt it as spec. Trace through target system's middleware, auth, routing.
-
-**Domain Context Discovery** (narrow scope, max 5 files):
-```bash
-git log --oneline --all -30 -- {affected_files} | grep -oP '#\d+' | sort -u
-```
-
-**Output format**: Verdict (CONFIRMED/PARTIAL/INVALID), Confidence, Severity, Task Type, What Was Claimed, What We Found, Root Cause, Affected Files, Evidence, Recommendation.
-
-### 1C: Post investigation comment
-```bash
-gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:INVESTIGATOR -->
-<!-- INVESTIGATION:COMPLETE -->
-## Investigation Report
-{report}"
-```
-
-### 1D: Update labels
-CONFIRMED/PARTIAL → add `workflow:ready-to-build`, continue to Phase 3.
-INVALID → close issue, add `workflow:invalid`, STOP.
-
----
-
-## Phase 3: Build
-
-**Skip if**: `<!-- FORGE:BUILDER -->` exists.
-
-### 3A: Re-read state from GitHub (MANDATORY)
-```bash
-gh issue view {NUMBER} {GH_FLAG} --json body,labels
-gh api repos/{GH_REPO}/issues/{NUMBER}/comments --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body'
-```
-
-### 3B: Classify task type
-
-| Signal | Type | Approach |
-|--------|------|----------|
-| UI/UX, feature + web/ files | UI/UX | `frontend-design` skill |
-| Feature + services/ | Backend Feature | Implement directly |
-| Feature + both | Full-Stack | Backend first, then frontend-design |
-| Bug + web/ | Frontend Fix | Direct |
-| Bug + services/ | Backend Fix | Direct |
-| Refactor/docs | Maintenance | Direct |
-
-### 3C: Builder Contract (MANDATORY)
-Post `<!-- FORGE:CONTRACT -->` comment with: task type, proposed approach, deliverables table (file/change/why), acceptance criteria, quality considerations.
-
-### 3C.5: Context Gathering (max 2 minutes)
-
-Surface institutional memory before writing code. For each affected file:
-```bash
-# Recent agent work on these files
-git log --oneline --all -30 -- {affected_files} | grep -oP '#\d+' | sort -u | head -5
-# Check for review findings on same files
-for ISSUE_NUM in {related_issue_numbers}; do
-  gh api repos/{GH_REPO}/issues/${ISSUE_NUM}/comments --jq '.[] | select(.body | contains("FORGE:")) | .body' 2>/dev/null | head -20
-done
-```
-
-Post `<!-- FORGE:CONTEXT -->` comment with findings (or skip if no relevant history).
-
-### 3C.6: Architecture Plan
-
-For multi-file changes, trace ALL affected code paths before writing code:
-- Map the call chain: entry point → middleware → handler → service → model → response
-- Identify every file that needs to change
-- Order implementation steps to avoid broken intermediate states
-
-Post `<!-- FORGE:ARCHITECT -->` comment with the implementation plan.
-
-For single-file or trivial changes, skip this step.
-
-### 3D: Set building label
-```bash
-gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:building" --remove-label "workflow:ready-to-build,workflow:investigating"
-```
-
-### 3E: Create worktree
-Branch slug from title (lowercase, hyphenated, max 40 chars). Prefix: `fix/` (bugs) or `feat/` (features).
-- Review-finding → branch from `origin/{SOURCE_BRANCH}`
-- Fast lane → branch from `origin/{STAGING_BRANCH}`
-- Feature lane → branch from `origin/milestone/{slug}`
-
-```bash
-cd {REPO_PATH}
-git fetch origin
-BRANCH="fix/{slug}-{NUMBER}"
-git worktree add {WORKTREE_BASE}/{BRANCH} -b {BRANCH} origin/{PR_BASE}
-```
-
-### 3F: Implement
-Route by task type. Read the investigation report and contract. Implement the fix/feature.
-
-### 3F.5: Quality Gate
-Invoke quality-gate on changed files:
-```
-Skill(skill="quality-gate", args="{changed_files} --worktree {WORKTREE_PATH}")
-```
-Fix HIGH/MEDIUM findings. Max 2 iterations. Skip for 1-file config/docs edits.
-
-### 3G: Format and verify
-- Python: `black` + `isort` + `py_compile`
-- TypeScript (primary repo): `prettier --write` + `tsc --noEmit` (BLOCKING if fails)
-- TypeScript (satellite): `npm run build` + `prettier --write`
-
-### 3H: Frontend proxy wiring check (MANDATORY)
-All client-side fetch/useSWR/apiFetch must use `/api/...` proxy routes, NEVER `/api/v1/...` directly.
-
-### 3I: Deployment completeness check (MANDATORY)
-Skip if no new env vars introduced.
-
-For each new env var, verify present in ALL required locations:
-
-| Location | Required for |
-|----------|-------------|
-| `.env.example` | All new vars |
-| Secrets backend (see `deploy.secrets_backend`) | Secret vars — skip if backend is `none` or unset |
-| `app/env_validation.py` | API service vars (if project has one) |
-
-**Secrets backend check** *(trigger: `deploy.secrets_backend == "sops"`)*:
-
-If the project uses SOPS, verify the new var is present in all SOPS chain locations:
-- `infra/secrets/prod.enc.yaml` — SOPS-encrypted secret store
-- `infra/decrypt-secrets.sh` ENV_MAPPING — maps SOPS key to env var name
-
-If `deploy.secrets_backend` is absent or not `sops`, skip these checks and log:
-> `SKIP: SOPS chain check — deploy.secrets_backend is not "sops". Configure deploy.secrets_backend in forge.yaml to enable.`
-
-### 3J: Commit
-Conventional prefix (fix/feat/refactor/docs). Reference #{NUMBER} in the commit message.
-
-### 3K: Post implementation comment
-Post `<!-- FORGE:BUILDER -->` with: branch, commit, files changed, approach, changes list, testing checklist.
-
----
-
-## Phase 4: PR Creation
-
-### 4A: Push branch
-```bash
-cd {WORKTREE_PATH} && git push -u origin {BRANCH}
-```
-If fails: try `--force-with-lease`. If still fails: post comment, add `needs-human`, STOP.
-
-### 4B: Determine PR target
-No milestone → `staging`. Has milestone → `milestone/{slug}`. NEVER `main`.
-
-### 4C: Create PR
-```bash
-gh pr create {GH_FLAG} --base {PR_BASE} --title "{Fix|Feat}: {description} (#{NUMBER})" --body "..."
-```
-Include `Closes #{NUMBER}`.
-
-### 4D: Update labels
-```bash
-gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:in-review" --remove-label "workflow:building"
-```
-
----
-
-## Phase 5: Auto-Review
-
-### 5A: Re-read state from GitHub (MANDATORY)
-### 5B: Invoke /review-pr with --auto-merge
-```
-Skill(skill="review-pr", args="{PR_NUMBER} --auto-merge --issue {NUMBER} --base {PR_BASE} --gh-flag {GH_FLAG}")
-```
-
-### 5C: Verify merge and close (recovery)
-- PR MERGED + issue CLOSED → proceed to Phase 6/7
-- PR MERGED + issue OPEN → close issue manually
-- PR NOT MERGED → `gh pr merge --merge {GH_FLAG}`, close issue. If merge fails → post comment, add `needs-human`, STOP.
-
-### 5D: Project board update (Workflow=Merged, Status=Done)
-
-### 5E: Final issue body update
-Check off remaining items.
-
----
-
-## Phase 6: Parent Tracker Update (Sub-Issues Only)
-
-**Skip if**: Not a sub-issue.
-
-Check off this sub-issue in parent body. If ALL sub-issues closed → close parent with `workflow:merged`.
-
----
-
-## Phase 7: Summary & Trajectory
-
-### 7A: Report
-```
-## Done: #{NUMBER} — {TITLE}
-- Investigation: {verdict} ({confidence})
-- Lane: {FAST/FEATURE}
-- Fix: {branch} → PR #{PR_NUMBER} → merged to `{PR_BASE}`
-- Files changed: {count}
-```
-
-### 7B: Trajectory Log (MANDATORY)
-Post `<!-- FORGE:TRAJECTORY -->` comment with phase-by-phase results table, decisions, anomalies.
-
----
-
-## Error Handling
-
-- Worktree exists: reuse or clean up
-- PR creation fails: check if branch pushed, if PR already exists
-- Merge conflicts: report to user, do NOT auto-resolve
-- gh CLI fails: check `gh auth status`
-- Label missing: create it