forgedock 1.1.7 → 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/FORGE-PROTOCOL.md

@@ -13,3 +13,104 @@
 > and usable in any product with attribution. This older draft was mistakenly
 > marked AGPL-3.0; the protocol description itself has always been intended for
 > open, license-compatible adoption.
+
+---
+
+## Forge Ledger — Derived Artifact of the Protocol
+
+The **Forge Ledger** is the persistent, file/symbol-keyed knowledge index built from FORGE
+annotations. It is a _derived artifact_ of the protocol: the ledger is rebuilt by re-parsing
+the annotation corpus on GitHub (source of truth), not by maintaining separate authoritative
+state.
+
+### Architecture
+
+```
+GitHub Issues/PRs (annotation corpus, source of truth)
+          │
+          ▼
+scripts/build-knowledge-index.mjs   ← incremental indexer (watermarked by issue.updated_at)
+          │   uses packages/protocol/src/parse.js (FORGE annotation parser)
+          ▼
+~/.forge/index/
+  knowledge.jsonl    ← card records (one JSON per line, keyed by issue/kind/seq)
+  postings.json      ← BM25-lite inverted index (term → card IDs with per-field tf)
+  manifest.json      ← issue → content-hash map + watermark + card count
+  renames.jsonl      ← git rename log (old path → new path for query-time resolution)
+          │
+          ▼ (mirrored to orphan branch)
+forge-knowledge branch  ← versioned, diffable, hydratable by any clone or CI
+```
+
+### Card Schema
+
+Cards are keyed by provenance (`{issue}/{kind}/{seq}`), never by file path. Paths are
+attributes maintained by the indexer; renames are metadata updates, not re-keys.
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "1370/pattern/0",
+  "kind": "pattern",
+  "issue": 1370,
+  "pattern": "...",
+  "rootCause": "...",
+  "prevention": "...",
+  "paths": ["bin/runner.mjs"],
+  "symbols": ["scrubEnv"],
+  "anchor": { "path": "bin/runner.mjs", "symbol": "scrubEnv" },
+  "status": "fresh",
+  "createdAt": "2026-07-04"
+}
+```
+
+### CLI
+
+```
+# Query by file path (exact lookup):
+forge recall --file bin/runner.mjs --json
+
+# Query by symbol:
+forge recall --symbol scrubEnv --json
+
+# Free-text BM25 search:
+forge recall "env scrub proc environ" --k 5
+
+# Index health:
+forge recall --doctor
+
+# Rebuild index from scratch:
+node scripts/build-knowledge-index.mjs --full-rebuild
+
+# Incremental update (used by close phase):
+node scripts/build-knowledge-index.mjs --issue {NUMBER}
+```
+
+### Invariants
+
+- **Full rebuild = incremental parity**: running a full rebuild produces byte-identical
+  card content to a sequence of incremental runs over the same issue range.
+- **Idempotency**: re-indexing the same issue twice produces the same card content (card IDs
+  are deterministic; content is a pure function of current annotation state).
+- **GitHub wins**: the index is always rebuildable from the annotation corpus alone. Deleting
+  `~/.forge/index/` loses nothing — a rebuild restores the same state.
+- **Non-blocking**: ledger indexing at close time never stalls the pipeline. Failure is logged
+  and the close phase continues.
+
+### Staleness Detection (tiered, cheapest first)
+
+1. Current blob sha of `anchor.path` matches stored blob sha → **FRESH**
+2. `anchor.symbol` is still defined in the current file → **FRESH**
+3. Rolling-hash scan finds `snippetHash` elsewhere in file → **MOVED** (re-anchor)
+4. `snippetHash` found in a file touched by rename log → **MOVED** (re-anchor path)
+5. Otherwise → **STALE** (excluded from binding injection; recallable with `--include-stale`)
+
+### Integration Points
+
+- **`commands/work-on/build/context.md` Phase C1**: uses `forge recall --file` for exact
+  file-path lookup; falls back to live `gh issue list --search` when index is absent.
+- **`commands/work-on/close.md` Phase C5.3**: calls `build-knowledge-index.mjs --issue`
+  after merge to index the just-closed issue; advances watermark.
+
+See issue [#1732](https://github.com/RapierCraftStudios/ForgeDock/issues/1732) for the
+implementation history and design decisions.

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/forge-protocol-v1.md

@@ -449,6 +449,43 @@ artifact so a sub-issue builder can fetch upstream context directly.
 <!-- FORGE:PRIOR_GIST: {https://example.com/artifact} -->
 ```
 
