forgedock 1.1.8 → 1.1.9

package/docs/CONFIG.md

@@ -42,6 +42,7 @@ The default (no flags) is the annotated review screen: detection runs, AI enrich
 | [`project`](#project-required) | **Yes** | GitHub identity (owner, repo, name) |
 | [`paths`](#paths-required) | **Yes** | Local filesystem locations |
 | [`branches`](#branches-required) | **Yes** | Branch naming conventions |
+| [`agents`](#agents-optional) | No | Default model for pipeline agents |
 | [`repos`](#repos-optional) | No | Multi-repository routing |
 | [`project_board`](#project_board-optional) | No | GitHub Projects v2 integration |
 | [`services`](#services-optional) | No | External service URLs and IDs |
@@ -125,6 +126,40 @@ branches:
 
 ---
 
+## `agents` (OPTIONAL)
+
+Model configuration for pipeline agents. `default_model` governs the main agent — the one you invoke directly (`work-on`, `orchestrate`, `review-pr`, etc.), referenced by every command spec's "Agent model policy" line. `subagent_model` governs the **child** sub-agents that a top-level command spawns internally — e.g. `/orchestrate`'s per-issue `/work-on` agents, `/review-pr`'s domain persona reviewers, `/analytics`'s parallel data-collection agents, `/incident-response`'s validation/root-cause agents.
+
+```yaml
+agents:
+  default_model: "sonnet"
+  subagent_model: "sonnet"
+```
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `default_model` | string | No | `"sonnet"` | Short alias — `"sonnet"`, `"opus"`, or `"haiku"` — the same values the Agent/Task tool's `model` parameter accepts. This is the only form that works for interactive command-spec sub-agent spawning. |
+| `subagent_model` | string | No | `default_model`, else `"sonnet"` | Short alias, same accepted values as `default_model`. Overrides the model used for child agents spawned internally by a top-level command (see above). Omit to inherit `default_model`. |
+
+**Resolution order** (highest precedence first):
+1. `--model <id>` — CLI flag, `npx forgedock run` only (headless; main agent only).
+2. `FORGEDOCK_MODEL` env var — headless runner only (main agent only).
+3. `agents.default_model` — this field. Governs the main agent.
+4. Hardcoded default — `"sonnet"` for interactive agents, `"claude-sonnet-5"` for the headless runner (`bin/runner.mjs`'s `DEFAULT_MODEL`).
+
+**Sub-agent resolution order** (highest precedence first):
+1. `agents.subagent_model` — this field. Governs child agents spawned by a top-level command.
+2. `agents.default_model` — falls back here when `subagent_model` is unset.
+3. Hardcoded default — `"sonnet"`.
+
+**Headless runner note**: `bin/runner.mjs` (`npx forgedock run`, used for CI/headless invocations) calls the Anthropic SDK directly and also accepts a full Anthropic model ID here as a pass-through escape hatch (e.g. `"claude-opus-4-6"`). A full model ID does **not** work for interactive Agent/Task tool calls in command specs — those only accept the short-alias enum (`sonnet`/`opus`/`haiku`/`fable`). Prefer the short alias unless you specifically need a headless-only override. `subagent_model` is interactive-only — it has no headless-runner equivalent, since the headless runner does not spawn child sub-agents.
+
+Projects without this section see no behavior change — everything defaults exactly as it did before these fields existed.
+
+**Commands that use this section**: all commands with an "Agent model policy" line (`default_model`, nearly every command spec) and all commands that spawn internal sub-agents — `orchestrate`, `review-pr`, `analytics`, `incident-response` (`subagent_model`).
+
+---
+
 ## `repos` (OPTIONAL)
 
 Multi-repository routing. Use this when your project spans multiple GitHub repositories and you want to route issues to satellite repos by prefix.
@@ -571,6 +606,26 @@ Colors are grouped by semantic meaning:
 
 ---
 
+## GitHub App Install
+
+During `npx forgedock`, the installer prompts you to install the ForgeDock GitHub App (`rapiercraft-forgedock`) on your account or org.
+
+**What installing it does today**: registers the app against the account/org you choose. That's it.
+
+**What it does NOT do (yet)**:
+- It does **not** create a bot token. GitHub App *installation* tokens can only be minted with the app's private key, and that key is held solely by RapierCraft Studios (the app's owner) — your installation grants *your* installation ID against *RapierCraft's* app, not a key you can use yourself.
+- It does **not** auto-refresh anything, and there is no background process managing token expiry.
+- It does **not** change which `gh` auth context pipeline commands (`/work-on`, `/orchestrate`, etc.) use. Every pipeline `gh` call always uses whatever auth is currently active in your shell — your personal token unless you've manually configured something else.
+- It does **not** wire up webhook-driven "automatic pipeline triggers" — no webhook receiver exists yet.
+
+**Why this matters**: GitHub App installation tokens get materially higher API rate limits than a personal access token, and actions taken with them are attributed to the bot (`rapiercraft-forgedock[bot]`) rather than your personal account. Those benefits are real, but delivering them to arbitrary installers requires a hosted token-minting backend service that doesn't exist yet (tracked as forge#1890). Installing the app today is safe and free, but on its own changes nothing about how the pipeline authenticates.
+
+`npx forgedock doctor` reports this status explicitly (Check 12: "GitHub App / bot token") so you aren't left guessing whether a bot token is active.
+
+**If you want bot-token behavior today**: you'd need to register your own GitHub App (with your own private key), and drive your own token-refresh loop (mint an installation token via the app's `/app/installations/{id}/access_tokens` API, then `gh auth login --with-token`, repeating before the ~1-hour expiry). This is an advanced, self-hosted setup — ForgeDock does not package a generic version of this for you.
+
+---
+
 ## `marketing` (OPTIONAL)
 
 Controls opt-in growth features such as 'Powered by ForgeDock' footers on PR descriptions created by the pipeline.
@@ -730,6 +785,53 @@ See [Per-Directory State Registry](#per-directory-state-registry) below for how
 
 ---
 
+## Persisted Toolset Home (`~/.forge/`)
+
+`npx`/`npm` never installs `forgedock` to a stable location on your machine — it resolves to wherever `npx`'s cache (or a global npm install, or a git clone) happens to physically live. Historically, `~/.claude/commands/` and the SessionStart hook's script path were symlinked **directly** from that ephemeral location. When npm/npx (or the OS) later evicted its cache, those symlinks silently dangled — Claude Code sessions stopped getting ForgeDock context with no error shown.
+
+As of this feature, every `npx forgedock` (or `npx forgedock update`) run copies ForgeDock's own installable payload into a stable, version-independent home:
+
+```
+~/.forge/
+  bin/          — the same bin/ tree bundled with the resolved package (hooks, CLI entry points)
+  commands/     — the slash-command specs (.md)
+  scripts/      — the universal pipeline-agent scripts (classify-lane.sh, etc.)
+  templates/    — scaffold templates (e.g. the demo repo)
+  version       — plain-text file containing the source package's version (e.g. "1.7.2")
+```
+
+`~/.claude/commands/` symlinks and the SessionStart hook's baked-in script path are then built from **this** copy, not the original ephemeral source — so they keep working even after the npm/npx cache that originally served them is cleared.
+
+### When It Runs
+
+| Command | Behavior |
+|---------|----------|
+| `npx forgedock` / `npx forgedock install` | Copies the resolved package's payload into `~/.forge/` (content-compared — unchanged files are never rewritten) before linking commands, then links from `~/.forge/`, not the original source |
+| `npx forgedock init` | Does not touch `~/.forge/` — `init` only writes `forge.yaml`, it never installs commands |
+| `npx forgedock update` (npm/npx install) | Refreshes `~/.forge/` from whatever the currently-resolved package looks like, then relinks |
+| `npx forgedock update` (git-clone install) | **Does not** touch `~/.forge/` at all — see the exemption below |
+| `npx forgedock doctor` | Reports `~/.forge/version` and confirms `~/.forge/{bin,commands,scripts,templates}` exist |
+
+The copy is idempotent: files whose content is already byte-identical are never rewritten, so steady-state re-runs are fast and don't generate false "updated" noise.
+
+### The Git-Clone Exemption
+
+If you run ForgeDock from a git clone (or a git worktree) of the repo itself — the development/self-hosted install mode — nothing is copied into `~/.forge/`. A git clone is already a stable, user-owned location; copying it into `~/.forge/` and linking commands from the copy instead of the clone would silently disconnect `git pull` (or `npx forgedock update`'s git branch) from what's actually linked into `~/.claude/commands/`. So:
+
+- `~/.claude/commands/` continues to symlink directly from the clone, exactly as before this feature.
+- `~/.forge/{bin,commands,scripts,templates}` correctly does **not** exist for this install mode — `npx forgedock doctor` treats that absence as healthy, not a warning.
+
+### Not the Same as `~/.forge/{runs,index}`
+
+`~/.forge/` also hosts two **unrelated, pre-existing** directories used by other parts of ForgeDock:
+
+- `~/.forge/runs/` — durable engine run state for `npx forgedock run-issue` / `resume-stalled` (see `bin/engine.mjs`).
+- `~/.forge/index/` — the `recall` knowledge index (see `bin/recall.mjs`, `docs/FORGE-PROTOCOL.md`).
+
+These are **engine data**, not the toolset itself, and this feature does not read, write, or otherwise change them. `~/.forge/{bin,commands,scripts,templates,version}` (this section) and `~/.forge/{runs,index}` (engine data) are unrelated siblings that merely happen to live under the same `~/.forge/` root — don't conflate the two when reading `~/.forge/`'s contents.
+
+---
+
 ## Per-Directory State Registry
 
 ForgeDock tracks per-directory opt-out state in a central registry file on the local machine.
@@ -810,6 +912,90 @@ npx forgedock status [dir]   # Show a directory's resolved state (default: cwd)
 
 ---
 
+## Install Receipt
+
+ForgeDock writes a machine-readable receipt of what the last install or update actually did, so debugging drift (wrong commands installed, wrong tier, stale hooks) can start from a recorded fact instead of re-deriving state from scratch.
+
+### Receipt File Location
+
+```
+~/.forge/install-receipt.json
+```
+
+The directory (`~/.forge/`) is created automatically on first write with `mkdir(..., { recursive: true })`. The file is never committed to version control — it is per-user, per-machine state.
+
+### When It's Written
+
+- After every successful `npx forgedock install` (end of the onboarding journey, right after the "Forged." celebration screen).
+- After every `npx forgedock update` — both the git-clone branch (fast-forward pull) and the npm branch (version-check advisory) route through the same repair step (`relinkAndHint()`), so the receipt is refreshed either way.
+
+The write is best-effort and never blocks or fails the install/update it records: any error (permission denied, disk full, unusual `FORGE_HOME` layout) degrades silently to a no-op, matching the fail-open contract already used by the command-manifest and hook-registration steps.
+
+### Receipt Schema
+
+```json
+{
+  "schemaVersion": 1,
+  "timestamp": "2026-07-10T12:00:00.000Z",
+  "forgedockVersion": "1.1.6",
+  "installMode": "npm",
+  "forgeHome": "/home/user/.npm/_npx/abc123/node_modules/forgedock",
+  "cwd": "/home/user/projects/my-repo",
+  "platform": {
+    "platform": "linux",
+    "platformLabel": "Linux",
+    "isWSL": false,
+    "wslDistro": null,
+    "shell": "bash"
+  },
+  "tier": "core",
+  "commands": {
+    "count": 42,
+    "list": ["work-on", "review-pr", "quality-gate", "orchestrate/phase-1-resolve"]
+  },
+  "hooks": {
+    "sessionStart": "registered",
+    "preToolUse": "registered",
+    "subagentStopEnforce": null
+  },
+  "forgeYaml": {
+    "present": true,
+    "validShape": true
+  }
+}
+```
+
+| Field | Type | Description |
+|-------|------|--------------|
+| `schemaVersion` | number | Schema version — currently `1` |
+| `timestamp` | string | ISO-8601 timestamp of this install/update |
+| `forgedockVersion` | string | `version` field from `{forgeHome}/package.json` (empty string if unreadable) |
+| `installMode` | `"npm"` \| `"git-clone"` | Detected from whether `{forgeHome}/.git` exists — same predicate `update()` already uses to choose its update strategy |
+| `forgeHome` | string | Absolute path to the ForgeDock package install (`FORGE_HOME`) |
+| `cwd` | string | Absolute path to the project directory the command was run in |
+| `platform` | object | `detectEnvironment()`'s output — platform, human label, WSL status/distro, detected shell |
+| `tier` | `"core"` \| `"extras"` | Whether `--extras` was passed (opt-in command tier, see `install: extras` frontmatter) |
+| `commands` | object | `count` and `list` (relative slash-command names) of everything installed for the resolved tier, sourced from `findMarkdownFiles()` — never a separately maintained list |
+| `hooks.sessionStart` | string \| null | SessionStart hook registration status (`"registered"`, `"already"`, `"skipped-malformed"`) |
+| `hooks.preToolUse` | string \| null | PreToolUse enforcement hook status, or `null` when the installed Claude Code version doesn't support it |
+| `hooks.subagentStopEnforce` | string \| null | Cleanup status of the (retired) SubagentStop enforce hook |
+| `forgeYaml.present` | boolean | Whether `forge.yaml` exists in `cwd` at receipt-write time |
+| `forgeYaml.validShape` | boolean | Whether `forge.yaml` contains the 3 required top-level sections (`project:`, `paths:`, `branches:`) — a lightweight regex check, not a full YAML parse |
+
+### No PII or Secrets
+
+The receipt never contains `process.env` values, GitHub tokens, API keys, or the contents of `forge.yaml` — only the `present`/`validShape` booleans above. Absolute filesystem paths (`forgeHome`, `cwd`) are included for drift debugging; they typically contain the OS username but nothing more sensitive, consistent with other per-machine ForgeDock state (e.g. `registry.json`'s path-keyed entries, see above).
+
+### Reading the Receipt
+
+```bash
+cat ~/.forge/install-receipt.json
+```
+
+There is no CLI subcommand to read it yet — `doctor()` reading the receipt to detect drift is a deliberately deferred stretch goal, not part of this feature.
+
+---
+
 ## Complete Example
 
 See [`forge.yaml.example`](../forge.yaml.example) at the repository root for a fully annotated example covering all sections.

package/docs/site/command-reference.md

@@ -592,7 +592,37 @@ These are invoked automatically by `/work-on` but can also be run standalone.
 | `/work-on/review` | Phase 5 | Review only |
 | `/work-on/close` | Phase 6 | Close & cleanup only |
 | `/work-on/decompose` | Phase 2 | Decompose into sub-issues |
-| `/review-pr-agents` | PR review | Agent catalog read by `/review-pr` during dispatch (not user-invokable directly) |
+| `/work-on/remediate` | Phase 0A.1 | Remediate a `needs-human` PR: fix findings, re-review, re-gate (`/work-on <pr> --remediate`) |
+| `/review-pr-agents` | PR review | Agent catalog router read by `/review-pr` during dispatch (not user-invokable directly) |
+
+`/review-pr` (core) reads the following per-persona and shared-protocol templates from `commands/review-pr-agents/` at runtime during Phase 3C dispatch. They ship as part of every install alongside `/review-pr` — not user-invokable directly.
+
+| Command | Phase | Purpose |
+|---------|-------|---------|
+| `/review-pr-agents/protocols` | Phase 3C | Shared Evidence-Based/Structured-Findings/Input-Scoping protocols read before every persona template |
+| `/review-pr-agents/security` | Phase 3C | General security & quality scan (always runs) |
+| `/review-pr-agents/auth` | Phase 3C | Auth conventions auditor (AUTH domain) |
+| `/review-pr-agents/billing` | Phase 3C | Billing/payments auditor (BILLING domain) |
+| `/review-pr-agents/concurrency` | Phase 3C | Concurrency/locking auditor (CONCURRENCY domain) |
+| `/review-pr-agents/database` | Phase 3C | Database/migration auditor (DATABASE domain) |
+| `/review-pr-agents/frontend` | Phase 3C | Frontend conventions auditor (FRONTEND domain) |
+| `/review-pr-agents/infra` | Phase 3C | Infra/deploy auditor (INFRA domain) |
+| `/review-pr-agents/api` | Phase 3C | API/SDK contract auditor (API domain) |
+| `/review-pr-agents/scraper` | Phase 3C | Scraping/anti-bot auditor (SCRAPING domain) |
+
+`/orchestrate` (core) reads the following phase files from `commands/orchestrate/` at runtime. They ship as part of every install alongside `/orchestrate` — not user-invokable directly.
+
+| Command | Phase | Purpose |
+|---------|-------|---------|
+| `/orchestrate/config` | Phase 0 | Hard rules, config resolution, multi-repo support — read first |
+| `/orchestrate/phase-1-resolve` | Phase 1 | Resolve the issue set from input |
+| `/orchestrate/phase-2-triage` | Phase 2 | Investigation-first triage, Wave 0 |
+| `/orchestrate/phase-2.5-synthesis` | Phase 2.5 | Investigation synthesis and deconfliction |
+| `/orchestrate/phase-3-dependency` | Phase 3 | Dependency analysis, DAG construction, execution plan |
+| `/orchestrate/phase-4-execution` | Phase 4 | Streaming DAG execution, agent dispatch, stall detection |
+| `/orchestrate/phase-5-cleanup` | Phase 5 | Post-batch cleanup sweep and agent audit |
+| `/orchestrate/phase-6-report` | Phase 6 | Consolidated report and pipeline summary |
+| `/orchestrate/safety` | Reference | Safety rules and examples |
 
 ---
 

package/docs/site/getting-started.md

@@ -49,9 +49,9 @@ Run the installer with `npx` from your project directory:
 npx forgedock
 ```
 
-This installs all 25+ ForgeDock command specs into the current project (project-scoped by default) — making them available as slash commands in Claude Code sessions for this repo.
+This installs all 25+ ForgeDock command specs into `~/.claude/commands/` — making them available as slash commands in every Claude Code session on this machine, not just this repo.
 
-> **Want commands available across all projects on this machine?** Use `npx forgedock --global` to install into `~/.claude/commands/` instead. Project-scoped is the default for new installs; use `--global` as an explicit opt-in.
+> Install is always global. `--global` is still accepted on the command line for backward compatibility, but it's a no-op — `npx forgedock` and `npx forgedock --global` do exactly the same thing.
 
 **Verify the install:**
 
@@ -75,7 +75,7 @@ ForgeDock Doctor — Installation Health Check
 
 It exits `0` when everything passes and `1` if any check fails, so you can also use it in CI.
 
-> Prefer a quick spot-check? `ls .claude/commands/ | grep -E "work-on|review-pr|quality-gate"` should list `work-on.md`, `review-pr.md`, and `quality-gate.md`. (For a `--global` install, use `ls ~/.claude/commands/` instead.)
+> Prefer a quick spot-check? `ls ~/.claude/commands/ | grep -E "work-on|review-pr|quality-gate"` should list `work-on.md`, `review-pr.md`, and `quality-gate.md`.
 
 ---
 
@@ -205,7 +205,7 @@ The quick fixes below cover the most common first-run issues. For the full list
 
 **`/work-on` not found in Claude Code**
 
-The symlink wasn't created. Re-run `npx forgedock` and check `ls .claude/commands/` (project-scoped, default) or `ls ~/.claude/commands/` (if you used `--global`).
+The symlink wasn't created. Re-run `npx forgedock` and check `ls ~/.claude/commands/`.
 
 **`forge.yaml` not found**
 
@@ -221,37 +221,12 @@ The issue may have been marked `workflow:invalid`. Check the issue comments for
 
 ---
 
-## Migrating from a global install
+## A note on install location
 
-If you installed ForgeDock before project-scoped became the default (prior to v1.0.22), your commands live in `~/.claude/commands/`. You have two options:
-
-**Option A: Keep the global install (no action required)**
-
-Add `--global` to all future `npx forgedock install/update/uninstall/doctor` calls. Your existing setup is unchanged.
-
-```bash
-npx forgedock update --global   # re-link after a version bump
-```
-
-**Option B: Switch to project-scoped (recommended for per-repo version control)**
-
-1. Remove the global install:
-   ```bash
-   npx forgedock uninstall --global
-   ```
-2. In each repo you want ForgeDock in, run a fresh project-scoped install:
-   ```bash
-   cd /path/to/your-repo
-   npx forgedock install
-   ```
-3. Verify:
-   ```bash
-   npx forgedock doctor      # auto-detects project-scoped install
-   ```
-
-**Detect your current mode:**
+ForgeDock briefly shipped a project-scoped-by-default install mode. It was backed out after causing a "split-brain" bug (`doctor`/`status` assumed project-scoped while the installer still wrote globally — [#1589](https://github.com/RapierCraftStudios/ForgeDock/issues/1589)), so install has always been global (`~/.claude/commands/`) since. If you have scripts or CI that still pass `--global`, there's nothing to change — it's accepted for backward compatibility and does exactly what a plain `npx forgedock` does.
 
 ```bash
-npx forgedock doctor          # prints "Mode: project-scoped" or "Mode: global"
-npx forgedock status          # shows install path
+npx forgedock update           # re-link after a version bump
+npx forgedock doctor           # confirm the install is healthy
+npx forgedock status           # shows the install path (~/.claude/commands/)
 ```

package/docs/site/index.md

@@ -56,7 +56,7 @@ No more coordinating between agent sessions. No more lost context. No more start
 npx forgedock
 ```
 
-Installs commands into the current project (project-scoped by default). Add `--global` to install into `~/.claude/commands/` for all projects on this machine.
+Installs commands into `~/.claude/commands/`, available in every Claude Code session on this machine. `--global` is still accepted as a flag for backward compatibility, but install is always global — there's nothing to opt into.
 
 **Requirements**: Claude Code, Node.js 18+, `gh` CLI authenticated with GitHub.
 

package/docs/spec/label-state-machine.md

@@ -20,7 +20,7 @@ See also: [FORGE Annotation Protocol §6](forge-protocol-v1.md#6-label-state-mac
 | `workflow:decomposed` | Issue decomposed into sub-issues | Decomposer agent |
 | `needs-human` | Pipeline blocked, human intervention required | Any agent on error |
 
-`workflow:awaiting-merge` vs `needs-human`: both are terminal (the pipeline stops advancing the issue automatically), but they mean different things. `needs-human` means the pipeline hit a condition it cannot resolve on its own (genuinely blocked — conflicting PR, failed verdict, calibration/trust escalation, etc.) and a human must diagnose and act. `workflow:awaiting-merge` means the opposite: the PR was previously escalated to `needs-human`, has since been remediated and re-reviewed to a clean `APPROVED` verdict with no mergeability blockers, but does not yet meet the automated auto-land bar (see forge#1809 Q1) — a human only needs to click merge, not diagnose a problem. `scripts/transition-label.sh` clears `needs-human` (best-effort) on every transition, so moving an issue onto `workflow:awaiting-merge` also clears any stale `needs-human` label.
+`workflow:awaiting-merge` vs `needs-human`: both are terminal (the pipeline stops advancing the issue automatically), but they mean different things. `needs-human` means the pipeline hit a condition it cannot resolve on its own (genuinely blocked — conflicting PR, failed verdict, calibration/trust escalation, etc.) and a human must diagnose and act. `workflow:awaiting-merge` means the opposite: the PR was previously escalated to `needs-human`, has since been remediated and re-reviewed to a clean `APPROVED` verdict with no mergeability blockers, but does not yet meet the automated auto-land bar (see forge#1809 Q1) — a human only needs to click merge, not diagnose a problem. `scripts/transition-label.sh` only clears `needs-human` (best-effort) when the target state is `workflow:awaiting-merge` — every other forward transition leaves a pre-existing `needs-human` label untouched, preserving its sticky/terminal semantics.
 
 ## Transitions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.1.8",
+  "version": "1.1.9",
   "description": "Autonomous dev pipeline for Claude Code. GitHub as institutional memory — every issue, PR, and annotation survives context resets and makes the next agent smarter.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"
@@ -40,6 +40,7 @@
     "examples/",
     "packages/protocol/src/",
     "scripts/",
+    "!scripts/refresh-bot-token.sh",
     "templates/",
     "LICENSE",
     "README.md"

package/packages/protocol/src/types.js

@@ -228,7 +228,7 @@ export const RESERVED_TYPES = {
   },
 
   // §4.2 Machine-surface cross-artifact annotation (Base64url encoded — design decision 2026-07-08)
-  // Format: <!-- FORGE:CARD v1 sha:{sha8hex} b64:{base64url_of_canonical_json} -->
+  // Format: <!-- FORGE:CARD: v1 sha:{sha8hex} b64:{base64url_of_canonical_json} -->
   // The inline value carries the full encoding: "v1 sha:XXXXXXXX b64:YYYYYY..."
   // This is an inline-value type — parse() extracts the full encoding as inlineValue.
   CARD: {

package/scripts/check-command-docs-drift.sh

@@ -96,7 +96,9 @@ declare -a DOCUMENTED_COMMANDS=()
 
 while IFS= read -r line; do
   # Match H3 heading: ### `/command-name` or ### `/command/sub`
-  if [[ "$line" =~ ^###[[:space:]]+\`(/[a-zA-Z0-9_/-]+)\` ]]; then
+  # Character class includes `.` to support dotted phase filenames (e.g.
+  # commands/orchestrate/phase-2.5-synthesis.md -> /orchestrate/phase-2.5-synthesis).
+  if [[ "$line" =~ ^###[[:space:]]+\`(/[a-zA-Z0-9_./-]+)\` ]]; then
     cmd="${BASH_REMATCH[1]}"
     DOCUMENTED_COMMANDS+=("$cmd")
   # Match table cell containing a bare command path: | `/command-name` | ...
@@ -105,7 +107,7 @@ while IFS= read -r line; do
   # matching inline code examples in prose or fix-instruction blocks.
   elif [[ "$line" =~ ^\| ]]; then
     # Extract all backtick-wrapped tokens that look like command paths
-    while [[ "$line" =~ \`(/[a-zA-Z0-9_/-]+)\` ]]; do
+    while [[ "$line" =~ \`(/[a-zA-Z0-9_./-]+)\` ]]; do
       cmd="${BASH_REMATCH[1]}"
       DOCUMENTED_COMMANDS+=("$cmd")
       # Remove the matched portion so the loop can find multiple tokens per line

package/scripts/danger-zones.mjs

@@ -333,21 +333,28 @@ function buildFileFindingStats(cards) {
 function collectCommits(repoPath, sinceDate) {
   const since = sinceDate || `${WINDOW_DAYS} days ago`;
 
-  let gitOutput;
-  try {
-    // --name-only: list files changed per commit
-    // --pretty=format:'COMMIT %H %ai': commit hash + author date (ISO)
-    // No pathspec = full repo scan for matrix building (this is intentional —
-    // we need the global commit stream to compute n(a) and N correctly)
-    gitOutput = execSync(
-      `git -C "${repoPath}" log --name-only --since="${since}" --pretty=format:"COMMIT %H %ai"`,
-      { encoding: 'utf8', maxBuffer: 50 * 1024 * 1024, timeout: 60000 },
-    );
-  } catch (e) {
-    log(`WARNING: git log failed — ${e.message}`);
+  // --name-only: list files changed per commit
+  // --pretty=format:COMMIT %H %ai: commit hash + author date (ISO)
+  // No pathspec = full repo scan for matrix building (this is intentional —
+  // we need the global commit stream to compute n(a) and N correctly)
+  // spawnSync with an argument array avoids shell interpolation of repoPath
+  // (operator/env-controlled input) — see #1842.
+  const result = spawnSync(
+    'git',
+    ['-C', repoPath, 'log', '--name-only', `--since=${since}`, '--pretty=format:COMMIT %H %ai'],
+    { encoding: 'utf8', maxBuffer: 50 * 1024 * 1024, timeout: 60000 },
+  );
+
+  if (result.error || result.status !== 0) {
+    const reason = result.error
+      ? result.error.message
+      : `exit code ${result.status}${result.signal ? ` (signal ${result.signal})` : ''}`;
+    log(`WARNING: git log failed — ${reason}`);
     return [];
   }
 
+  const gitOutput = result.stdout;
+
   const commits = [];
   let current = null;
 

package/scripts/transition-label.sh

@@ -123,6 +123,13 @@ fi
 # in between is GH_FLAG (e.g. -R RapierCraftStudios/forgedock).
 # ---------------------------------------------------------------------------
 
+# Deferred exit code (forge#1929) — set to 1 by the persistent stale-label
+# removal failure branch below instead of exiting immediately, so that the
+# unconditional needs-human clear step (scoped to awaiting-merge) always
+# gets a chance to run before the script actually exits. Initialized here,
+# before any conditional logic, so `set -u` never sees it unbound.
+TRANSITION_EXIT_CODE=0
+
 if [ "$#" -lt 2 ]; then
   echo "ERROR: Usage: transition-label.sh <ISSUE_NUMBER> [GH_FLAG...] <TARGET_STATE>" >&2
   echo "       Example: transition-label.sh 674 -R RapierCraftStudios/forgedock investigating" >&2
@@ -292,29 +299,110 @@ done
 if [ -n "$TO_REMOVE" ]; then
   echo "Removing stale workflow:* labels present on the issue ($TO_REMOVE)..."
   gh issue edit "$ISSUE_NUMBER" "${GH_ARGS[@]}" --remove-label "$TO_REMOVE" 2>/dev/null || true
+
+  # -------------------------------------------------------------------------
+  # Post-condition verification + single retry (forge#1915)
+  #
+  # The intersection fix above (forge#1810) already prevents the "unbootstrapped
+  # label 404" all-or-nothing failure — every candidate in $TO_REMOVE is known
+  # to exist on the issue at the time it was computed. But the removal call
+  # itself can still fail for reasons unrelated to label existence (a transient
+  # `gh`/GitHub API hiccup, rate limiting, a dropped connection), and that
+  # failure was previously swallowed unconditionally by `2>/dev/null || true`
+  # with no verification — leaving stale workflow:* labels stacked alongside
+  # the newly-added terminal label with no diagnostic trail. Live evidence:
+  # issue #1892 closed with both workflow:in-review and workflow:merged applied
+  # simultaneously because this exact removal call silently failed once.
+  #
+  # Fix: re-fetch the issue's labels after the removal call. If any label in
+  # $TO_REMOVE is still present, retry the removal once. If it's *still*
+  # present after the retry, this is a real, persistent failure — surface it
+  # loudly (stderr ERROR + non-zero exit) instead of the unconditional "OK".
+  #
+  # forge#1929: the non-zero exit is DEFERRED (via $TRANSITION_EXIT_CODE)
+  # rather than immediate. This block runs before the needs-human clear step
+  # further down, which is scoped to TARGET_STATE=awaiting-merge and must
+  # run regardless of this failure — it is unrelated to stale-label removal.
+  # An immediate `exit 1` here would silently skip that unrelated cleanup
+  # step in the one case (persistent removal failure) it's most important
+  # for the caller to see a consistent, fully-applied label state.
+  # -------------------------------------------------------------------------
+  POST_REMOVE_LABELS=$(gh issue view "$ISSUE_NUMBER" "${GH_ARGS[@]}" --json labels \
+    --jq '[.labels[].name] | join(",")' 2>/dev/null || echo "")
+
+  STILL_PRESENT=""
+  IFS=',' read -ra TO_REMOVE_CHECK <<< "$TO_REMOVE"
+  for candidate in "${TO_REMOVE_CHECK[@]}"; do
+    case ",$POST_REMOVE_LABELS," in
+      *",$candidate,"*)
+        STILL_PRESENT="${STILL_PRESENT:+$STILL_PRESENT,}$candidate"
+        ;;
+    esac
+  done
+
+  if [ -n "$STILL_PRESENT" ]; then
+    echo "WARNING: label removal did not take effect for ($STILL_PRESENT) — retrying once..." >&2
+    gh issue edit "$ISSUE_NUMBER" "${GH_ARGS[@]}" --remove-label "$STILL_PRESENT" 2>/dev/null || true
+
+    POST_RETRY_LABELS=$(gh issue view "$ISSUE_NUMBER" "${GH_ARGS[@]}" --json labels \
+      --jq '[.labels[].name] | join(",")' 2>/dev/null || echo "")
+
+    STILL_PRESENT_AFTER_RETRY=""
+    IFS=',' read -ra RETRY_CHECK <<< "$STILL_PRESENT"
+    for candidate in "${RETRY_CHECK[@]}"; do
+      case ",$POST_RETRY_LABELS," in
+        *",$candidate,"*)
+          STILL_PRESENT_AFTER_RETRY="${STILL_PRESENT_AFTER_RETRY:+$STILL_PRESENT_AFTER_RETRY,}$candidate"
+          ;;
+      esac
+    done
+
+    if [ -n "$STILL_PRESENT_AFTER_RETRY" ]; then
+      echo "ERROR: failed to remove stale label(s) ($STILL_PRESENT_AFTER_RETRY) from issue #$ISSUE_NUMBER after retry — label state machine now inconsistent (issue carries both '$EFFECTIVE_LABEL' and the stale label(s) above)." >&2
+      TRANSITION_EXIT_CODE=1
+    else
+      echo "Retry succeeded — stale label(s) removed."
+    fi
+  fi
 else
   echo "No stale workflow:* labels present on the issue — nothing to remove."
 fi
 
 # ---------------------------------------------------------------------------
-# Clear needs-human (best-effort)
+# Clear needs-human (best-effort) — SCOPED to workflow:awaiting-merge only
 #
 # needs-human is NOT a workflow:* label, so it is never included in
-# VALID_STATES/REMOVE_LABELS above. Historically no code path ever cleared it
-# (forge#1809/#1810) — it was a write-only, sticky, terminal label even after
-# the pipeline made forward progress past the condition that set it.
+# VALID_STATES/REMOVE_LABELS above. It is a write-only, sticky, terminal
+# label: once a human flags an issue/PR as needing attention, no routine
+# forward-progress transition (investigating, ready-to-build, building,
+# in-review, merged, invalid, decomposed) should silently clear it.
+#
+# The ONE deliberate exception is workflow:awaiting-merge (forge#1809/#1810):
+# a remediated + re-reviewed PR that has moved off needs-human without yet
+# meeting the auto-land bar. That is the single code path allowed to clear
+# needs-human — every other TARGET_STATE must leave a pre-existing
+# needs-human label untouched.
 #
-# This script only runs at explicit forward-progress transition points (the
-# dispatcher STOPs on needs-human before ever reaching a transition-label.sh
-# call in normal operation — see commands/work-on.md's terminal-state checks),
-# so clearing needs-human here is safe: it only fires when something has
-# deliberately decided to move the issue/PR to a new state, most notably
-# workflow:awaiting-merge (a remediated + re-reviewed PR moving off
-# needs-human without yet meeting the auto-land bar — see #1809 Q1).
 # Best-effort: `|| true` so a missing label never fails the script under
 # `set -euo pipefail`.
 # ---------------------------------------------------------------------------
-echo "Clearing needs-human (best-effort)..."
-gh issue edit "$ISSUE_NUMBER" "${GH_ARGS[@]}" --remove-label "needs-human" 2>/dev/null || true
+if [ "$TARGET_STATE" = "awaiting-merge" ]; then
+  echo "Clearing needs-human (best-effort, scoped to awaiting-merge)..."
+  gh issue edit "$ISSUE_NUMBER" "${GH_ARGS[@]}" --remove-label "needs-human" 2>/dev/null || true
+else
+  echo "Skipping needs-human clear — TARGET_STATE is '$TARGET_STATE', not 'awaiting-merge'."
+fi
+
+# ---------------------------------------------------------------------------
+# Final exit (forge#1929) — honor any deferred failure from the persistent
+# stale-label removal check above. The needs-human clear step just above
+# always ran first, regardless of that failure, so the caller-visible exit
+# code still surfaces the same "fail loud" signal introduced by forge#1915,
+# just after the unrelated cleanup step has had a chance to run.
+# ---------------------------------------------------------------------------
+if [ "$TRANSITION_EXIT_CODE" -ne 0 ]; then
+  echo "FAILED: $EFFECTIVE_LABEL set on issue #$ISSUE_NUMBER, but persistent stale-label removal failure occurred (see ERROR above)." >&2
+  exit "$TRANSITION_EXIT_CODE"
+fi
 
 echo "OK: $EFFECTIVE_LABEL set on issue #$ISSUE_NUMBER"