forgedock 1.1.1 → 1.1.3

package/commands/work-on/investigate.md

@@ -11,9 +11,11 @@ argument-hint: [issue number] [--repo {owner}/{repo}] [--gh-flag "-R {owner}/{re
 
 Standalone investigation phase for the work-on pipeline. Validates whether an issue is real, determines root cause, posts a structured FORGE:INVESTIGATOR comment to GitHub, and updates workflow labels.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**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).**
 
+<!-- FORGE:SPEC_LOADED — work-on/investigate.md loaded and active. Agent is bound by this spec. -->
+
 ---
 
 ## Inputs
@@ -27,6 +29,67 @@ If called from `work-on`, these are passed through. If invoked standalone, `--re
 
 ---
 
+## Phase 0.5: Memory Retrieval — Prior Run Priors <!-- Added: forge#1316 -->
+
+**Goal**: Before investigating, retrieve the top-k relevant prior pipeline runs from the per-repo memory index. Inject confirmed priors into the investigation context so the pipeline compounds intelligence across runs.
+
+**This phase is non-blocking** — if the memory index is absent or retrieval fails, log the reason and proceed to Phase 1A. Never stall the pipeline for memory.
+
+**Note on Gist visibility (forge#1587)**: The memory-index Gist is created **secret** (see `close.md` Phase C5.2 — no `--public` flag). `gh gist list` and `gh gist view` operate against the authenticated user's own Gists by description/id regardless of public/secret status, so the retrieval steps below work unchanged against a secret Gist. No code change is needed here — this note exists only so a future edit doesn't reintroduce a "must be public to be readable" assumption.
+
+### Step 1: Locate memory index Gist
+
+The memory index is a GitHub Gist tagged `<!-- FORGE:MEMORY_INDEX: {GH_REPO} -->`. Find it:
+
+```bash
+MEMORY_INDEX_URL=$(gh gist list --limit 100 \
+  --jq '.[] | select(.description | contains("FORGE:MEMORY_INDEX: {GH_REPO}")) | .url' 2>/dev/null | head -1)
+
+MEMORY_INDEX_ID=$(gh gist list --limit 100 \
+  --jq '.[] | select(.description | contains("FORGE:MEMORY_INDEX: {GH_REPO}")) | .id' 2>/dev/null | head -1)
+```
+
+If no memory index found: log `[MEMORY] No memory index for {GH_REPO} — starting fresh` and skip to Phase 1A.
+
+### Step 2: Retrieve relevant priors (top-k similarity)
+
+Read the memory index content:
+
+```bash
+MEMORY_CONTENT=$(gh gist view "$MEMORY_INDEX_ID" 2>/dev/null)
+```
+
+The memory index is a newline-delimited list of prior run entries, each formatted as:
+
+```
+MEMORY_ENTRY: issue={N} title="{TITLE}" domain="{DOMAIN_TAGS}" root_cause="{ROOT_CAUSE_SUMMARY}" outcome="{merged|invalid|blocked}" files="{AFFECTED_FILES}" lesson="{KEY_LESSON_ONE_LINE}" timestamp={ISO}
+```
+
+**Retrieve top-3 relevant priors** by matching against the current issue title and body:
+
+1. Extract keywords from the current issue title: lowercase, remove stop words, keep noun/verb tokens
+2. Score each memory entry: +2 for a file path overlap, +1 per keyword match in title/root_cause/lesson
+3. Return the top-3 highest-scoring entries (minimum score ≥ 1 to filter noise)
+
+If no entries score ≥ 1: log `[MEMORY] No relevant priors found` and skip to Phase 1A.
+
+### Step 3: Inject priors into investigation context
+
+For each retrieved prior, emit a structured block that Phase 1B can reference:
+
+```
+[MEMORY PRIOR #{RANK}]
+Issue: #{issue} — {title}
+Root cause: {root_cause}
+Outcome: {outcome}
+Key lesson: {lesson}
+Affected files: {files}
+```
+
+Print these blocks to stdout before Phase 1A begins. During Phase 1B (step 3 — blame analysis and step 5 — pickaxe pass), **explicitly check whether the current issue's suspected symbol or file appears in any prior root cause or affected files**. If a match is found, cite it in the FORGE:INVESTIGATOR comment's History Findings field as a `[MEMORY PRIOR]` hit.
+
+---
+
 ## Phase 1A: Load Issue & Check Resume State
 
 ```bash
@@ -67,10 +130,33 @@ The target repo is `{GH_REPO}` (resolved from `forge.yaml → project`). The wor
 
 If the issue specifies a **Code branch** (`**Code branch**: \`{branch}\``), check out that branch — the affected files may not be on the default branch.
 
+### Code Index Query (run BEFORE any grep exploration)
+
+If `scripts/code-index.sh` exists under `{REPO_PATH}`, query the pre-built symbol/import index first. This yields deterministic answers in one tool call and avoids redundant grep exploration across agents.
+
+```bash
+# Step 0A: Ensure index is current (cache-hit on unchanged HEAD — zero cost if already built)
+bash {REPO_PATH}/scripts/code-index.sh --repo-path {REPO_PATH} 2>/dev/null || true
+
+# Step 0B: Look up the symbol or file named in the issue (replace {SYMBOL} with the relevant name)
+bash {REPO_PATH}/scripts/code-index.sh query --symbol {SYMBOL} --repo-path {REPO_PATH} 2>/dev/null || true
+
+# Step 0C: Find all callers of that symbol
+bash {REPO_PATH}/scripts/code-index.sh query --callers {SYMBOL} --repo-path {REPO_PATH} 2>/dev/null || true
+
+# Step 0D: Find all importers of an affected file
+bash {REPO_PATH}/scripts/code-index.sh query --importers {AFFECTED_FILE} --repo-path {REPO_PATH} 2>/dev/null || true
+
+# Step 0E: Get all files in the affected domain (from issue labels/body)
+bash {REPO_PATH}/scripts/code-index.sh query --domain {DOMAIN_LABEL} --repo-path {REPO_PATH} 2>/dev/null || true
+```
+
+**Fallback**: If `scripts/code-index.sh` is absent or returns no results, proceed with standard grep exploration below. The index is an acceleration layer — its absence never blocks investigation.
+
 ### Investigation steps
 
 1. **Check the right branch** — read from the branch specified in the issue body (`**Code branch**: \`{branch}\``) if present
-2. **Read domain files** — start with the key files for the affected domain
+2. **Read domain files** — start with the key files for the affected domain (use index query results from Step 0E as the file list; fall back to directory inspection if index is absent)
 3. **Verify claims** — does the code actually have the problem described?
 4. **Git blame** — trace when/why the relevant code was written. Run bounded, local commands (no network round-trip):
    ```bash
@@ -106,6 +192,19 @@ If the issue specifies a **Code branch** (`**Code branch**: \`{branch}\``), chec
 
 The comment MUST include `<!-- INVESTIGATION:COMPLETE -->` at the very end, AFTER all required sections are present. This marker signals the investigation finished successfully.
 
