forgedock 1.0.16 → 1.0.17

package/docs/BRAND.md

@@ -0,0 +1,51 @@
+# ForgeDock Brand Handles
+
+Status of reserved and blocked brand handles across platforms.
+
+## Domain
+
+| Domain | Status |
+|--------|--------|
+| `forgedock.dev` | **Owned** — canonical marketing and App URL |
+
+## npm
+
+| Package | Status |
+|---------|--------|
+| `forgedock` | **Owned** — published AGPL CLI at https://www.npmjs.com/package/forgedock |
+
+No action needed. The package name was claimed on first publish.
+
+## GitHub Organization
+
+| Slug | Status |
+|------|--------|
+| `forgedock` | **Blocked** — parked org created 2024-05-23, not administered by RapierCraft Studios |
+
+The bare `forgedock` org slug cannot be used for the ForgeDock GitHub App name — GitHub
+slugifies App display names and rejects collisions with existing user/org accounts.
+
+**Recommended App slug**: `forgedock-ai` (or `forgedock-app`). The App ID in use during
+development is **3978349** (registered under RapierCraftStudios with `public: false`).
+Update the display name and slug when the L2 central public App launches.
+
+## Social Handles
+
+| Platform | Handle | Status |
+|----------|--------|--------|
+| X / Twitter | `@forgedock` | Check and reserve if available |
+| Bluesky | `forgedock.bsky.social` | Check and reserve if available |
+| LinkedIn | `forgedock` company page | Check and reserve if available |
+| Product Hunt | `forgedock` | Reserve at launch |
+
+Social handle registration is an operational task. Reserve handles before public launch
+(L1 milestone) to prevent squatting. The public App launch (L2) is gated on L1 completion.
+
+## Summary
+
+| Platform | Action |
+|----------|--------|
+| Domain | Done |
+| npm | Done |
+| GitHub org slug | Blocked — use variant for App slug |
+| Social handles | Reserve before L1 public launch |

package/docs/CONFIG.md

