forgedock 1.1.7 → 1.1.9

package/commands/work-on/decompose.md

@@ -12,7 +12,7 @@ argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG]
 **Invoked by**: `work-on.md` routing loop, when `INVESTIGATE_RESULT.decompose = YES`.
 **Output**: Create sub-issues, update parent tracker, post `<!-- FORGE:DECOMPOSED -->` comment, set labels. STOP — each sub-issue runs its own /work-on.
 
-**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. This file's mechanical bits (label transitions, sub-issue creation) stay at this tier because they're interleaved with the reasoning-heavy sub-issue design steps in the same `Skill()` invocation — see `work-on.md` section "Model and Effort Tiering — What Actually Applies". <!-- Added: forge#1827 -->
 **NEVER use plan mode (EnterPlanMode).**
 
 ---

package/commands/work-on/investigate.md

@@ -11,7 +11,7 @@ argument-hint: [issue number] [--repo {owner}/{repo}] [--gh-flag "-R {owner}/{re
 
 Standalone investigation phase for the work-on pipeline. Validates whether an issue is real, determines root cause, posts a structured FORGE:INVESTIGATOR comment to GitHub, and updates workflow labels.
 
-**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. This file's mechanical bits (1A label set, `FORGE:CHECKPOINT` writes) stay at this tier because they're interleaved with the reasoning-heavy investigation steps in the same `Skill()` invocation — see `work-on.md` section "Model and Effort Tiering — What Actually Applies". <!-- Added: forge#1827 -->
 **NEVER use plan mode (EnterPlanMode).**
 
 <!-- FORGE:SPEC_LOADED — work-on/investigate.md loaded and active. Agent is bound by this spec. -->
@@ -90,6 +90,171 @@ Print these blocks to stdout before Phase 1A begins. During Phase 1B (step 3 —
 
 ---
 
+## Phase 0.6: Forge Ledger Pre-Recall <!-- Added: forge#1740 -->
+
+**Goal**: Query the Forge Ledger knowledge index for prior cards matching this issue's title terms, affected files, and symbols — **before reading any code**. Inject above-threshold results with explicit delta-verification framing so the investigator builds on prior knowledge rather than re-deriving it.
+
+**This phase is non-blocking** — if the index is absent, empty, or returns no match above threshold, log a single line and proceed to Phase 1A. Never stall the pipeline for recall.
+
+**Relationship to Phase 0.5**: Phase 0.5 retrieves structured priors from the Gist-based FORGE:MEMORY_INDEX (coarse keyword scoring over MEMORY_ENTRY lines). Phase 0.6 queries the Forge Ledger index (BM25 over structured knowledge cards, indexed by `build-knowledge-index.mjs`). Both are complementary and both run — neither replaces the other.
+
+### Step 1: Probe for index
+
+```bash
+RECALL_PATH="${REPO_PATH:-$(git rev-parse --show-toplevel 2>/dev/null)}/bin/recall.mjs"
+LEDGER_AVAILABLE=0
+
+if [ -f "$RECALL_PATH" ]; then
+  # Quick probe: does the index exist and have at least one card?
+  PROBE=$(node "$RECALL_PATH" --doctor 2>/dev/null | grep "^Total cards:" | grep -v "^Total cards:    0" || true)
+  [ -n "$PROBE" ] && LEDGER_AVAILABLE=1
+fi
+
+if [ "$LEDGER_AVAILABLE" -eq 0 ]; then
+  echo "[recall] Forge Ledger index absent or empty — skipping Phase 0.6, proceeding to Phase 1A"
+  # → Continue to Phase 1A
+fi
+```
+
+### Step 2: Build combined query (title terms + symbols + affected files)
+
+Extract query components from the issue body and title. The recall CLI accepts free text (BM25 ranked) plus repeated `--file` flags (exact-match boost):
+
+```bash
+# Extract title keywords: lowercase, remove stop words, keep noun/verb tokens (≥4 chars)
+ISSUE_TITLE=$(gh issue view {NUMBER} {GH_FLAG} --json title --jq '.title' 2>/dev/null || echo '')
+TITLE_TERMS=$(echo "$ISSUE_TITLE" | tr '[:upper:]' '[:lower:]' \
+  | sed 's/[^a-z0-9 ]/ /g' \
+  | tr ' ' '\n' \
+  | grep -E '^[a-z]{4,}$' \
+  | grep -vE '^(with|that|this|from|into|have|will|when|then|than|them|they|been|were|also|only|does|some|each|more|over|such|both|most|other|many|after|about|should|would|could|their|these|those|which|where|there|being|while|using|since|until|before|under|above)$' \
+  | sort -u | head -10 | tr '\n' ' ' | xargs)
+
+# Extract affected files from the issue body's ## Affected Files section
+ISSUE_BODY=$(gh issue view {NUMBER} {GH_FLAG} --json body --jq '.body' 2>/dev/null || echo '')
+AFFECTED_FILES_RAW=$(echo "$ISSUE_BODY" \
+  | sed -n '/^## Affected Files/,/^## /p' \
+  | grep -oE '`[^`]+\.(md|mjs|js|ts|py|sh|yaml|yml|json)`' \
+  | tr -d '`' | sort -u | head -5)
+
+# Extract symbols: backtick-quoted identifiers from the issue body (≥4 chars, camelCase or snake_case)
+SYMBOLS_RAW=$(echo "$ISSUE_BODY" \
+  | grep -oE '`[A-Za-z_][A-Za-z0-9_]{3,}`' \
+  | tr -d '`' | sort -u | head -5)
+
+# Build --file flags (one per affected file)
+FILE_FLAGS=""
+while IFS= read -r f; do
+  [ -n "$f" ] && FILE_FLAGS="$FILE_FLAGS --file $f"
+done <<< "$AFFECTED_FILES_RAW"
+
+# Build --symbol flag (first symbol only — recall supports one --symbol)
+SYMBOL_FLAG=""
+FIRST_SYMBOL=$(echo "$SYMBOLS_RAW" | head -1)
+[ -n "$FIRST_SYMBOL" ] && SYMBOL_FLAG="--symbol $FIRST_SYMBOL"
+```
+
+### Step 3: Run recall query and capture results
+
+```bash
+RECALL_RESULTS=""
+RECALL_ISSUE_CITATIONS=""
+
+if [ "$LEDGER_AVAILABLE" -eq 1 ] && [ -n "$TITLE_TERMS$FILE_FLAGS$SYMBOL_FLAG" ]; then
+  echo "[recall] Querying Forge Ledger: terms='${TITLE_TERMS}' files='${AFFECTED_FILES_RAW}' symbol='${FIRST_SYMBOL}'"
+
+  # Run combined query: title terms (free text) + file flags + symbol + min-score threshold
+  # --json for machine-readable output; --min-score 0.3 filters weak matches (noise gate)
+  RECALL_JSON=$(node "$RECALL_PATH" \
+    $TITLE_TERMS \
+    $FILE_FLAGS \
+    $SYMBOL_FLAG \
+    --k 5 \
+    --min-score 0.3 \
+    --json \
+    2>/dev/null || echo '[]')
+
+  # Count results
+  RECALL_COUNT=$(echo "$RECALL_JSON" | node -e "
+    let d = ''; process.stdin.on('data', c => d += c);
+    process.stdin.on('end', () => {
+      try { console.log(JSON.parse(d).length); } catch { console.log(0); }
+    });
+  " 2>/dev/null || echo "0")
+
+  if [ "${RECALL_COUNT:-0}" -gt 0 ]; then
+    echo "[recall] Found ${RECALL_COUNT} prior card(s) above threshold — injecting with delta-verification framing"
+
+    # Extract issue citations for the Prior Investigations field in the FORGE:INVESTIGATOR comment
+    RECALL_ISSUE_CITATIONS=$(echo "$RECALL_JSON" | node -e "
+      let d = ''; process.stdin.on('data', c => d += c);
+      process.stdin.on('end', () => {
+        try {
+          const cards = JSON.parse(d);
+          const seen = new Set();
+          const cites = cards
+            .filter(c => { if (seen.has(c.issue)) return false; seen.add(c.issue); return true; })
+            .map(c => '#' + c.issue)
+            .join(', ');
+          console.log(cites);
+        } catch { console.log(''); }
+      });
+    " 2>/dev/null || echo '')
+
+    # Format cards as human-readable text for injection (not raw JSON)
+    RECALL_FORMATTED=$(echo "$RECALL_JSON" | node -e "
+      let d = ''; process.stdin.on('data', c => d += c);
+      process.stdin.on('end', () => {
+        try {
+          const cards = JSON.parse(d);
+          const lines = [];
+          for (const c of cards) {
+            lines.push('── ' + c.kind.toUpperCase() + ' from #' + c.issue + ' (score: ' + c.score.toFixed(2) + ') ──');
+            if (c.rootCause)  lines.push('Root Cause: ' + c.rootCause);
+            if (c.prevention) lines.push('Fix/Prevention: ' + c.prevention);
+            if (c.pattern)    lines.push('Pattern: ' + c.pattern);
+            if (c.verdict)    lines.push('Verdict: ' + c.verdict + ' (' + (c.confidence || '?') + ')');
+            if (c.paths && c.paths.length) lines.push('Files: ' + c.paths.slice(0,3).join(', '));
+          }
+          console.log(lines.join('\n'));
+        } catch (e) { console.log(''); }
+      });
+    " 2>/dev/null || echo '')
+
+    # Cap at ≤ 2K chars (same budget as context C0 Gist summaries)
+    RECALL_RESULTS=$(echo "$RECALL_FORMATTED" | head -c 2048)
+  else
+    echo "[recall] No prior cards above threshold (min-score 0.3) — investigating from scratch"
+  fi
+fi
+```
+
+### Step 4: Inject recall results into investigation context
+
+If `RECALL_RESULTS` is non-empty, print the following block to stdout **before Phase 1A begins**. The investigation steps in Phase 1B MUST treat this as starting context — verify deltas against current code rather than re-deriving the prior model.
+
+**If `RECALL_RESULTS` is empty**: skip this step entirely and proceed to Phase 1A.
+
+```
+[FORGE:RECALL_PRIOR — Forge Ledger pre-recall results]
+Prior cards matched this issue above threshold (min-score 0.3).
+
+CRITICAL FRAMING: These cards describe prior findings on the same files/symbols.
+  → Verify the deltas against current code — do NOT re-derive the prior model.
+  → Stale cards (status: stale) are excluded by default — the query runs without
+     --include-stale. Do not treat any card as authoritative without confirming
+     the finding still exists in the current code.
+  → Cite confirmed priors in the FORGE:INVESTIGATOR "Prior Investigations" field.
+
+${RECALL_RESULTS}
+
+[END FORGE:RECALL_PRIOR]
+```
+
+Store `RECALL_ISSUE_CITATIONS` in a variable — it is used in Phase 1C to populate the `**Prior Investigations (via recall)**` field in the FORGE:INVESTIGATOR comment.
+
+---
+
 ## Phase 1A: Load Issue & Check Resume State
 
 ```bash
@@ -192,6 +357,20 @@ bash {REPO_PATH}/scripts/code-index.sh query --domain {DOMAIN_LABEL} --repo-path
 
 The comment MUST include `<!-- INVESTIGATION:COMPLETE -->` at the very end, AFTER all required sections are present. This marker signals the investigation finished successfully.
 
+**CODEC PATH (forge#1727)**: Construct the annotation body via the protocol codec — do NOT hand-roll the `<!-- FORGE:INVESTIGATOR -->` header. Use `forge-annotation.sh write INVESTIGATOR --field ...` or `node packages/protocol/src/cli.js emit INVESTIGATOR --field ...` to produce the opening tag and completion sentinel. Fill in the Markdown body sections below. The full pattern:
+
+```bash
+# Build the annotation body via codec (escaping and sentinel handled by codec)
+ANNOTATION_BODY=$(node packages/protocol/src/cli.js emit INVESTIGATOR \
+  --field "Verdict={VERDICT}" \
+  --field "Confidence={CONFIDENCE}" \
+  --field "Severity={SEVERITY}" \
+  --field "Task Type={TASK_TYPE}" \
+  --field "Decomposition Assessment={YES|NO} — {reason}")
+# ANNOTATION_BODY now has opening tag + required fields + INVESTIGATION:COMPLETE sentinel.
+# Append the Markdown body sections to it before posting.
+```
+
 Before posting, resolve the attribution annotation link from `forge.yaml`:
 
 ```bash
@@ -234,6 +413,7 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:INVESTIGATOR -->
 **Last touched**: {hash — author — date — subject}
 **Pickaxe hits (prior fixes / regressions)**: {commit(s) found via \`git log -S\`/\`-G\`, or 'None found' — max 5}
 {This field is MANDATORY — populate from the git blame + pickaxe commands in step 4/5. If a file is newly created (no history), write 'New file — no history.'}
+**Prior Investigations (via recall)**: {Comma-separated issue citations from \`RECALL_ISSUE_CITATIONS\` (e.g. '#1172, #1243 — building on, not repeating'), or 'None — no Forge Ledger match above threshold' if \`RECALL_RESULTS\` was empty. Use the \`RECALL_ISSUE_CITATIONS\` variable populated in Phase 0.6.}
 
 ### Recommendation
 {what to build/fix, concrete and actionable}
@@ -245,12 +425,19 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:INVESTIGATOR -->
 **{YES|NO}** — {reason}
 {if YES: proposed sub-issues with titles and dependencies}
 
-### Acceptance Spec
+### Acceptance Spec <!-- Added: forge#1829 -->
 {For each item in the issue's ## Acceptance Criteria section, emit one machine-checkable check line using the format below. If the issue has no Acceptance Criteria section, derive checks from the Recommendation above. Each check MUST be specific, observable, and testable — not vague prose. Checks are consumed by build/validate Phase B6.5 as the merge gate.}
 
+**Quoting (MANDATORY)**: `target=` and `matcher=` MUST always be wrapped in double quotes — `target="..."` / `matcher="..."` — even when the value is a single token (e.g. a plain file path). The downstream Phase B6.5 parser only extracts quoted values; an unquoted `target=`/`matcher=` will silently truncate at the first space and cause a false-negative gate failure for any multi-word value (shell commands with flags/arguments/pipes are almost always multi-word). Neither `target` nor `matcher` may contain a literal `"` character — use single quotes for any embedded string/regex literal inside the value, as shown below. `id=` and `type=` are always single tokens and are never quoted. `description=` is always the last field on the line and is captured to end-of-line — it does not need quoting.
+
 ```
-ACCEPTANCE_CHECK: id={ac-1} type={exists|contains|command|behavior} target={file_path|command|url} matcher={string|exit_0|regex} description={one-line human description}
-ACCEPTANCE_CHECK: id={ac-2} type={exists|contains|command|behavior} target={file_path|command|url} matcher={string|exit_0|regex} description={one-line human description}
+ACCEPTANCE_CHECK: id={ac-1} type={exists|contains|command|behavior} target="{file_path|command|url}" matcher="{string|exit_0|regex}" description={one-line human description}
+ACCEPTANCE_CHECK: id={ac-2} type={exists|contains|command|behavior} target="{file_path|command|url}" matcher="{string|exit_0|regex}" description={one-line human description}
+```
+
+Example with a multi-word shell command target (the case that previously broke — note the embedded single quotes around the regex, and the double quotes wrapping the whole target):
+```
+ACCEPTANCE_CHECK: id=ac-4 type=command target="grep -qE '(>= ?2|2\+)' commands/orchestrate/phase-1-resolve.md" matcher="exit_0" description=Fan-out cap is documented as >=2 or 2+
 ```
 
 **Check types**:
@@ -259,7 +446,9 @@ ACCEPTANCE_CHECK: id={ac-2} type={exists|contains|command|behavior} target={file
 - `command` — run a shell command and assert exit 0 (`target` = shell command, `matcher` = `exit_0`)
 - `behavior` — assert a runtime/observable behavior via shell command (`target` = shell command, `matcher` = expected output string or regex)
 
-**Skipping**: if the issue has no verifiable acceptance criteria and none can be derived from the recommendation, emit a single sentinel: `ACCEPTANCE_CHECK: id=ac-skip type=skipped target=none matcher=none description=No machine-checkable criteria available — human review required`
+**Self-defeating pipe guideline**: do NOT chain a `-q`/`--quiet` command into a downstream pipe consumer (e.g. `grep -q ... | grep ...`). A `-q` flag suppresses all stdout, so the next command in the pipe always receives empty input and the check can never pass regardless of the actual file content. If a check needs to verify two conditions against the same output, sequence them instead — e.g. `grep -qE 'first' file && grep -qE 'second' file` — or capture the output once and grep the captured variable.
+
+**Skipping**: if the issue has no verifiable acceptance criteria and none can be derived from the recommendation, emit a single sentinel: `ACCEPTANCE_CHECK: id=ac-skip type=skipped target="none" matcher="none" description=No machine-checkable criteria available — human review required`
 ${ANNOTATION_LINK_FOOTER}
 <!-- INVESTIGATION:COMPLETE -->"
 ```
@@ -541,6 +730,47 @@ fi
 
 ## Phase 1D: Update Labels & Return Verdict
 
+### 1D.0: Finding Lifecycle Label Transition (MANDATORY — run before workflow label update)
+
+**Purpose**: Wire the investigation verdict into the finding-validation lifecycle. If the issue under investigation is a review-finding (carries `needs-validation`), translate the verdict into `validated` or `false-positive` using `transition-label.sh --validate`. This is the primary mechanism that resolves the `needs-validation → validated/false-positive` lifecycle gap. <!-- Added: forge#1730 -->
+
+**Run this block regardless of verdict (CONFIRMED, PARTIAL, INVALID) — the verdict-to-label mapping handles all cases:**
+
+```bash
+# Check if this issue is a finding awaiting validation
+ISSUE_LABELS=$(gh issue view {NUMBER} {GH_FLAG} --json labels --jq '[.labels[].name] | join(",")' 2>/dev/null || echo "")
+
+if echo "$ISSUE_LABELS" | grep -q "needs-validation"; then
+  echo "Issue #{NUMBER} has needs-validation — applying verdict label transition..."
+  RESOLUTION=$(resolve_script 'transition-label')
+  TIER="${RESOLUTION%%:*}"
+  SCRIPT_PATH="${RESOLUTION#*:}"
+  case "$TIER" in
+    adaptive|universal)
+      bash "$SCRIPT_PATH" --validate {VERDICT} {NUMBER} {GH_FLAG} || true
+      ;;
+    prose)
+      # Prose fallback: apply label transition directly via gh
+      if [ "{VERDICT}" = "CONFIRMED" ]; then
+        gh issue edit {NUMBER} {GH_FLAG} --add-label "validated" --remove-label "needs-validation" 2>/dev/null || true
+        echo "Applied: needs-validation → validated (verdict: CONFIRMED)"
+      else
+        gh issue edit {NUMBER} {GH_FLAG} --add-label "false-positive" --remove-label "needs-validation" 2>/dev/null || true
+        echo "Applied: needs-validation → false-positive (verdict: {VERDICT})"
+      fi
+      ;;
+  esac
+else
+  echo "Issue #{NUMBER} does not have needs-validation — no finding lifecycle transition needed"
+fi
+```
+
+**Verdict → label mapping**: `CONFIRMED` → `validated`; `PARTIAL`, `NOT-CONFIRMED`, `INVALID` → `false-positive`.
+
+**Idempotency**: `transition-label.sh --validate` is a no-op if the issue already has `validated` or `false-positive`, or if it lacks `needs-validation`. Safe to call on any issue.
+
+---
+
 **CONFIRMED or PARTIAL with decompose: NO**:
 ```bash
 gh issue edit {NUMBER} {GH_FLAG} --add-label "workflow:ready-to-build" --remove-label "workflow:investigating"

package/commands/work-on/remediate.md

@@ -0,0 +1,331 @@
+---
+description: Remediate subcommand — checkout a needs-human PR, fix review findings, re-review, and re-gate with a FORGE:REMEDIATION paper trail
+argument-hint: [PR number] [--issue N] [--repo GH_REPO] [--gh-flag GH_FLAG] [--base PR_BASE]
+---
+<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios -->
+<!-- SPDX-License-Identifier: AGPL-3.0-or-later -->
+
+# work-on/remediate — Remediation Subcommand
+
+**Input**: $ARGUMENTS
+
+**Invoked by**:
+- `work-on.md` Phase 0A, standalone: `/work-on <pr> --remediate` (see forge#1813).
+- `commands/orchestrate/phase-4-execution.md` item 6.4, auto-dispatched against a `needs-human`-gated predecessor's own open PR.
+
+**Output**: Checkout the PR's existing branch → classify the block reason (fixable vs. policy escalation) → apply fixes → quality-gate → commit/push → re-invoke `/review-pr --auto-merge` → compute the #1809 Q1 auto-land bar → merge-if-verified or hold at `workflow:awaiting-merge` → emit a `FORGE:REMEDIATION` paper trail. Return result to caller.
+
+**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**NEVER use plan mode (EnterPlanMode).**
+
+**Scope note**: This mode owns exactly one gap — re-driving a `needs-human` PR's own remediation. It does NOT implement the `needs-human` sub-label taxonomy (#1815's scope) and it does NOT edit `review-pr.md`'s Phase 8 guard (forge#1810) — that guard's existing safe-default (`workflow:awaiting-merge` on any clean re-review of a previously-escalated PR) is reused as-is; this file only adds a bar-check *after* that guard has already fired.
+
+---
+
+## Inputs
+
+Parse from $ARGUMENTS:
+- `{PR_NUMBER}` — PR number to remediate (required, first positional arg). This is the `needs-human`-gated PR itself, NOT the linked issue number.
+- `--issue {ISSUE_NUMBER}` — linked issue number (optional). If absent, resolved in Phase M0 from the PR body's `Closes #N` reference.
+- `--repo {GH_REPO}` — GitHub repo (resolved from `forge.yaml → project` if omitted)
+- `--gh-flag {GH_FLAG}` — gh CLI repo flag
+- `--base {PR_BASE}` — PR target branch (optional; resolved from the PR's `baseRefName` if omitted)
+
+---
+
+## Phase M0: Load State & Guard Rails (MANDATORY)
+
+Re-read current state before doing anything:
+
+```bash
+PR_STATE=$(gh pr view {PR_NUMBER} {GH_FLAG} --json state,headRefName,baseRefName,body,mergeable,mergeStateStatus,url)
+PR_OPEN_STATE=$(echo "$PR_STATE" | jq -r '.state')
+HEAD_BRANCH=$(echo "$PR_STATE" | jq -r '.headRefName')
+PR_BASE="${PR_BASE:-$(echo "$PR_STATE" | jq -r '.baseRefName')}"
+PR_BODY=$(echo "$PR_STATE" | jq -r '.body')
+```
+
+**PR state guard**:
+- `PR_OPEN_STATE = MERGED` → EXIT `REMEDIATE_RESULT: status: ALREADY_DONE` (nothing to remediate — already landed).
+- `PR_OPEN_STATE = CLOSED` (not merged) → EXIT `REMEDIATE_RESULT: status: BLOCKED`, blocker: "PR #{PR_NUMBER} is closed, not merged — nothing to remediate."
+
+**Resolve the linked issue** (`--issue` flag takes precedence; else parse from the PR body — anchored, matching the `"Closes #N" in:body` precedent from forge#1634/#1646, never a bare-number scan):
+
+```bash
+ISSUE_NUMBER="${ISSUE_NUMBER:-$(echo "$PR_BODY" | grep -oP '(?i)\bCloses #\K\d+' | head -1)}"
+if [ -z "$ISSUE_NUMBER" ]; then
+  echo "BLOCKED: cannot resolve linked issue — pass --issue explicitly"
+  # EXIT REMEDIATE_RESULT: status: BLOCKED, blocker: "cannot resolve linked issue — pass --issue explicitly"
+fi
+```
+
+**Load the linked issue and validate it is a genuine remediation target**:
+
+```bash
+ISSUE_STATE=$(gh issue view {ISSUE_NUMBER} {GH_FLAG} --json labels,state,body,milestone)
+ISSUE_LABELS=$(echo "$ISSUE_STATE" | jq -r '[.labels[].name] | join(",")')
+```
+
+- If `needs-human` is NOT among `ISSUE_LABELS` → EXIT `REMEDIATE_RESULT: status: BLOCKED`, blocker: "issue #{ISSUE_NUMBER} is not `needs-human` — remediation mode only targets `needs-human`-gated PRs; use the normal `/work-on {ISSUE_NUMBER}` resume path instead." This keeps blast radius scoped to exactly the gap this mode fills — it is not a general-purpose re-review trigger.
+
+**Idempotency / resume check** — the paper trail lives on **both** the PR (primary — checked by the orchestrator's item 6.4 dispatch guard) and the linked issue (mirror — keeps `/work-on`'s standard FORGE-annotation trajectory and resume logic consistent with every other phase):
+
+```bash
+PR_REMEDIATION_COMMENT=$(gh api repos/{GH_REPO}/issues/{PR_NUMBER}/comments \
+  --jq '[.[] | select(.body | contains("FORGE:REMEDIATION"))] | last')
+```
+
+- If a comment is found AND its body contains `FORGE:REMEDIATION:COMPLETE` → EXIT `REMEDIATE_RESULT: status: ALREADY_DONE`. **Single-attempt semantics (AC5)**: once a `FORGE:REMEDIATION:COMPLETE` marker exists for this PR, do NOT re-attempt fixes on a subsequent invocation, regardless of the prior verdict — this is what prevents an infinite remediation retry loop on a genuinely-blocked PR.
+- If a comment is found WITHOUT `:COMPLETE` → a prior attempt was interrupted mid-flight (same failure mode as the investigation phase's partial-comment case). Delete the partial comment(s) on both the PR and the issue, then continue below as a fresh attempt:
+  ```bash
+  gh api repos/{GH_REPO}/issues/comments/{PARTIAL_PR_COMMENT_ID} -X DELETE 2>/dev/null || true
+  gh api repos/{GH_REPO}/issues/comments/{PARTIAL_ISSUE_COMMENT_ID} -X DELETE 2>/dev/null || true
+  ```
+- If no comment is found → fresh attempt, continue below.
+
+---
+
+## Phase M1: Load Prior Findings & Classify the Block Reason
+
+Gather everything that caused (or is still causing) `needs-human`:
+
+**M1a — Open review-finding issues spawned from this PR** (same title-match precedent as `review-pr.md` Phase 8B/9A):
+```bash
+FINDINGS=$(gh issue list {GH_FLAG} --state open --label "review-finding" --limit 100 \
+  --json number,title,body \
+  --jq "[.[] | select(.title | test(\"PR #{PR_NUMBER}\"))]")
+```
+
+**M1b — PR review verdicts and merge-block reasons** (Phase 8 of `review-pr.md` records the exact block reason on the linked issue when it aborts auto-merge — read that trail rather than re-deriving it):
+```bash
+BLOCK_COMMENTS=$(gh api repos/{GH_REPO}/issues/{ISSUE_NUMBER}/comments \
+  --jq '[.[] | select(.body | test("Auto-merge aborted|not mergeable|Pre-Push Ancestry Guard Failed|Push Failed|Quality Gate Failed"; "i"))] | last')
+```
+
+**Classify into FIXABLE vs. UNFIXABLE**:
+- **FIXABLE** — open `review-finding` issues (CONFIRMED/LIKELY code defects), a `VERDICT=CHANGES REQUESTED` block with concrete findings attached, a mergeability guard failure (`CONFLICTING`/`DIRTY`/`BLOCKED` — resolvable by rebasing onto `{PR_BASE}`), or a quality-gate/build failure.
+- **UNFIXABLE (policy escalation)** — `HAS_PURPOSE_REGRESSION=true` (the PR's behavior diverges from the issue's intent — a judgment call, not a code defect), `CALIBRATION_NEEDS_HUMAN=true` (statistical trust threshold), or `TRUST_NEEDS_HUMAN=true` (provenance `NOVEL_NEEDS_HUMAN` tier, insufficient prior data — a policy gate, not a bug). None of these are mechanically "fixable" by re-editing code.
+
+**If the block reason classifies as UNFIXABLE** (and no FIXABLE item accompanies it): do NOT attempt any fix. Skip directly to Phase M8 with verdict `UNFIXABLE`, re-affirm `needs-human` (it should already be present), and return `REMEDIATE_RESULT: status: UNFIXABLE`. This satisfies AC5 — "genuinely-blocked PRs still terminate at `needs-human`."
+
+**If at least one FIXABLE item exists**: proceed to Phase M2.
+
+---
+
+## Phase M2: Checkout the PR's Existing Branch
+
+Remediation always fixes forward on top of the PR's existing head commit — never rebase onto a different base and never force-push over the PR's history unless a fix genuinely requires it (e.g. resolving a merge conflict per the mergeability guard case, in which case use `git rebase`/`git merge` onto `origin/{PR_BASE}` exactly as the branch's own commit history would, then `--force-with-lease`).
+
+```bash
+cd {REPO_PATH}
+git fetch origin
+WORKTREE_PATH="{WORKTREE_BASE}/remediate-{HEAD_BRANCH_SLUG}-{PR_NUMBER}"
+if [ -d "{WORKTREE_PATH}" ]; then
+  git -C "{WORKTREE_PATH}" fetch origin
+  git -C "{WORKTREE_PATH}" checkout {HEAD_BRANCH}
+  git -C "{WORKTREE_PATH}" reset --hard "origin/{HEAD_BRANCH}"
+else
+  git worktree add "{WORKTREE_PATH}" {HEAD_BRANCH} "origin/{HEAD_BRANCH}"
+fi
+```
+
+If the worktree/branch checkout fails for any reason (branch deleted, force-pushed out from under us, etc.): post a comment, add `needs-human`, EXIT `REMEDIATE_RESULT: status: BLOCKED`.
+
+---
+
+## Phase M3: Apply Fixes
+
+For each FIXABLE item from Phase M1: read the affected file(s) in `{WORKTREE_PATH}` before editing (never assume current state), apply the fix. Follow the same implementation discipline as `work-on.md` Phase 3F (cross-lane import guard, library-callback verification, deliverable-type consistency, no unrequested scope) — this file does not restate those rules, it inherits them.
+
+**If the block reason was a mergeability conflict** (`CONFLICTING`/`DIRTY`/`BLOCKED`): resolve it by rebasing `{HEAD_BRANCH}` onto `origin/{PR_BASE}` (or merging `{PR_BASE}` in, whichever preserves a clean, reviewable history) — resolve conflicts manually, do not blindly take "ours"/"theirs".
+
+**Quality Gate** (same loop as Phase 3G, max 3 iterations):
+```
+iteration = 0
+while iteration < 3:
+    iteration += 1
+    Skill("quality-gate", args="{CHANGED_FILES} --worktree {WORKTREE_PATH}")
+    if result == "QUALITY GATE: PASS": GATE_PASSED=true; break
+    else: fix each HIGH/MEDIUM finding, re-stage
+```
+If still failing after 3 iterations: post a comment, re-affirm `needs-human`, EXIT `REMEDIATE_RESULT: status: BLOCKED`. Do not proceed to re-review with an unresolved gate failure — that would just re-escalate one phase later with a worse paper trail.
+
+**Format/verify**: run the project's configured `verification.commands` (same as Phase 3H) before committing.
+
+---
+
+## Phase M4: Commit, Push, and Close Addressed Findings
+
+```bash
+cd {WORKTREE_PATH}
+git add -u
+git commit -s -m "fix(remediate): {description} (#{ISSUE_NUMBER})"
+git push origin {HEAD_BRANCH}
+```
+
+If push fails, retry with `--force-with-lease` (expected when M3 rebased to resolve a conflict). If it still fails: post a comment, add `needs-human`, EXIT `REMEDIATE_RESULT: status: BLOCKED`.
+
+**Close each addressed review-finding issue directly** (this remediation fixes findings in-place on the existing PR, rather than each finding spawning its own downstream `/work-on` pipeline — leaving them open would have a future run rediscover already-fixed code). Track the closed numbers in `ADDRESSED_FINDING_NUMBERS[]` — Phase M8 reports this array in the final paper trail:
+```bash
+ADDRESSED_FINDING_NUMBERS=()
+for FINDING_NUM in {FIXABLE_FINDING_NUMBERS_FROM_M1}; do
+  gh issue close "$FINDING_NUM" {GH_FLAG} \
+    --comment "Fixed by remediation of PR #{PR_NUMBER} (commit {COMMIT_SHA}). See #{ISSUE_NUMBER}."
+  ADDRESSED_FINDING_NUMBERS+=("$FINDING_NUM")
+done
+```
+Only close findings actually addressed in this commit — leave any FIXABLE-but-deferred or unrelated open findings untouched.
+
+---
+
+## Phase M5: Post Interim FORGE:REMEDIATION Progress (before re-review)
+
+Post the same body to **both** `{PR_NUMBER}` and `{ISSUE_NUMBER}` (PR copy is the idempotency source of truth; issue copy keeps the standard trajectory/resume logic consistent):
+
+```bash
+gh pr comment {PR_NUMBER} {GH_FLAG} --body "<!-- FORGE:REMEDIATION -->
+## Remediation In Progress for PR #{PR_NUMBER}
+
+**Findings addressed**:
+{bulleted list: finding # — title — one-line fix summary}
+
+**Commit**: {COMMIT_SHA}
+**Quality gate**: {iterations} iteration(s), PASS
+
+Re-invoking \`/review-pr --auto-merge\` now."
+gh issue comment {ISSUE_NUMBER} {GH_FLAG} --body "<!-- FORGE:REMEDIATION -->
+## Remediation In Progress for PR #{PR_NUMBER}
+
+**Findings addressed**:
+{bulleted list: finding # — title — one-line fix summary}
+
+**Commit**: {COMMIT_SHA}
+**Quality gate**: {iterations} iteration(s), PASS
+
+Re-invoking \`/review-pr --auto-merge\` now."
+```
+
+Note the marker is `<!-- FORGE:REMEDIATION -->` with **no** `:COMPLETE` suffix yet — per the marker-presence convention (forge#1360/#1357), the absence of `:COMPLETE` correctly signals "in progress" to any concurrent reader, and the M0 resume check above treats this exact state as an interrupted attempt if a session dies before M8.
+
+---
+
+## Phase M6: Re-Invoke /review-pr
+
+```
+Skill(skill="review-pr", args="{PR_NUMBER} --auto-merge --issue {ISSUE_NUMBER} --base {PR_BASE} --gh-flag {GH_FLAG}")
+```
+
+This re-runs the full review (domain agents → verdict → Phase 8 auto-merge gate). Because `{ISSUE_NUMBER}` still carries `needs-human` at this point, one of two things happens inside `review-pr.md`'s existing, **unedited** Phase 8:
+
+- **Re-escalated**: the re-review itself trips a fresh block (`CHANGES REQUESTED`, purpose-regression, calibration, trust, or a still-`CONFLICTING` mergeability check) → `needs-human` remains set, no merge attempted.
+- **Clean re-review**: `VERDICT=APPROVED`-equivalent, mergeable, and the "Previously-escalated re-review guard" (forge#1810) fires — clearing `needs-human` and setting `workflow:awaiting-merge`, *without* auto-merging (that guard's own safe default, left untouched by this file).
+
+Extract the re-review verdict for the paper trail (Phase M8 reports this verbatim):
+```bash
+RE_REVIEW_VERDICT=$(gh api repos/{GH_REPO}/issues/{PR_NUMBER}/comments \
+  --jq '[.[] | select(.body | test("APPROVED:|CHANGES REQUESTED:"; "i"))] | last | .body // "unknown"' 2>/dev/null | head -c 200)
+```
+
+---
+
+## Phase M7: Compute the #1809 Q1 Auto-Land Bar
+
+Re-read the issue's current labels after M6:
+```bash
+POST_REVIEW_LABELS=$(gh issue view {ISSUE_NUMBER} {GH_FLAG} --json labels --jq '[.labels[].name] | join(",")')
+```
+
+**If `needs-human` is present** (re-escalated case): the bar does not apply — nothing to compute. `RE_GATE_OUTCOME="RE-ESCALATED"`. Skip to Phase M8.
+
+**If `workflow:awaiting-merge` is present** (clean re-review case — the only branch where `review-pr.md`'s guard has already safely parked this PR): compute the bar.
+
+```bash
+REVIEW_BODIES=$(gh pr view {PR_NUMBER} {GH_FLAG} --json reviews,comments \
+  --jq '[.reviews[].body // ""] + [.comments[].body // ""] | .[]')
+APPROVED_COUNT=$(echo "$REVIEW_BODIES" | grep -cE 'APPROVED:' 2>/dev/null || true); APPROVED_COUNT=${APPROVED_COUNT:-0}
+```
+
+**Auto-land bar** (per #1809 Q1) — BOTH conditions required:
+1. `APPROVED_COUNT >= 2` — at least two distinct adversarial `APPROVED:` review comments (same counting convention as `work-on.md` Phase 7A).
+2. `GATE_PASSED = true` from this remediation's own Phase M3 quality-gate loop.
+
+**If the bar is met**:
+```bash
+gh pr merge {PR_NUMBER} {GH_FLAG} --merge
+MERGE_STATE=$(gh pr view {PR_NUMBER} {GH_FLAG} --json state --jq '.state')
+if [ "$MERGE_STATE" = "MERGED" ]; then
+  RESOLUTION=$(resolve_script 'transition-label')
+  TIER="${RESOLUTION%%:*}"; SCRIPT_PATH="${RESOLUTION#*:}"
+  case "$TIER" in
+    adaptive|universal) bash "$SCRIPT_PATH" {ISSUE_NUMBER} {GH_FLAG} merged ;;
+    prose)
+      gh issue edit {ISSUE_NUMBER} {GH_FLAG} --add-label "workflow:merged" \
+        --remove-label "workflow:awaiting-merge,needs-human,workflow:investigating,workflow:ready-to-build,workflow:building,workflow:in-review,workflow:invalid,workflow:decomposed" 2>/dev/null || true
+      ;;
+  esac
+  RE_GATE_OUTCOME="AUTO-LANDED"
+else
+  RE_GATE_OUTCOME="HELD-AWAITING-MERGE"
+  # gh pr merge reported success but the PR isn't actually MERGED — leave workflow:awaiting-merge
+  # in place (unchanged) and let a human merge manually rather than retrying automatically.
+fi
+```
+
+**If the bar is NOT met**: leave the issue at `workflow:awaiting-merge` exactly as `review-pr.md`'s guard set it — do NOT attempt a merge. `RE_GATE_OUTCOME="HELD-AWAITING-MERGE"`. Fail-safe direction: any doubt about the bar defaults to holding, matching `review-pr.md`'s own existing default for every other caller.
+
+---
+
+## Phase M8: Finalize FORGE:REMEDIATION Paper Trail
+
+Post the completion body to **both** `{PR_NUMBER}` and `{ISSUE_NUMBER}` — this is the single idempotency marker checked by Phase M0 (this file, on future resume) and by the orchestrator's item 6.4 dispatch guard:
+
+```bash
+case "$RE_GATE_OUTCOME" in
+  AUTO-LANDED)         AUTO_LAND_BAR_TEXT="MET (${APPROVED_COUNT:-0} APPROVED: reviews + quality gate pass)"; OUTCOME_DETAIL="to {PR_BASE}" ;;
+  HELD-AWAITING-MERGE) AUTO_LAND_BAR_TEXT="NOT MET (${APPROVED_COUNT:-0} APPROVED: reviews)"; OUTCOME_DETAIL="at workflow:awaiting-merge" ;;
+  RE-ESCALATED)        AUTO_LAND_BAR_TEXT="N/A — re-escalated before the bar was evaluated"; OUTCOME_DETAIL="at needs-human" ;;
+  UNFIXABLE)           AUTO_LAND_BAR_TEXT="N/A — unfixable (see Phase M1 classification)"; OUTCOME_DETAIL="at needs-human" ;;
+  *)                   AUTO_LAND_BAR_TEXT="N/A"; OUTCOME_DETAIL="" ;;
+esac
+
+REMEDIATION_BODY="<!-- FORGE:REMEDIATION -->
+## Remediation Complete for PR #{PR_NUMBER}
+
+**Findings addressed**: ${#ADDRESSED_FINDING_NUMBERS[@]} (${ADDRESSED_FINDING_NUMBERS[*]:-none})
+**Re-review verdict**: ${RE_REVIEW_VERDICT:-unknown}
+**Auto-land bar**: ${AUTO_LAND_BAR_TEXT}
+**Re-gate outcome**: ${RE_GATE_OUTCOME} ${OUTCOME_DETAIL}
+
+<!-- FORGE:REMEDIATION:COMPLETE -->"
+
+gh pr comment {PR_NUMBER} {GH_FLAG} --body "$REMEDIATION_BODY"
+gh issue comment {ISSUE_NUMBER} {GH_FLAG} --body "$REMEDIATION_BODY"
+```
+
+**If the outcome was `AUTO-LANDED`**: this Skill invocation is itself the caller's terminal delegate (Phase 0A.1 of `work-on.md` already told its own routing loop to STOP after dispatching here) — so `remediate.md` must drive the close phase itself rather than assume some other inline logic will. Invoke the close subcommand directly, the same way `work-on/review.md` does when it hands off from a spawned sub-agent context:
+
+```
+Skill("work-on:close", args="{ISSUE_NUMBER} --repo {GH_REPO} --gh-flag {GH_FLAG} --pr {PR_NUMBER} --base {PR_BASE}")
+```
+
+`work-on:close` handles project board update, final issue body, parent tracker, trajectory log, and worktree cleanup (including the remediation worktree at `{WORKTREE_PATH}`) — do not duplicate any of that here.
+
+**If the outcome was `HELD-AWAITING-MERGE`, `RE-ESCALATED`, or `UNFIXABLE`**: leave the worktree in place (a human may need it for manual inspection/merge) and return the structured result below without invoking close. Do not close the issue.
+
+---
+
+## Output
+
+Return this structured block to the caller:
+
+```
+REMEDIATE_RESULT:
+  status: COMPLETE | ALREADY_DONE | UNFIXABLE | BLOCKED
+  pr_number: {PR_NUMBER}
+  issue_number: {ISSUE_NUMBER}
+  re_gate_outcome: AUTO-LANDED | HELD-AWAITING-MERGE | RE-ESCALATED | UNFIXABLE | N/A
+  findings_addressed: [{finding_number}, ...]
+  blocker: {description if status=BLOCKED}
+```
+
+**Caller behavior**: this Skill already drives its own close phase when `re_gate_outcome: AUTO-LANDED` (see Phase M8) — the caller does not need to invoke close itself. For every other `re_gate_outcome`, this result is terminal for the current invocation: the issue is left at `needs-human` or `workflow:awaiting-merge`, both already recognized as terminal states in the Universal Phase Dispatcher (see `work-on.md`). Whether invoked standalone (`/work-on <pr> --remediate`) or via the orchestrator's item 6.4 dispatch, no further action is required from the caller.

package/commands/work-on/review.md

@@ -12,7 +12,7 @@ argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree P
 **Invoked by**: `work-on.md` Phase 4–5, after `build/validate.md` returns `GATE_PASSED: true`.
 **Output**: Push branch, create PR, invoke /review-pr --auto-merge, return result to caller.
 
-**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. This file's mechanical bits (label transitions, `FORGE:CHECKPOINT` writes) stay at this tier because they're interleaved with the review/merge-decision steps in the same `Skill()` invocation — see `work-on.md` section "Model and Effort Tiering — What Actually Applies". <!-- Added: forge#1827 -->
 **NEVER use plan mode (EnterPlanMode).**
 
 <!-- FORGE:SPEC_LOADED — work-on/review.md loaded and active. Agent is bound by this spec. -->