forgedock 1.0.22 → 1.1.2

package/commands/work-on.md

@@ -11,8 +11,21 @@ argument-hint: [issue number or "next" to pick highest priority]
 
 Orchestrator for the full issue lifecycle: investigate → decompose (if needed) → build → review → merge → close. GitHub issues are the persistent context layer — read existing comments before starting, write structured reports back, use `workflow:*` labels to track state.
 
-**Agent model policy**: Default `model: "sonnet"`. Fallback: `model: "opus"` if Sonnet is rate-limited.
+**Agent model policy**: `model: "sonnet"` (standard tier). Fallback: `model: "opus"` if rate-limited. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.
 **NEVER use plan mode (EnterPlanMode).**
+**NEVER use the Agent tool** — this spec uses `Skill(...)` for sub-phase dispatch. The Agent tool spawns opaque subprocesses that bypass phase protocols, skip FORGE annotations, and cannot be constrained by allowed-tools. Always use `Skill(skill="...", args="...")` for sub-phase invocations.
+
+<!-- FORGE:SPEC_LOADED — work-on.md loaded and active. Agent is bound by this spec. -->
+
+## HARD RULES — READ BEFORE ANYTHING ELSE
+
+1. **Every sub-phase MUST be invoked via `Skill(...)`.** You do NOT implement inline. You invoke `Skill(skill="work-on/investigate", ...)`, `Skill(skill="work-on/build", ...)`, etc. The Skill tool invocation is what triggers label updates, FORGE annotations, and structured output. Without it, the phase has no paper trail.
+
+2. **Write to GitHub after EVERY phase.** Every FORGE annotation (HEARTBEAT, INVESTIGATOR, CONTRACT, BUILDER, etc.) must be posted before the next phase starts. A phase that completes without a GitHub write is effectively invisible to the stall detector and future sessions.
+
+3. **Follow the Universal Phase Dispatcher.** The phase sequence table is the SINGLE source of truth for transitions. Do NOT skip phases, do NOT reorder phases, do NOT treat intermediate completions as terminal. Only the terminal states listed in the Dispatcher allow stopping.
+
+4. **PRs NEVER target `main`.** Target `staging` (fast lane) or `milestone/{slug}` (feature lane). A PR to main is a pipeline violation regardless of what the issue description says.
 
 ### Compaction Resilience
 
@@ -58,6 +71,44 @@ Orchestrator for the full issue lifecycle: investigate → decompose (if needed)
 
 ---
 
+## Spawn-Decision Policy
+
+<!-- FORGE:SPAWN_POLICY — Canonical spawn-decision table. Sibling specs (orchestrate.md, review-pr.md) link to this section. Sub-issues #1276–#1279 reference this table. -->
+
+**Default: run inline.** Every skill, phase, and sub-agent runs inline in the current context unless one of the three criteria below explicitly applies. A sub-agent buys exactly two things — parallelism and context isolation. If neither is needed, forking is waste.
+
+### Spawn-Decision Table
+
+| Row | Criterion | Fork? | Example |
+|-----|-----------|-------|---------|
+| a | **Parallel fan-out** — two or more independent work units can execute concurrently and the total wall time saving justifies the fork overhead | YES — spawn one sub-agent per work unit | `/orchestrate` dispatching multiple `/work-on` agents; `review-pr` spawning domain-specific reviewers in parallel |
+| b | **Fresh-context isolation** — the work unit is a structured review or audit whose value depends on seeing the artefact without the builder's accumulated context bias, AND the review result is load-bearing for the merge decision | YES — spawn a dedicated sub-agent | Phase 5C review-fork when build context is large (see Row c for the quantitative threshold) |
+| c | **Parent context near overflow** — the parent agent has made ≥20 Skill invocations OR the build changed ≥10 files, meaning delegating review inline risks a mid-review token overflow | YES — spawn a fresh sub-agent for review | Phase 5C: `Skill(skill="work-on/review", …)` instead of direct `review-pr` invocation |
+
+**If none of the three rows match: run inline.** Do not fork for convenience, narrative clarity, or to avoid reading a large file. Context cost of a fork (spawning, context reconstruction, result aggregation) is paid every time, even when parallelism or isolation adds no value.
+
+### Depth Budget
+
+**Available depth**: 5 levels (since Claude Code v2.1.172).
+
+**Target depth for a standard run**: ≤ 3.
+
+| Depth | Agent | Notes |
+|-------|-------|-------|
+| 1 | `/orchestrate` | Top-level dispatcher — never implements directly |
+| 2 | `/work-on` | Issue pipeline — runs build phases inline |
+| 3 | Parallel reviewers (Row a/b/c fork) | Domain review agents spawned by Phase 5C |
+
+**Build phases (3A–3M) run inline at depth 2** — they are sequential sub-phases of `/work-on`, not independent agents. Forking the build into a sub-agent (depth 3) is a violation of Row a/b/c unless the build itself fans out independently scoped work units.
+
+**Depth 4–5 are reserved** for exceptional cases (e.g. an orchestrate agent that itself spawns an orchestrate agent for a sub-milestone). Agents that reach depth 4 MUST log a justification comment on the relevant issue.
+
+### Phase 5C Cross-Reference
+
+The existing Phase 5C context-budget check (≥10 changed files OR ≥20 Skill invocations → spawn `work-on/review` sub-agent) is an instance of **Row (c)** above. The quantitative thresholds are not changed — only their framing: they are now a specific application of the spawn-decision table, not a standalone ad-hoc rule.
+
+---
+
 ## Pipeline Rules
 
 - **NEVER merge to main.** PRs target `staging` (fast lane) or `milestone/{slug}` (feature lane).
