forgedock 1.2.0 → 1.4.0

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 |
@@ -210,6 +212,9 @@ repos:
 | `satellites[].local_path` | string | No | Absolute local path to the satellite repo's checkout |
 | `satellites[].subpaths` | map(string→string) | No | Named sub-directory paths within `local_path`, for monorepo satellites that publish multiple packages. Each key is a logical name; the value is the relative path to that package's root. Used by `/sync-ecosystem` to locate per-package version files and publish workflows. |
 | `satellites[].billing_enabled` | boolean | No | Set to `true` to run Phase 4 (Financial Integrity) of `/security-audit` against this satellite repo. Mirrors the top-level [`billing.enabled`](#billing-optional) flag but scoped per-satellite. Defaults to `false` when absent. |
+| `satellites[].trigger_on_merge` | boolean | No | When `true`, fires a cross-repo trigger when a PR merges in the parent repo and touches paths matching `trigger_paths`. Set to `false` to disable triggering for this satellite. Defaults to `true` when `trigger_paths` is present; otherwise has no effect until runtime trigger support is configured. |
+| `satellites[].trigger_paths` | list of strings | No | Path glob patterns that constrain when the trigger fires. Uses GitHub Actions glob syntax (same as `on: push: paths:`). The trigger fires only when at least one changed file matches a pattern in this list. When omitted, the trigger fires on every merge (if `trigger_on_merge: true`). |
+| `satellites[].auto_run` | boolean | No | When `true`, automatically invokes `/work-on` on the satellite issue when the cross-repo trigger fires. Requires a running Claude Code session with ForgeDock installed in the satellite repo. Advanced opt-in — defaults to `false`. Do not set to `true` unless a persistent Claude Code session is available in the satellite repo. |
 
 **Routing syntax in commands**: `<prefix>:<issue_number>` — e.g., `mcp:5`, `sdk:12`
 
@@ -287,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.
@@ -609,6 +732,39 @@ Colors are grouped by semantic meaning:
 
 ---
 
+## `branding` (OPTIONAL)
+
+Controls attribution in FORGE annotation comments posted to GitHub issues and PRs by pipeline commands.
+
+When `show_attribution` is `true` (the default), every annotation comment (`FORGE:INVESTIGATOR`, `FORGE:CONTRACT`, `FORGE:BUILDER`, `FORGE:TRAJECTORY`, `FORGE:DECOMPOSED`, etc.) ends with a one-line footer:
+
+```
+> Pipeline powered by [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock)
+```
+
+This follows the pattern established by Dependabot, Renovate, and similar tools. It helps new users discover the tooling when they encounter FORGE: annotations in a public thread. Set to `false` to suppress the attribution entirely.
+
+```yaml
+branding:
+  show_attribution: true
+```
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `show_attribution` | boolean | No | `true` | When `true`, annotation comments posted by the pipeline include a one-line attribution footer. Set to `false` to suppress it entirely. Opt-out model — attribution is on by default. |
+
+**Commands that use this section**: `work-on` (all phases that post FORGE: annotation comments)
+
+**Config read pattern** (yq, with default-true fallback):
+
+```bash
+SHOW_ATTRIBUTION=$(yq '.branding.show_attribution // "true"' forge.yaml 2>/dev/null || echo "true")
+[ "$SHOW_ATTRIBUTION" = "false" ] && ATTRIBUTION_LINE="" || ATTRIBUTION_LINE="
+> Pipeline powered by [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock)"
+```
+
+---
+
 ## GitHub App Install
 
 During `npx forgedock`, the installer prompts you to install the ForgeDock GitHub App (`rapiercraft-forgedock`) on your account or org.

package/docs/CURSOR.md

@@ -0,0 +1,135 @@
+# Cursor Support
+
+ForgeDock has a Cursor adapter that lets Cursor Agent mode run the ForgeDock pipeline via shell commands and the `gh` CLI.
+
+## Architecture
+
+Shared source:
+- `commands/**/*.md` remains the canonical workflow spec for all runtimes
+
+Cursor wrapper:
+- `templates/cursor/forge.mdc` — a static Cursor rules file that instructs Cursor Agent to execute pipeline phases using shell commands, `gh` CLI, and `git`
+- Users install this file into their repo's `.cursor/rules/forge.mdc`
+
+This is a static injection model, not a dynamic skill-loading mechanism. The adapter cannot replicate Claude Code's `Skill()` invocation or Codex's installed skill wrappers. Instead, it instructs the agent to read command specs directly from `commands/` and execute them using available terminal tools.
+
+## Install
+
+### Automatic (via `npx forgedock`)
+
+If your project already has a `.cursor/` directory, `npx forgedock` will detect it and automatically write `templates/cursor/forge.mdc` to `.cursor/rules/forge.mdc`:
+
+```bash
+npx forgedock
+```
+
+The installer skips this step if `.cursor/rules/forge.mdc` already exists (idempotent — never overwrites customizations).
+
+### Manual
+
+Copy the template directly:
+
+```bash
+mkdir -p .cursor/rules
+cp node_modules/forgedock/templates/cursor/forge.mdc .cursor/rules/forge.mdc
+# or, if installed globally:
+cp "$(npx forgedock which-dir)/templates/cursor/forge.mdc" .cursor/rules/forge.mdc
+```
+
+Commit the file to version control so all team members get it:
+
+```bash
+git add .cursor/rules/forge.mdc
+git commit -m "chore: add ForgeDock Cursor rules adapter"
+```
+
+## Usage
+
+### Running the Pipeline
+
+Open a Cursor Agent session and describe the pipeline task:
+
+```
+Work on GitHub issue #123 using the ForgeDock pipeline.
+Read commands/work-on.md and follow all phases.
+```
+
+The rules file will instruct Cursor Agent to:
+
+1. Load issue context from GitHub using `gh issue view`
+2. Follow the Universal Phase Dispatcher in `commands/work-on.md`
+3. Write FORGE annotations (HTML comments) to issue comments after each phase
+4. Transition `workflow:*` labels as phases complete
+5. Continue until a terminal label is set
+
+### Checking Pipeline State
+
+```bash
+# See current workflow state
+gh issue view NUMBER --json labels --jq '[.labels[].name]'
+
+# Read existing pipeline annotations
+gh api repos/OWNER/REPO/issues/NUMBER/comments \
+  --jq '.[] | select(.body | contains("FORGE:")) | {body: .body[:200]}'
+```
+
+### Continuing After a Phase
+
+Because Cursor Agent mode does not persist between invocations, start a new session and describe the resume:
+
+```
+Resume the ForgeDock pipeline for GitHub issue #123.
+Read commands/work-on.md — it will re-read GitHub state and pick up from the current label.
+```
+
+The pipeline is designed for compaction resilience — every phase re-reads GitHub state at the start, so a new Cursor Agent session picks up exactly where the previous session left off.
+
+## Limitations
+
+| Capability | Claude Code | Cursor (this adapter) |
+|------------|-------------|----------------------|
+| Skill loading | Dynamic (`~/.claude/commands/`) | Static (this rules file) |
+| Multi-phase pipeline | Automatic (single continuous session) | Manual (re-invoke agent per phase) |
+| Sub-skill invocation | `Skill("review-pr")` | Read `commands/review-pr.md` directly |
+| Session continuity | Native compaction resilience | Re-read GitHub state each invocation |
+| Tool set | Claude-native (`Bash`, `Read`, `Grep`, `Glob`, `WebFetch`) | Cursor Agent terminal tools |
+
+### Multi-Phase Pipeline
+
+The ForgeDock pipeline has 7 phases (investigate → build → review → merge → close → trajectory). Cursor Agent mode does not automatically advance through all phases in a single session. After each phase completes, you will need to start a new agent invocation and ask it to continue.
+
+The pipeline's compaction resilience handles this correctly: each invocation re-reads the issue's labels and comments, determines the current phase, and continues from there. No context is lost between sessions.
+
+### Sub-Skill Invocation
+
+When the pipeline spec calls `Skill("review-pr")` or `Skill("quality-gate")`, Cursor Agent should read the referenced command spec file directly:
+
+```bash
+cat commands/review-pr.md   # Then execute that spec
+cat commands/quality-gate.md
+```
+
+### Project Board Steps
+
+Some pipeline phases (0C: Sync to Project board) call GitHub Projects API operations. These work via `gh` CLI but require the project number and field IDs from `forge.yaml`. Verify your `forge.yaml` has the correct project configuration before running the pipeline.
+
+## Configuration
+
+ForgeDock reads `forge.yaml` for project-specific settings:
+
+```bash
+cat forge.yaml   # Review before running the pipeline
+```
+
+Key fields used by the pipeline:
+- `project.github.owner` / `project.github.repo` — GitHub repo coordinates
+- `branches.staging` — target branch for fast-lane PRs
+- `branches.main` — default branch
+
+## Reference
+
+- `commands/work-on.md` — Full pipeline spec (all phases)
+- `commands/review-pr.md` — PR review spec
+- `commands/quality-gate.md` — Pre-commit quality checks (14+ domains)
+- `docs/FORGE-PROTOCOL.md` — FORGE annotation protocol specification
+- `docs/CODEX.md` — Codex CLI adapter (dynamic skill model)

package/docs/OPENCODE.md

@@ -0,0 +1,312 @@
+# OpenCode Support
+
+ForgeDock has an OpenCode adapter that lets OpenCode run the ForgeDock pipeline
+using its native bash tool and the `gh` CLI.
+
+## Architecture
+
+Shared source:
+- `commands/**/*.md` remains the workflow spec for all runtimes
+
+Claude Code wrapper:
+- `install.sh` (or `npx forgedock`) symlinks command files into `~/.claude/commands/`
+
+Codex wrapper:
+- `install-codex.sh` generates namespaced skills in `~/.codex/skills/`
+
+Aider wrapper:
+- `install-aider.sh` writes `~/.aider-forge.md` loaded via `--read`
+
+**OpenCode wrapper** (this document):
+- `install-opencode.sh` writes `~/.opencode-forge.md` — a conventions file
+  OpenCode loads via the `instructions` field in `opencode.json`
+- `install-opencode.sh` also patches `~/.config/opencode/opencode.json` to
+  register ForgeDock pipeline commands as native OpenCode slash commands
+  (`/work-on`, `/review-pr`, `/quality-gate`, `/orchestrate`)
+
+This is a conventions-file + command-registration architecture. The shared
+`commands/` directory remains the single source of truth — the adapter
+registers entry points that read from it.
+
+## Feasibility
+
+OpenCode is the **highest-fidelity** non-Claude Code adapter because:
+
+| Capability | Requirement | OpenCode support |
+|-----------|-------------|-----------------|
+| Load instruction files | `instructions` field in `opencode.json` | Native |
+| Execute shell commands | `gh`, `git`, standard tools | Native `Bash` tool |
+| Read/write files | File editing | Native `Read`/`Write`/`Edit` tools |
+| GitHub API | `gh` CLI | Via `Bash("gh ...")` |
+| Multi-step workflows | Follow sequential instructions | Supported |
+| Compaction resilience | Re-read GitHub state at phase start | Supported (via `Bash("gh ...")`) |
+| Native slash commands | `/work-on 967` in TUI | Via `command` config |
+| Tool name parity | Same tool names as Claude Code | Direct — no translation needed |
+
+**Key advantage over Aider and Cursor**: OpenCode shares Claude Code's tool
+names (`Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `WebFetch`) — no
+translation table required for most operations. Pipeline command specs run
+nearly unmodified.
+
+## Install
+
+### Option A — standalone bash installer
+
+```bash
+cd /path/to/forgedock
+./install-opencode.sh
+```
+
+This writes `~/.opencode-forge.md` with ForgeDock conventions and patches
+`~/.config/opencode/opencode.json` with:
+- `instructions`: adds `~/.opencode-forge.md` to OpenCode's system prompt
+- `command`: registers `/work-on`, `/review-pr`, `/quality-gate`, `/orchestrate`
+
+### Option B — via npx forgedock
+
+When `opencode` is detected on your PATH, `npx forgedock` writes
+`~/.opencode-forge.md` and patches `opencode.json` as an additional install
+step. No existing Claude Code files are affected.
+
+```bash
+npx forgedock
+```
+
+## Usage
+
+### Native slash commands (recommended)
+
+After running `install-opencode.sh`, use ForgeDock commands in the OpenCode
+TUI:
+
+```
+/work-on 967
+/review-pr 123
+/quality-gate
+```
+
+Or headlessly via `opencode run`:
+
+```bash
+opencode run --command work-on "967"
+opencode run --command review-pr "123"
+```
+
+### Manual pipeline loading
+
+Read a pipeline command spec directly and follow it:
+
+```
+Read the file /path/to/forgedock/commands/work-on.md and run the pipeline for issue 967.
+```
+
+OpenCode will load the spec and execute each phase using its native tools.
+
+### Phase routing with forge-run.sh
+
+`forge-run.sh` emits JSON phase state for the current issue without invoking
+an LLM. Use it to determine the current pipeline phase:
+
+```bash
+Bash("/path/to/forgedock/scripts/forge-run.sh work-on 967 -R OWNER/REPO")
+```
+
+Output (NDJSON):
+```json
+{"event":"phase_detected","command":"work-on","issue":967,"phase":"no-comments","ts":"..."}
+{"event":"phase_detail","phase":"no-comments","lane":"feature","branch":"milestone/dev-exp","labels":[]}
+{"event":"action_required","phase":"no-comments","action":"No pipeline activity detected. Invoke /work-on 967 to start investigation.","ts":"..."}
+```
+
+## Tool Translation
+
+OpenCode and Claude Code share the same tool names. Most pipeline operations
+run without modification:
+
+| Claude Code | OpenCode | Notes |
+|-------------|----------|-------|
+| `Bash("git status")` | `Bash("git status")` | Direct |
+| `Read("path/to/file")` | `Read("path/to/file")` | Direct |
+| `Write("path", content)` | `Write("path", content)` | Direct |
+| `Edit("path", ...)` | `Edit("path", ...)` | Direct |
+| `Glob("**/*.md")` | `Glob("**/*.md")` | Direct |
+| `Grep(pattern, path)` | `Grep(pattern, path)` | Direct |
+| `WebFetch(url)` | `WebFetch(url)` | Direct |
+| `Skill("work-on", args="123")` | Read `commands/work-on.md` | No skill loader — read spec directly |
+| `Skill("review-pr", args="456")` | Read `commands/review-pr.md` | No skill loader — read spec directly |
+| `Agent(...)` / `Task(...)` | Continue the sub-task inline | No sub-agent model; inline it |
+
+### Nested Skill references
+
+When a command spec calls `Skill("x")` or references another command, read
+the referenced command spec directly:
+
+```
+# Load the referenced command spec:
+Read("/path/to/forgedock/commands/quality-gate.md")
+```
+
+Map command names to file paths:
+- `Skill("work-on")` → `commands/work-on.md`
+- `Skill("review-pr")` → `commands/review-pr.md`
+- `Skill("quality-gate")` → `commands/quality-gate.md`
+- `Skill("orchestrate")` → `commands/orchestrate.md`
+
+## GitHub Operations
+
+All FORGE annotations are written to GitHub issue/PR comments via the `gh`
+CLI. Use `Bash()` for every GitHub operation.
+
+### Label management
+
+```bash
+Bash("gh issue edit 123 -R OWNER/REPO --add-label 'workflow:investigating'")
+Bash("gh issue edit 123 -R OWNER/REPO --remove-label 'workflow:investigating'")
+```
+
+### Reading existing annotations
+
+```bash
+Bash("gh api repos/OWNER/REPO/issues/123/comments \
+  --jq '.[] | select(.body | contains(\"FORGE:INVESTIGATOR\")) | .body'")
+```
+
+### Writing a FORGE annotation comment
+
+For multi-line comment bodies, write the content to a temp file first:
+
+```bash
+# Write comment body to temp file (avoids shell quoting issues)
+Write("/tmp/forge_comment.md", """<!-- FORGE:INVESTIGATOR -->
+## Investigation Report
+
+**Verdict**: CONFIRMED
+...
+<!-- INVESTIGATION:COMPLETE -->""")
+
+Bash("gh issue comment 123 -R OWNER/REPO --body \"$(cat /tmp/forge_comment.md)\"")
+```
+
+### Creating a PR
+
+```bash
+Write("/tmp/pr_body.md", """## Summary
+...
+
+Closes #967""")
+
+Bash("gh pr create -R OWNER/REPO \
+  --base milestone/developer-experience-distribution \
+  --head feat/opencode-adapter-967 \
+  --title 'feat: OpenCode adapter (#967)' \
+  --body \"$(cat /tmp/pr_body.md)\"")
+```
+
+## Worktrees
+
+ForgeDock uses git worktrees to isolate branch work. Create one with:
+
+```bash
+Bash("git fetch origin")
+Bash("git worktree add .claude/worktrees/feat-my-feature-123 \
+  -b feat/my-feature-123 origin/staging")
+```
+
+Work inside the worktree for all file edits and commits:
+
+```bash
+Read("/path/to/repo/.claude/worktrees/feat-my-feature-123/file.py")
+Edit("/path/to/repo/.claude/worktrees/feat-my-feature-123/file.py", ...)
+Bash("git -C /path/to/repo/.claude/worktrees/feat-my-feature-123 status")
+```
+
+## FORGE Annotation Protocol
+
+Every pipeline stage writes a structured annotation to GitHub. Key rules:
+
+1. **Idempotency**: Check for existing annotations BEFORE starting a phase.
+   Do not re-run a completed phase.
+2. **Compaction resilience**: Write annotations AFTER completing each
+   significant step. GitHub is the persistent state layer.
+3. **Restart partial annotations**: If an annotation exists without its
+   `:COMPLETE` sentinel, delete it and restart the phase.
+4. **Respect label state**: Labels track workflow state. Read and set them
+   at each phase boundary.
+
+### Label state machine
+
+```
+workflow:investigating
+    → workflow:ready-to-build   (investigation complete)
+    → workflow:building         (build started)
+    → workflow:in-review        (PR created)
+    → workflow:merged           (PR merged) [TERMINAL]
+
+workflow:invalid                [TERMINAL]
+workflow:decomposed             [TERMINAL]
+needs-human                     [TERMINAL]
+```
+
+Stop the pipeline when any terminal label is set.
+
+## Limitations
+
+| Capability | Claude Code | OpenCode (this adapter) |
+|------------|-------------|------------------------|
+| Skill loading | Dynamic (`~/.claude/commands/`) | Read `commands/*.md` directly |
+| Native slash commands | `/work-on 967` | `/work-on 967` (via `command` config) |
+| Tool name parity | Native | Direct (same names) |
+| Sub-agent invocation | `Skill("review-pr")` | Read `commands/review-pr.md` directly |
+| Session continuity | Native compaction resilience | Re-read GitHub state each session |
+| Multi-phase pipeline | Automatic (single continuous session) | Supported (GitHub state is persistent) |
+
+**Sub-skill invocation**: When a command spec calls `Skill("x")`, OpenCode
+has no native skill loader. Read the referenced command spec file directly
+instead.
+
+**Parallel tasks**: When a command spec calls `Agent(...)` or `Task(...)` for
+parallelism (e.g., multi-agent review in `review-pr-agents.md`), execute the
+sub-tasks sequentially. OpenCode runs one agent context at a time.
+
+## Configuration
+
+`install-opencode.sh` patches `~/.config/opencode/opencode.json`. Example
+of what is added:
+
+```json
+{
+  "instructions": [
+    "~/.opencode-forge.md"
+  ],
+  "command": {
+    "work-on": {
+      "description": "Run the ForgeDock full issue pipeline (investigate → build → review → merge)",
+      "template": "Read /path/to/forgedock/commands/work-on.md and execute the pipeline for issue {{args}}."
+    },
+    "review-pr": {
+      "description": "Run the ForgeDock PR review pipeline",
+      "template": "Read /path/to/forgedock/commands/review-pr.md and execute the PR review for PR {{args}}."
+    },
+    "quality-gate": {
+      "description": "Run ForgeDock pre-commit quality checks",
+      "template": "Read /path/to/forgedock/commands/quality-gate.md and run all quality gate checks."
+    },
+    "orchestrate": {
+      "description": "Run ForgeDock parallel multi-issue orchestration",
+      "template": "Read /path/to/forgedock/commands/orchestrate.md and orchestrate the issues: {{args}}."
+    }
+  }
+}
+```
+
+Existing config keys (provider, model, etc.) are preserved. ForgeDock only
+adds to the `instructions` array and `command` object — never overwrites.
+
+## Reference
+
+- [FORGE Protocol spec](FORGE-PROTOCOL.md) — annotation format, label state machine
+- [Aider adapter](AIDER.md) — parallel adapter reference (Aider uses `/run` translation)
+- [Codex adapter](CODEX.md) — parallel adapter reference (Codex skill model)
+- [Pipeline commands](../commands/) — shared workflow specs (authoritative for all runtimes)
+- [`install-opencode.sh`](../install-opencode.sh) — installer script
+- [`scripts/forge-run.sh`](../scripts/forge-run.sh) — universal shell phase router

package/docs/eval/README.md

@@ -8,8 +8,8 @@ Per-release pipeline evaluation results for ForgeDock. Every scorecard here was
 
 | Field | Value |
 |-------|-------|
-| Scorecard | [claude-sonnet-5-2026-07-04.json](published/claude-sonnet-5-2026-07-04.json) |
-| Model | claude-sonnet-5 |
+| Scorecard | [claude-sonnet-4-6-2026-07-04.json](published/claude-sonnet-4-6-2026-07-04.json) |
+| Model | claude-sonnet-4-6 |
 | Corpus | seed-v1 |
 | Run date | 2026-07-04 |
 | One-shot success rate | — (pending harness) |
@@ -17,7 +17,7 @@ Per-release pipeline evaluation results for ForgeDock. Every scorecard here was
 
 > **Note**: The baseline above is a format placeholder. The harness (#1285) and CI gate (#1286) must be operational before real scorecard values can be populated. When the first real run completes, update this table and remove this note.
 >
-> **Model upgrade**: Default model was updated from `claude-sonnet-4-5` to `claude-sonnet-5` in PR #1441 (issue #1248, committed 2026-07-04). The `--model` flag and `FORGEDOCK_MODEL` env var override the default at runtime.
+> **Model upgrade**: Default model was updated from `claude-sonnet-4-5` to `claude-sonnet-5` in PR #1441 (issue #1248, committed 2026-07-04). The `--model` flag and `FORGEDOCK_MODEL` env var override the default at runtime. No `claude-sonnet-5` scorecard has been published yet — see the Published results table below.
 
 ---
 
@@ -25,7 +25,7 @@ Per-release pipeline evaluation results for ForgeDock. Every scorecard here was
 
 | Run ID | Model | Corpus | Date | One-shot success | Human interventions/issue | Scorecard |
 |--------|-------|--------|------|-----------------|--------------------------|-----------|
-| claude-sonnet-5-2026-07-04 | claude-sonnet-5 | seed-v1 | 2026-07-04 | pending | pending | [scorecard](published/claude-sonnet-5-2026-07-04.json) |
+| claude-sonnet-5-2026-07-04 | claude-sonnet-5 | seed-v1 | 2026-07-04 | pending | pending | not yet published |
 | claude-sonnet-4-6-2026-07-04 | claude-sonnet-4-6 | seed-v1 | 2026-07-04 | pending | pending | [scorecard](published/claude-sonnet-4-6-2026-07-04.json) |
 
 ---