@@ -41,6 +41,7 @@ The default (`npx forgedock init` with no flags) remains the zero-question autop
 | [`devdocs`](#devdocs-optional) | No | Devdocs knowledge tree path |
 | [`verification`](#verification-optional) | No | Health-check patterns |
 | [`billing`](#billing-optional) | No | Enable financial integrity audit phase |
+| [`adaptive_scripts`](#adaptive_scripts-optional) | No | Per-repo script override configuration |
 
 ---
 
@@ -330,14 +331,38 @@ Run `npx forgedock docs init` to scaffold the tree from ForgeDock's seed templat
 ```yaml
 devdocs:
   path: "devdocs"
+  # index_path: "devdocs/index.yaml"   # optional; defaults to {path}/index.yaml
 ```
 
 | Field | Type | Required | Description |
 |-------|------|----------|-------------|
 | `path` | string (relative path) | No | Path to the devdocs tree, relative to project root. Default: `devdocs`. |
+| `index_path` | string (relative or absolute path) | No | Path to the selective loading index file. Default: `{path}/index.yaml`. When the index file exists at this path, agents read it first (~400 tokens) and load only docs whose domain matches the current issue's labels. When absent, agents fall back to loading all docs with `applies_to: work-on` (backward compatible). Scaffold the index with `npx forgedock docs init`. |
 
 **Commands that use this section**: `docs init`, `work-on/build/context` (Phase C-1), `work-on/build/architect` (Phase A0)
 
+### Selective Loading (index.yaml)
+
+When `devdocs/index.yaml` exists, agents use **domain-filtered selective loading** instead of reading all applicable devdocs:
+
+1. Read `index.yaml` (~400 tokens)
+2. Extract issue labels (e.g. `billing`, `infra`, `auth`)
+3. Load only docs in matching domains + all `always_load` entries
+4. When no labels match any domain key: load only `always_load` entries
+
+**Domain matching**: GitHub issue labels map directly to domain keys in `index.yaml`. For example, a label `billing` matches `domains.billing`. Prefixes like `workflow:`, `priority:`, and `review-finding` are stripped before matching.
+
+**`always_load` entries** are loaded for every task regardless of domain. Use for `project/custom-instructions.md` and other files every agent must read.
+
+**Token savings**: A typical task loads 1-3 docs (~1,500-3,000 tokens) instead of all docs (~8,000-12,000 tokens). The index itself costs ~400 tokens — break-even at 1 file avoided.
+
+**Backward compatibility**: If `index.yaml` is absent, behavior is unchanged — all docs with `applies_to: work-on` are loaded. No migration required for existing devdocs trees.
+
+Scaffold the index with:
+```bash
+npx forgedock docs init
+```
+
 ### Migration from `review.context`
 
 If you previously stored project context in `forge.yaml → review.context`, move that content into the appropriate devdocs file after running `npx forgedock docs init`:
@@ -431,6 +456,75 @@ billing:
 
 ---
 
+## `adaptive_scripts` (OPTIONAL)
+
+Per-repo script override configuration. Controls whether ForgeDock looks for project-specific scripts in `.forgedock/scripts/` before falling back to universal scripts.
+
+```yaml
+adaptive_scripts:
+  enabled: true
+  directory: ".forgedock/scripts"
+  commit: false
+```
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `enabled` | boolean | No | `true` | When `true`, pipeline agents check `.forgedock/scripts/` for a per-repo script before using the universal one. Set to `false` to disable per-repo overrides entirely and always use universal scripts. |
+| `directory` | string (relative path) | No | `".forgedock/scripts"` | Directory where per-repo adaptive scripts live, relative to the project root. Scaffolded by `npx forgedock init`. |
+| `commit` | boolean | No | `false` | When `false`, `.forgedock/scripts/` is `.gitignore`d — scripts are local-only and not shared with the team. Set to `true` (and remove the `.gitignore` entry) to commit per-repo scripts to version control. |
+
+**Commands that use this section**: `work-on` (Phase 0B script resolution), any pipeline command that calls a deterministic script
+
+### Script Precedence
+
+ForgeDock resolves which script handles each operation using a strict 4-level hierarchy (highest to lowest authority):
+
+```
+1. forge.yaml → learned: (machine-captured corrections)        ← highest
+2. .forgedock/scripts/{operation}.sh  (per-repo adaptive)
+3. scripts/{operation}.sh             (universal, ships with npm)
+4. Prose instructions in command specs (fallback)              ← lowest
+```
+
+### Override Semantics
+
+- **Per-repo scripts completely replace** the universal script for that operation — there is no partial inheritance or merging.
+- **Per-repo scripts may call universal scripts** via the `$FORGEDOCK_SCRIPTS/{operation}.sh` path. Every universal script exports `FORGEDOCK_SCRIPTS` (absolute path to the universal scripts directory) and `FORGEDOCK_HOME` (absolute path to the ForgeDock installation root) so that per-repo scripts can delegate back to them.
+- **No circular dependencies**: per-repo scripts may call universal scripts but must NOT call other per-repo scripts. One level of delegation only.
+- **`forge.yaml → learned:`** overrides take precedence over everything. They represent explicit user corrections captured by the pipeline.
+
+### Example: per-repo script that delegates to universal
+
+```bash
+#!/usr/bin/env bash
+# .forgedock/scripts/classify-lane.sh
+# Override: this repo uses 'develop' instead of 'staging' for the fast lane.
+
+set -euo pipefail
+
+# Delegate to universal classify-lane.sh to get the standard result
+UNIVERSAL_RESULT=$(bash "$FORGEDOCK_SCRIPTS/classify-lane.sh" "$@")
+
+# Override only the fast-lane output for this project
+if [ "$UNIVERSAL_RESULT" = "staging" ]; then
+  echo "develop"
+else
+  echo "$UNIVERSAL_RESULT"
+fi
+```
+
+### Logging
+
+When a pipeline agent resolves a script tier, it logs the result in the FORGE annotation:
+
+```
+Script tier: adaptive (.forgedock/scripts/classify-lane.sh)
+Script tier: universal (scripts/classify-lane.sh)
+Script tier: prose (no script found — using spec instructions)
+```
+
+---
+
 ## Label Bootstrap
 
 ForgeDock manages a canonical set of GitHub labels for use across all pipeline commands. Labels cover workflow state, priority, review findings, audit findings, and category classification.

package/docs/articles/per-repo-adaptive-scripts-token-savings.md

@@ -0,0 +1,174 @@
+---
+title: "Per-Repo Adaptive Scripts: Measured Token Savings vs Per-Session Rediscovery"
+description: "Every AI coding session rediscovers the same project-specific patterns — branch names, test commands, commit style. We measured the cost and quantified how per-repo adaptive scripts eliminate it."
+tags: ["ai", "performance", "tokens", "productivity", "opensource"]
+cover_image:
+canonical_url: https://github.com/RapierCraftStudios/ForgeDock
+published: false
+---
+
+<!-- Generated by ForgeDock pipeline — Issue #673 -->
+
+AI coding agents are expensive to run. Every session starts from scratch, re-reading files, running commands, and re-learning the same project-specific patterns that have not changed since last week. This article measures how much that costs, and what per-repo adaptive scripts do about it.
+
+---
+
+## The Problem: Per-Session Rediscovery
+
+Every time a ForgeDock agent starts working on an issue, it must answer the same questions about the project:
+
+- What is the PR base branch? (staging? milestone/something? main?)
+- How do I run the tests? (pnpm test? pytest? npm run test:unit?)
+- What commit format does this project use? (conventional commits? what scope?)
+- Where do the tests live? (tests/? __tests__/? spec/?)
+- What workflow labels exist on this repo?
+
+None of these change between sessions. The codebase does not reorganize its test directory overnight. The commit convention does not shift on a Tuesday. But the agent re-discovers all of them from scratch on every run — reading files, executing commands, inferring patterns.
+
+We measured this cost across five representative completed issues.
+
+---
+
+## Methodology
+
+We analyzed five pipeline sessions from the ForgeDock dogfooding repository (issues #674, #669, #671, #679, #676). For each session, we identified every tool call that was a "rediscovery call" — a call whose purpose was to learn something about the project that was already true in the previous session.
+
+Token counts were estimated at 1 token per 4 characters (conservative; actual tokenization may differ by model and content type). We counted command invocation + output, not context window overhead.
+
+---
+
+## Baseline: Per-Session Rediscovery Cost
+
+| Operation | Mechanism (baseline) | Token estimate |
+|-----------|---------------------|----------------|
+| forge.yaml full read | Read 111-line, 4,228-byte file | ~1,050 |
+| Branch name determination | `gh issue view` + LLM milestone-to-slug inference | ~350 |
+| Commit style detection | `git log --oneline -5` + LLM pattern inference | ~200 |
+| Test command discovery | Read package.json/pyproject.toml + grep test scripts | ~400 |
+| Test location discovery | `ls tests/`, `ls __tests__/`, parse package.json | ~250 |
+| Label scheme discovery | `gh label list` or inferred from pipeline comments | ~300 |
+| **Total per session** | | **~2,550 tokens** |
+
+These numbers are per-session. On a repository with active development (10-30 issues/month), this rediscovery tax runs 25,500–76,500 tokens/month on patterns that have not changed.
+
+The branch name example is instructive. Before `classify-lane.sh` was introduced in #669, agents would:
+
+1. Call `gh issue view NUMBER --json milestone` (~200 tokens output)
+2. Extract the milestone title string
+3. LLM-infer the slug transformation (`Deterministic Pipeline v2` → `milestone/deterministic-pipeline-v2`)
+4. Sometimes get it wrong and hallucinate `milestone/project-agnostic` (the bug that motivated #639)
+
+After `classify-lane.sh`: one deterministic script execution with a 6-token output. No LLM inference in the critical path.
+
+---
+
+## Target: Per-Repo Adaptive Script Overhead
+
+After `/optimize` generates `.forgedock/scripts/` entries from `forge.yaml → learned:`, the same operations become:
+
+| Script | Size | Execution cost |
+|--------|------|----------------|
+| `branch-targets.sh` | 23 lines, ~470 bytes | ~170 tokens |
+| `run-tests.sh` | 10 lines, ~200 bytes | ~80 tokens |
+| `format-commit.sh` | 15 lines, ~300 bytes | ~100 tokens |
+| `forge.yaml` learned section (4 targeted yq reads) | subset of 4,228-byte file | ~100 tokens |
+| **Total per session** | | **~450 tokens** |
+
+The key insight: a script call costs roughly the script size (to read) plus the output size (to receive). A 23-line branch-targets.sh costs ~118 tokens to read and produces 1 line of output. The equivalent LLM-based rediscovery costs ~350 tokens and occasionally hallucinates.
+
+---
+
+## Savings Calculation
+
+```
+savings_per_session = 2,550 - 450 = 2,100 tokens
+
+range:
+  low  = 1,200 tokens  (simple fast-lane issues, no test discovery needed)
+  high = 3,500 tokens  (complex multi-file issues with full pattern rediscovery)
+```
+
+At claude-sonnet-4-5 pricing ($3.00 per million input tokens):
+
+```
+2,100 tokens/session × $3.00 / 1,000,000 = $0.0063/session
+```
+
+At observed ForgeDock dogfooding pace (5–15 issues/day, averaging ~10):
+
+```
+300 sessions/month × $0.0063 = $1.89/month per repo
+```
+
+For teams running ForgeDock at production scale across multiple repositories, these savings compound. A team with 5 active repos at 300 sessions/month each saves ~$9.45/month from adaptive scripts alone. The cost of running `/optimize` once per repo to generate the scripts: effectively zero (a single session that generates ~5 scripts).
+
+**Payback period: 1 session.**
+
+---
+
+## Comparison with DevDocs
+
+Per-repo scripts and devdocs solve different problems:
+
+| Pattern type | Script approach | DevDocs approach | Winner |
+|-------------|----------------|-----------------|--------|
+| Branch target | `branch-targets.sh` — 23 lines, 1 execution call | 1 line in architecture.md | **DevDocs** (simpler for static values already documented) |
+| Test commands | `run-tests.sh` — executable, deterministic output | Section in devdocs, LLM parses prose | **Scripts** (executable beats interpreted) |
+| Commit format | `format-commit.sh` — outputs exact string | Convention in devdocs, LLM infers | **Scripts** (deterministic output vs interpretation) |
+| Architecture decisions | Cannot encode reasoning in scripts | `devdocs/project/architecture.md` | **DevDocs** (irreplaceable for reasoning context) |
+| Debug runbooks | Script could wrap commands, but context matters | DevDocs with structured steps | **DevDocs** (context-dependent) |
+
+The boundary rule: if the knowledge produces a **deterministic output** (a branch name, a command string, a file path), encode it as a script. If it requires **contextual interpretation** (design rationale, tradeoff analysis, conventions with exceptions), encode it in devdocs.
+
+Per-repo scripts replace approximately 25–40% of devdocs content for projects with established operational patterns. This reduces per-session devdocs loading by an estimated 500–1,000 tokens, complementing the token savings from selective devdocs loading introduced in #675.
+
+**Combined savings per session** (adaptive scripts + devdocs selective loading):
+
+```
+Rediscovery elimination (adaptive scripts): ~2,100 tokens
+Devdocs selective loading (#675):           ~1,000 tokens
+────────────────────────────────────────────────────────
+Total combined:                             ~3,100 tokens/session
+```
+
+---
+
+## What Gets Generated
+
+Running `/optimize` on a ForgeDock repository after the `learned:` section is populated produces:
+
+| Script | Trigger | What it replaces |
+|--------|---------|-----------------|
+| `branch-targets.sh` | `learned.branch_targets.staging` is set | gh issue milestone lookup + LLM slug inference |
+| `run-tests.sh` | `learned.test_commands` is non-empty | package.json/pyproject.toml read + LLM test command inference |
+| `format-commit.sh` | `learned.commit_style` is set + 3+ commits confirm pattern | git log --oneline + LLM conventional commit inference |
+| `find-tests.sh` | `learned.test_locations` is non-empty | ls tests/, __tests__/ + LLM path inference |
+| `label-map.sh` | `learned.label_map` is non-empty | gh label list + LLM label mapping |
+
+Each script is generated at confidence >= 0.7 (two independent signals) or 1.0 (explicit `learned:` value). The confidence threshold ensures scripts are only generated when there is enough signal to trust the encoded knowledge.
+
+---
+
+## Limitations and Confidence Intervals
+
+The estimates in this article carry these caveats:
+
+1. **Token counting method**: We use 1 token per 4 characters. Actual tokenization varies by model and content type (code tokenizes more densely than prose). Error: ±20%.
+
+2. **Baseline measurement**: We analyzed 5 issues from one repository (ForgeDock itself). A ForgeDock-type repository (markdown command specs, minimal code) may have lower rediscovery cost than a large application codebase with many test configurations. Application repos with complex test setups may see 4,000–6,000 tokens of rediscovery per session.
+
+3. **LLM hallucination cost not counted**: Our baseline counts only the token cost of rediscovery, not the token cost of correcting a hallucinated branch name or wrong test command. Including rework, the actual cost of rediscovery-induced errors is higher.
+
+4. **Model pricing changes**: The $3.00/M figure is current as of June 2026. Pricing trends downward over time; the absolute dollar savings will decrease, but the proportional savings (rediscovery as a fraction of session cost) remain constant.
+
+---
+
+## Prioritization Conclusion
+
+This measurement was created to inform the prioritization decision for #667 (learned section) and #668 (/optimize command). Both are now merged.
+
+The data confirms: **adaptive scripts are worth implementing.** The payback period is less than one session. The primary value is not dollar savings (which are modest for individual repos) but **reliability** — replacing LLM inference with deterministic script output eliminates a class of hallucination errors that were causing production-impacting bugs (see #639: agents hallucinating `milestone/project-agnostic` instead of `staging`).
+
+Token savings are the measurable proxy for the deeper value: an agent that runs `branch-targets.sh` and gets `milestone/deterministic-pipeline-v2` in 6 tokens cannot hallucinate the branch name. An agent that reads a 350-token prose description and infers the branch name sometimes gets it wrong.
+
+Scripts do not just save tokens. They eliminate a category of error.

package/docs/claude-breakpoints.json

@@ -0,0 +1,47 @@
+{
+  "_comment": "claude-breakpoints.json — structured registry of known Claude Code version breakpoints. Each entry documents a version where Claude Code changed behavior that ForgeDock depends on, introduced a feature ForgeDock leverages, or broke a capability ForgeDock uses. Format is append-only and human-editable. Consumers: detectClaudeVersion() (issue #680), /compat-audit (issue #686), forgedock doctor (issue #682).",
+  "schema": {
+    "version": "Claude Code version string where the breakpoint was introduced (e.g. '2.1.157')",
+    "type": "Category of change: 'feature' | 'behavior_change' | 'compatibility' | 'deprecation'",
+    "description": "Human-readable description of what changed in Claude Code at this version",
+    "forgedock_impact": "How this change affects ForgeDock — what commands, scripts, or behaviors are affected",
+    "severity": "Impact level if a user is on this version or older: 'high' | 'medium' | 'low' | 'info'"
+  },
+  "breakpoints": [
+    {
+      "version": "2.1.157",
+      "type": "behavior_change",
+      "description": "EnterWorktree now unlocks worktrees automatically when the agent session finishes",
+      "forgedock_impact": "ForgeDock no longer needs --force on worktree cleanup commands. The cleanup phase in work-on.md can use standard git worktree remove without the force flag.",
+      "severity": "low"
+    },
+    {
+      "version": "2.1.157",
+      "type": "feature",
+      "description": "Plugins in .claude/skills are auto-loaded without requiring marketplace installation",
+      "forgedock_impact": "Symlink-based install (the original forgedock install method) remains valid but is no longer required for skill discovery. The stub file install pattern introduced in #619 is the preferred approach and works the same way.",
+      "severity": "info"
+    },
+    {
+      "version": "2.1.163",
+      "type": "compatibility",
+      "description": "requiredMinimumVersion and requiredMaximumVersion managed settings added for enterprise deployments",
+      "forgedock_impact": "ForgeDock's own version check (forgedock doctor, #682) is the OSS equivalent of this enterprise feature. No conflict — enterprise users with managed settings may have stricter version constraints than ForgeDock requires.",
+      "severity": "info"
+    },
+    {
+      "version": "2.1.172",
+      "type": "feature",
+      "description": "Sub-agents can spawn sub-agents up to 5 levels deep (increased nesting depth)",
+      "forgedock_impact": "ForgeDock's orchestrate.md uses multi-agent orchestration. The 5-level nesting limit is compatible with ForgeDock's orchestration patterns. No changes needed.",
+      "severity": "info"
+    },
+    {
+      "version": "2.1.154",
+      "type": "compatibility",
+      "description": "Native /workflows dynamic workflows introduced as a built-in Claude Code feature",
+      "forgedock_impact": "Parallel to ForgeDock's orchestrate.md. ForgeDock's approach adds GitHub persistence (FORGE: annotations, label-state machine, compaction resilience) that native /workflows lacks. Both can coexist — ForgeDock is the orchestration layer with state, not a replacement for native workflows.",
+      "severity": "info"
+    }
+  ]
+}

package/docs/site/getting-started.md

@@ -17,6 +17,27 @@ This tutorial gets you from zero to your first autonomous pipeline run in under
 - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated
 - Git and GitHub CLI (`gh`) installed and authenticated (`gh auth login`)
 - Node.js 18 or higher
+- [`yq`](https://github.com/mikefarah/yq) — YAML parser used by all pipeline commands to read `forge.yaml`
+
+**Install `yq`:**
+
+```bash
+# macOS
+brew install yq
+
+# Ubuntu / Debian
+sudo apt-get install yq
+# or: sudo snap install yq
+
+# Windows
+winget install mikefarah.yq
+# or: choco install yq
+
+# Any platform (via Go)
+go install github.com/mikefarah/yq/v4@latest
+```
+
+> **Note:** Without `yq`, pipeline commands that read `forge.yaml` (including `/work-on`, `/scope`, `/orchestrate`, and most others) will fall back to defaults or skip config-driven steps silently.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.0.16",
+  "version": "1.0.17",
   "description": "GitHub as a knowledge graph for AI agents. Autonomous dev pipeline for Claude Code.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"
@@ -27,7 +27,7 @@
     "type": "git",
     "url": "git+https://github.com/RapierCraftStudios/ForgeDock.git"
   },
-  "homepage": "https://github.com/RapierCraftStudios/ForgeDock",
+  "homepage": "https://forgedock.dev",
   "bugs": {
     "url": "https://github.com/RapierCraftStudios/ForgeDock/issues"
   },
@@ -52,7 +52,7 @@
   },
   "peerDependenciesMeta": {
     "@anthropic-ai/claude-code": {
-      "optional": false
+      "optional": true
     }
   }
 }

package/scripts/classify-lane.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+# classify-lane.sh — Deterministic lane routing from issue milestone
+#
+# Usage: classify-lane.sh <issue_number> [-R <owner/repo>]
+#   issue_number: GitHub issue number (required)
+#   -R <owner/repo>: GitHub repository (optional, defaults to current repo)
+#
+# Output: lane string written to stdout
+#   staging              — issue has no milestone (fast lane)
+#   milestone/{slug}     — issue has a milestone (feature lane, slug = lowercased, spaces→hyphens, git-invalid chars stripped)
+#
+# Exit codes: 0 = success, 1 = error (invalid issue, gh auth failure, branch missing, etc.)
+#
+# Branch existence validation:
+#   Both fast-lane (staging) and feature-lane (milestone/{slug}) outputs are validated
+#   against the remote via `git ls-remote`. If the target branch does not exist, the
+#   script exits 1 with a descriptive error. This prevents agents from creating PRs
+#   targeting phantom branches and catches misconfigured branches.staging values early.
+#   Fast-lane staging branch name is read from forge.yaml (branches.staging key),
+#   defaulting to "staging" when forge.yaml is absent or yq is unavailable.
+
+set -euo pipefail
+
+ISSUE_NUMBER="${1:-}"
+GH_REPO_ARGS=()
+
+# Parse arguments: issue number + optional -R flag
+if [ -z "$ISSUE_NUMBER" ]; then
+  echo "ERROR: issue number is required" >&2
+  echo "Usage: classify-lane.sh <issue_number> [-R <owner/repo>]" >&2
+  exit 1
+fi
+
+shift
+while [ $# -gt 0 ]; do
+  case "$1" in
+    -R)
+      if [ $# -lt 2 ]; then
+        echo "ERROR: -R requires a value <owner/repo>" >&2
+        echo "Usage: classify-lane.sh <issue_number> [-R <owner/repo>]" >&2
+        exit 1
+      fi
+      if ! [[ "$2" =~ ^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$ ]]; then
+        echo "ERROR: -R value must be owner/repo format, got: $2" >&2
+        exit 1
+      fi
+      GH_REPO_ARGS=(-R "$2")
+      shift 2
+      ;;
+    *)
+      echo "ERROR: unknown argument: $1" >&2
+      exit 1
+      ;;
+  esac
+done
+
+# Validate issue number is numeric
+if ! [[ "$ISSUE_NUMBER" =~ ^[0-9]+$ ]]; then
+  echo "ERROR: issue number must be numeric, got: $ISSUE_NUMBER" >&2
+  exit 1
+fi
+
+# Fetch milestone title from GitHub
+# gh issue view exits non-zero if the issue does not exist or auth fails
+GH_STDERR_TMP=$(mktemp)
+MILESTONE_TITLE=$(gh issue view "$ISSUE_NUMBER" "${GH_REPO_ARGS[@]}" --json milestone --jq '.milestone.title // empty' 2>"$GH_STDERR_TMP") || {
+  echo "ERROR: failed to fetch issue #$ISSUE_NUMBER — check issue number and repo flag" >&2
+  cat "$GH_STDERR_TMP" >&2
+  rm -f "$GH_STDERR_TMP"
+  exit 1
+}
+rm -f "$GH_STDERR_TMP"
+
+# Export universal script environment so per-repo scripts can call back into universal scripts.
+# Per-repo scripts (.forgedock/scripts/{operation}.sh) source these to delegate to universal ones.
+export FORGEDOCK_SCRIPTS
+FORGEDOCK_SCRIPTS="$(cd "$(dirname "$0")" && pwd)"
+export FORGEDOCK_HOME
+FORGEDOCK_HOME="$(cd "$(dirname "$0")/.." && pwd)"
+
+# Resolve staging branch name from forge.yaml (branches.staging), defaulting to "staging".
+# Uses yq if available; falls back gracefully when forge.yaml is absent or yq is not installed.
+STAGING_BRANCH=$(yq '.branches.staging // "staging"' forge.yaml 2>/dev/null || echo 'staging')
+# yq returns literal "null" when the key exists but is null-valued — treat as default
+[ "$STAGING_BRANCH" = "null" ] && STAGING_BRANCH="staging"
+# Trim any surrounding whitespace or quotes that yq might emit
+STAGING_BRANCH=$(echo "$STAGING_BRANCH" | tr -d '"' | xargs)
+# Final safety net: if somehow empty, use default
+[ -z "$STAGING_BRANCH" ] && STAGING_BRANCH="staging"
+
+# Classify lane based on milestone presence
+if [ -z "$MILESTONE_TITLE" ]; then
+  # Fast lane: validate staging branch exists on remote before returning it.
+  # This mirrors the feature-lane validation below and catches misconfigured
+  # branches.staging values early, with a descriptive error instead of an
+  # opaque failure in the subsequent git worktree add or gh pr create call.
+  if ! git ls-remote --exit-code origin "$STAGING_BRANCH" >/dev/null 2>&1; then
+    echo "ERROR: Fast-lane PR target branch '$STAGING_BRANCH' does not exist on remote 'origin'." >&2
+    echo "       This branch is configured via forge.yaml → branches.staging (default: staging)." >&2
+    echo "       Create the branch first, or update forge.yaml to point to an existing branch." >&2
+    echo "       Run: git push origin HEAD:$STAGING_BRANCH  (from the default branch)" >&2
+    exit 1
+  fi
+  echo "$STAGING_BRANCH"
+else
+  # Slugify: lowercase, spaces → hyphens, strip git-invalid chars, collapse multiple hyphens,
+  # strip leading/trailing hyphens.
+  # `tr -cd 'a-z0-9-'` removes every character that is not a lowercase letter, digit, or hyphen —
+  # this covers all chars forbidden by git-check-ref-format (colons, brackets, parens, etc.).
+  # It runs after space→hyphen so that word boundaries become hyphens before the strip pass,
+  # and before the hyphen-collapse step so consecutive hyphens (produced by stripping special
+  # chars between words) are collapsed into a single hyphen.
+  SLUG=$(echo "$MILESTONE_TITLE" \
+    | tr '[:upper:]' '[:lower:]' \
+    | tr ' ' '-' \
+    | tr -cd 'a-z0-9-' \
+    | sed 's/--*/-/g' \
+    | sed 's/^-//;s/-$//')
+
+  # Guard: empty slug means the milestone title contained no ASCII letters, digits, or hyphens
+  # (e.g. purely Unicode/emoji titles like "🚀✨"). An empty slug would produce LANE="milestone/"
+  # which is an invalid branch reference — catch this early with an actionable error.
+  if [ -z "$SLUG" ]; then
+    echo "ERROR: Milestone title '$MILESTONE_TITLE' produced an empty slug after slugification." >&2
+    echo "       Milestone titles must contain at least one ASCII letter, digit, or hyphen." >&2
+    echo "       Rename the milestone to include an ASCII-safe name (e.g. add a short English suffix)." >&2
+    exit 1
+  fi
+
+  LANE="milestone/$SLUG"
+
+  # Validate that the computed milestone branch exists on the remote.
+  # A non-existent branch means either: (a) the milestone slug was hallucinated, or
+  # (b) the milestone branch has not been created yet. Either way, targeting it would
+  # strand the PR on a phantom branch — hard-fail so a human can investigate.
+  if ! git ls-remote --exit-code origin "$LANE" >/dev/null 2>&1; then
+    echo "ERROR: PR target branch '$LANE' does not exist on remote 'origin'." >&2
+    echo "       Milestone: '$MILESTONE_TITLE' → slug: '$SLUG'" >&2
+    echo "       Create the branch first, or check that the milestone title is correct." >&2
+    echo "       Run: git push origin HEAD:$LANE  (from the base branch)" >&2
+    exit 1
+  fi
+
+  echo "$LANE"
+fi