@@ -193,7 +244,7 @@ gh api repos/{GH_REPO}/issues/{NUMBER}/comments --jq '.[] | {id: .id, author: .u
 
 **Check**: state (closed → STOP), terminal labels (`workflow:merged`/`workflow:invalid` → STOP), existing agent comments (`FORGE:INVESTIGATOR`, `FORGE:DECOMPOSED`, `FORGE:CONTRACT`, `FORGE:BUILDER`, `FORGE:TRAJECTORY`, `FORGE:DECISION_RECORD`), parent tracker status, sub-issue status.
 
-**Determine resume point**: No comments → Phase 1. Investigation exists + ready-to-build → Phase 3. Builder + no PR → Phase 4. Builder + PR open → Phase 5. PR merged + issue open → Phase 6.
+**Determine resume point**: No comments → Phase 1. Investigation exists + ready-to-build → Phase 3. Builder:COMPLETE + no PR → Phase 4. Builder without :COMPLETE (partial/interrupted build) + no PR → Phase 3 (partial-build cleanup). Builder + PR open → Phase 5. PR merged + issue open → Phase 6.
 
 ### 0B.5: Read Phase Checkpoint (MANDATORY — executes before any phase-skip decision)
 
@@ -225,6 +276,35 @@ fi
 
 **Classify lane**: Milestone → feature lane (`milestone/{slug}`). No milestone → fast lane (`staging`).
 
+**Batch issue detection**: <!-- Added: forge#1333 --> If the issue body contains `<!-- FORGE:BATCH_MEMBERS -->`, this is a P3 batch issue. Set `IS_BATCH=true` and extract the member issue list:
+
+```bash
+IS_BATCH=0
+BATCH_MEMBERS=()
+
+BATCH_MEMBERS_BLOCK=$(gh issue view {NUMBER} {GH_FLAG} --json body --jq '.body' \
+  | sed -n '/<!-- FORGE:BATCH_MEMBERS -->/,/<!-- \/FORGE:BATCH_MEMBERS -->/p' 2>/dev/null || true)
+
+if [ -n "$BATCH_MEMBERS_BLOCK" ]; then
+  IS_BATCH=1
+  # Extract member issue numbers (- [ ] #NNN: title lines)
+  BATCH_MEMBERS=($(echo "$BATCH_MEMBERS_BLOCK" | grep -oP '(?<=- \[ \] #)\d+' || true))
+  echo "Batch issue detected — member issues: ${BATCH_MEMBERS[*]}"
+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:
+  ```bash
+  for MEMBER in "${BATCH_MEMBERS[@]}"; do
+    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
+  done
+  ```
+- Member issues are closed in Phase 6 (after PR merge) — NOT before
+
 **Source branch for review-findings**: Parse `**Code branch**: \`{branch}\`` from body. Branch from there, not main.
 
 **Script resolution** — Use the following `resolve_script()` function whenever calling a pipeline script. It enforces the 4-level precedence hierarchy (see `devdocs/project/architecture.md → Script Precedence`):
