forgedock 1.7.1 → 1.8.1

package/commands/work-on.md

@@ -273,7 +273,7 @@ If detected, dispatch immediately and STOP — do NOT fall through to Phase 0B's
 Skill(skill="work-on/remediate", args="${REMEDIATE_PR_NUMBER} ${REMEDIATE_ISSUE_FLAG} --repo {GH_REPO} --gh-flag {GH_FLAG}")
 ```
 
-**After `REMEDIATE_RESULT` returns, STOP unconditionally** — do not run any further Phase 0–7 logic in this file. `work-on/remediate.md` is self-contained: when `re_gate_outcome: AUTO-LANDED`, it drives its own close phase internally (Phase M8 invokes `Skill("work-on:close", ...)` directly) before returning. For every other outcome (`HELD-AWAITING-MERGE`, `RE-ESCALATED`, `UNFIXABLE`, `BLOCKED`, `ALREADY_DONE`), the issue is already at a terminal state (`workflow:awaiting-merge` or `needs-human`, or already closed) per the Universal Phase Dispatcher — nothing further to do.
+**After `REMEDIATE_RESULT` returns, STOP unconditionally** — do not run any further Phase 0–7 logic in this file. `work-on/remediate.md` is self-contained: a FIXABLE remediation replaces `needs-human` with the active `workflow:in-review` state only while it is running, then ends at `workflow:merged`, `workflow:awaiting-merge`, or a newly asserted `needs-human` label. When `re_gate_outcome: AUTO-LANDED`, it drives its own close phase internally (Phase M8 invokes `Skill("work-on:close", ...)` directly) before returning. For every other outcome (`HELD-AWAITING-MERGE`, `RE-ESCALATED`, `UNFIXABLE`, `BLOCKED`, `ALREADY_DONE`), the issue is already at a terminal state (`workflow:awaiting-merge` or `needs-human`, or already closed) per the Universal Phase Dispatcher — nothing further to do.
 
 This mode is reachable both standalone (a human or script running `/work-on <pr> --remediate` directly) and via the orchestrator (`commands/orchestrate/phase-4-execution.md` item 6.4 auto-dispatches the identical `Skill(skill='work-on', args='{PR} --remediate --issue {N} ...')` invocation against a `needs-human`-gated predecessor's own PR).
 
@@ -358,9 +358,21 @@ fi
 
 **Batch issue pipeline rules** (when `IS_BATCH=true`):
 - Build phases execute exactly as normal (the batch issue body IS the spec for what to fix)
-- After successful merge, auto-close all member issues with a cross-reference:
+- Batch members are referenced in the PR body with `Refs #N`, never `Closes #N`; the batch issue is the only issue the PR may close.
+- After successful merge, re-read every member's live state and labels before closing it. A member that is `needs-human`, `blocked`, or `operator-only` remains open and is reported as a split outcome:
   ```bash
   for MEMBER in "${BATCH_MEMBERS[@]}"; do
+    MEMBER_SNAPSHOT=$(gh issue view "$MEMBER" {GH_FLAG} --json state,labels \
+      --jq '{state: .state, labels: [.labels[].name]}' 2>/dev/null) || {
+      echo "WARNING: could not verify batch member #${MEMBER}; leaving it open"
+      continue
+    }
+    MEMBER_GATED=$(echo "$MEMBER_SNAPSHOT" | jq -r \
+      '(.state != "OPEN") or ([.labels[] | select(. == "needs-human" or . == "blocked" or . == "operator-only")] | length > 0)')
+    if [ "$MEMBER_GATED" = "true" ]; then
+      echo "SPLIT OUTCOME: #${MEMBER} remains open because it requires a human or operator action."
+      continue
+    fi
     gh issue close "$MEMBER" {GH_FLAG} \
       --comment "Resolved as part of batch PR #{PR_NUMBER} (#{ISSUE_NUMBER}). See batch issue for details."
     gh issue edit "$MEMBER" {GH_FLAG} --add-label "workflow:merged" 2>/dev/null || true
@@ -2081,11 +2093,42 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:CHECKPOINT -->
 
 ```bash
 BODY=$(gh issue view {NUMBER} {GH_FLAG} --json body --jq '.body')
