forgedock 1.3.0 → 1.5.0

package/commands/work-on/review.md

@@ -47,10 +47,49 @@ gh pr list {GH_FLAG} --head {BRANCH} --json number,state,url 2>/dev/null
 ```
 
 **Resume check**:
-- If PR already exists AND is OPEN → skip to Phase R3 (invoke /review-pr)
+- If PR already exists AND is OPEN → run the **HEAD-unchanged re-review guard** below before proceeding to Phase R3
 - If PR already exists AND is MERGED → return `REVIEW_RESULT: status: ALREADY_MERGED`
 - If no `<!-- FORGE:BUILDER -->` comment exists → EXIT with `REVIEW_RESULT: status: BLOCKED`, blocker: "FORGE:BUILDER comment not found — implement phase may not have completed"
 
+**HEAD-unchanged re-review guard** (MANDATORY when a PR already exists and is OPEN) <!-- Added: forge#2243 --> — a PR whose most recent review verdict was CHANGES REQUESTED must not be resubmitted for a full domain-agent review fan-out if nothing has changed since that verdict. `/review-pr` records the exact commit it reviewed in its verdict comment (`CHANGES REQUESTED: commit {sha} — ...`, see `commands/review-pr.md` Phase 8/9); compare that recorded sha against the PR's current `headRefOid`:
+
+```bash
+# NOTE: the CHANGES REQUESTED verdict is posted via `gh pr review --comment` (see
+# commands/review-pr.md Phase 7B) — that creates a PullRequestReview, which surfaces under
+# the `reviews` field, NOT `comments` (issue/PR comments are a separate GraphQL object).
+# Query both --json reviews and --json comments (same combined-read pattern already used in
+# work-on.md's REVIEW_BODIES/REVIEW_PRESENT checks) so this guard works regardless of which
+# GitHub object type carries the verdict text.
+LAST_VERDICT=$(gh pr view {PR_NUMBER} {GH_FLAG} --json reviews,comments \
+  --jq '([.reviews[] | {body, created_at: (.submittedAt // "")}] + [.comments[] | {body, created_at: (.createdAt // "")}]) | map(select(.body | test("CHANGES REQUESTED: commit "))) | sort_by(.created_at) | last | .body // ""' 2>/dev/null)
+LAST_VERDICT_SHA=$(echo "$LAST_VERDICT" | grep -oE 'CHANGES REQUESTED: commit [0-9a-f]+' | grep -oE '[0-9a-f]+$' | head -1)
+CURRENT_SHA_SHORT=$(gh pr view {PR_NUMBER} {GH_FLAG} --json headRefOid --jq '.headRefOid' 2>/dev/null | cut -c1-7)
+
+if [ -n "$LAST_VERDICT_SHA" ] && [ "$LAST_VERDICT_SHA" = "$CURRENT_SHA_SHORT" ]; then
+  echo "HEAD unchanged since last CHANGES REQUESTED verdict ($LAST_VERDICT_SHA) — skipping re-review."
+  # No DRY_RUN/governor guard here — consistent with every other gh issue comment/edit call
+  # already in this file (e.g. the Push Failed / Push Blocked sections below), none of which
+  # are gated either. This is a report-and-stop action (blocks re-review, does not merge or
+  # delete anything), same risk class as those pre-existing calls.
+  REREVIEW_SKIP_BODY=$(cat <<SKIP_EOF
+## Re-Review Skipped — HEAD Unchanged
+
+PR #{PR_NUMBER}'s HEAD (${CURRENT_SHA_SHORT}) has not changed since the last CHANGES REQUESTED verdict. Re-running /review-pr would re-review byte-identical code and reproduce the same verdict — this is a pure waste of a full domain-agent fan-out.
+
+The PR is already needs-human (or will be shortly, if this is the first time this guard has fired for it). Progress here now depends on remediation (fix the findings, push a new commit, re-review) rather than another raw review submission. If running under /orchestrate, item 6.4 in phase-4-execution.md auto-dispatches remediation for any needs-human-gated issue, including this one (see forge#2243) — no manual action should be needed. If running standalone, invoke /work-on {PR_NUMBER} --remediate --issue {NUMBER} directly.
+
+<!-- FORGE:REREVIEW_SKIPPED -->
+SKIP_EOF
+)
+  gh issue comment {NUMBER} {GH_FLAG} --body "$REREVIEW_SKIP_BODY" # <!-- allowlist:check-command-side-effects -->
+  gh issue edit {NUMBER} {GH_FLAG} --add-label needs-human 2>/dev/null || true # <!-- allowlist:check-command-side-effects -->
+  # Return REVIEW_RESULT: status: BLOCKED — do not invoke /review-pr again on unchanged HEAD
+  exit 1
+fi
+```
+
+If `LAST_VERDICT_SHA` is empty (no prior CHANGES REQUESTED verdict found) or differs from the current HEAD (a new commit was pushed since the last verdict — e.g. by remediation), proceed normally to Phase R3.
+
 ---
 
 ## Phase R1: Pre-Push Ancestry Guard

package/commands/work-on.md

@@ -247,6 +247,8 @@ Extract project prefix and issue number. If `next`/`pick`: list open issues sort
 
 ### 0A.1: Remediation Mode Detection (`--remediate`) <!-- Added: forge#1813 -->
 
+**Engine coverage** (forge#2379): `remediate` is now a registered phase in the headless engine's phase table (`packages/protocol/src/phases.js`, `bin/engine/phases.mjs`) — see `commands/work-on/remediate.md`'s own "Engine coverage" note for the current, documented limitation (a single continuous headless `runIssue()` walk cannot yet reach it; this prose-layer standalone-invocation path below remains the only way `remediate` actually runs today).
+
 **Check first, before any other Phase 0 routing** — if `$ARGUMENTS` contains `--remediate`, this is NOT a normal issue-pipeline invocation. The first positional argument is a **PR number**, not an issue number:
 
 ```bash
@@ -524,9 +526,9 @@ a hard dependency.
 
 ## Phase 1: Investigation
 
-**Skip if**: `<!-- FORGE:INVESTIGATOR -->` exists with `<!-- INVESTIGATION:COMPLETE -->` in the SAME comment.
+**Skip if**: `<!-- FORGE:INVESTIGATOR -->` exists with `<!-- INVESTIGATION:COMPLETE -->` OR `<!-- INVESTIGATION:INVALID -->` in the SAME comment. `INVESTIGATION:INVALID` is the terminal sentinel Phase 1C emits for an INVALID verdict (see 1C below) — it signals investigation completion just as much as `INVESTIGATION:COMPLETE` does, not an interrupted state.
 
-**Partial investigation**: If investigator comment exists BUT `<!-- INVESTIGATION:COMPLETE -->` is ABSENT → investigation was interrupted. Delete the partial comment and restart:
+**Partial investigation**: If investigator comment exists BUT NEITHER `<!-- INVESTIGATION:COMPLETE -->` NOR `<!-- INVESTIGATION:INVALID -->` is present → investigation was interrupted. Delete the partial comment and restart:
 ```bash
 COMMENT_ID=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
   --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .id')
@@ -686,9 +688,18 @@ Use `forge.yaml → review.tech_stack` and the issue domain labels to identify e
 
 ### 1C: Post investigation comment
 
-The comment MUST include `<!-- INVESTIGATION:COMPLETE -->` at the very end.
+The comment MUST include a terminal sentinel at the very end. **The sentinel is conditional on the resolved Verdict — it is NOT always `<!-- INVESTIGATION:COMPLETE -->`:**
+
+- **Verdict is INVALID** → close with `<!-- INVESTIGATION:INVALID -->`. This is a distinct, already-wired-up terminal marker: `bin/engine/phases.mjs`'s `detectOutcome` for the `investigate` phase checks for it explicitly (ahead of `INVESTIGATION:COMPLETE`) and routes to `terminalReason: "invalid"`; `bin/hooks/interactive-engine.mjs`'s `PHASE_MARKERS` table also already treats it as terminal. Emitting `INVESTIGATION:COMPLETE` for an INVALID verdict is what previously caused every completed investigation to read as `{verdict: "CONFIRMED"}` regardless of actual outcome — do NOT regress this (forge#2350).
+- **Verdict is CONFIRMED or PARTIAL** → close with `<!-- INVESTIGATION:COMPLETE -->` as before (PARTIAL still routes to `ready-to-build` below — only INVALID gets the distinct terminal sentinel).
 
 ```bash
+if [ "{VERDICT}" = "INVALID" ]; then
+  INVESTIGATION_SENTINEL="<!-- INVESTIGATION:INVALID -->"
+else
+  INVESTIGATION_SENTINEL="<!-- INVESTIGATION:COMPLETE -->"
+fi
+
 gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:INVESTIGATOR -->
 ## Investigation Report
 
@@ -728,9 +739,11 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:INVESTIGATOR -->
 **{YES|NO}** — {reason}
 {if YES: proposed sub-issues with titles and dependencies}
 
-<!-- INVESTIGATION:COMPLETE -->"
+${INVESTIGATION_SENTINEL}"
 ```
 
+**Do not hardcode `<!-- INVESTIGATION:COMPLETE -->` as the closing line.** The closing line MUST be the `${INVESTIGATION_SENTINEL}` variable computed above — it resolves to `<!-- INVESTIGATION:INVALID -->` for an INVALID verdict and `<!-- INVESTIGATION:COMPLETE -->` otherwise. `INVESTIGATION:COMPLETE` and `INVESTIGATION:INVALID` are mutually exclusive within a single posted comment — never emit both.
+
 ### 1D: Correction capture (MANDATORY — run before label update)
 
 Before routing, scan all non-agent comments for correction signals from the repository owner. Correction signals are owner comments that contain phrases like "no, use", "actually use", "use X instead", "not X, use Y", or "wrong branch". If found, write the correction to `forge.yaml → learned:` and emit a `FORGE:LEARNED` annotation.
@@ -890,6 +903,8 @@ gh issue close {NUMBER} {GH_FLAG} --comment "Closing as invalid: {reason from in
 
 ## Phase 2: Decomposition (Conditional)
 
+**Engine coverage** (forge#2379): this phase's dispatch target (`work-on/decompose`) is now a real phase in the headless engine's phase table — `decompose` in `packages/protocol/src/phases.js`/`bin/engine/phases.mjs`, live-wired so `investigate`'s `DECOMPOSE:YES` outcome hands off to it instead of terminating the run in place. This prose Phase 2 remains the interactive/prose dispatch path; the engine path is the headless equivalent, both invoking the same `commands/work-on/decompose.md` subcommand.
+
 **Skip if**: Already decomposed, is a sub-issue, or investigation says decompose: NO.
 
 **Trigger if**: Investigation assessment says YES — 2+ signals match (at least 1 Strong): multiple task types, 3+ service groups, phased requirements, 6+ files across directories.

package/docs/CONFIG.md

@@ -48,6 +48,8 @@ If you have both a local `claude` CLI and `ANTHROPIC_API_KEY` set and want to pi
 | [`agents`](#agents-optional) | No | Default model for pipeline agents |
 | [`repos`](#repos-optional) | No | Multi-repository routing |
 | [`project_board`](#project_board-optional) | No | GitHub Projects v2 integration |
+| [`orchestration`](#orchestration-optional) | No | `/orchestrate` concurrency and cascade admission policy |
+| [`pipeline`](#pipeline-optional) | No | `/orchestrate` batch-engine tuning (stall detection, token budget, narration) |
 | [`services`](#services-optional) | No | External service URLs and IDs |
 | [`review`](#review-optional) | No | Context injected into review agents |
 | [`devdocs`](#devdocs-optional) | No | Devdocs knowledge tree path |
@@ -290,6 +292,124 @@ gh project field-list <project_number> --owner <owner> --format json \
 
 ---
 
+## `orchestration` (OPTIONAL)
+
+Concurrency limits and cascade admission policy for `/orchestrate`'s batch engine. Previously read at runtime (`orchestration.max_concurrent`) but undocumented; this section is the first place it — and the newer `cascade` sub-section (forge#2234) — are formally specified.
+
+```yaml
+orchestration:
+  # Maximum number of /work-on sub-agents dispatched concurrently. Guards against
+  # saturating the Anthropic API rate limit in one burst on a large ready set.
+  # Default: 12.
+  max_concurrent: 12
+
+  cascade:
+    # Named preset expanding to the granular keys below. Any granular key set
+    # explicitly overrides just that field — the preset supplies defaults, not
+    # hard values. Default: "balanced".
+    #   all          — admit everything: no generation cap, no token cap, every
+    #                  heuristic-based defer disabled. For a maintainer draining
+    #                  a backlog who wants /orchestrate to "pick up everything."
+    #   balanced     — the pre-#2234 hardcoded behavior, unchanged: generation
+    #                  cap at 1 (i.e. cascade-spawned findings deferred),
+    #                  900000-token per-batch ceiling, idle/keyword/same-file
+    #                  heuristics all active.
+    #   conservative — same admission shape as balanced, with a lower
+    #                  (450000) token ceiling for cost-sensitive or noisy repos.
+    policy: "balanced"
+
+    # Maximum cascade generation depth admitted. Generation 1 = an original
+    # issue (not spawned from a review-finding). Generation 2 = spawned from a
+    # review-finding. Generation 3 = spawned from a finding that was itself
+    # spawned from a review-finding. Accepts a positive integer or the literal
+    # string "unlimited". Governs Phase 1 resolve-time admission only (the
+    # `cascade`/`review-findings`/`findings` resolution in phase-1-resolve.md)
+    # — it does NOT relax Step 4C's absolute autonomous-cascade defer, which
+    # stays hardcoded regardless of this value (see phase-4-execution.md Step
+    # 4C rule 1). This is what makes "admit gen-2, stop at gen-3" expressible,
+    # which the pre-#2234 --allow-gen2 flag (all-or-nothing) could not say.
+    # Default: 1 (from the "balanced" preset); "unlimited" under "all".
+    max_generation: 1
+
+    # Per-batch token ceiling for Step 4C's review-finding cascade dispatch.
+    # New home for the same lever previously read only as
+    # `pipeline.token_budget_per_batch` (kept working as a deprecated alias —
+    # see the `pipeline` section below). Accepts a positive integer or
+    # "unlimited". Default: 900000 (from "balanced"); 450000 under
+    # "conservative"; "unlimited" under "all".
+    token_budget: 900000
+
+    # Whether a fully human-gated original batch (forge#1814's
+    # BATCH_FULLY_GATED — every original-batch issue DONE/FAILED/GATED with at
+    # least one GATED) suppresses further cascade-finding dispatch. Default:
+    # true (from "balanced"); false under "all".
+    defer_on_batch_gated: true
+
+    # Whether the comment/typo title-keyword heuristic defers P3-and-below
+    # cascade findings. Default: true (from "balanced"); false under "all".
+    keyword_heuristic: true
+
+    # Whether a P3 finding sharing a file with the active batch is deferred
+    # (avoids serializing agents on same-file predecessor edges). Default:
+    # true (from "balanced"); false under "all".
+    p3_same_file_defer: true
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `max_concurrent` | integer | No | Max concurrent `/work-on` sub-agent dispatch. Default: 12 |
+| `cascade.policy` | string | No | `all` \| `balanced` \| `conservative`. Default: `balanced` |
+| `cascade.max_generation` | integer or `"unlimited"` | No | Max cascade generation admitted at Phase 1 resolve time. Default: 1 |
+| `cascade.token_budget` | integer or `"unlimited"` | No | Per-batch token ceiling for Step 4C cascade dispatch. Default: 900000 (deprecated alias: `pipeline.token_budget_per_batch`) |
+| `cascade.defer_on_batch_gated` | boolean | No | Suppress cascade dispatch when the original batch is fully human-gated. Default: `true` |
+| `cascade.keyword_heuristic` | boolean | No | Defer P3-and-below comment/typo-titled findings. Default: `true` |
+| `cascade.p3_same_file_defer` | boolean | No | Defer P3 findings sharing a file with the active batch. Default: `true` |
+
+**Hard invariant — not configurable**: safety exclusions (findings whose `## Problem` section indicates security/billing/anti-bot/auth concerns) are never batched and never auto-admitted by any `cascade.policy`, including `all`. That exclusion is enforced upstream of this section (the P3 batching eligibility check) and has no corresponding key here by design.
+
+**CLI overrides**: `--policy`, `--max-generation`, `--token-budget` on `/orchestrate` take precedence over these keys for a single invocation — see `commands/orchestrate/config.md` → "Cascade Policy CLI Flags".
+
+**Commands that use this section**: `orchestrate`
+
+---
+
+## `pipeline` (OPTIONAL)
+
+Tuning knobs for `/orchestrate`'s batch engine — stall detection, narration verbosity, and (deprecated alias only, see `orchestration.cascade` above) the review-finding cascade token budget. All keys optional; sane defaults apply when omitted.
+
+```yaml
+pipeline:
+  # Minutes an agent may sit idle (no FORGE:HEARTBEAT / label change) before
+  # /orchestrate's stall detector treats it as stuck and attempts an
+  # auto-resume. Default: 15.
+  stall_timeout_minutes: 15
+
+  # Deprecated alias for orchestration.cascade.token_budget (forge#2234) — kept
+  # working so existing configs are unaffected. When both are set,
+  # orchestration.cascade.token_budget wins. Default: 900000.
+  token_budget_per_batch: 900000
+
+  # Estimated token cost of a single P3-or-lower review-finding /work-on
+  # pipeline, used to decrement the token budget above. Default: 150000.
+  token_estimate_per_finding: 150000
+
+  # Narration verbosity for /orchestrate's per-completion status updates.
+  # "terse" (default): one line per completion. "verbose": adds a running
+  # per-completion recap table. Cosmetic only — never changes which phases run.
+  narration: "terse"
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `stall_timeout_minutes` | integer | No | Idle minutes before the stall detector attempts auto-resume. Default: 15 |
+| `token_budget_per_batch` | integer | No | **Deprecated** — use `orchestration.cascade.token_budget`. Default: 900000 |
+| `token_estimate_per_finding` | integer | No | Estimated tokens per P3-or-lower cascade finding. Default: 150000 |
+| `narration` | string | No | `terse` \| `verbose`. Default: `terse` |
+
+**Commands that use this section**: `orchestrate`
+
+---
+
 ## `services` (OPTIONAL)
 
 External service endpoints and identifiers. Used by analytics and monitoring commands.

package/docs/spec/eval-run-result.md

@@ -27,7 +27,9 @@ Each headless run of a single corpus issue produces one JSON object:
   "interventionCount": 0,       // integer — number of human interventions (see below)
 
   // Optional fields (nullable — do NOT block on missing upstream data)
-  "cost": null,                 // null | number — token/USD cost; null until #1255 lands
+  "cost": null,                 // null | number — total billed tokens (input + output); null when
+                                 // the run reports no usage data (e.g. CLI backend, or an errored
+                                 // run). NOT a USD amount — no per-model pricing table exists yet.
   "iterations": 23,             // integer — tool-use loop iteration count
   "stopReason": "end_turn",     // string — Anthropic stop_reason or "max_iterations"
   "error": null,                // null | string — error message when status === "error"
@@ -109,7 +111,8 @@ a scorecard in the format consumed by `scripts/eval-gate-scorecard.mjs` (#1286):
   "mean_wall_clock_ms": 38200,    // number | null — arithmetic mean wall-clock
   "median_wall_clock_ms": 35000,  // number | null — median wall-clock
   "total_intervention_count": 1,  // integer — sum of interventionCount across all runs
-  "cost": null,                   // null | number — sum of per-run cost; null if any run has cost: null
+  "cost": null,                   // null | number — sum of per-run billed-token counts (not USD);
+                                   // null if any run has cost: null
   "run_mode": "full",             // "full" | "subset"
   "spec_sha": "abc123"            // string | null — git SHA of commands/ at run time
 }
@@ -128,8 +131,9 @@ hangs and crashes, not just logic failures.
    `wallClockMs`, `interventionCount`) or non-integer/non-string values cause
    exit code 1 (validation error).
 3. **Cost is nullable**: if any run has `cost: null`, the scorecard's
-   `cost` is `null`. The field becomes numeric only when every run reports a
-   real cost value (post-#1255).
+   `cost` is `null`. The field becomes numeric once every run reports a
+   billed-token count (see the per-run `cost` field above — this is a
+   token-count sum, not a USD amount).
 4. **Rate consistency**: `success_rate_pct` is always computed as
    `round(successful_runs / issues_run * 100, 2)`. The CI gate (#1286) validates
    this computed value matches the reported value.

package/docs/spec/label-state-machine.md

@@ -19,9 +19,12 @@ See also: [FORGE Annotation Protocol §6](forge-protocol-v1.md#6-label-state-mac
 | `workflow:invalid` | Issue closed as invalid | Investigator agent |
 | `workflow:decomposed` | Issue decomposed into sub-issues | Decomposer agent |
 | `needs-human` | Pipeline blocked, human intervention required | Any agent on error |
+| `workflow:engine-error` | Pipeline blocked by the engine/tool itself breaking (CLI crash, missing SDK/API key, exhausted retries with no attempt ever reaching a real outcome) — not a genuine content-level judgment call | `terminate()` in `bin/engine.mjs` |
 
 `workflow:awaiting-merge` vs `needs-human`: both are terminal (the pipeline stops advancing the issue automatically), but they mean different things. `needs-human` means the pipeline hit a condition it cannot resolve on its own (genuinely blocked — conflicting PR, failed verdict, calibration/trust escalation, etc.) and a human must diagnose and act. `workflow:awaiting-merge` means the opposite: the PR was previously escalated to `needs-human`, has since been remediated and re-reviewed to a clean `APPROVED` verdict with no mergeability blockers, but does not yet meet the automated auto-land bar (see forge#1809 Q1) — a human only needs to click merge, not diagnose a problem. `scripts/transition-label.sh` only clears `needs-human` (best-effort) when the target state is `workflow:awaiting-merge` — every other forward transition leaves a pre-existing `needs-human` label untouched, preserving its sticky/terminal semantics.
 
+`workflow:engine-error` vs `needs-human` (taxonomy split — commit `90376f5` / #2261): before this commit, `terminate()` wrote `needs-human` for *every* exhausted-retry blocked outcome, including cases where the engine/CLI tool itself was breaking (crash, missing API key, no SDK) rather than a genuine human-judgment call. As of `90376f5`, `runPhaseWithRetry()` tags an outcome `engine-error` when every exhausted attempt failed via a thrown runner exception (never reached `detectOutcome()`) — the engine/tool is broken, not the issue content — and `terminate()` writes `workflow:engine-error` instead of `needs-human` for that case. A genuine content-level block (unmerged PR, unresolved branch, a fixed-point zero-commits case) still writes `needs-human` unchanged. **Consequence for downstream consumers**: any dashboard, query, or health metric that counts `needs-human` issues computed a different, larger population before `90376f5` than after — a subset of what used to be `needs-human` now shows up as `workflow:engine-error` instead. This is a one-time taxonomy discontinuity, not a real change in pipeline reliability; consumers tracking `needs-human` counts over time should also track `workflow:engine-error` from this commit forward to get a like-for-like comparison. `bin/labels.json` already includes `workflow:engine-error` in this repo; syncing it to consumer/satellite repos is tracked separately (see forge#2346).
+
 ## Transitions
 
 ```
@@ -35,8 +38,13 @@ See also: [FORGE Annotation Protocol §6](forge-protocol-v1.md#6-label-state-mac
   → workflow:invalid [TERMINAL] [Any phase: closed as invalid]
   → workflow:decomposed [TERMINAL] [Phase 2: split into sub-issues]
   → needs-human     [TERMINAL]  [Any phase: pipeline blocked]
+  → workflow:engine-error [TERMINAL] [Any phase: the engine/tool itself broke — CLI crash, missing API key, no SDK — not a content-level judgment call]
 ```
 
+**`workflow:invalid` after `ready-to-build`/`building`/`in-review`** (#2326): the enforcement hook (`bin/hooks/pre-tool-use.mjs`) allows `workflow:invalid` as a successor of these three states — not only of `workflow:investigating` — because invalidity is sometimes only discovered during architecture planning or build, once the actual code/tests are read (see #2312). This is gated, not unconditional: the hook requires a posted reversal comment already on the issue — a second `FORGE:INVESTIGATOR` annotation carrying `**Verdict**: INVALID` — before it allows the transition through. A bare relabel with no evidence trail is still blocked. `workflow:investigating → workflow:invalid` remains evidence-free (Phase 1D's normal path).
+
+The reversal comment must also carry a trusted `authorAssociation` — `OWNER`, `MEMBER`, or `COLLABORATOR` (#2332). Marker+verdict text alone is forgeable by any commenter on a public issue with no repo write access; the hook additionally requires GitHub's own `authorAssociation` classification on that comment (returned by `gh issue view --json comments` at no extra cost) to be one of those three tiers. This check is deliberately identity-agnostic rather than a hardcoded bot-login allowlist, so it survives the pipeline's `gh` identity rotating between accounts (#1722) without needing to be updated.
+
 ## Terminal Labels
 
 Processing stops when any of these labels is set:
@@ -46,6 +54,7 @@ Processing stops when any of these labels is set:
 - `workflow:decomposed`
 - `workflow:awaiting-merge`
 - `needs-human`
+- `workflow:engine-error`
 
 ## Label Exclusivity
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "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"
@@ -46,7 +46,7 @@
     "README.md"
   ],
   "scripts": {
-    "test": "node --test \"bin/tests/**/*.test.mjs\" \"packages/protocol/test/**/*.test.mjs\"",
+    "test": "node --test \"bin/tests/**/*.test.mjs\" \"bin/engine/**/*.test.mjs\" \"packages/protocol/test/**/*.test.mjs\"",
     "docs:dev": "vitepress dev docs/site",
     "docs:build": "vitepress build docs/site",
     "docs:preview": "vitepress preview docs/site"

package/packages/protocol/src/emit.js

@@ -12,6 +12,7 @@
  */
 
 import { RESERVED_TYPES, RESERVED_TYPE_NAMES } from './types.js';
+import { escapeHtmlCommentDelimiters } from './html-comment-escape.js';
 
 // A folded field/inline value that is itself (whole, trimmed) shaped like a FORGE
 // opening tag or a generic sentinel line has no legitimate reason to look that way —
@@ -40,7 +41,9 @@ const NEWLINE_RE = /\r\n|\r|\n/g;
  *      subsequent lines including the completion sentinel, and treats a literal
  *      `-->` as ending the enclosing comment early, leaking the remainder as
  *      visible rendered text. Both directions of the delimiter pair must be
- *      escaped. (forge#1594, forge#1638)
+ *      escaped. (forge#1594, forge#1638) Delegated to the shared
+ *      `escapeHtmlCommentDelimiters()` helper (forge#2225) so this scheme has a
+ *      single implementation shared with `bin/engine/state.mjs`.
  *
  * As defense in depth, if a value still folds down to a line that is itself a
  * bare FORGE tag/sentinel shape, emit() rejects it outright rather than silently
@@ -56,27 +59,7 @@ function sanitizeFieldValue(rawValue) {
       `emit(): field value resolves to a bare FORGE tag/sentinel line, which is not permitted: ${JSON.stringify(rawValue)}`,
     );
   }
-  // Escape "&" FIRST, before either delimiter-escape pass below. Without this,
-  // a value that already contains literal entity-like text (e.g. "<!--&gt;"
-  // or "&lt;!--") collides with the encoded form of an unrelated real
-  // delimiter — sanitizeFieldValue() would not be injective, and the
-  // collision is unrecoverable by unescapeFieldValue() on decode
-  // (forge#2137). Escaping "&" first guarantees every "&lt;!--"/"--&gt;"/
-  // "--!&gt;" sequence in the output was produced by *this* pass, never by
-  // pre-existing entity text (which is now doubly-escaped, e.g.
-  // "&" -> "&amp;", left untouched by the delimiter passes that only match
-  // literal "<!--"/"--"+">" character sequences).
-  const withAmpEscaped = folded.replace(/&/g, '&amp;');
-  // Escape the HTML comment opener ("<!--") so a value cannot start a new
-  // unterminated HTML comment in GitHub's renderer, which would visually swallow
-  // subsequent lines — the same rendering-leak the closer escaping below prevents
-  // from the opposite direction. (forge#1638)
-  const withOpenerEscaped = withAmpEscaped.replace(/<!--/g, '&lt;!--');
-  // Escape both HTML comment-close forms ("-->" and "--!>") — only replacing the
-  // literal character sequence (not just documenting the risk) prevents the
-  // enclosing comment from terminating early. (forge#1594; the FORGE:STATE codec
-  // in bin/engine/state.mjs now mirrors this full three-form scheme — forge#2119)
-  return withOpenerEscaped.replace(/--(!)?>/g, (_, bang) => `--${bang || ''}&gt;`);
+  return escapeHtmlCommentDelimiters(folded);
 }
 
 /**

package/packages/protocol/src/html-comment-escape.js

@@ -0,0 +1,68 @@
+/**
+ * Shared HTML-comment-delimiter escape/unescape pair for the FORGE annotation
+ * wire format.
+ *
+ * This scheme is used by two independent callers that must agree byte-for-byte:
+ *   - `packages/protocol/src/emit.js` / `parse.js` (per-field-value escaping)
+ *   - `bin/engine/state.mjs` (whole-JSON-payload escaping for the FORGE:STATE
+ *     compact-index block)
+ *
+ * Extracting it here removes the drift vector between those two call sites —
+ * they previously hand-duplicated this exact regex chain, kept in sync only by
+ * cross-referencing code comments, and had already drifted once (forge#1638's
+ * fix was applied to `emit.js` before `state.mjs` caught up in forge#2119).
+ *
+ * @license MIT
+ */
+
+/**
+ * Escape the three HTML comment delimiter forms so a payload/value can never
+ * open or close an HTML comment in GitHub's renderer:
+ *   - `<!--`         the comment opener — an unescaped opener would start a new
+ *     (nested-looking) comment, visually swallowing subsequent content.
+ *   - `-->` and `--!>`  the two comment-close forms browsers/HTML parsers
+ *     honour. An unescaped closer could end the enclosing comment early,
+ *     leaking the remainder as visible rendered text (CodeQL js/bad-tag-filter).
+ *
+ * The `&` escape MUST run first, before either delimiter-escape pass. Without
+ * it, a value that already contains literal entity-like text (e.g. `<!--&gt;`
+ * or `&lt;!--`) collides with the encoded form of an unrelated real delimiter —
+ * the encoder would not be injective, and the collision is unrecoverable on
+ * decode (forge#2137). Escaping `&` first guarantees every `&lt;!--`/`--&gt;`/
+ * `--!&gt;` sequence in the output was produced by *this* pass, never by
+ * pre-existing entity text (which is now doubly-escaped, e.g.
+ * `&` -> `&amp;`, left untouched by the delimiter passes that only match the
+ * literal `<!--`/`--`+`>` character sequences).
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+export function escapeHtmlCommentDelimiters(value) {
+  return value
+    .replace(/&/g, '&amp;')
+    .replace(/<!--/g, '&lt;!--')
+    .replace(/--(!)?>/g, (_, bang) => `--${bang || ''}&gt;`);
+}
+
+/**
+ * Inverse of {@link escapeHtmlCommentDelimiters}. Restores `--&gt;`, `--!&gt;`,
+ * `&lt;!--`, then `&amp;` — in that order.
+ *
+ * Unescape order matters: the closer forms are restored first (most-specific
+ * `--!&gt;` before `--&gt;`) so a dangling `!` is never left behind, then the
+ * opener is restored. The `&amp;` -> `&` unescape MUST run LAST (mirroring the
+ * encode side running it FIRST) so it never touches the `&` that is part of a
+ * just-restored `<!--`/`-->`/`--!>` sequence (forge#2137; forge#1662 — parse()
+ * previously failed to apply the exact inverse of emit()'s escape, corrupting
+ * round-trips).
+ *
+ * @param {string} raw
+ * @returns {string}
+ */
+export function unescapeHtmlCommentDelimiters(raw) {
+  return raw
+    .replace(/--!&gt;/g, '--!>')
+    .replace(/--&gt;/g, '-->')
+    .replace(/&lt;!--/g, '<!--')
+    .replace(/&amp;/g, '&');
+}

package/packages/protocol/src/index.js

@@ -30,6 +30,7 @@ export { validate } from './validate.js';
 export { emit, emitPartial, isKnownType } from './emit.js';
 export { RESERVED_TYPES, RESERVED_TYPE_NAMES, Category, SentinelState } from './types.js';
 export { canonicalJson, toBase64url, encodeCard, decodeCardInlineValue } from './card.js';
+export { PHASE_IDS, PHASE_MARKERS } from './phases.js';
 
 /**
  * @typedef {Object} ParsedAnnotation

package/packages/protocol/src/parse.js

@@ -17,6 +17,7 @@
  */
 
 import { RESERVED_TYPES, RESERVED_TYPE_NAMES, SentinelState } from './types.js';
+import { unescapeHtmlCommentDelimiters } from './html-comment-escape.js';
 
 // Matches: <!-- FORGE:TYPE --> or <!-- FORGE:TYPE: value -->
 // Anchored to require the tag to be the ENTIRE (trimmed) line — a FORGE-tag-shaped
@@ -119,17 +120,15 @@ function escapeRegExp(str) {
  * on decode is what makes the scheme injective: any pre-existing entity-like
  * text in the original value (e.g. `&lt;!--` or `<!--&gt;`) is doubly-escaped
  * at encode time and can never collide with the single-escaped form produced
- * by a real delimiter (forge#2137; forge#1662).
+ * by a real delimiter (forge#2137; forge#1662). Delegated to the shared
+ * `unescapeHtmlCommentDelimiters()` helper (forge#2225) so this scheme has a
+ * single implementation shared with `bin/engine/state.mjs`.
  *
  * @param {string} raw
  * @returns {string}
  */
 function unescapeFieldValue(raw) {
-  return raw
-    .replace(/--!&gt;/g, '--!>')
-    .replace(/--&gt;/g, '-->')
-    .replace(/&lt;!--/g, '<!--')
-    .replace(/&amp;/g, '&');
+  return unescapeHtmlCommentDelimiters(raw);
 }
 
 /**

package/packages/protocol/src/phases.js

@@ -0,0 +1,105 @@
+/**
+ * Canonical FORGE pipeline phase table — single source of truth for phase ids
+ * (in dispatch order) and the exact marker/label strings that indicate each
+ * phase has committed.
+ *
+ * Consumers: `bin/engine/phases.mjs` (the authoritative engine gate) and
+ * `bin/hooks/interactive-engine.mjs` (the interactive-session SubagentStop
+ * hook) both import this module instead of hand-declaring their own copies
+ * of the marker strings. Before this module existed, the two files carried
+ * independent literal copies of the same strings and drifted out of sync at
+ * least twice (forge#1669 established the strict `:COMPLETE` gate for
+ * `context`/`architect`; forge#2375/PR#2395 then had to hand-patch the hook's
+ * copy back into agreement with the engine's). See forge#2378.
+ *
+ * `completionMarker` values are sourced from `RESERVED_TYPES[*].completionSentinel`
+ * wherever that reserved annotation type exists (INVESTIGATOR, CONTEXT,
+ * ARCHITECT, BUILDER) — so the reserved-annotation registry in `types.js` and
+ * this phase registry cannot drift apart for those four phases; there is
+ * exactly one literal declaration of each of those marker strings in the
+ * entire codebase, in `types.js`.
+ *
+ * `review` and `close` have no corresponding `RESERVED_TYPES` entry with a
+ * matching sentinel today (`REVIEWER` has no `completionSentinel` defined in
+ * spec §4.1; `close` is gated on a GitHub *label*, not a comment annotation),
+ * so those two are declared directly in this file — still single-sourced
+ * across the two consumers, just not additionally derived from `types.js`.
+ *
+ * @license MIT
+ */
+
+import { RESERVED_TYPES } from './types.js';
+
+/** Phase ids, in canonical dispatch order (mirrors `commands/work-on.md`'s
+ * "Universal Phase Dispatcher" table and `bin/engine/phases.mjs`'s `PHASES`
+ * array).
+ *
+ * `decompose` and `remediate` (forge#2379) are branch phases, not part of the
+ * six-phase linear happy path — `decompose` is reached only when `investigate`
+ * signals `DECOMPOSE:YES`, and `remediate` only when `review` escalates to
+ * `needs-human`. They are still declared here, in the exact same array
+ * position `bin/engine/phases.mjs`'s `PHASES` array declares them, because
+ * `scripts/check-phase-registry-drift.mjs` requires the two lists to match
+ * index-for-index — see that file's own doc comment. */
+export const PHASE_IDS = ['investigate', 'decompose', 'context', 'architect', 'build', 'review', 'remediate', 'close'];
+
+/**
+ * @typedef {Object} PhaseMarkerEntry
+ * @property {string} [completionMarker] - marker/sentinel string (or label, for `close`)
+ *   whose presence means this phase has committed.
+ * @property {string} [invalidMarker] - (investigate only) marks the issue INVALID.
+ * @property {string} [decomposedMarker] - (investigate only) marks the issue DECOMPOSED.
+ * @property {string} [partialMarker] - sentinel for an interrupted/partial annotation.
+ * @property {string} [presenceMarker] - bare annotation-opener substring, used only by
+ *   phases whose completion is non-critical (see `context` below) — presence alone
+ *   (without `:COMPLETE`) is enough to report a soft/visible skip rather than a hard fail.
+ * @property {string} [completionLabel] - a GitHub issue *label* (not a comment marker)
+ *   whose presence means this phase has committed. Only `close` uses this form.
+ */
+
+/** @type {Object.<string, PhaseMarkerEntry>} */
+export const PHASE_MARKERS = {
+  investigate: {
+    completionMarker: RESERVED_TYPES.INVESTIGATOR.completionSentinel, // 'INVESTIGATION:COMPLETE'
+    invalidMarker: 'INVESTIGATION:INVALID',
+    decomposedMarker: 'DECOMPOSE:YES',
+  },
+  // forge#2379: `decompose` actually runs work-on/decompose (sub-issue
+  // fan-out) once `investigate` hands off on `DECOMPOSE:YES` — see
+  // bin/engine/phases.mjs's `decompose` phase entry for the handoff mechanics.
+  decompose: {
+    completionMarker: RESERVED_TYPES.DECOMPOSED.completionSentinel, // 'FORGE:DECOMPOSED:COMPLETE'
+  },
+  context: {
+    completionMarker: RESERVED_TYPES.CONTEXT.completionSentinel, // 'FORGE:CONTEXT:COMPLETE'
+    partialMarker: RESERVED_TYPES.CONTEXT.partialSentinel, // 'FORGE:CONTEXT:PARTIAL'
+    // Bare presence marker: context is documented as non-critical (spec §7) — a
+    // missing completion marker is a visible skip, not a hard fail. Only
+    // bin/engine/phases.mjs's `context.detectOutcome` uses this bare form;
+    // `context.reconcile` (and everything in interactive-engine.mjs) uses the
+    // strict `completionMarker` above. Do not collapse these two fields.
+    presenceMarker: `FORGE:${RESERVED_TYPES.CONTEXT.type}`, // 'FORGE:CONTEXT'
+  },
+  architect: {
+    completionMarker: RESERVED_TYPES.ARCHITECT.completionSentinel, // 'FORGE:ARCHITECT:COMPLETE'
+    partialMarker: RESERVED_TYPES.ARCHITECT.partialSentinel, // 'FORGE:ARCHITECT:PARTIAL'
+  },
+  build: {
+    completionMarker: RESERVED_TYPES.BUILDER.completionSentinel, // 'FORGE:BUILDER:COMPLETE'
+  },
+  review: {
+    // No RESERVED_TYPES entry defines this sentinel (REVIEWER has no
+    // completionSentinel in spec §4.1) — declared directly here.
+    completionMarker: 'FORGE:REVIEWER:MERGED',
+  },
+  // forge#2379: `remediate` re-drives a needs-human PR (commands/work-on/remediate.md).
+  // Posted to BOTH the PR and the linked issue (Phase M8) — bin/engine/phases.mjs's
+  // `remediate` phase reads it off the issue, consistent with every other phase here.
+  remediate: {
+    completionMarker: RESERVED_TYPES.REMEDIATION.completionSentinel, // 'FORGE:REMEDIATION:COMPLETE'
+  },
+  close: {
+    // A GitHub label, not a comment marker — see `completionLabel` above.
+    completionLabel: 'workflow:merged',
+  },
+};

package/packages/protocol/src/types.js

@@ -86,6 +86,23 @@ export const RESERVED_TYPES = {
     requiredFields: ['Verdict'],
     verdictValues: ['APPROVED', 'CHANGES_REQUESTED', 'COMMENTED'],
   },
+  /**
+   * REMEDIATION — paper trail for a needs-human PR re-driven by
+   * commands/work-on/remediate.md. Posted to BOTH the PR and the linked
+   * issue (Phase M8) once the re-gate outcome (AUTO-LANDED /
+   * HELD-AWAITING-MERGE / RE-ESCALATED / UNFIXABLE) is known. Added in
+   * forge#2379 to single-source the completion sentinel that
+   * bin/engine/phases.mjs's `remediate` phase gates on. <!-- Added: forge#2379 -->
+   */
+  REMEDIATION: {
+    type: 'REMEDIATION',
+    category: Category.LIFECYCLE,
+    completionSentinel: 'FORGE:REMEDIATION:COMPLETE',
+    partialSentinel: null,
+    inlineValue: false,
+    requiredFields: [],
+    reGateOutcomeValues: ['AUTO-LANDED', 'HELD-AWAITING-MERGE', 'RE-ESCALATED', 'UNFIXABLE'],
+  },
   TRAJECTORY: {
     type: 'TRAJECTORY',
     category: Category.LIFECYCLE,