@@ -673,6 +753,31 @@ case "$TIER" in
 esac
 ```
 
+**Marker gate — Phase 1 exit** (see Marker Gate table in Universal Phase Dispatcher): <!-- forge#1419, forge#1418 -->
+```bash
+INV_MARKER=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '[.[] | select(.body | contains("INVESTIGATION:COMPLETE"))] | length')
+if [ "${INV_MARKER:-0}" -eq 0 ]; then
+  echo "MARKER GATE FAIL: INVESTIGATION:COMPLETE absent — re-invoking work-on/investigate once"
+  Skill(skill="work-on/investigate", args="{NUMBER} --repo {GH_REPO} --gh-flag {GH_FLAG}")
+  INV_MARKER=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+    --jq '[.[] | select(.body | contains("INVESTIGATION:COMPLETE"))] | length')
+  if [ "${INV_MARKER:-0}" -eq 0 ]; then
+    gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:GATE_FAILURE -->
+## Marker Gate Failure — Phase 1 (Investigation)
+
+**Expected marker**: \`INVESTIGATION:COMPLETE\` inside a \`FORGE:INVESTIGATOR\` comment
+**Status**: Absent after subcommand re-invocation. Human review required.
+
+The router re-invoked \`work-on/investigate\` once but the marker was still not posted.
+Inspect the subcommand output above for errors. <!-- forge#1418 -->"
+    gh issue edit {NUMBER} {GH_FLAG} --add-label "needs-human" \
+      --remove-label "workflow:investigating" 2>/dev/null || true
+    exit 1
+  fi
+fi
+```
+
 Write machine-readable phase checkpoint (MUST execute immediately after label transition, before continuing):
 ```bash
 CHECKPOINT_TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
@@ -835,7 +940,19 @@ esac
 
 <!-- FORGE:PHASE_COMPLETE — Entering Phase 3 (Build). See Universal Phase Dispatcher: sub-phases 3A–3M execute in sequence. No sub-phase completion is terminal. -->
 
-**Skip if**: `<!-- FORGE:BUILDER -->` exists.
+**Canonical path**: Sub-phases 3A–3M run **inline** in the current context window for STANDARD and fast-lane issues. This is the single authoritative build topology. `work-on/build.md` and `work-on-monolithic.md` ([BENCHMARK]) describe the same inline model with different levels of detail; they are not separate competing paths. `Skill()` sub-agent spawns for build sub-phases are only permitted under the Spawn-Decision Table Row (c) exception (≥20 Skill invocations or ≥10 files changed before the build). <!-- Added: forge#1276 -->
+
+**Skip if**: `<!-- FORGE:BUILDER:COMPLETE -->` is present in a BUILDER comment. <!-- Added: forge#1305 — require completion marker, not mere presence of BUILDER annotation -->
+
+**Partial build detection**: If `<!-- FORGE:BUILDER -->` exists BUT `<!-- FORGE:BUILDER:COMPLETE -->` is ABSENT → the build was interrupted after implement.md Phase I6 (comment posted) but before validate.md Phase V5 (commit). Delete the partial comment and restart Phase 3 from the top: <!-- Added: forge#1305 -->
+```bash
+PARTIAL_ID=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '[.[] | select(.body | contains("FORGE:BUILDER") and (contains("FORGE:BUILDER:COMPLETE") | not))] | last | .id // ""')
+if [ -n "$PARTIAL_ID" ]; then
+  gh api repos/{GH_REPO}/issues/comments/$PARTIAL_ID -X DELETE
+  echo "Deleted partial FORGE:BUILDER comment (no FORGE:BUILDER:COMPLETE) — restarting build"
+fi
+```
 
 **CRITICAL: You MUST execute ALL sub-phases 3A–3M in order. Sub-phases 3C.5 (context) and 3C.6 (architect) are skipped ONLY for TRIVIAL tasks and Investigation tasks — see Phase 3B for classification. For STANDARD and COMPLEX tasks they post mandatory `FORGE:CONTEXT` and `FORGE:ARCHITECT` comments that Phase 3F reads as its primary input. Skipping them without a TRIVIAL/Investigation classification degrades build quality and causes review findings. After each sub-phase, continue to the next — no sub-phase is terminal.**
 
@@ -857,9 +974,9 @@ gh issue view {NUMBER} {GH_FLAG} --json number,title,body,labels,state,milestone
 gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
   --jq '.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body'
 
-# Check if build already completed
+# Check if build already completed (require FORGE:BUILDER:COMPLETE — not just FORGE:BUILDER)
 gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
-  --jq '.[] | select(.body | contains("FORGE:BUILDER")) | .body'
+  --jq '.[] | select(.body | contains("FORGE:BUILDER:COMPLETE")) | .body'
 
 # Check for existing COMPLEXITY_BAND from a prior run (resume path)
 EXISTING_FAST_PATH=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
@@ -1181,6 +1298,14 @@ esac
 **Determine source branch**:
 - Review-finding → parse `**Code branch**: \`{branch}\`` from issue body; branch from `origin/{branch}`
   - **Milestone review-finding hybrid lane** (Code branch matches `milestone/*`): High-risk lane. NEVER use `git merge` to resolve conflicts — use `git rebase` or `git cherry-pick` only. If conflicts can't be resolved without merge, post comment, add `needs-human`, STOP.