-REMAINING_BEFORE=$(echo "$BODY" | grep -c '^- \[ \]' || true)
-HAS_PHASE_HEADINGS=$(echo "$BODY" | grep -cP '^#{2,3} ' || true)
+REMAINING_BEFORE=$(printf '%s\n' "$BODY" | grep -cE '^[-*+] \[ \]' || true)
+
+# Structural test: count heading-delimited sections that contain checkbox items.
+# Multi-phase == 2+ checkbox-bearing sections. A single checkbox group is
+# single-phase regardless of how many prose headings surround it.
+#
+# - Fenced code blocks are stripped first: issue bodies routinely embed fenced
+#   blocks whose lines start with '#' or contain a literal '- [ ]'. An
+#   unterminated fence keeps the original body so later work is never hidden.
+# - ATX headings and setext underlines both delimit sections. The ATX pattern
+#   avoids awk interval-quantifier variance across awk implementations.
+# - grep -E / awk only — no PCRE. '^#+ ' needs none.
+FENCE_COUNT=$(printf '%s\n' "$BODY" | grep -cE '^(```+|~~~+)' || true)
+if [ $(( ${FENCE_COUNT:-0} % 2 )) -ne 0 ]; then
+  BODY_STRIPPED="$BODY"
+else
+  BODY_STRIPPED=$(printf '%s\n' "$BODY" | awk '/^(```+|~~~+)/{f=!f; next} !f')
+fi
+
+CHECKBOX_SECTIONS=$(printf '%s\n' "$BODY_STRIPPED" | awk '
+  /^#+ / { if (in_section && has) n++; in_section=1; has=0; previous=""; next }
+  /^(=+|-+)$/ && previous != "" { if (in_section && has) n++; in_section=1; has=0; previous=""; next }
+  { if (in_section && /^[-*+] \[[ xX]\]/) has=1; previous=$0 }
+  END { if (in_section && has) n++; print n+0 }
+')
+
+# Sub-issue-tracker guard: a decompose parent whose only checkbox group is
+# '## Sub-Issue Tracker' counts 1 section. Checking those off would mark open
+# sub-issues done and close the tracker, so any unchecked GFM task item for an
+# issue forces multi-phase.
+SUBISSUE_ITEMS=$(printf '%s\n' "$BODY_STRIPPED" | grep -cE '^[-*+] \[ \] #[0-9]+' || true)
 ```
 
-If multi-phase (`HAS_PHASE_HEADINGS > 0` AND `REMAINING_BEFORE > 0`): do NOT check off future phase items. Add PR reference only.
+**Sync invariant:** Keep the structural computation above and its consuming multi-phase guard in `commands/work-on/close.md` Phase C1 synchronized. The guard is `CHECKBOX_SECTIONS >= 2 OR SUBISSUE_ITEMS > 0`; this Phase 6A path is reached only when `REMAINING_BEFORE > 0`. <!-- Fixed: forge#2840, #2874 -->
+
+If multi-phase (`CHECKBOX_SECTIONS >= 2` OR a `- [ ] #NNN` sub-issue item is present): do NOT check off future phase items. Add PR reference only. A heading count is **not** the test — every templated issue carries `## Problem`/`## Evidence`/`## Context`, so it is `> 0` universally.
 
 If single-phase or final phase: check off all `[ ]` items, add PR reference.
 

package/docs/CONFIG.md

@@ -298,9 +298,13 @@ Concurrency limits and cascade admission policy for `/orchestrate`'s batch engin
 
 ```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.
+  # Maximum number of top-level /work-on agents dispatched concurrently. Each
+  # worker normally fans out to about 8 total subagent spawns (build, quality
+  # gate, and review included), so set this to no more than session_budget / 8.
+  # Default: 12; use 25 or fewer for a 200-spawn session budget. This limits
+  # in-flight workers only: under cascade.policy: all, raising it increases
+  # both completion and finding-spawn throughput and does not itself bound or
+  # shrink cascade queue growth.
   max_concurrent: 12
 
   cascade:
@@ -324,13 +328,26 @@ orchestration:
     # 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.
+    # — it does NOT individually dispatch deferred generation-2+ findings in
+    # Step 4C. Bounded P3 batching is the sole automated exception: it may
+    # aggregate a finite generation-2 member set under batch_max_generation,
+    # as implemented by #2849. This is what makes "admit gen-2, stop at gen-3"
+    # expressible, which the pre-#2234 --allow-gen2 flag could not say.
     # Default: 1 (from the "balanced" preset); "unlimited" under "all".
     max_generation: 1
 
+    # Maximum generation a P3 batch may aggregate. Batching is a sanctioned,
+    # auditable exception to Step 4C's autonomous cascade cap: it can fold
+    # several deferred low-priority findings into one reviewed unit, but it
+    # must never make recursion unbounded. Every batch records the maximum
+    # member generation in FORGE:BATCH_MAX_GENERATION. This value is always
+    # finite, even under policy: all. Default: 2.
+    batch_max_generation: 2
+
+    # Permit closure only of mechanically identical bot/app alerts: same
+    # normalized title, generator, and trigger condition, while retaining one
+    # canonical issue. Human reports are never included. Default: false.
+    dedup_automated: false
     # 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 —
@@ -353,17 +370,30 @@ orchestration:
     # (avoids serializing agents on same-file predecessor edges). Default:
     # true (from "balanced"); false under "all".
     p3_same_file_defer: true
+
+    # Running findings-spawned / merged-units ceiling. "off" (the default)
+    # only reports amplification; a positive decimal defers further
+    # same-lineage refinements to the completion sweep once exceeded.
+    max_amplification: "off"
+
+    # Number of consecutive merged-unit observations at ratio >= 1.0 before
+    # printing a convergence warning. Default: 3.
+    convergence_window: 3
 ```
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
-| `max_concurrent` | integer | No | Max concurrent `/work-on` sub-agent dispatch. Default: 12 |
+| `max_concurrent` | integer | No | Max concurrent top-level `/work-on` dispatches. It does not bound cascade growth; under `policy: all` it raises drain and spawn throughput together. 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.batch_max_generation` | integer | No | Finite maximum member generation that an automated P3 batch may aggregate. Default: 2 |
+| `cascade.dedup_automated` | boolean | No | Allow only mechanically identical bot/app alerts to be closed with a retained canonical issue. Default: `false` |
 | `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` |
+| `cascade.max_amplification` | positive number or `"off"` | No | Opt-in ceiling for same-lineage refinement dispatch. Default: `"off"` |
+| `cascade.convergence_window` | positive integer | No | Consecutive ratio observations at or above 1.0 before warning. Default: 3 |
 
 **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.
 
@@ -375,10 +405,14 @@ orchestration:
 
 ## `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.
+Tuning knobs for the CLI backend and `/orchestrate`'s batch engine — invocation and stall timeouts, 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:
+  # Wall-clock limit for one CLI backend invocation. The environment variable
+  # FORGEDOCK_CLI_TIMEOUT_MS (milliseconds) takes precedence. Default: 60.
+  cli_timeout_minutes: 60
+
   # 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.
@@ -401,12 +435,13 @@ pipeline:
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
+| `cli_timeout_minutes` | integer | No | Wall-clock minutes for one CLI backend invocation. Default: 60. `FORGEDOCK_CLI_TIMEOUT_MS` (milliseconds) takes precedence. |
 | `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`
+**Commands that use this section**: CLI backend (`cli_timeout_minutes`); `orchestrate` (remaining keys)
 
 ---
 

package/docs/OPENCODE.md

@@ -64,8 +64,8 @@ The generated plugin has no prompt text. It:
   preserving explicit lower limits;
 - grants the built-in `general` subagent permission to invoke native `task`
   unless the user explicitly configured a task permission;
-- opts into OpenCode background subagents by default so each completed issue can
-  wake the parent orchestrator independently; set
+- opts into OpenCode background subagents for the orchestrator's explicit
+  ready-issue dispatches so each completed issue can wake the parent independently; set
   `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=false` to opt out;
 - selects Git Bash on Windows only when the user has not explicitly configured
   an OpenCode shell, because the shared workflows and helper scripts use Bash.
@@ -104,6 +104,14 @@ The adapter follows these rules:
 - Orchestration dispatches independent issues with `task(background=true)` and
   processes each injected task-result event immediately; it does not wait for a
   wave or the slowest sibling.
+- The `/orchestrate` entrypoint reads only runtime config, then runs
+  `bin/orchestrate-preflight.mjs` before loading the phase specs. The helper batches the initial GitHub
+  snapshot and emits only the compact ready queue needed for the first native task.
+  Interactive runs keep the confirmation gate; `--auto` or `--confirm` is the
+  explicit headless authorization.
+- The full Phase 3/4 prose is reserved for investigations, unsupported or multi-repo
+  queries, explicit deep planning, and recovery after a task-result event. It remains
+  authoritative for cascade handling, leases, cleanup, and reporting.
 - GitHub state and the durable engine remain the recovery source instead of
   replaying prior prompt context.
 
@@ -115,12 +123,12 @@ specs evaluate Claude's literal `Task`/`Agent` names, an OpenCode runtime marker
 selects `DISPATCH_TOOL=task`; the absence of those Claude names must not produce
 a false `FORGE:REVIEW_BLOCKED` result.
 
-Every isolated review dispatch uses the explicit native argument shape. Every
+Every isolated review dispatch uses a foreground native task. Every
 native task call must include the schema-required `subagent_type` at the top
 level alongside its `description` and `prompt`:
 
 ```js
-{ description: "...", prompt: "...", subagent_type: "general", background: true }
+{ description: "...", prompt: "...", subagent_type: "general", background: false }
 ```
 
 Implementation and review work uses `general`; read-only discovery uses
@@ -131,8 +139,9 @@ generated adapter safely defaults it to `general`; unsupported types stop with
 If the native `task` capability itself is unavailable, the workflow posts
 `FORGE:REVIEW_BLOCKED` and stops rather than falling back to inline review or
 another pipeline controller.
-The generated plugin adds `background: true` unless
-`OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=false` is explicitly set.
+The generated plugin defaults omitted `background` to `false`. Only the
+orchestrator's ready-issue dispatcher sets `background: true`; setting
+`OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=false` forces foreground execution.
 
 `commands/work-on.md` is still a large entry dispatcher and is loaded in full,
 matching the Claude Code path. The adapter prevents additional eager loading,
@@ -218,6 +227,12 @@ Commands that inspect Claude-specific transcripts or Claude installation state
 remain runtime-specific and should not be represented as portable until they
 receive dedicated implementations.
 
+The preflight is intentionally bounded. It handles explicit issue sets and the
+common single-repository `fast-lane`, `milestone`, `next`, `priority`, and
+`no:milestone` queries, plus explicit dependencies and scoped issue-body file
+overlap. Unsupported or complex inputs fall back to the shared phase specs rather
+than silently weakening their safety rules.
+
 ## Orchestration Runtime
 
 OpenCode orchestration uses the native OpenCode `task` tool for isolated issue

package/docs/spec/review-protocol.md

@@ -122,6 +122,12 @@ Every finding must include:
 
 **All review agents MUST include a machine-readable findings block at the end of their PR comment.** This is NON-OPTIONAL. Without structured findings, the review system cannot create GitHub issues, and findings die as unread PR comments. Every finding that doesn't become a GitHub issue is a finding that will never be addressed.
 
+### Persist Before Post
+
+GitHub is a delivery channel, not the sole record of a review. Before the first `gh pr comment` attempt, write the finalized complete review body, including its `<!-- FORGE:REVIEW-AGENT:{domain} -->` marker and structured findings block, to a uniquely named durable file such as `${TMPDIR:-/tmp}/forge-review-${PR_NUMBER}-${DOMAIN}-$$.md`. Use `gh pr comment --body-file "$REVIEW_BODY_PATH"`; do not construct a retry loop around a failed write.
+
+Every agent MUST return its verdict, finding count, and one line per finding to the orchestrator even when posting succeeds. If the post fails, return the durable body path and the same finding summary, then stop. A 403 or other write failure is a failed delivery, not a clean review and not a reason to retry in the background.
+
 ### Format
 
 Append this block at the very end of your comment (after the `---` footer line, still inside the EOF heredoc). It uses HTML comments so it's invisible in rendered markdown:
@@ -140,6 +146,7 @@ Append this block at the very end of your comment (after the `---` footer line,
 6. **Summary**: Concise one-line description (no pipe `|` characters in summary)
 7. **Empty block**: If no findings at all, include just the START/END markers
 8. **HTML comments**: The block is invisible in rendered markdown but parseable by the review system
+9. **Agent marker**: Include exactly one `<!-- FORGE:REVIEW-AGENT:{domain} -->` marker in the persisted body, where `{domain}` is the lowercase dispatched domain.
 
 ### Domain Prefixes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.7.1",
+  "version": "1.8.1",
   "description": "Autonomous development pipeline for coding agents. GitHub as institutional memory, with native Claude Code and OpenCode entrypoints.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"

package/scripts/check-admission-parity.mjs

@@ -47,6 +47,7 @@ function parseArmBody(body) {
   };
   return {
     maxGeneration: get("PRESET_MAX_GEN"),
+    batchMaxGeneration: get("PRESET_BATCH_MAX_GEN"),
     tokenBudget: get("PRESET_TOKEN_BUDGET"),
     deferOnBatchGated: get("PRESET_DEFER_GATED"),
     keywordHeuristic: get("PRESET_KEYWORD"),

package/scripts/check-command-side-effects.sh

@@ -120,7 +120,7 @@ class_a_scan() {
   # accumulated violation silently. (forge#2289 added the equivalent
   # end-of-file flush for Class B only; this closes the same gap in Class A.)
   flush_a_block() {
-    if [ "$HAS_GIST" -eq 1 ] && echo "$BLOCK_LINES" | grep -qE '^[[:space:]]*--public([[:space:]]|$)'; then
+    if [ "$HAS_GIST" -eq 1 ] && [[ "$BLOCK_LINES" =~ (^|$'\n')[[:space:]]*--public([[:space:]]|$) ]]; then
       # Find the line number of --public within the block
       PUBLIC_LN=$(echo "$BLOCK_LINES" | grep -n '^[[:space:]]*--public' | head -1 | cut -d: -f1)
       ACTUAL_LINE=$((BLOCK_START + PUBLIC_LN))
@@ -149,9 +149,9 @@ class_a_scan() {
     # content; forge#2288 adds true depth so 2+ nesting levels close correctly.)
     IS_FENCE=0
     IS_BARE=0
-    if echo "$line" | grep -qE "^[[:space:]]*${FENCE}"; then
+    if [[ "$line" =~ ^[[:space:]]*${FENCE} ]]; then
       IS_FENCE=1
-      if echo "$line" | grep -qE "^[[:space:]]*${FENCE}[[:space:]]*\$"; then
+      if [[ "$line" =~ ^[[:space:]]*${FENCE}[[:space:]]*$ ]]; then
         IS_BARE=1
       fi
     fi
@@ -188,7 +188,7 @@ class_a_scan() {
     BLOCK_LINES="${BLOCK_LINES}${line}
 "
     # Check if this line has gh gist create/edit (even with line continuation \)
-    if echo "$line" | grep -qE 'gh[[:space:]]+gist[[:space:]]+(create|edit)'; then
+    if [[ "$line" =~ gh[[:space:]]+gist[[:space:]]+(create|edit) ]]; then
       HAS_GIST=1
     fi
   done < "$file"
@@ -296,9 +296,9 @@ else
         # 2+ nesting levels close correctly.)
         IS_FENCE=0
         IS_BARE=0
-        if echo "$line" | grep -qE "^[[:space:]]*${FENCE}"; then
+        if [[ "$line" =~ ^[[:space:]]*${FENCE} ]]; then
           IS_FENCE=1
-          if echo "$line" | grep -qE "^[[:space:]]*${FENCE}[[:space:]]*\$"; then
+          if [[ "$line" =~ ^[[:space:]]*${FENCE}[[:space:]]*$ ]]; then
             IS_BARE=1
           fi
         fi
@@ -314,8 +314,9 @@ else
           # (forge#2289) and is always already at rest here, since this branch
           # is only reached when IN_CB is 0 — i.e. any block that was open has
           # already been closed and flushed at its own fence-close below.
-          if echo "$line" | grep -qE '^#{1,6}[[:space:]]+'; then
-            heading=$(echo "$line" | sed 's/^#*[[:space:]]*//' | sed 's/[[:space:]]*$//')
+          if [[ "$line" =~ ^#{1,6}[[:space:]]+(.*)$ ]]; then
+            heading="${BASH_REMATCH[1]}"
+            heading="${heading%"${heading##*[![:space:]]}"}"
             SECTION="$heading"
             continue
           fi
@@ -338,18 +339,18 @@ else
         fi
 
         # Content line while inside (at any depth).
-        if echo "$line" | grep -qF "$ALLOWLIST_TOKEN"; then continue; fi
+        if [[ "$line" == *"$ALLOWLIST_TOKEN"* ]]; then continue; fi
 
         # Check for guard — scoped to THIS code block only (forge#2289)
-        echo "$line" | grep -qE "$GUARD_PATTERN" && BLOCK_HAS_GUARD=1
+        [[ "$line" =~ $GUARD_PATTERN ]] && BLOCK_HAS_GUARD=1
 
         # Check if this line is in the diff's added lines AND has a side-effect verb
-        if [ "$BLOCK_HAS_ADDED_SE" -eq 0 ] && echo "$line" | grep -qE "$SIDE_EFFECT_PATTERN"; then
+        if [ "$BLOCK_HAS_ADDED_SE" -eq 0 ] && [[ "$line" =~ $SIDE_EFFECT_PATTERN ]]; then
           # Is this specific line in the added content?
-          if echo "$ADDED_CONTENT" | grep -qF "${line:0:80}" 2>/dev/null; then
+          if [[ "$ADDED_CONTENT" == *"${line:0:80}"* ]]; then
             BLOCK_HAS_ADDED_SE=1
             BLOCK_SE_LINE=$LN
-            BLOCK_SE_VERB=$(echo "$line" | grep -oE "$SIDE_EFFECT_PATTERN" | head -1 || echo "side-effect")
+            BLOCK_SE_VERB="${BASH_REMATCH[0]:-side-effect}"
           fi
         fi
       done < "$file"

package/scripts/check-shell-portability.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# check-shell-portability.sh — Verify shipped shell scripts have an explicit
+# Bash interpreter and parse successfully before a quality gate executes them.
+
+set -euo pipefail
+
+SCRIPTS_DIR="${1:-./scripts}"
+
+if [ ! -d "$SCRIPTS_DIR" ]; then
+  echo "ERROR: scripts directory not found: $SCRIPTS_DIR" >&2
+  exit 2
+fi
+
+violations=0
+while IFS= read -r -d '' script; do
+  first_line=$(IFS= read -r line < "$script" || true; printf '%s' "$line")
+  if [ "$first_line" != "#!/usr/bin/env bash" ]; then
+    echo "HIGH | $script | shell scripts must declare #!/usr/bin/env bash" >&2
+    violations=$((violations + 1))
+    continue
+  fi
+  if ! bash -n "$script"; then
+    echo "HIGH | $script | shell syntax validation failed" >&2
+    violations=$((violations + 1))
+  fi
+done < <(find "$SCRIPTS_DIR" -type f -name '*.sh' -print0 | sort -z)
+
+if [ "$violations" -gt 0 ]; then
+  echo "check-shell-portability: $violations violation(s) found. See stderr for details." >&2
+  exit 1
+fi
+
+echo "OK: Shell scripts declare Bash and pass syntax validation"

package/scripts/check-spec-markers.sh

@@ -87,9 +87,11 @@ MARKER_REGISTRY="
   BATCH_MEMBERS
   BENCH_SCORECARD
   BLOCKED_ON_HUMAN_MERGE
+  BODY
   BUILDER
   CALIBRATION_CHECK
   CARD
+  CLASS
   CHECKPOINT
   CLAIM
   CLAIM_RELEASED
@@ -100,6 +102,7 @@ MARKER_REGISTRY="
   DECISION_RECORD
   DECOMPOSED
   DESIGN
+  DISPATCH
   DISPATCHER
   DOSSIER_UPDATED
   ENGINE_FALLBACK
@@ -187,28 +190,29 @@ while IFS= read -r file; do
     content="${markerline#*:}"
 
     # Skip allowlisted lines
-    if echo "$content" | grep -qF "$ALLOWLIST_TOKEN"; then
+    if [[ "$content" == *"$ALLOWLIST_TOKEN"* ]]; then
       continue
     fi
 
     # Skip markers that are inside code spans (backtick-quoted) — those are docs examples
     # Heuristic: if the FORGE:TYPE appears between backticks on the same line, skip it
     # We check for backtick on either side of the FORGE: marker
-    if echo "$content" | grep -qE "\`[^\`]*FORGE:[A-Z_]"; then
+    if [[ "$content" =~ \`[^\`]*FORGE:[A-Z_] ]]; then
       continue
     fi
 
     # Extract the full marker string after FORGE: — everything up to a space, -->, or end
     # This captures compound markers like REVIEW-AGENT:material-change
-    full_marker=$(echo "$content" | grep -oE 'FORGE:[A-Z][A-Z0-9_:-]*' | head -1 | sed 's/^FORGE://')
+    [[ "$content" =~ FORGE:([A-Z][A-Z0-9_:-]*) ]] || continue
+    full_marker="${BASH_REMATCH[1]}"
 
     [ -z "$full_marker" ] && continue
 
     # Extract PRIMARY type: part before the first - or : separator
-    primary_type=$(echo "$full_marker" | sed 's/[-:].*//')
+    primary_type="${full_marker%%[-:]*}"
 
     # Validate primary type against registry
-    if ! echo "$primary_type" | grep -qE "$REGISTRY_PATTERN"; then
+    if ! [[ "$primary_type" =~ $REGISTRY_PATTERN ]]; then
       echo "HIGH | $file:$lineno | unknown FORGE: marker 'FORGE:${full_marker}' (primary type '${primary_type}') — not in registry" >&2
       VIOLATIONS=$((VIOLATIONS + 1))
     fi
@@ -242,21 +246,27 @@ if [ -d "$WORKFLOWS_DIR" ]; then
       LINENO=$((LINENO + 1))
 
       # Skip allowlisted lines
-      if echo "$line" | grep -qF "$ALLOWLIST_TOKEN"; then
+      if [[ "$line" == *"$ALLOWLIST_TOKEN"* ]]; then
         continue
       fi
 
       # Skip comment lines
-      if echo "$line" | grep -qE '^[[:space:]]*#'; then
+      if [[ "$line" =~ ^[[:space:]]*# ]]; then
         continue
       fi
 
       # Strip bash ${VAR} and $VAR patterns before checking for template placeholders
       # so that ELAPSED in "${ELAPSED}s" doesn't false-positive as {ELAPSED}
-      stripped=$(echo "$line" | sed 's/\${\([^}]*\)}/BASH_VAR/g; s/\$[A-Za-z_][A-Za-z0-9_]*/BASH_VAR/g')
-
-      if echo "$stripped" | grep -qE "$PLACEHOLDER_PATTERN"; then
-        placeholder=$(echo "$stripped" | grep -oE "$PLACEHOLDER_PATTERN" | head -1)
+      stripped="$line"
+      while [[ "$stripped" =~ \$\{[^}]*\} ]]; do
+        stripped="${stripped/"${BASH_REMATCH[0]}"/BASH_VAR}"
+      done
+      while [[ "$stripped" =~ \$[A-Za-z_][A-Za-z0-9_]* ]]; do
+        stripped="${stripped/"${BASH_REMATCH[0]}"/BASH_VAR}"
+      done
+
+      if [[ "$stripped" =~ $PLACEHOLDER_PATTERN ]]; then
+        placeholder="${BASH_REMATCH[0]}"
         echo "HIGH | $wf_file:$LINENO | unsubstituted placeholder '$placeholder' in workflow" >&2
         VIOLATIONS=$((VIOLATIONS + 1))
       fi

package/scripts/checkbox-sections.test.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+# checkbox-sections.test.sh — Regression tests for the close-path classifier.
+#
+# Usage: bash scripts/checkbox-sections.test.sh
+
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+
+extract_block() {
+  awk '/^FENCE_COUNT=/{printing=1} printing{print} /^SUBISSUE_ITEMS=/{exit}' "$1"
+}
+
+extract_classifier() {
+  awk '
+    /^CHECKBOX_SECTIONS=.*awk .$/ { printing=1; next }
+    printing && /^\047\)$/ { exit }
+    printing { print }
+  ' "$1"
+}
+
+CLOSE_BLOCK=$(extract_block "$ROOT/commands/work-on/close.md")
+INLINE_BLOCK=$(extract_block "$ROOT/commands/work-on.md")
+[[ "$CLOSE_BLOCK" == "$INLINE_BLOCK" ]] || {
+  printf 'FAIL: mirrored classifier blocks differ\n' >&2
+  exit 1
+}
+
+CLOSE_CLASSIFIER=$(extract_classifier "$ROOT/commands/work-on/close.md")
+INLINE_CLASSIFIER=$(extract_classifier "$ROOT/commands/work-on.md")
+[[ "$CLOSE_CLASSIFIER" == "$INLINE_CLASSIFIER" ]] || {
+  printf 'FAIL: mirrored classifier implementations differ\n' >&2
+  exit 1
+}
+
+if grep -q 'echo "\$BODY\|echo "\$BODY_STRIPPED' \
+  "$ROOT/commands/work-on/close.md" "$ROOT/commands/work-on.md"; then
+  printf 'FAIL: arbitrary issue bodies must be piped with printf, not echo\n' >&2
+  exit 1
+fi
+
+grep -Fq 'Keep the structural computation above and its consuming multi-phase guard' "$ROOT/commands/work-on.md" || {
+  printf 'FAIL: Phase 6A sync invariant must cover the consuming guard\n' >&2
+  exit 1
+}
+grep -Fq 'The guard is `CHECKBOX_SECTIONS >= 2 OR SUBISSUE_ITEMS > 0`' "$ROOT/commands/work-on.md" || {
+  printf 'FAIL: Phase 6A must document the Phase C1 guard\n' >&2
+  exit 1
+}
+grep -Fq 'if [ "${CHECKBOX_SECTIONS:-0}" -ge 2 ] || [ "${SUBISSUE_ITEMS:-0}" -gt 0 ]; then' "$ROOT/commands/work-on/close.md" || {
+  printf 'FAIL: Phase C1 multi-phase guard changed unexpectedly\n' >&2
+  exit 1
+}
+
+SETEXT_BODY=$'Phase One\n=========\n- [x] complete\n\nPhase Two\n---------\n- [ ] remaining'
+[[ "$(printf '%s\n' "$SETEXT_BODY" | awk "$CLOSE_CLASSIFIER")" == "2" ]] || {
+  printf 'FAIL: setext phases must count as two sections\n' >&2
+  exit 1
+}
+
+SINGLE_BODY=$'## Acceptance Criteria\n- [ ] complete this work'
+[[ "$(printf '%s\n' "$SINGLE_BODY" | awk "$CLOSE_CLASSIFIER")" == "1" ]] || {
+  printf 'FAIL: one checkbox-bearing section must remain single-phase\n' >&2
+  exit 1
+}
+
+printf 'PASS: mirrored classifier supports setext section boundaries\n'