+Before posting, resolve the attribution annotation link from `forge.yaml`:
+
+```bash
+ATTRIBUTION_ANNOTATION_LINK=$(grep -A5 "^attribution:" forge.yaml 2>/dev/null | grep "annotation_link:" | awk '{print $2}' | tr -d '"' || echo "false")
+ANNOTATION_LINK_FOOTER=""
+if [ "$ATTRIBUTION_ANNOTATION_LINK" = "true" ]; then
+  ANNOTATION_LINK_FOOTER="
+
+---
+*Pipeline powered by [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock)*"
+fi
+```
+
 ```bash
 gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:INVESTIGATOR -->
 ## Investigation Report
@@ -146,6 +245,22 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:INVESTIGATOR -->
 **{YES|NO}** — {reason}
 {if YES: proposed sub-issues with titles and dependencies}
 
+### Acceptance Spec
+{For each item in the issue's ## Acceptance Criteria section, emit one machine-checkable check line using the format below. If the issue has no Acceptance Criteria section, derive checks from the Recommendation above. Each check MUST be specific, observable, and testable — not vague prose. Checks are consumed by build/validate Phase B6.5 as the merge gate.}
+
+```
+ACCEPTANCE_CHECK: id={ac-1} type={exists|contains|command|behavior} target={file_path|command|url} matcher={string|exit_0|regex} description={one-line human description}
+ACCEPTANCE_CHECK: id={ac-2} type={exists|contains|command|behavior} target={file_path|command|url} matcher={string|exit_0|regex} description={one-line human description}
+```
+
+**Check types**:
+- `exists` — assert a file or directory exists (`target` = path, `matcher` = ignored)
+- `contains` — assert a file contains a string or regex (`target` = file path, `matcher` = string/regex)
+- `command` — run a shell command and assert exit 0 (`target` = shell command, `matcher` = `exit_0`)
+- `behavior` — assert a runtime/observable behavior via shell command (`target` = shell command, `matcher` = expected output string or regex)
+
+**Skipping**: if the issue has no verifiable acceptance criteria and none can be derived from the recommendation, emit a single sentinel: `ACCEPTANCE_CHECK: id=ac-skip type=skipped target=none matcher=none description=No machine-checkable criteria available — human review required`
+${ANNOTATION_LINK_FOOTER}
 <!-- INVESTIGATION:COMPLETE -->"
 ```
 

