forgedock 1.7.0 → 1.8.0

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)
 
 ---
 
@@ -927,7 +962,7 @@ The hook entry is registered idempotently: re-installing (`npx forgedock update`
 | Command | Action |
 |---------|--------|
 | `npx forgedock` / `npx forgedock install` | Registers the SessionStart hook (along with installing commands and writing `forge.yaml`) |
-| `npx forgedock update` | Re-registers the hook (relink only — does not touch `forge.yaml`) |
+| `npx forgedock update` | Re-registers the hook when the resolved source can be safely refreshed (relink only — does not touch `forge.yaml`) |
 | `npx forgedock uninstall` | Removes the hook entry from `settings.json` |
 
 ### Opting Out
@@ -948,7 +983,7 @@ See [Per-Directory State Registry](#per-directory-state-registry) below for how
 
 `npx`/`npm` never installs `forgedock` to a stable location on your machine — it resolves to wherever `npx`'s cache (or a global npm install, or a git clone) happens to physically live. Historically, `~/.claude/commands/` and the SessionStart hook's script path were symlinked **directly** from that ephemeral location. When npm/npx (or the OS) later evicted its cache, those symlinks silently dangled — Claude Code sessions stopped getting ForgeDock context with no error shown.
 
-As of this feature, every `npx forgedock` (or `npx forgedock update`) run copies ForgeDock's own installable payload into a stable, version-independent home:
+For npm/npx sources, every `npx forgedock` (or `npx forgedock update`) run copies ForgeDock's own installable payload into a stable, version-independent home:
 
 ```
 ~/.forge/
@@ -968,8 +1003,8 @@ As of this feature, every `npx forgedock` (or `npx forgedock update`) run copies
 | `npx forgedock` / `npx forgedock install` | Copies the resolved package's payload into `~/.forge/` (content-compared — unchanged files are never rewritten) before linking commands, then links from `~/.forge/`, not the original source |
 | `npx forgedock init` | Does not touch `~/.forge/` — `init` only writes `forge.yaml`, it never installs commands |
 | `npx forgedock update` (npm/npx install) | Refreshes `~/.forge/` from whatever the currently-resolved package looks like, then relinks |
-| `npx forgedock update` (git-clone install) | **Does not** touch `~/.forge/` at all — see the exemption below |
-| `npx forgedock doctor` | Reports `~/.forge/version` and confirms `~/.forge/{bin,commands,scripts,templates}` exist |
+| `npx forgedock update` (git-clone install) | Updates and relinks a `main` checkout; a non-main checkout is left untouched and gets actionable guidance because the current source must remain the source used after the command returns |
+| `npx forgedock doctor` | Reports the effective source path, version, and git branch, then reports `~/.forge/version` and confirms `~/.forge/{bin,commands,scripts,templates}` for npm installs |
 
 The copy is idempotent: files whose content is already byte-identical are never rewritten, so steady-state re-runs are fast and don't generate false "updated" noise.
 
@@ -979,6 +1014,7 @@ If you run ForgeDock from a git clone (or a git worktree) of the repo itself —
 
 - `~/.claude/commands/` continues to symlink directly from the clone, exactly as before this feature.
 - `~/.forge/{bin,commands,scripts,templates}` correctly does **not** exist for this install mode — `npx forgedock doctor` treats that absence as healthy, not a warning.
+- `npx forgedock update` never switches a non-main checkout to `main` and then restores it. That transient update would leave the next invocation running the old branch source, so the command reports the effective path, branch, and version and tells you to run from a main checkout instead.
 
 ### Not the Same as `~/.forge/{runs,index}`
 
@@ -1086,7 +1122,7 @@ The directory (`~/.forge/`) is created automatically on first write with `mkdir(
 ### When It's Written
 
 - After every successful `npx forgedock install` (end of the onboarding journey, right after the "Forged." celebration screen).
-- After every `npx forgedock update` — both the git-clone branch (fast-forward pull) and the npm branch (version-check advisory) route through the same repair step (`relinkAndHint()`), so the receipt is refreshed either way.
+- After every successful `npx forgedock update` — the main git-clone branch and npm branch route through the same repair step (`relinkAndHint()`), so the receipt is refreshed either way. A non-main git-clone advisory intentionally does not relink or rewrite the receipt.
 
 The write is best-effort and never blocks or fails the install/update it records: any error (permission denied, disk full, unusual `FORGE_HOME` layout) degrades silently to a no-op, matching the fail-open contract already used by the command-manifest and hook-registration steps.
 

package/docs/OPENCODE.md

@@ -19,12 +19,12 @@ For the optional command tier:
 npx forgedock opencode install --extras
 ```
 
-Restart OpenCode after install or update. OpenCode loads commands and plugins
-at startup.
+Restart OpenCode after install or update. OpenCode loads commands, skills, and
+plugins at startup.
 
-The installer does not edit `opencode.json` or `opencode.jsonc`. It writes only
-ForgeDock-owned files under OpenCode's config directory and records them in
-`forgedock/manifest.json` for safe updates and removal.
+The native adapter does not add or modify user-owned OpenCode settings. It
+writes only ForgeDock-owned files under OpenCode's config directory and records
+them in `forgedock/manifest.json` for safe updates and removal.
 
 ## Usage
 
@@ -62,9 +62,29 @@ The generated plugin has no prompt text. It:
 - injects `FORGE_HOME` into OpenCode shell environments;
 - defaults `subagent_depth` to 2 when the user has not configured it, while
   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 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.
 
+The adapter also registers every eligible ForgeDock workflow as a native
+OpenCode skill. Top-level and nested source paths are normalized to valid
+hyphenated skill names while the wrapper continues to point at the authoritative
+source file:
+
+```text
+commands/work-on.md             -> skills/work-on/SKILL.md
+commands/work-on/investigate.md -> skills/work-on-investigate/SKILL.md
+commands/review-pr.md           -> skills/review-pr/SKILL.md
+```
+
+The wrapper is intentionally thin. It carries the workflow's `name` and
+`description` frontmatter, preserves the current-context arguments, and loads
+only the referenced `commands/**/*.md` spec.
+
 OpenCode's provider configuration remains entirely user-owned. ForgeDock does
 not require Anthropic when invoked through OpenCode; any provider and model
 supported by the user's OpenCode configuration can execute the commands.
@@ -74,19 +94,54 @@ supported by the user's OpenCode configuration can execute the commands.
 The adapter follows these rules:
 
 - No global ForgeDock `instructions` entry.
-- No generated skill for every source file. Large skill catalogs add metadata
-  to every session even when ForgeDock is unused.
-- Only top-level user entry commands are registered.
+- Top-level user entry commands are registered under `/forge/*`.
+- Every eligible workflow is registered as a native skill so nested
+  `Skill(...)` dispatch resolves through OpenCode's `skill` tool instead of
+  filesystem guessing.
 - Nested phase specs are loaded only when their dispatcher reaches them.
 - Task/Agent work uses OpenCode subagents only for the parallelism, isolation,
   or context-pressure cases required by the shared workflow.
+- 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.
 
 The generated adapter preamble is intentionally small. It maps Claude Code's
-in-conversation `Skill(...)` loading to a lazy read of the corresponding shared
-spec. It maps isolated `Task(...)` and permitted `Agent(...)` calls to
-OpenCode's native `task` tool.
+in-conversation `Skill(...)` loading to the normalized native skill name and
+authoritative shared spec. It maps isolated `Task(...)` and permitted
+`Agent(...)` calls to OpenCode's native `task` tool. Before the shared review
+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 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: false }
+```
+
+Implementation and review work uses `general`; read-only discovery uses
+`explore`. Claude `general-purpose` maps to `general` and
+`codebase-explorer` maps to `explore`. When a source task omits its type, the
+generated adapter safely defaults it to `general`; unsupported types stop with
+`FORGE_OPENCODE_CAPABILITY_ERROR` instead of reaching schema validation.
+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 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,
@@ -102,13 +157,27 @@ npx forgedock opencode install --extras
 npx forgedock opencode uninstall
 ```
 
+`npx forgedock update` also refreshes an existing managed OpenCode adapter,
+including its plugin and generated skills. It preserves the installed core vs.
+`--extras` tier, migrates the sentinel-marked legacy adapter, and does not
+install OpenCode files when no ForgeDock adapter is already registered.
+
 Updates are deterministic and prune stale ForgeDock-owned command files.
 Uninstall removes only files listed in the ownership manifest and still marked
 with a ForgeDock sentinel. User-owned commands, plugins, and files placed in
 the `forgedock/` namespace are never removed; that namespace is pruned only
 when it is empty.
-Install also removes the previous ForgeDock-managed `~/.opencode-forge.md`
-instructions file and its exact legacy config entries when they are present.
+For backward compatibility, install and uninstall may rewrite `opencode.json`
+only to remove legacy entries whose two-key `description` and `template` still
+exactly match one of the definitions emitted by the retired adapter and point to
+the active ForgeDock home (or the home recorded in the ownership manifest during
+uninstall), and the sentinel-marked legacy instructions file is present. It also
+removes references to that managed `~/.opencode-forge.md` instructions file. The
+migration does not rewrite `opencode.jsonc`. User-owned settings and customized commands are preserved;
+definitions with extra keys, edited fields, different
+paths, a missing ownership marker, or ambiguous ownership are left in place. If
+a legacy config cannot be parsed or written, the migration leaves the legacy
+artifacts in place.
 
 ## Locations
 
@@ -117,6 +186,7 @@ Default global location:
 ```text
 ~/.config/opencode/
   commands/forge/*.md
+  skills/<workflow-name>/SKILL.md
   plugins/forgedock.js
   forgedock/manifest.json
 ```
@@ -133,25 +203,43 @@ The separate `forgedock run` and `forgedock run-issue` backend still supports
 only Claude CLI and the Anthropic API. An OpenCode engine backend must be added
 and validated before ForgeDock can claim provider-neutral headless parity.
 
-Claude's `PreToolUse` safety hook has not yet been ported to an OpenCode plugin.
-The shared workflow rules and deterministic scripts still apply, but equivalent
-mechanical enforcement must be implemented and tested before claiming complete
-Claude-runtime safety parity.
-
-OpenCode 1.18.4 keeps background subagents experimental. When they are not
-enabled, the command adapter requires independent foreground tasks to be
-launched concurrently where supported and uses ForgeDock's GitHub-label polling
-fallback. This preserves isolated review contexts but does not yet prove equal
-wall-clock behavior for `/forge/orchestrate`.
+The ForgeDock plugin provides the OpenCode-specific runtime boundary for shell
+and task execution. Its `tool.execute.before` hook rejects Claude-backed and
+recursive ForgeDock controller commands, and normalizes native task arguments
+before execution; the shared workflow rules and deterministic scripts remain
+the source of truth for all other behavior.
+
+OpenCode 1.18.4 keeps background subagents experimental. ForgeDock opts into
+that feature by default because the streaming DAG depends on the parent session
+receiving one completion event per child. A native background task returns a
+`<task id="..." state="running">` marker immediately and later injects a
+`state="completed"` or `state="error"` result into the parent session. The
+orchestrator maps that id to the issue, re-reads GitHub state, and dispatches
+newly unlocked successors in the same response.
+
+If `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=false` is explicitly set,
+ForgeDock uses independent foreground tasks where OpenCode can execute them
+concurrently and labels the run as degraded. Foreground tasks cannot provide
+the same per-completion wake behavior, so this opt-out intentionally restores a
+wave-like fallback rather than silently claiming Claude-equivalent throughput.
 
 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
-work and follows the shared `commands/work-on.md` state machine. It must not
+work and follows the shared `commands/work-on.md` state machine. Each ready
+issue is launched as `task(subagent_type="general", background=true)` and its
+task-result event is treated as the completion notification for that issue. It
+must not
 route through `forgedock run-issue` when that would select the Claude CLI or
 Anthropic API backend. If the host does not expose an OpenCode runtime marker,
 set the runtime explicitly before launching a headless command:
@@ -162,10 +250,25 @@ FORGE_RUNTIME=opencode opencode run --command forge/orchestrate "fast-lane"
 
 Each task re-reads GitHub labels and `FORGE:*` comments after every phase and
 continues until `workflow:merged`, `workflow:invalid`, `needs-human`, or
-`workflow:awaiting-merge`. If native task dispatch is unavailable, post a
+`workflow:awaiting-merge`. The parent orchestrator processes every child
+completion independently, so a completed predecessor can unlock and dispatch
+its successors while unrelated issues continue running. If native task
+dispatch is unavailable, post a
 `FORGE:OPENCODE_BLOCKED` diagnostic naming the missing capability and add
 `needs-human`; do not leave an issue stranded at `workflow:engine-error`.
 
+If a generated command or skill cannot load its authoritative workflow, it must
+stop with an actionable `FORGE_OPENCODE_CAPABILITY_ERROR`. It must not recover
+by invoking `forgedock run-issue`, `npx forgedock run-issue`, or a recursive
+`opencode run`; those paths select a competing controller or Claude-backed
+backend.
+
+The same boundary is enforced below the plugin for direct CLI callers. With
+`FORGE_RUNTIME=opencode`, `forgedock run`, `forgedock run-issue`, and Claude
+backend preflight fail before selecting a provider. The stable error is
+`FORGE_OPENCODE_CAPABILITY_ERROR`; continue by using the registered native
+Skill and Task workflow instead.
+
 This runtime branch is additive. Claude keeps its existing engine and
 background-agent paths, and Codex keeps its installed namespaced skills and
 repo-local adapters.

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.0",
+  "version": "1.8.0",
   "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"