+  - **Missing ref fallback**: After parsing, verify the Code branch still exists on remote. If not (e.g., the source PR's head branch was deleted post-merge before a corrected stamp took effect), fall back to `PR_BASE` (the lane default) and note the fallback:
+    ```bash
+    SOURCE_BRANCH="{CODE_BRANCH_FROM_ISSUE_BODY}"
+    if ! git ls-remote --exit-code origin "$SOURCE_BRANCH" >/dev/null 2>&1; then
+      echo "WARNING: Code branch '$SOURCE_BRANCH' not found on remote — falling back to PR_BASE '$PR_BASE'"
+      SOURCE_BRANCH="$PR_BASE"
+    fi
+    ```
 - Feature lane (has milestone) → branch from `origin/{PR_BASE}` (PR_BASE now set above)
 - Fast lane (no milestone) → branch from `origin/{PR_BASE}` (PR_BASE = `{STAGING_BRANCH}`)
 
@@ -1289,6 +1414,11 @@ if iteration == max_iterations AND not PASS:
 
 All tool commands are read from `forge.yaml → verification.commands`. When a key is absent, the step logs `SKIPPED — not configured in verification.commands` and continues rather than silently passing.
 
+**Track skipped checks** — initialize before any check runs:
+```bash
+VERIFICATION_SKIPPED_CHECKS=""
+```
+
 **Python**:
 ```bash
 cd {WORKTREE_PATH}
@@ -1298,6 +1428,7 @@ if [ -n "$PYTHON_FORMAT" ]; then
     eval "$PYTHON_FORMAT" 2>&1
 else
     echo "SKIPPED — python.format not configured in verification.commands"
+    VERIFICATION_SKIPPED_CHECKS="${VERIFICATION_SKIPPED_CHECKS:+$VERIFICATION_SKIPPED_CHECKS, }python.format"
 fi
 
 # Compile check always runs (no config needed — catches syntax errors)
@@ -1317,6 +1448,7 @@ if [ -n "$TS_FORMAT" ]; then
     eval "$TS_FORMAT" 2>&1
 else
     echo "SKIPPED — typescript.format not configured in verification.commands"
+    VERIFICATION_SKIPPED_CHECKS="${VERIFICATION_SKIPPED_CHECKS:+$VERIFICATION_SKIPPED_CHECKS, }typescript.format"
 fi
 
 if [ -n "$TS_TYPECHECK" ]; then
@@ -1327,6 +1459,7 @@ elif [ -n "$TS_BUILD" ]; then
     TS_EXIT=$?
 else
     echo "SKIPPED — typescript.typecheck and typescript.build not configured in verification.commands"
+    VERIFICATION_SKIPPED_CHECKS="${VERIFICATION_SKIPPED_CHECKS:+$VERIFICATION_SKIPPED_CHECKS, }typescript.typecheck/build"
     TS_EXIT=0
 fi
 ```
@@ -1468,12 +1601,21 @@ Check off completed items, mark phases complete, add PR references.
 
 ### 3M: Post implementation comment
 ```bash
+# Compute verification status from VERIFICATION_SKIPPED_CHECKS (set in Phase 3H)
+if [ -z "$VERIFICATION_SKIPPED_CHECKS" ]; then
+  VERIFICATION_STATUS="✅ All configured verification commands passed"
+else
+  VERIFICATION_STATUS="⚠ Verification NOT run: ${VERIFICATION_SKIPPED_CHECKS} — verification.commands not configured for these checks"
+fi
+
 gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:BUILDER -->
 ## Implementation Complete
 
 **Branch**: \`{BRANCH}\`
 **Commits**: {COMMIT_SHA(S)}
 **Files changed**: {COUNT}
+**Verification Status**: ${VERIFICATION_STATUS}
+**Cost (build phase)**: ${PHASE_COST_USD:-unavailable} (best-effort — session telemetry; omit if unavailable)
 
 ### Approach
 {what was built, key decisions}
@@ -1502,6 +1644,31 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:CHECKPOINT -->
 \`\`\`"
 ```
 
+**Marker gate — Phase 3 exit** (see Marker Gate table in Universal Phase Dispatcher): <!-- forge#1419, forge#1418 -->
+```bash
+BUILD_MARKER=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '[.[] | select(.body | contains("FORGE:BUILDER:COMPLETE"))] | length')
+if [ "${BUILD_MARKER:-0}" -eq 0 ]; then
+  echo "MARKER GATE FAIL: FORGE:BUILDER:COMPLETE absent — re-invoking work-on/build once"
+  Skill(skill="work-on/build", args="{NUMBER} --repo {GH_REPO} --gh-flag {GH_FLAG} --worktree {WORKTREE_PATH} --branch {BRANCH} --base {PR_BASE}")
+  BUILD_MARKER=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+    --jq '[.[] | select(.body | contains("FORGE:BUILDER:COMPLETE"))] | length')
+  if [ "${BUILD_MARKER:-0}" -eq 0 ]; then
+    gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:GATE_FAILURE -->
+## Marker Gate Failure — Phase 3 (Build)
+
+**Expected marker**: \`FORGE:BUILDER:COMPLETE\` inside a \`FORGE:BUILDER\` comment
+**Status**: Absent after subcommand re-invocation. Human review required.
+
+The router re-invoked \`work-on/build\` once but the marker was still not posted.
+Inspect the subcommand output above for errors. <!-- forge#1418 -->"
+    gh issue edit {NUMBER} {GH_FLAG} --add-label "needs-human" \
+      --remove-label "workflow:building" 2>/dev/null || true
+    exit 1
+  fi
+fi
+```
+
 ---
 
 ## Phase 4: PR Creation
@@ -1639,7 +1806,7 @@ PR #${PR_NUMBER} created targeting \`{PR_BASE}\`. Invoking /review-pr with --aut
 
 **Context budget check** (run before invoking review-pr): <!-- Added: forge#93 -->
 
-Large-context sessions that accumulated significant build history cause review-pr to hit the token limit mid-review. Check the accumulated context before delegating:
+Large-context sessions that accumulated significant build history cause review-pr to hit the token limit mid-review. This check is an instance of **Spawn-Decision Policy Row (c)** (parent context near overflow) — see the [Spawn-Decision Table](#spawn-decision-table) for the general policy. Check the accumulated context before delegating:
 
 - If the build changed **≥10 files** OR this agent has made **≥20 Skill invocations** since it started: invoke `work-on/review` as a fresh sub-agent (via `Skill(skill="work-on/review", args="...")`) rather than calling review-pr directly. The sub-agent starts with a clean context window.
 - Otherwise (small build, few skill calls): invoke review-pr directly as below.
@@ -1651,9 +1818,39 @@ Skill(skill="review-pr", args="{PR_NUMBER} --auto-merge --issue {NUMBER} --base
 ```
 
 **Sub-agent invocation** (large builds — ≥10 changed files OR ≥20 Skill invocations):
+
+Before spawning, build a distilled hot-copy of the key annotations the review sub-agent would otherwise re-fetch from GitHub. This reduces gh round-trips in the child without replacing the durable FORGE annotation record. <!-- Added: forge#1277 -->
+
+```bash
+# Hot-copy: extract CONTRACT and ARCHITECT annotation bodies for inline injection
+HOT_CONTRACT=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '[.[] | select(.body | contains("<!-- FORGE:CONTRACT -->"))] | last | .body // ""' 2>/dev/null \
+  | head -60)  # Scope: first 60 lines — captures Proposed Approach + Deliverables table
+
+HOT_ARCHITECT=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '[.[] | select(.body | contains("<!-- FORGE:ARCHITECT -->"))] | last | .body // ""' 2>/dev/null \
+  | head -40)  # Scope: first 40 lines — captures Affected Paths + Implementation Order
+
+# Build inline context block (omit sections where annotation was not found)
+HOT_COPY_BLOCK=""
+if [ -n "$HOT_CONTRACT" ]; then
+  HOT_COPY_BLOCK="${HOT_COPY_BLOCK}
+**HOT COPY — FORGE:CONTRACT** (do not re-fetch; durable record is on the issue):
+${HOT_CONTRACT}"
+fi
+if [ -n "$HOT_ARCHITECT" ]; then
+  HOT_COPY_BLOCK="${HOT_COPY_BLOCK}
+
+**HOT COPY — FORGE:ARCHITECT** (do not re-fetch; durable record is on the issue):
+${HOT_ARCHITECT}"
+fi
 ```
-Skill(skill="work-on/review", args="{NUMBER} --repo {GH_REPO} --gh-flag {GH_FLAG} --worktree {WORKTREE_PATH} --branch {BRANCH} --base {PR_BASE}")
+
 ```
+Skill(skill="work-on/review", args="{NUMBER} --repo {GH_REPO} --gh-flag {GH_FLAG} --worktree {WORKTREE_PATH} --branch {BRANCH} --base {PR_BASE}", context="{HOT_COPY_BLOCK}")
+```
+
+The `{HOT_COPY_BLOCK}` is an optimization that avoids the child re-discovering context already held by the parent. The FORGE annotations on GitHub remain the durable, compaction-safe record. If the hot-copy block is empty (annotations not yet posted), the sub-agent falls back to reading them from GitHub as before.
 
 Review-pr handles: full domain-agent review → post findings as separate issues → merge PR. It does NOT close the issue or clean up the worktree — those run in Phase 6.
 
@@ -1887,6 +2084,13 @@ This check is **audit-only** — it annotates the trajectory for visibility. It
 Post `<!-- FORGE:TRAJECTORY -->` comment with phase-by-phase results table:
 
 ```bash
+# Compute verification row from VERIFICATION_SKIPPED_CHECKS (set in Phase 3H)
+if [ -z "$VERIFICATION_SKIPPED_CHECKS" ]; then
+  VERIFICATION_ROW="✅ Ran"
+else
+  VERIFICATION_ROW="⚠ Skipped — verification.commands not configured for: ${VERIFICATION_SKIPPED_CHECKS}"
+fi
+
 gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:TRAJECTORY -->
 ## Pipeline Trajectory — #{NUMBER}
 
@@ -1897,6 +2101,7 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:TRAJECTORY -->
 | Phase 2: Decomposition | ⏭ Skipped | {reason} |
 | Phase 3: Build | ✅ Complete | Branch: \`{BRANCH}\` |
 | Phase 3G: Quality Gate | ✅ Gate passed | {iterations} iterations |
+| Phase 3H: Verification | ${VERIFICATION_ROW} | |
 | Phase 4–5: Review + PR | {REVIEW_ROW} | PR #{PR_NUMBER} → \`{PR_BASE}\` |
 | Phase 6: Close | ✅ Complete | Issue closed |
 
@@ -1947,6 +2152,40 @@ AGENTS_RUN=$(echo "$REVIEW_SUMMARY" | grep -oE '[0-9]+ agents' | grep -oE '[0-9]
 AGENTS_RUN="${AGENTS_RUN:-0}"
 ```
 
+**Capture best-effort cost signal** from session telemetry before posting GDR. This is best-effort — if the signal is unavailable, the cost block is omitted rather than blocking the pipeline or fabricating a number. Field names align with `bin/runner.mjs` usage accounting from #1295 so downstream tooling shares one schema:
+```bash
+# Best-effort: read per-stage usage from FORGE:BUILDER/FORGE:CONTEXT/FORGE:ARCHITECT phase annotations
+# Source: session telemetry when available (e.g. OTEL_LOG_TOOL_DETAILS, Claude Code usage reporting).
+# If unavailable, set COST_BLOCK to null — the field is omitted from the GDR rather than fabricated.
+COST_INVESTIGATION=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '[.[] | select(.body | contains("FORGE:INVESTIGATOR")) | .body] | last // ""' 2>/dev/null \
+  | grep -oP '(?<=cost_usd: )\S+' | head -1 || echo "")
+COST_BUILD=$(gh api repos/{GH_REPO}/issues/{NUMBER}/comments \
+  --jq '[.[] | select(.body | contains("FORGE:BUILDER")) | .body] | last // ""' 2>/dev/null \
+  | grep -oP '(?<=cost_usd: )\S+' | head -1 || echo "")
+COST_REVIEW=$(gh api repos/{GH_REPO}/issues/{PR_NUMBER}/comments \
+  --jq '[.[] | select(.body | contains("FORGE:REVIEWER")) | .body] | last // ""' 2>/dev/null \
+  | grep -oP '(?<=cost_usd: )\S+' | head -1 || echo "")
+
+# Build cost block JSON only if at least one stage value is present; otherwise null
+if [ -n "$COST_INVESTIGATION" ] || [ -n "$COST_BUILD" ] || [ -n "$COST_REVIEW" ]; then
+  COST_INV_JSON="${COST_INVESTIGATION:-null}"
+  COST_BUILD_JSON="${COST_BUILD:-null}"
+  COST_REVIEW_JSON="${COST_REVIEW:-null}"
+  COST_BLOCK="\"cost\": {
+    \"stages\": {
+      \"investigation\": $COST_INV_JSON,
+      \"build\": $COST_BUILD_JSON,
+      \"review\": $COST_REVIEW_JSON
+    },
+    \"total_usd\": null,
+    \"source\": \"session-telemetry\"
+  },"
+else
+  COST_BLOCK=""
+fi
+```
+
 **Post GDR to PR** (not to issue — PR comment survives as permanent artifact on the merged diff):
 ```bash
 if [ "$GDR_EXISTS" != "true" ] && [ -n "{PR_NUMBER}" ]; then
@@ -1973,6 +2212,7 @@ if [ "$GDR_EXISTS" != "true" ] && [ -n "{PR_NUMBER}" ]; then
     \"confidence\": \"{CONFIDENCE}\",
     \"task_type\": \"{TASK_TYPE}\"
   },
+  ${COST_BLOCK}
   \"context\": {
     \"historical_edges_referenced\": ${REVIEW_FINDING_COUNT},
     \"forge_annotations_read\": [\"FORGE:INVESTIGATOR\", \"FORGE:CONTRACT\", \"FORGE:CONTEXT\", \"FORGE:ARCHITECT\", \"FORGE:BUILDER\"]

package/docs/BRAND.md

@@ -6,7 +6,10 @@ Status of reserved and blocked brand handles across platforms.
 
 | Domain | Status |
 |--------|--------|
-| `forgedock.dev` | **Owned** — canonical marketing and App URL |
+| `forgedock.dev` | **Not owned** — owner-confirmed 2026-07-05 as NOT controlled by RapierCraft Studios; live content is an unrelated third-party product. Retired from ForgeDock branding — do not use anywhere. |
+| `forgedock.io` | **Owned** — owner-confirmed 2026-07-05 as registered to RapierCraft Studios. Canonical ForgeDock domain. Currently a Porkbun parked page; a site/holding page is pending deploy — do not link publicly until the site is live. |
+
+> **Rule**: No public ForgeDock surface (npm homepage, repo description, plugin manifests, docs) may point at a domain until its live content is verified as controlled by RapierCraft Studios.
 
 ## npm
 
@@ -25,9 +28,16 @@ No action needed. The package name was claimed on first publish.
 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.
+**Canonical public App**: **App ID 4051319** (Client ID `Iv23ligZAftI2QDt5CUa`), owner-confirmed
+2026-07-05. Currently owned by the personal `@RapierCraft` account — **to be transferred to the
+`RapierCraftStudios` org** (a public/commercial App should not live on a personal account). Its
+public listing still needs a real description and a homepage that resolves publicly.
+
+Superseded / legacy Apps — do **not** present as the public identity:
+- **3978349** — earlier dev App (registered under RapierCraftStudios, `public: false`); superseded by 4051319.
+- **3731547** (`rapiercraft-forge`) — placeholder description "test"; authored the early public merged PRs but is legacy, its listing being wound down.
+
+Recommended slug when finalizing the org-owned App: `forgedock-ai` (the bare `forgedock` slug is blocked, per above).
 
 ## Social Handles
 
@@ -45,7 +55,8 @@ Social handle registration is an operational task. Reserve handles before public
 
 | Platform | Action |
 |----------|--------|
-| Domain | Done |
+| Domain (forgedock.dev) | Not owned (owner-confirmed 2026-07-05) — retired from branding |
+| Domain (forgedock.io) | Owned — canonical; site deploy pending before public linking |
 | npm | Done |
 | GitHub org slug | Blocked — use variant for App slug |
 | Social handles | Reserve before L1 public launch |

package/docs/CI.md

@@ -20,7 +20,7 @@ The `forgedock-review.yml` workflow template triggers on every pull request (ope
 ## Prerequisites
 
 1. **Anthropic API key** — Claude Code runs against the Anthropic API. Get one at [console.anthropic.com](https://console.anthropic.com).
-2. **ForgeDock installed** — The workflow installs ForgeDock automatically via `npx forgedock install`.
+2. **ForgeDock installed** — The workflow installs ForgeDock automatically via `npx forgedock install --global` (CI uses global install so commands are available system-wide in the runner).
 3. **GitHub Actions enabled** — Standard for all public repos; enabled by default for private repos.
 
 ---
@@ -47,7 +47,7 @@ mkdir -p .github/workflows
 cp "$(npx forgedock which-dir)/templates/workflows/forgedock-review.yml" .github/workflows/forgedock-review.yml
 ```
 
-Or copy it manually — the file is in `~/.claude/commands/../templates/workflows/forgedock-review.yml` after running `npx forgedock install`.
+Or copy it manually — the file is in `~/.claude/commands/../templates/workflows/forgedock-review.yml` after running `npx forgedock install --global`.
 
 ### 3. Commit and push
 

package/docs/CODEX.md

@@ -8,7 +8,7 @@ Shared source:
 - `commands/**/*.md` remains the workflow spec for both runtimes
 
 Claude wrapper:
-- `install.sh` symlinks command files into `~/.claude/commands`
+- `install.sh` symlinks command files into the current project directory by default; pass `--global` to install into `~/.claude/commands/` for all projects
 
 Codex wrapper:
 - `install-codex.sh` generates namespaced skills in `~/.codex/skills`
@@ -84,6 +84,41 @@ trust_level = "trusted"
 
 The installer does not modify global trust settings automatically.
 
+## Conformance Verification
+
+The Codex adapter produces and consumes the same FORGE annotation wire format as the Claude Code path. `scripts/conformance-check.mjs` validates annotation output from any producer (Claude Code, Codex, Cursor, or fixtures) against the FORGE Annotation Protocol v1.0 (`docs/spec/forge-protocol-v1.md`).
+
+### Running the check
+
+Pipe real or fixture-captured Codex-adapter-produced FORGE comments into the script:
+
+```bash
+# Validate a fixture file containing FORGE annotation blocks
+node scripts/conformance-check.mjs docs/spec/fixtures/codex-adapter-annotations.md
+
+# Validate live annotations from a merged PR (replace 1234 with the PR number)
+gh api repos/RapierCraftStudios/ForgeDock/issues/1234/comments \
+  --jq '[.[].body]' \
+  | node scripts/conformance-check.mjs -
+
+# Validate all comments on recent merged PRs (last 10)
+gh pr list -R RapierCraftStudios/ForgeDock --state merged --limit 10 --json number \
+  --jq '.[].number' | while read pr; do
+    gh api "repos/RapierCraftStudios/ForgeDock/issues/$pr/comments" \
+      --jq '[.[].body]'
+done | node scripts/conformance-check.mjs -
+```
+
+Exit code 0 = all annotations conform. Exit code 1 = violations found (see output for details). Unrecognized annotation types are tolerated per spec §7.2 (WARN, not FAIL). An annotation explicitly marked `:PARTIAL` is also reported as a WARN, not a failure — only a fully missing/interrupted completion sentinel fails the exit code. (The reference `validate()` in `@forgedock/protocol` still reports `valid: false` for PARTIAL annotations per §3.2 — that strict signal is for library consumers deciding whether data is safe to treat as complete, not for this CLI's pass/fail gate.)
+
+### Re-running when the adapter changes
+
+Run the conformance check any time `.agents/skills/` adapter files are modified or after a new release of the spec. Conformance gaps found must be documented as follow-up GitHub issues (findings become issues per repo convention), not silently patched inline.
+
+### Verified implementation claim
+
+The Codex adapter path (`.agents/skills/*/SKILL.md` + `commands/*.md`) is a proven second implementation of the FORGE Annotation Protocol. Both the Claude Code path and the Codex adapter path produce annotations that pass `scripts/conformance-check.mjs`. See `docs/spec/forge-protocol-v1.md` Section 11 for the vendor-neutrality acknowledgement.
+
 ## Usage Notes
 
 - Use the installed `forge` skill as the overview/router entrypoint.