package/commands/work-on/review.md

@@ -12,9 +12,11 @@ argument-hint: [issue number] [--repo GH_REPO] [--gh-flag GH_FLAG] [--worktree P
 **Invoked by**: `work-on.md` Phase 4–5, after `build/validate.md` returns `GATE_PASSED: true`.
 **Output**: Push branch, create PR, invoke /review-pr --auto-merge, return result to caller.
 
-**Agent model policy**: Default `model: "sonnet"`. If Sonnet is rate-limited, fall back to `model: "opus"`.
+**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).**
 
+<!-- FORGE:SPEC_LOADED — work-on/review.md loaded and active. Agent is bound by this spec. -->
+
 ---
 
 ## Inputs
@@ -146,7 +148,21 @@ Derive from issue title:
 - `docs(...):`  → `Docs: {description}`
 - fallback: use issue title as-is
 
-### R2B: Create PR
+### R2B: Resolve attribution footer (optional)
+
+Before creating the PR, check `forge.yaml → attribution.pr_footer`:
+
+```bash
+ATTRIBUTION_PR_FOOTER=$(grep -A5 "^attribution:" forge.yaml 2>/dev/null | grep "pr_footer:" | awk '{print $2}' | tr -d '"' || echo "false")
+```
+
+If `ATTRIBUTION_PR_FOOTER` is `true`, append the following footer to the PR body (once — never duplicate on retries):
+
+```
+> Orchestrated with [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) — state, scheduling, review, and memory on GitHub.
+```
+
+### R2C: Create PR
 
 ```bash
 gh pr create {GH_FLAG} \
@@ -170,18 +186,22 @@ gh pr create {GH_FLAG} \
 Closes #{NUMBER}
 
 **Implementation branch**: \`{BRANCH}\`
-**Base**: \`{PR_BASE}\`"
+**Base**: \`{PR_BASE}\`
+{IF_ATTRIBUTION_PR_FOOTER_TRUE:
+> Orchestrated with [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) — state, scheduling, review, and memory on GitHub.}"
 ```
 
 **Note**: `Closes #{NUMBER}` documents intent but does NOT auto-close for non-default-branch PRs. The close subcommand handles explicit closure after merge.
 
+**Attribution guard**: The footer line is appended once at PR creation. If the PR already exists (resume path), do NOT append the footer again — check the existing PR body first.
+
 If PR creation fails because a PR already exists for this branch:
 ```bash
 gh pr list {GH_FLAG} --head {BRANCH} --json number,url --jq '.[0]'
 ```
 Use the existing PR number and continue.
 