+#### Security: Gist Visibility — Normative Requirement <!-- Added: forge#1729 -->
+
+**All FORGE gist types (`FORGE:KNOWLEDGE_GIST`, `FORGE:MILESTONE_INDEX`, `FORGE:PRIOR_GIST`,
+and the memory-index Gist referenced by `FORGE:MEMORY_INDEX` in `close.md`) MUST be created
+secret. Publishing them as public Gists is a protocol violation.**
+
+Rationale: these artifacts embed investigation findings — root causes, file paths, affected
+service names, and security details. A public Gist exposes this content to a world-readable
+URL with no access control. `gh gist create` is secret by default; the requirement is that
+no pipeline spec or operator script must pass `--public` when creating any of these artifacts.
+
+**Enforcement**: The `pre-tool-use.mjs` hook (Rule 3) hard-blocks `gh gist create --public`
+in pipeline sessions. The `doctor-pipeline-state.sh` check I8 audits existing annotation-referenced
+gists and reports a CRITICAL finding if any are public.
+
+**Migration** (if a public gist is found): GitHub does not support changing a Gist's visibility
+in place. To replace a public pipeline gist with a secret one:
+
+```bash
+# 1. Save current content
+gh gist view {GIST_ID} > /tmp/gist_migrate.md
+[ -s /tmp/gist_migrate.md ] || { echo "ABORT: empty save"; exit 1; }
+
+# 2. Delete the public gist
+gh gist delete {GIST_ID} --yes
+
+# 3. Recreate secret (no --public) with same description
+gh gist create /tmp/gist_migrate.md --desc "{ORIGINAL_DESCRIPTION}"
+# gh gist create without --public creates a secret gist.
+
+# 4. Update the FORGE annotation on the issue to point to the new URL
+```
+
+**Override**: set `FORGE_ALLOW_PUBLIC_GIST=1` in the operator's shell environment before
+starting Claude Code only if a public gist is genuinely required (e.g., sharing a demo
+artifact). This must not be used for pipeline memory gists.
+
 ### 4.3 Control and error markers
 
 These markers carry no Markdown body; their presence is the signal.
@@ -1143,16 +1180,71 @@ separate, MIT-licensed npm package:
 **`@forgedock/protocol`** — available at `packages/protocol/` in the ForgeDock
 repository.
 
-It provides:
+### 13.1 Normative codec path
+
+**`packages/protocol/` is the normative write and read path for all FORGE
+annotations.** Hand-rolled annotation construction (embedding raw
+`<!-- FORGE:TYPE -->` strings in inline heredocs or `--body` blocks) is
+**non-conformant** because it bypasses the codec's escaping and round-trip
+guarantees. Every producer MUST route annotation construction through one of:
+
+1. **`forge-annotation.sh write <TYPE> --field KEY=VALUE ...`** (AGPL-licensed,
+   ships with the npm package at `scripts/forge-annotation.sh`), or
+2. **`node packages/protocol/src/cli.js emit <TYPE> --field KEY=VALUE ...`**
+   (MIT-licensed, part of the `@forgedock/protocol` package)
+
+Both paths delegate to `emit()` from `packages/protocol/src/emit.js`, which
+applies the complete escaping and sanitization policy (§3.5 injection hardening).
+
+### 13.2 JavaScript API
+
+```js
+import { parse, validate, emit, emitPartial } from '@forgedock/protocol';
+```
 
 - `parse(commentBody)` — extracts all annotations from a comment body string
 - `validate(annotation)` — checks conformance per §3–4; returns `{ valid, errors, warnings }`
-- `emit(type, fields)` — produces well-formed annotation strings
+- `emit(type, fields)` — produces a well-formed annotation string; applies all §3.5 escaping
 - `emitPartial(type)` — produces the partial sentinel for a type (§3.3)
 
