forgedock 1.4.0 → 1.5.1

package/commands/review-pr-staging.md

@@ -681,14 +681,32 @@ gh label create "needs-validation" --color "FBCA04" --description "Review findin
 gh label create "staging-review" --color "1D76DB" --description "Finding from a staging branch review before deploy to main. Managed by ForgeDock." --force -R {GH_REPO} 2>/dev/null
 ```
 
-### 7D: Milestone Detection
-Only assign milestone if reviewing a milestone/* branch. Plain staging reviews get no milestone.
+### 7D: Milestone & Code Branch Detection
+
+Derive both `CODE_BRANCH` and `MILESTONE_FLAG` from the reviewed PR before creating any findings. Unlike `commands/review-pr.md` (feature-lane PRs with short-lived HEAD branches that get deleted post-merge — see the rationale comment on that spec's finding template), `review-pr-staging.md` reviews long-lived branches (`staging`, `milestone/*`) that persist after merge, so `CODE_BRANCH` uses `headRefName` (the PR's HEAD — the branch actually being reviewed), consistent with forge#1391's original fix. This replaces the previous hardcoded `staging` literal, which was silently wrong whenever this spec reviewed a `milestone/X → staging` PR instead of a `staging → main` PR — `CODE_BRANCH` used to always say `staging` even when the reviewed branch was `milestone/X`.
+
+```bash
+CODE_BRANCH=$(gh pr view ${PR_NUMBER} --json headRefName --jq '.headRefName')
+MILESTONE_FLAG=""
+
+# scripts/derive-finding-milestone.sh is the single source of truth for
+# milestone derivation — commands/review-pr.md and commands/review-pr-staging.md
+# both call it identically so the two specs cannot independently drift.
+# <!-- forge#2443 -->
+MILESTONE_TITLE=$(bash scripts/derive-finding-milestone.sh "${PR_NUMBER}" -R {GH_REPO})
+# Quoted so multi-word milestone titles survive as a single value wherever
+# MILESTONE_FLAG is later interpolated — matches the quoting convention already
+# used for --title/--body-file/--label below.
+[ -n "$MILESTONE_TITLE" ] && MILESTONE_FLAG="--milestone \"$MILESTONE_TITLE\""
+```
+
+Plain staging→main reviews resolve `CODE_BRANCH` to `staging` dynamically (same value as before, now derived rather than hardcoded) and typically resolve no milestone. A milestone→staging review resolves `CODE_BRANCH` to `milestone/X` and (via the shared script) the matching milestone.
 
 ### 7E: Deduplicate Against Existing Issues
 Check for open review-finding issues at same file:line → skip. Closed issues at same location → potential regression (elevate priority).
 
 ### 7F: Create Issues
-Sequential creation. Title: `Staging Review: {summary} (staging → main)`. Labels: review-finding, needs-validation, staging-review, priority:P1/priority:P2/priority:P3. Body includes: source branch context (`staging`), code context, evidence, validation checklist.
+Sequential creation. Title: `Staging Review: {summary} (staging → main)`. Labels: review-finding, needs-validation, staging-review, priority:P0-P3 (derived from Severity — see below). Body includes: source branch context (`${CODE_BRANCH}`, derived in Phase 7D — not a hardcoded `staging` literal), code context, evidence, validation checklist.
 
 **For each finding** (that passes dedup), create issue through the `/issue` create-hook's programmatic invocation contract (see `commands/issue.md` § "Programmatic Invocation Contract") instead of calling the raw issue-creation command directly:
 ```bash
@@ -716,10 +734,10 @@ Files that need changes:
 
 ## Source Branch Context
 
-**Code branch**: `staging`
-**Worktree base**: `origin/staging`
+**Code branch**: `[CODE_BRANCH]`
+**Worktree base**: `origin/[CODE_BRANCH]`
 
-> When fixing: `git worktree add ../fix-{slug} -b fix/{slug} origin/staging`
+> When fixing: `git worktree add ../fix-{slug} -b fix/{slug} origin/[CODE_BRANCH]`
 
 ## Code Context
 [10 lines around finding]
@@ -733,8 +751,32 @@ Files that need changes:
 - [ ] If VALIDATED: fix implemented and tested on correct branch
 ISSUE_EOF
 
+# STAGING_FINDING_SEVERITY is extracted from the finding's own **Severity**
+# body field (set above in the heredoc) — example assignment shown here for
+# clarity, same convention as STAGING_FINDING_TITLE etc.
+STAGING_FINDING_SEVERITY="LOW"
+
+# priority:* label is a deterministic function of the finding's **Severity**
+# (CRITICAL/HIGH/MEDIUM/LOW) — NEVER of its Confidence
+# (CONFIRMED/LIKELY/POSSIBLE). scripts/severity-to-priority.sh is the single
+# source of truth for this mapping; commands/review-pr.md calls the identical
+# script so the two specs cannot independently drift. <!-- forge#2447 -->
+STAGING_FINDING_PRIORITY=$(bash scripts/severity-to-priority.sh "$STAGING_FINDING_SEVERITY")
+STAGING_FINDING_PRIORITY_EXIT=$?
+
+# Exit code MUST be checked before use — severity-to-priority.sh exits 1 (empty stdout)
+# on a missing/unrecognized severity. Proceeding with an empty $STAGING_FINDING_PRIORITY
+# would call Skill(issue, --label "") instead of aborting issue creation for this finding.
+# Mirrors the identical check in commands/review-pr.md. <!-- forge#2479 -->
+if [ "$STAGING_FINDING_PRIORITY_EXIT" -ne 0 ]; then
+  echo "PRIORITY: severity-to-priority.sh failed (exit $STAGING_FINDING_PRIORITY_EXIT) for severity '$STAGING_FINDING_SEVERITY' — skipping finding issue creation"
+  # Skip this finding — do NOT fall through to issue creation with an empty label
+else
+
 # --label is repeatable (not comma-joined) per the /issue programmatic contract.
-Skill(skill="issue", args="--title \"$STAGING_FINDING_TITLE\" --body-file \"$STAGING_FINDING_BODY_FILE\" --label review-finding --label needs-validation --label staging-review --label \"{priority}\"")
+# ${MILESTONE_FLAG} carries the Phase 7D derivation through — empty string is
+# a no-op arg when the reviewed branch has no milestone (plain staging→main).
+Skill(skill="issue", args="--title \"$STAGING_FINDING_TITLE\" --body-file \"$STAGING_FINDING_BODY_FILE\" --label review-finding --label needs-validation --label staging-review --label \"$STAGING_FINDING_PRIORITY\" ${MILESTONE_FLAG}")
 rm -f "$STAGING_FINDING_BODY_FILE"
 
 # /issue has no machine-readable return contract — resolve the created issue's number by
@@ -746,9 +788,10 @@ for _resolve_attempt in 1 2 3; do
   [ -n "$ISSUE_NUM" ] && break
   sleep 2
 done
+fi
 ```
 
-Labels: `review-finding` + `needs-validation` + `staging-review` + priority (`priority:P1` CONFIRMED, `priority:P2` LIKELY, `priority:P3` POSSIBLE).
+Labels: `review-finding` + `needs-validation` + `staging-review` + priority. `priority:*` is derived from the finding's `**Severity**` field via `scripts/severity-to-priority.sh` (identical script used by `commands/review-pr.md` — single documented mapping, see that script's header comment): `CRITICAL` → `priority:P0`, `HIGH` → `priority:P1`, `MEDIUM` → `priority:P2`, `LOW` → `priority:P3`. **Never derive `priority:*` from Confidence** (CONFIRMED/LIKELY/POSSIBLE) — conflating the two axes previously mislabeled LOW-severity CONFIRMED findings as `priority:P1`, defeating orchestrate's P3 batching rule. <!-- forge#2447 -->
 
 **No pre-filtering**: Every finding becomes an issue. Validation agents sort out false positives downstream.
 

package/commands/review-pr.md

@@ -1626,26 +1626,28 @@ gh label create "false-positive" --color "CCCCCC" --description "Review finding
 
 **Milestone detection:**
 ```bash
-# Check BOTH head and base branches — feature PRs targeting milestone/* branches
-# should inherit the milestone for their review findings
+# BASE_BRANCH is what the finding template stamps as **Code branch** below
+# (see the rationale comment at that template block) — HEAD_BRANCH is no
+# longer needed here; derive-finding-milestone.sh resolves its own
+# base/head branch lookup internally for its Tier 3 slug match.
 BASE_BRANCH=$(gh pr view ${PR_NUMBER} --json baseRefName --jq '.baseRefName')
-HEAD_BRANCH=$(gh pr view ${PR_NUMBER} --json headRefName --jq '.headRefName')
 MILESTONE_FLAG=""
 
-# First check: PR's base branch is a milestone branch (most common for feature-lane PRs)
-MILESTONE_BRANCH=""
-if echo "$BASE_BRANCH" | grep -qE "^milestone/"; then
-    MILESTONE_BRANCH="$BASE_BRANCH"
-elif echo "$HEAD_BRANCH" | grep -qE "^milestone/"; then
-    MILESTONE_BRANCH="$HEAD_BRANCH"
-fi
-
-if [ -n "$MILESTONE_BRANCH" ]; then
-    BRANCH_SLUG=$(echo "$MILESTONE_BRANCH" | sed 's|^milestone/||')
-    MILESTONE_NUMBER=$(gh api repos/${REPO}/milestones 2>/dev/null | jq --arg slug "$BRANCH_SLUG" '.[] | select((.title | ascii_downcase | gsub("[^a-z0-9]+"; "-")) == $slug) | .number' 2>/dev/null | head -1)
-    [ -z "$MILESTONE_NUMBER" ] && MILESTONE_NUMBER=$(gh api repos/${REPO}/milestones 2>/dev/null | jq --arg slug "$BRANCH_SLUG" '.[] | select((.title | ascii_downcase | gsub("[^a-z0-9]+"; "-")) | test($slug)) | .number' 2>/dev/null | head -1)
-    [ -n "$MILESTONE_NUMBER" ] && MILESTONE_FLAG="--milestone $(gh api repos/${REPO}/milestones/${MILESTONE_NUMBER} --jq '.title')"
-fi
+# scripts/derive-finding-milestone.sh is the single source of truth for
+# milestone derivation — commands/review-pr.md and commands/review-pr-staging.md
+# both call it identically so the two specs cannot independently drift the
+# way they did before this fix (forge#2443 Instance B/C: findings from a
+# milestone-lane PR sometimes inherited the milestone and sometimes didn't,
+# depending on incidental inheritance rather than an explicit step). The
+# script's 3-tier resolution (PR's own milestone -> originating issue's
+# milestone via Closes/Fixes/Resolves #N -> branch-slug match against
+# milestone/* branches) supersedes the old base/head-branch-only slug match
+# that used to be hand-rolled here.
+MILESTONE_TITLE=$(bash scripts/derive-finding-milestone.sh "${PR_NUMBER}" -R "${REPO}")
+# Quoted so multi-word milestone titles (e.g. "Watch & Fleet Observability") survive
+# as a single value wherever MILESTONE_FLAG is later interpolated — matches the
+# quoting convention already used for --title/--body-file/--label below.
+[ -n "$MILESTONE_TITLE" ] && MILESTONE_FLAG="--milestone \"$MILESTONE_TITLE\""
 ```
 
 **Dedup against existing issues (MANDATORY before creating):**
@@ -1763,10 +1765,26 @@ Files that need changes:
 
 ## Source Branch Context
 
-**Code branch**: `[HEAD_BRANCH]`
-**Worktree base**: `origin/[HEAD_BRANCH]`
-
-> When fixing: `git worktree add ../fix-{slug} -b fix/{slug} origin/[HEAD_BRANCH]`
+<!--
+  BASE_BRANCH, not HEAD_BRANCH, is correct here (forge#2443). This looks like
+  a revert of forge#1391 ("review-finding template stamps BASE_BRANCH instead
+  of HEAD_BRANCH — fixes target wrong code state") but is NOT: forge#1391's
+  scenario was a staging->main review where HEAD (staging) is a long-lived
+  branch that already had the bug's code, while BASE (main) had not yet
+  received it. review-pr.md's scenario is different — HEAD here is a
+  short-lived feat/*|fix/* branch that Phase 6E deletes once the auto-merge
+  step completes, which happens SYNCHRONOUSLY within this same /review-pr run,
+  before any downstream consumer (a human, or /work-on) ever reads this
+  finding. By the time the finding is read, HEAD no longer exists but BASE
+  does, and BASE now contains the merged code the finding is about.
+  commands/review-pr-staging.md keeps HEAD_BRANCH semantics (as a dynamic
+  ${CODE_BRANCH}, not a hardcoded literal) because ITS reviewed branches
+  (staging, milestone/*) are long-lived — consistent with forge#1391.
+-->
+**Code branch**: `[BASE_BRANCH]`
+**Worktree base**: `origin/[BASE_BRANCH]`
+
+> When fixing: `git worktree add ../fix-{slug} -b fix/{slug} origin/[BASE_BRANCH]`
 
 ## Code Context
 [10 lines around finding]
@@ -1785,8 +1803,30 @@ Files that need changes:
 [BATCHABLE_ANNOTATION]
 ISSUE_EOF
 
+# FINDING_SEVERITY is extracted from the finding's own **Severity** body field
+# (set above in the heredoc) — example assignment shown here for clarity, same
+# convention as FINDING_ISSUE_TITLE etc.
+FINDING_SEVERITY="LOW"
+
+# priority:* label is a deterministic function of the finding's **Severity**
+# (CRITICAL/HIGH/MEDIUM/LOW) — NEVER of its Confidence
+# (CONFIRMED/LIKELY/POSSIBLE). scripts/severity-to-priority.sh is the single
+# source of truth for this mapping; commands/review-pr-staging.md calls the
+# identical script so the two specs cannot independently drift. <!-- forge#2447 -->
+FINDING_PRIORITY=$(bash scripts/severity-to-priority.sh "$FINDING_SEVERITY")
+FINDING_PRIORITY_EXIT=$?
+
+# Exit code MUST be checked before use — severity-to-priority.sh exits 1 (empty stdout)
+# on a missing/unrecognized severity, mirroring the DEDUP_EXIT idiom above. Proceeding
+# with an empty $FINDING_PRIORITY would call Skill(issue, --label "") instead of aborting
+# issue creation for this finding. <!-- forge#2479 -->
+if [ "$FINDING_PRIORITY_EXIT" -ne 0 ]; then
+  echo "PRIORITY: severity-to-priority.sh failed (exit $FINDING_PRIORITY_EXIT) for severity '$FINDING_SEVERITY' — skipping finding issue creation"
+  # Skip this finding — do NOT fall through to issue creation with an empty label
+else
+
 # --label is repeatable (not comma-joined) per the /issue programmatic contract.
-Skill(skill="issue", args="--title \"$FINDING_ISSUE_TITLE\" --body-file \"$FINDING_ISSUE_BODY_FILE\" --label review-finding --label needs-validation --label \"{priority}\" ${MILESTONE_FLAG}")
+Skill(skill="issue", args="--title \"$FINDING_ISSUE_TITLE\" --body-file \"$FINDING_ISSUE_BODY_FILE\" --label review-finding --label needs-validation --label \"$FINDING_PRIORITY\" ${MILESTONE_FLAG}")
 rm -f "$FINDING_ISSUE_BODY_FILE"
 
 # /issue has no machine-readable return contract (it's a user-facing command, not a work-on
@@ -1799,15 +1839,16 @@ for _resolve_attempt in 1 2 3; do
   [ -n "$ISSUE_NUM" ] && break
   sleep 2
 done
+fi
 ```
 
-Labels: `review-finding` + `needs-validation` + priority (`priority:P1` CONFIRMED, `priority:P2` LIKELY, `priority:P3` POSSIBLE).
+Labels: `review-finding` + `needs-validation` + priority. `priority:*` is derived from the finding's `**Severity**` field via `scripts/severity-to-priority.sh` (single documented mapping — see that script's header comment): `CRITICAL` → `priority:P0`, `HIGH` → `priority:P1`, `MEDIUM` → `priority:P2`, `LOW` → `priority:P3`. **Never derive `priority:*` from Confidence** (CONFIRMED/LIKELY/POSSIBLE) — Confidence and Severity are independent axes; conflating them previously mislabeled LOW-severity CONFIRMED findings as `priority:P1`, defeating the P3 batching rule below. <!-- forge#2447 -->
 
-**P3 batchable annotation** — <!-- Added: forge#1333 --> When priority resolves to `priority:P3` (POSSIBLE confidence), check whether the finding qualifies for batching. If the affected file does NOT touch a security or billing path, substitute `[BATCHABLE_ANNOTATION]` with the `<!-- FORGE:BATCHABLE -->` marker. This signals the orchestrator's Phase 1 batching rule that this finding can be grouped with other P3s in the same domain:
+**P3 batchable annotation** — <!-- Added: forge#1333 --> When priority resolves to `priority:P3` (i.e. `**Severity**: LOW`), check whether the finding qualifies for batching. If the affected file does NOT touch a security or billing path, substitute `[BATCHABLE_ANNOTATION]` with the `<!-- FORGE:BATCHABLE -->` marker. This signals the orchestrator's Phase 1 batching rule that this finding can be grouped with other P3s in the same domain:
 
 ```bash
 # Determine batchable eligibility for this finding
-FINDING_PRIORITY="{priority}"  # priority:P1 / priority:P2 / priority:P3
+# $FINDING_PRIORITY was already computed above (severity-to-priority.sh) — reuse it, do not re-derive.
 BATCHABLE_ANNOTATION=""
 
 if [ "$FINDING_PRIORITY" = "priority:P3" ]; then
@@ -2089,19 +2130,41 @@ if [ "$PRE_MERGE_HEALTH" = "CONFLICTING" ] || [ "$PRE_MERGE_HEALTH_STATE" = "DIR
     # STOP — do not attempt gh pr merge on a CONFLICTING/DIRTY PR
 else
 
-# Previously-escalated re-review guard <!-- Added: forge#1810 -->
+# Previously-escalated re-review guard <!-- Added: forge#1810; base-scoped: forge#2570 -->
 # If the linked issue currently carries needs-human, this PR was escalated at some
 # earlier point (VERDICT/purpose-regression/calibration/trust/mergeability) and has
 # now been remediated + re-reviewed back to a clean, mergeable APPROVED state above.
-# The "auto-land bar" (≥2 independent adversarial approvals + domain gates — see
-# #1809 Q1) is not yet implemented (future #1809 sub-issues B/C/D), so the safe
-# default here is to land on workflow:awaiting-merge (clearing needs-human) rather
-# than silently auto-merging a PR that was once flagged human-risk.
+#
+# forge#2570: the hold is now scoped by the PR's target branch. This PR still transitions
+# to workflow:awaiting-merge (clearing needs-human) in BOTH cases below — the transition is
+# unchanged; only who acts next differs:
+#   - `main` / deploy gate (or an unresolved base — fail closed): held for a HUMAN merge
+#     decision, because `staging → main` is the genuine human gate no agent performs.
+#   - any other base (staging, milestone/* — reversible integration branches): NOT held for
+#     a human. It is parked for remediate.md Phase M7's base-scoped auto-land bar (bot APPROVED
+#     + quality-gate pass), which merges it on the SAME condition the normal /work-on fast lane
+#     uses for the same target branch — no manual click. This reconciles the asymmetry where a
+#     bot-only re-review (authorAssociation=NONE) could never satisfy the strict ≥2 verified-
+#     human bar and so stranded staging PRs the fast lane would auto-merge.
 PREVIOUSLY_ESCALATED=$(gh issue view {MERGE_ISSUE} {MERGE_GH_FLAG} --json labels \
   --jq '[.labels[].name] | any(. == "needs-human")' 2>/dev/null || echo "false")
+GUARD_BASE=$(gh pr view {PR_NUMBER} {MERGE_GH_FLAG} --json baseRefName --jq '.baseRefName' 2>/dev/null || echo "")
 
 if [ "$PREVIOUSLY_ESCALATED" = "true" ]; then
-    gh issue comment {MERGE_ISSUE} {MERGE_GH_FLAG} --body "🟠 PR #{PR_NUMBER} was previously escalated (\`needs-human\`) and has now been re-reviewed to \`${VERDICT:-APPROVED}\` with a clean mergeability check. The automated auto-land bar for previously-escalated PRs is not yet implemented, so this PR is held at \`workflow:awaiting-merge\` for a human merge decision instead of auto-merging. Merge manually once reviewed: \`gh pr merge {PR_NUMBER} {MERGE_GH_FLAG} --merge\`."
+    # forge#2625: `jq -r '.baseRefName'` stringifies a JSON null to the literal text "null" (not
+    # an empty string), so the `-n` check alone does not catch it — add an explicit `!= "null"`
+    # check so a literal-string "null" is treated the same as an empty/unresolved base (strict).
+    if [ -n "$GUARD_BASE" ] && [ "$GUARD_BASE" != "null" ] && [ "$GUARD_BASE" != "main" ]; then
+      # forge#2570: non-`main` base — defer to remediate.md M7's auto-land, not a human.
+      # forge#2626: standalone `/review-pr` (no remediate.md M6→M7 chain) would otherwise
+      # strand this PR at `workflow:awaiting-merge` with no actionable guidance — add a
+      # manual-merge fallback so the comment is correct in both the chained and standalone cases.
+      # GOVERNOR-exempt: intentional coordination side-effect (best-effort lease/board/finding post), DRY_RUN-safe — reviewed & accepted for the check-command-side-effects gate. Flagged only by the staging->main full-diff; passes on every feature PR. forge#2627
+      gh issue comment {MERGE_ISSUE} {MERGE_GH_FLAG} --body "🟠 PR #{PR_NUMBER} was previously escalated (\`needs-human\`) and has now been re-reviewed to \`${VERDICT:-APPROVED}\` with a clean mergeability check on non-\`main\` base \`${GUARD_BASE}\`. It is parked at \`workflow:awaiting-merge\` for the remediation auto-land bar (\`remediate.md\` Phase M7, forge#2570) — which auto-merges it on the same fast-lane condition the normal \`/work-on\` path uses for this target branch — NOT for a human merge decision. If no remediation \`M7\` follows (e.g. this review was invoked standalone), merge manually once reviewed: \`gh pr merge {PR_NUMBER} {MERGE_GH_FLAG} --merge\`."
+    else
+      # forge#2570: `main` / deploy gate (or unresolved base — fail closed to the human gate).
+      gh issue comment {MERGE_ISSUE} {MERGE_GH_FLAG} --body "🟠 PR #{PR_NUMBER} was previously escalated (\`needs-human\`) and has now been re-reviewed to \`${VERDICT:-APPROVED}\` with a clean mergeability check. This PR targets the deploy gate (\`${GUARD_BASE:-unresolved base}\`), so it is held at \`workflow:awaiting-merge\` for a human merge decision — \`staging → main\` is the genuine human gate. Merge manually once reviewed: \`gh pr merge {PR_NUMBER} {MERGE_GH_FLAG} --merge\`."
+    fi
     RESOLUTION=$(resolve_script 'transition-label')
     TIER="${RESOLUTION%%:*}"; SCRIPT_PATH="${RESOLUTION#*:}"
     case "$TIER" in
@@ -2111,7 +2174,9 @@ if [ "$PREVIOUSLY_ESCALATED" = "true" ]; then
           --remove-label "needs-human,workflow:investigating,workflow:ready-to-build,workflow:building,workflow:in-review,workflow:merged,workflow:invalid,workflow:decomposed" 2>/dev/null || true
         ;;
     esac
-    # STOP — do not attempt gh pr merge; a human decides the merge from here
+    # STOP — do not attempt gh pr merge here. The merge decision belongs to a human for a
+    # `main`/deploy-gate base, or to remediate.md Phase M7's base-scoped auto-land bar for a
+    # non-`main` base (forge#2570). Either way this guard only parks at workflow:awaiting-merge.
 else
     # Checkpoint comment on issue
     gh issue comment {MERGE_ISSUE} {MERGE_GH_FLAG} --body "Review complete for PR #{PR_NUMBER}. Verdict: ${VERDICT:-APPROVED}. Proceeding to merge."

package/commands/work-on/build/architect.md

@@ -29,7 +29,7 @@ COMPLEXITY_BAND=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
 COMPLEXITY_BAND="${COMPLEXITY_BAND:-STANDARD}"
 ```
 
-**If COMPLEXITY_BAND: TRIVIAL** → skip all phases (A0 through A5), post NO comment, return empty plan to caller immediately. Do not read any files. This is not an error — trivial single-file changes have no cross-path consistency risk. <!-- Added: forge#679 -->
+**If COMPLEXITY_BAND: TRIVIAL** → skip all phases (A0 through A5), **post the minimal skip marker comment described in "Skip Marker" under Skip Conditions below** (reason: `TRIVIAL complexity band`), then return an empty plan to caller immediately. Do not read any files. This is not an error — trivial single-file changes have no cross-path consistency risk. The skip marker (ending in `<!-- FORGE:ARCHITECT:COMPLETE -->`) is what makes a legitimate skip observable to the headless engine's marker-only gate, so the issue advances to build instead of being stranded at `needs-human`. <!-- Added: forge#679; skip-marker on skip: forge#2689 -->
 
 **If COMPLEXITY_BAND: STANDARD or COMPLEX** → proceed to Phase A0 below.
 
@@ -668,14 +668,39 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:ARCHITECT -->
 
 ## Skip Conditions
 
-Skip this entire step (post nothing, return empty plan to caller) if:
+Skip the planning work (Phases A0–A5) and return an empty plan to caller — **but always post the Skip Marker below first** — if:
 - **COMPLEXITY_BAND: TRIVIAL** — checked via FORGE:FAST_PATH comment at entry (see guard above) <!-- Primary skip path: forge#679 -->
 - Issue creates only **new files** with no callers to find (e.g. a new command file with no existing integration point yet)
 - Issue is a 1-file config or docs edit with no code logic
 - Issue title starts with "docs:" or "chore:"
 - `{AFFECTED_FILES}` is empty
 
-When skipped, the builder proceeds with investigation report + context briefing only.
+When skipped, the builder proceeds with investigation report + context briefing only (see Integration Point below — the builder falls back gracefully on an empty plan).
+
+### Skip Marker (MANDATORY on every skip — do NOT post nothing) <!-- forge#2689 -->
+
+**Do not post nothing.** The headless engine gate (`bin/engine/phases.mjs` → `architect.detectOutcome`) treats a **missing** `FORGE:ARCHITECT:COMPLETE` sentinel as a phase **failure**, retries to `maxAttempts` (3), then strands the issue at `needs-human`. It reads GitHub comment markers only — it cannot see this subcommand's in-process "empty plan" return value. So a skip that posts no marker is indistinguishable from a crashed architect run and deterministically strands **every** `chore:`/`docs:`/trivial issue.
+
+On **every** skip branch above, post exactly this minimal comment (substitute the concrete `{SKIP_REASON}`, e.g. `chore:/docs: title`, `TRIVIAL complexity band`, `new files only — no callers`, or `AFFECTED_FILES empty`) **before** returning the empty plan:
+
+```bash
+# The skip marker is mandatory and un-gated by design — posting it IS the point
+# (a missing marker strands the issue at needs-human; see above). Same report-only
+# risk class as the unguarded plan post in "Output Format" above, so it carries the
+# same allowlist rather than a DRY_RUN guard.
+SKIP_BODY=$(cat <<SKIP_EOF
+<!-- FORGE:ARCHITECT -->
+## Architecture Plan — Skipped
+
+**Skipped**: {SKIP_REASON}. No cross-path consistency risk — the builder proceeds with the investigation report + context briefing.
+
+<!-- FORGE:ARCHITECT:COMPLETE -->
+SKIP_EOF
+)
+gh issue comment {NUMBER} {GH_FLAG} --body "$SKIP_BODY" # <!-- allowlist:check-command-side-effects -->
+```
+
+The empty-plan-with-marker changes no downstream behavior — the builder already falls back to the investigation report + contract when the plan is empty (see Integration Point below). The marker only makes the legitimate skip **observable** to the marker-only engine gate. This intentionally does **not** weaken crash detection: a genuinely interrupted architect run still posts no marker at all, so `detectOutcome` still fails-and-escalates it correctly.
 
 ---
 

package/commands/work-on/remediate.md

@@ -255,11 +255,51 @@ REVIEW_BODIES=$(gh pr view {PR_NUMBER} {GH_FLAG} --json reviews,comments \
 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:
+**Auto-land bar — base-branch scoped** (forge#2570): the condition the PR must clear to auto-land depends on its target branch. This reconciles the remediation bar with the normal `/work-on` fast-lane merge bar for the *same target branch*, while keeping the strict human-verified bar only where a human is genuinely in the loop (the `staging → main` deploy gate).
+
+**Re-derive the base fresh — do NOT reuse `$PR_BASE` for this decision** (forge#2624): `$PR_BASE` was resolved in Phase M0 as `PR_BASE="${PR_BASE:-$(... .baseRefName)}"` — a caller-supplied `--base` wins over the PR's actual live base whenever non-empty. That is fine for M0's own purposes (worktree base, display text), but this is a security-relevant decision point: a wrong/stale `--base staging` on a PR that actually targets `main` must never be allowed to relax the strict deploy-gate bar. Mirror `review-pr.md`'s sibling guard (`GUARD_BASE`, which always re-fetches `baseRefName` fresh at its own decision point) by re-querying the PR's live base here, independent of whatever `$PR_BASE` currently holds:
+
+```bash
+# forge#2624: re-fetch baseRefName fresh from the PR itself — never trust the
+# M0-resolved $PR_BASE for this decision, since M0 prefers a caller-supplied
+# --base over the live value. This is the one line in this phase that makes
+# a trust/security decision, so it must be immune to a caller-overridable input.
+LIVE_BASE_REF=$(gh pr view {PR_NUMBER} {GH_FLAG} --json baseRefName --jq '.baseRefName' 2>/dev/null || echo "")
+
+# forge#2570: `main` (and any deploy-gate base) keeps the strict #1809 Q1 verified-human bar;
+# every other base (staging, milestone/* — the reversible integration branches) reconciles to
+# the fast-lane bar. Key on "is the deploy gate", NOT the literal string "staging", so milestone
+# branches reconcile too. Fail closed: only a KNOWN, non-empty, non-`main` LIVE base reconciles
+# to the fast lane; an empty/unresolved fetch is treated as the deploy gate (strict) so a base-
+# resolution failure (or a caller passing a stale/incorrect --base) can never accidentally
+# relax the bar.
+# forge#2625: `jq -r '.baseRefName'` stringifies a JSON null to the literal text "null" (not an
+# empty string), so the `-n` check alone does not catch it — add an explicit `!= "null"` check
+# so a literal-string "null" is treated the same as an empty/unresolved base (strict).
+if [ -n "$LIVE_BASE_REF" ] && [ "$LIVE_BASE_REF" != "null" ] && [ "$LIVE_BASE_REF" != "main" ]; then IS_DEPLOY_GATE=false; else IS_DEPLOY_GATE=true; fi
+```
+
+**Non-`main` base (`IS_DEPLOY_GATE=false` — staging / milestone)** — reconcile to the fast-lane bar. `review-pr.md`'s Phase 8 guard only parks a PR at `workflow:awaiting-merge` after a clean, mergeable `APPROVED` re-review (the same bot-`APPROVED` signal the normal fast lane auto-merges on), so the only additional condition is this remediation's own quality gate:
+1. `GATE_PASSED = true` from this remediation's Phase M3 quality-gate loop.
+
+The strict `APPROVED_COUNT >= 2` verified-human requirement does NOT apply here: it is structurally unsatisfiable for bot-only pipeline review (bot reviews are `authorAssociation=NONE`), and `staging` is reversible — the real human gate is `staging → main`, which no agent performs. This makes the remediation bar identical to the normal fast-lane bar for the same target branch (the issue's core ask). The `authorAssociation` trust filter above is **unchanged** — the relaxation is scoped by *target branch only*, never by *who* may approve (forge#1976/#2519).
+
+**`main` base (`IS_DEPLOY_GATE=true` — deploy gate)** — keep the strict #1809 Q1 bar, BOTH conditions required:
 1. `APPROVED_COUNT >= 2` — at least two distinct adversarial `APPROVED:` review comments from repo collaborators (`OWNER`/`MEMBER`/`COLLABORATOR` authorAssociation only — see trust filter above; 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**:
+**Evaluate the base-scoped bar**:
+```bash
+if [ "$IS_DEPLOY_GATE" = "true" ]; then
+  # main / deploy gate — strict verified-human bar
+  { [ "${APPROVED_COUNT:-0}" -ge 2 ] && [ "${GATE_PASSED:-false}" = "true" ]; } && BAR_MET=true || BAR_MET=false
+else
+  # staging / milestone — fast-lane bar (bot APPROVED already implied by workflow:awaiting-merge)
+  [ "${GATE_PASSED:-false}" = "true" ] && BAR_MET=true || BAR_MET=false
+fi
+```
+
+**If the bar is met** (`BAR_MET=true`):
 ```bash
 gh pr merge {PR_NUMBER} {GH_FLAG} --merge
 MERGE_STATE=$(gh pr view {PR_NUMBER} {GH_FLAG} --json state --jq '.state')
@@ -281,7 +321,7 @@ else
 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.
+**If the bar is NOT met** (`BAR_MET=false`): 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 (including an unresolved or unexpected `LIVE_BASE_REF`, which leaves `IS_DEPLOY_GATE=true`-equivalent strict handling) defaults to holding, matching `review-pr.md`'s own existing default for every other caller.
 
 ---
 
@@ -291,7 +331,16 @@ Post the completion body to **both** `{PR_NUMBER}` and `{ISSUE_NUMBER}` — this
 
 ```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}" ;;
+  AUTO-LANDED)
+    # forge#2570: the bar that was met differs by target branch. Non-`main` (staging/milestone)
+    # lands on the fast-lane bar (clean re-review APPROVED + quality-gate pass), identical to the
+    # normal /work-on path; `main`/deploy-gate lands only on the strict ≥2 verified-human bar.
+    if [ "${IS_DEPLOY_GATE:-true}" = "false" ]; then
+      AUTO_LAND_BAR_TEXT="MET — fast-lane bar for non-\`main\` base (clean re-review APPROVED + quality gate pass), matching the normal /work-on merge bar for the same target branch"
+    else
+      AUTO_LAND_BAR_TEXT="MET (${APPROVED_COUNT:-0} APPROVED: reviews + quality gate pass)"
+    fi
+    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" ;;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "Autonomous dev pipeline for Claude Code. GitHub as institutional memory — every issue, PR, and annotation survives context resets and makes the next agent smarter.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"

package/packages/protocol/src/validate.js

@@ -6,7 +6,7 @@
  * Checks:
  *   - Completion sentinel presence (§3.2) — for types that define one
  *   - Required field presence (§4.1 per-type field tables)
- *   - Required field enum values (Verdict, Confidence, Severity, Task Type)
+ *   - Required field enum values (Verdict, Confidence, Severity, Task Type, Re-gate outcome)
  *   - Inline-value non-empty (§3.4)
  *   - CARD inline-value decodability + sha8 integrity (§4.2 — see card.js)
  *   - Partial sentinel marking (§3.3) — generates a warning, not an error
@@ -129,5 +129,28 @@ export function validate(annotation) {
     }
   }
 
+  // REMEDIATION-specific enum validation (forge#2450): the Re-gate outcome field is
+  // optional at the required-field-presence layer (it is absent until
+  // commands/work-on/remediate.md's Phase M8 posts it), but when present its value
+  // must come from the single-sourced registry list — not a second hardcoded copy.
+  //
+  // Phase M8 posts this field as "**Re-gate outcome**: ${RE_GATE_OUTCOME} ${OUTCOME_DETAIL}"
+  // (see commands/work-on/remediate.md), so the parsed field value carries trailing free-text
+  // detail (e.g. "AUTO-LANDED to staging"), not just the bare outcome token. Only the leading
+  // token is the actual outcome — extract it the same way bin/engine/phases.mjs's own
+  // `/\*\*Re-gate outcome\*\*:\s*([A-Z-]+)/` regex does, so real production annotations with
+  // trailing detail text are not falsely rejected.
+  if (type === 'REMEDIATION') {
+    const reGateOutcome = fields['Re-gate outcome'];
+    if (reGateOutcome) {
+      const outcomeToken = reGateOutcome.match(/^([A-Z-]+)/)?.[1] ?? reGateOutcome;
+      if (!typeDef.reGateOutcomeValues.includes(outcomeToken)) {
+        errors.push(
+          `Invalid Re-gate outcome "${outcomeToken}" — must be one of: ${typeDef.reGateOutcomeValues.join(', ')}`,
+        );
+      }
+    }
+  }
+
   return { valid: errors.length === 0, errors, warnings };
 }

package/scripts/build-knowledge-index.mjs

@@ -48,7 +48,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, appendFileSync, rea
 import { execSync, spawnSync } from 'child_process';
 import { homedir } from 'os';
 import { dirname, join, resolve } from 'path';
-import { fileURLToPath } from 'url';
+import { fileURLToPath, pathToFileURL } from 'url';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -309,7 +309,11 @@ async function getParser() {
   const parsePath = join(repoRoot, 'packages', 'protocol', 'src', 'parse.js');
 
   try {
-    const mod = await import(parsePath);
+    // On win32 a bare absolute path (C:\...) makes Node parse the drive letter as a
+    // URL scheme (ERR_UNSUPPORTED_ESM_URL_SCHEME). Convert to a file:// URL first —
+    // valid on POSIX too, and matches the import(pathToFileURL(...).href) idiom used
+    // at check-admission-parity.mjs / validate-annotation-node.mjs / check-phase-registry-drift.mjs.
+    const mod = await import(pathToFileURL(parsePath).href);
     _parseAnnotation = mod.parse;
     return _parseAnnotation;
   } catch (e) {

package/scripts/check-phase-registry-drift.mjs

@@ -69,6 +69,28 @@ async function main() {
     process.exit(1);
   }
 
+  // Verify every id in PHASE_IDS has a corresponding key in PHASE_MARKERS.
+  // The empty-marker check below iterates Object.entries(PHASE_MARKERS), which
+  // only visits keys that actually exist on the object — a phase id that is
+  // entirely absent from PHASE_MARKERS (as opposed to present-but-empty) never
+  // appears in that iteration, so it would pass silently here and only surface
+  // later as a runtime TypeError in bin/engine/phases.mjs (e.g.
+  // `PHASE_MARKERS.someId.completionMarker` on an undefined `someId` entry).
+  // Catch that gap explicitly before the empty-marker check below.
+  const phaseMarkers = registryModule.PHASE_MARKERS || {};
+  const missingKeys = registryIds.filter(
+    (id) => !Object.prototype.hasOwnProperty.call(phaseMarkers, id)
+  );
+  if (missingKeys.length > 0) {
+    console.error(
+      `ERROR: PHASE_MARKERS is missing an entry entirely for: ${missingKeys.join(", ")}`
+    );
+    console.error(
+      "  Add a corresponding key to packages/protocol/src/phases.js's PHASE_MARKERS for each id above."
+    );
+    process.exit(1);
+  }
+
   // Also verify every registry marker entry that has a `completionMarker` or
   // `completionLabel` field is a non-empty string — catches an accidental
   // undefined/null slipping in (e.g. a typo'd RESERVED_TYPES key whose
@@ -76,7 +98,7 @@ async function main() {
   // has(blob, undefined) → substring "undefined" never matches, masking a
   // real bug as "phase never completes".
   const emptyMarkers = [];
-  for (const [phaseId, entry] of Object.entries(registryModule.PHASE_MARKERS || {})) {
+  for (const [phaseId, entry] of Object.entries(phaseMarkers)) {
     const marker = entry.completionMarker ?? entry.completionLabel;
     if (typeof marker !== "string" || marker.length === 0) {
       emptyMarkers.push(phaseId);

package/scripts/check-spec-markers.sh

@@ -117,6 +117,8 @@ MARKER_REGISTRY="
   KNOWLEDGE_GIST
   LEARNED
   LEARNED_RULES
+  LEASE
+  LEASE_RELEASED
   LEDGER_INDEXED
   MEMORY_INDEX
   MEMORY_INDEXED

package/scripts/classify-lane.sh

@@ -70,10 +70,15 @@ if ! [[ "$ISSUE_NUMBER" =~ ^[0-9]+$ ]]; then
   exit 1
 fi
 
-# Fetch milestone title from GitHub
-# gh issue view exits non-zero if the issue does not exist or auth fails
+# Fetch milestone title (and labels, for the review-finding staging-default
+# note below) from GitHub in a single call — gh issue view exits non-zero if
+# the issue does not exist or auth fails. Labels are fetched here rather
+# than via a second `gh issue view` call so this stays one round trip, same
+# failure surface as before this field was added. <!-- Added: forge#2443 -->
 GH_STDERR_TMP=$(mktemp)
-MILESTONE_TITLE=$(gh issue view "$ISSUE_NUMBER" "${GH_REPO_ARGS[@]}" --json milestone --jq '.milestone.title // empty' 2>"$GH_STDERR_TMP") || {
+chmod 600 "$GH_STDERR_TMP"
+trap 'rm -f "$GH_STDERR_TMP"' EXIT
+ISSUE_JSON=$(gh issue view "$ISSUE_NUMBER" "${GH_REPO_ARGS[@]}" --json milestone,labels 2>"$GH_STDERR_TMP") || {
   echo "ERROR: failed to fetch issue #$ISSUE_NUMBER — check issue number and repo flag" >&2
   cat "$GH_STDERR_TMP" >&2
   rm -f "$GH_STDERR_TMP"
@@ -81,6 +86,9 @@ MILESTONE_TITLE=$(gh issue view "$ISSUE_NUMBER" "${GH_REPO_ARGS[@]}" --json mile
 }
 rm -f "$GH_STDERR_TMP"
 
+MILESTONE_TITLE=$(echo "$ISSUE_JSON" | jq -r '.milestone.title // empty')
+HAS_REVIEW_FINDING_LABEL=$(echo "$ISSUE_JSON" | jq -r '[.labels[]?.name] | any(. == "review-finding")')
+
 # Resolve staging branch name from forge.yaml (branches.staging), defaulting to "staging".
 # Uses yq if available; falls back gracefully when forge.yaml is absent or yq is not installed.
 STAGING_BRANCH=$(yq '.branches.staging // "staging"' forge.yaml 2>/dev/null || echo 'staging')
@@ -104,6 +112,24 @@ if [ -z "$MILESTONE_TITLE" ]; then
     echo "       Run: git push origin HEAD:$STAGING_BRANCH  (from the default branch)" >&2
     exit 1
   fi
+  # Defense-in-depth visibility (forge#2443): a review-finding issue with no
+  # milestone defaults to the staging fast lane here — which is correct ONLY
+  # when the finding's subject code actually lives on staging. For a finding
+  # spawned from a milestone-lane PR whose body is missing **Code branch**
+  # and whose milestone wasn't propagated, this default silently routes the
+  # fix to the one branch where the code is guaranteed absent, causing
+  # /work-on's investigation phase to close it as invalid. This script has
+  # no way to know whether that mismatch applies to THIS issue (it only
+  # knows the issue has no milestone) — the note below is diagnostic only,
+  # non-fatal, so callers relying on stdout are unaffected.
+  # WIRE:PROVEN — manual: ran classify-lane.sh against a fake `gh issue view`
+  # returning labels:[{"name":"review-finding"}] and milestone:null; confirmed
+  # the NOTE lines below print to stderr while stdout stays unaffected.
+  if [ "$HAS_REVIEW_FINDING_LABEL" = "true" ]; then
+    echo "NOTE: issue #$ISSUE_NUMBER is a review-finding with no milestone — defaulting to staging fast lane ('$STAGING_BRANCH')." >&2
+    echo "      If this finding's subject code only exists on a milestone branch, this default is WRONG." >&2
+    echo "      See commands/orchestrate/phase-4-execution.md Step 4C for the repair/loud-failure guard." >&2
+  fi
   if [ "$JSON_OUTPUT" = "true" ]; then
     printf '{"lane":"%s","branch":"%s","source":"fast-lane","milestone":null}\n' \
       "$STAGING_BRANCH" "$STAGING_BRANCH"