-### R2C: Update labels
+### R2D: Update labels
 
 ```bash
 gh issue edit {NUMBER} {GH_FLAG} \

package/commands/work-on-monolithic.md

@@ -12,9 +12,14 @@ install: internal
 
 Orchestrator for the full issue lifecycle: investigate → 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).**
 
+> **Relationship to `/work-on` (canonical path)**: This file is a `[BENCHMARK]` reference variant. It documents the same inline-execution model that `/work-on` Phase 3 and `work-on/build.md` use as their **default** for STANDARD/fast-lane issues — all build sub-phases (context → architect → implement → validate) run inline in the current context window with no `Skill()` sub-agent spawns. The difference is that this file omits the worktree lifecycle, `FORGE:CONTRACT` posting, and the Spawn-Decision exception path for large builds. Use `/work-on` for production runs; use this file for baseline benchmarking or when comparing single-prompt token cost against the modular path. See `work-on/build.md` (Canonical Build Path section) for the reconciled build topology. <!-- Added: forge#1276 -->
+**NEVER use the Agent tool** — this spec executes all phases inline as a single monolithic prompt. The Agent tool would spawn a subprocess outside this context, breaking the single-prompt contract and losing all accumulated pipeline state.
+
+<!-- FORGE:SPEC_LOADED — work-on-monolithic.md loaded and active. Agent is bound by this spec. -->
+
 ### Compaction Resilience
 
 1. Write state to GitHub after EVERY significant step
@@ -65,7 +70,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:CONTRACT`, `FORGE:BUILDER`, `FORGE:TRAJECTORY`), parent tracker 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 → close issue.
+**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 → close issue.
 
 **Classify lane**: Milestone → feature lane (`milestone/{slug}`). No milestone → fast lane (`staging`).
 

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,6 +940,8 @@ 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. -->
 
+**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 -->
@@ -1508,6 +1615,7 @@ gh issue comment {NUMBER} {GH_FLAG} --body "<!-- FORGE:BUILDER -->
 **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}
@@ -1536,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
@@ -1673,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.
@@ -1685,10 +1818,40 @@ 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.
 
 ### 5D: Verify merge and close (recovery)
@@ -1989,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
@@ -2015,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,8 +6,8 @@ Status of reserved and blocked brand handles across platforms.
 
 | Domain | Status |
 |--------|--------|
-| `forgedock.dev` | **Unverified** — live content (2026-07-04) is a third-party product unrelated to ForgeDock; registrar verification pending. Do not use as a public-facing link until resolved. |
-| `forgedock.io` | **Parked** — Porkbun parked page, HTTP-only (HTTPS does not connect). Not controlled by RapierCraft Studios. Do not use as a public-facing link. |
+| `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.
 
@@ -28,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
 
@@ -48,8 +55,8 @@ Social handle registration is an operational task. Reserve handles before public
 
 | Platform | Action |
 |----------|--------|
-| Domain (forgedock.dev) | Unverified — registrar check pending; do not use as live surface |
-| Domain (forgedock.io) | Parked — not controlled by RapierCraft Studios; do not use as live surface |
+| 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.
 
 ---
@@ -37,6 +37,20 @@ In your repository: **Settings → Secrets and variables → Actions → New rep
 
 Never commit the API key to your repository. GitHub Actions masks secrets in logs, but only secrets stored via Settings are protected.
 
+### 1a. Set the deploy-gate repository variable
+
+If you use the `gate-marker-check` workflow (which enforces that every staging→main PR was reviewed by `/review-pr-staging` before merge), you must also set a **repository variable** that tells the gate which GitHub logins are authorized to post gate markers.
+
+In your repository: **Settings → Secrets and variables → Actions → Variables → New repository variable**
+
+| Name | Value |
+|------|-------|
+| `FORGE_TRUSTED_MARKER_AUTHORS` | Comma-separated list of GitHub logins authorized to run `/review-pr-staging` (e.g. `your-bot-login,your-personal-login`) |
+
+**Why this is required**: The gate-marker-check workflow verifies that gate markers (`FORGE:GATE_PASS` / `FORGE:GATE_FAILURE`) were posted by a trusted author — not hand-typed by an external contributor. If this variable is unset or empty, the gate rejects every marker and blocks all staging→main PRs. The gate will fail immediately with setup instructions rather than waiting 30 minutes and producing a cryptic timeout error.
+
+**What logins to include**: Add the GitHub login of the bot or user account that runs Claude Code sessions (the account that posts `/review-pr-staging` output). For automated CI setups this is typically the bot account; for manual runs it is your personal GitHub login.
+
 ### 2. Copy the workflow template
 
 Copy `templates/workflows/forgedock-review.yml` from your ForgeDock installation to your repository:
@@ -47,7 +61,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