-A conformance suite in `packages/protocol/fixtures/` covers all 13 reserved
-types with valid and invalid examples. The CLI runner can be invoked against any
-fixtures directory:
+### 13.3 CLI subcommands
+
+The CLI at `packages/protocol/src/cli.js` exposes three modes:
+
+```bash
+# Emit — print a well-formed annotation body to stdout
+node packages/protocol/src/cli.js emit INVESTIGATOR \
+  --field Verdict=CONFIRMED --field Confidence=HIGH \
+  --field Severity=MEDIUM --field "Task Type=Bug Fix" \
+  --field "Decomposition Assessment=NO — single fix."
+
+# Parse — read a comment body from stdin, extract a field value
+echo '<!-- FORGE:INVESTIGATOR -->...' | \
+  node packages/protocol/src/cli.js parse --type INVESTIGATOR --field Verdict
+# → CONFIRMED
+
+# Conformance runner (legacy — no subcommand keyword)
+node packages/protocol/src/cli.js fixtures/
+```
+
+The `emit` subcommand also supports the Base64url machine-surface form for
+`FORGE:CARD` annotations (design decision 2026-07-08: encoding beats escaping):
+
+```bash
+node packages/protocol/src/cli.js emit CARD \
+  --field issue=1370 --field status=merged --b64
+# → <!-- FORGE:CARD: v1 sha:7234c2d8 b64:eyJ... -->
+```
+
+The Base64url alphabet `[A-Za-z0-9_-]` cannot contain `>`, `<`, or `!`, making
+`-->`, `--!>`, and `<!--` structurally unrepresentable in the machine surface.
+
+### 13.4 Conformance suite
+
+A conformance suite in `packages/protocol/fixtures/` covers all reserved types
+with valid and invalid examples, including adversarial payloads that reproduce
+historical escaping vulnerabilities. The suite can be run against any fixtures
+directory:
 
 ```bash
 npx @forgedock/protocol fixtures/

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

@@ -14,11 +14,14 @@ See also: [FORGE Annotation Protocol §6](forge-protocol-v1.md#6-label-state-mac
 | `workflow:ready-to-build` | Investigation complete, build not started | Investigator agent |
 | `workflow:building` | Build phase active | Builder agent |
 | `workflow:in-review` | PR created, review active | Orchestrator agent |
+| `workflow:awaiting-merge` | Remediated + re-reviewed, awaiting a human merge decision | Review-pr Phase 8 (auto-merge guard) |
 | `workflow:merged` | PR merged, issue closed | Close phase agent |
 | `workflow:invalid` | Issue closed as invalid | Investigator agent |
 | `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` 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
 
 ```
@@ -27,6 +30,7 @@ See also: [FORGE Annotation Protocol §6](forge-protocol-v1.md#6-label-state-mac
   → workflow:ready-to-build     [Phase 2: Investigation complete]
   → workflow:building           [Phase 3: Build started]
   → workflow:in-review          [Phase 4: PR created]
+  → workflow:awaiting-merge [TERMINAL] [Phase 5/review-pr: re-reviewed after needs-human, awaiting human merge]
   → workflow:merged  [TERMINAL] [Phase 5: PR merged]
   → workflow:invalid [TERMINAL] [Any phase: closed as invalid]
   → workflow:decomposed [TERMINAL] [Phase 2: split into sub-issues]
@@ -40,6 +44,7 @@ Processing stops when any of these labels is set:
 - `workflow:merged`
 - `workflow:invalid`
 - `workflow:decomposed`
+- `workflow:awaiting-merge`
 - `needs-human`
 
 ## Label Exclusivity
@@ -49,7 +54,7 @@ At most one `workflow:*` label should be active on an issue at any time. When tr
 ```bash
 gh issue edit {NUMBER} -R {REPO} \
   --add-label "workflow:building" \
-  --remove-label "workflow:investigating,workflow:ready-to-build,workflow:in-review,workflow:merged,workflow:invalid,workflow:decomposed"
+  --remove-label "workflow:investigating,workflow:ready-to-build,workflow:in-review,workflow:awaiting-merge,workflow:merged,workflow:invalid,workflow:decomposed"
 ```
 
 This is enforced by `scripts/transition-label.sh` — use `resolve_script 'transition-label'` rather than calling `gh issue edit` directly when possible.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.1.7",
+  "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,12 +40,13 @@
     "examples/",
     "packages/protocol/src/",
     "scripts/",
+    "!scripts/refresh-bot-token.sh",
     "templates/",
     "LICENSE",
     "README.md"
   ],
   "scripts": {
-    "test": "node --test \"bin/tests/**/*.test.mjs\"",
+    "test": "node --test \"bin/tests/**/*.test.mjs\" \"packages/protocol/test/**/*.test.mjs\"",
     "docs:dev": "vitepress dev docs/site",
     "docs:build": "vitepress build docs/site",
     "docs:preview": "vitepress preview docs/site"