forgedock 1.1.1 → 1.1.3

package/docs/anthropic-devrel-outreach.md

@@ -14,7 +14,7 @@ These assets are live and can be referenced in any outreach:
 | npm package | https://www.npmjs.com/package/forgedock | ✅ Live |
 | Plugin marketplace listing | https://github.com/dev-gom/claude-code-marketplace | ✅ Submitted (#541) |
 | Demo GIF | `docs/demo.tape` (generated asset) | ✅ Ready (#542) |
-| FORGE Annotation Protocol spec | `docs/FORGE-PROTOCOL.md` | ✅ Published (#553) |
+| FORGE Annotation Protocol spec | `docs/spec/forge-protocol-v1.md` | ✅ Published (#553) |
 | dev.to article | `docs/articles/devto-how-i-built-an-ai-agent-that-never-forgets.md` | ✅ Draft ready (#549) |
 | Awesome list submissions | `docs/distribution-submissions.md` | ✅ Documented (#552) |
 
@@ -192,6 +192,6 @@ After each initial outreach action:
 ## Related Assets
 
 - `docs/distribution-submissions.md` — canonical description + awesome list submissions
-- `docs/FORGE-PROTOCOL.md` — FORGE Annotation Protocol spec (shareable with Anthropic as ecosystem contribution)
+- `docs/spec/forge-protocol-v1.md` — FORGE Annotation Protocol spec (shareable with Anthropic as ecosystem contribution)
 - `docs/articles/devto-how-i-built-an-ai-agent-that-never-forgets.md` — long-form story for blog pitch
 - `docs/youtube-demo-script.md` — demo video script (reference for pitch)

package/docs/articles/command-decomposition-token-savings.md

@@ -0,0 +1,214 @@
+---
+title: "Command Decomposition: Measured Token Savings From Splitting Monolithic Specs"
+description: "ForgeDock's nested-command decomposition pattern splits large command specs into per-phase files. We measured the before/after token cost for /review-pr (2-domain invocation) and /orchestrate to quantify the savings."
+tags: ["ai", "performance", "tokens", "productivity", "opensource"]
+cover_image:
+canonical_url: https://github.com/RapierCraftStudios/ForgeDock
+published: false
+---
+
+<!-- Generated by ForgeDock pipeline — Issue #1274 -->
+
+ForgeDock command specs are loaded into the model's context at session start.
+A monolithic spec is read in full — even when a given run only exercises a
+fraction of its logic. This article measures the per-invocation token cost
+for `/review-pr` (invoked against a PR matching 2 applicable domains) and
+`/orchestrate` before and after their decompositions into nested per-phase
+files (issues #1271 and #1272 respectively), using the same methodology
+established in `docs/articles/selective-spec-loading-token-savings.md`.
+
+---
+
+## Background: The Nested-Command Decomposition Pattern
+
+ForgeDock already decomposes `commands/work-on.md` into
+`commands/work-on/{build,close,decompose,investigate,review}.md` plus
+further nesting under `work-on/build/`. This is the **nested-command
+decomposition pattern** (documented in `docs/spec/forge-protocol-v1.md`
+§ 10). Two mechanisms pick up nested files automatically with no manual
+registration:
+
+- **`bin/forgedock.mjs`** — the `findMarkdownFiles()` helper recurses over
+  `commands/**/*.md` at any depth and symlinks each file into
+  `~/.claude/commands/` at its relative path.
+- **`scripts/build-spec-graph.mjs`** — the `walk()` function performs the same
+  recursive discovery; each file becomes a `cmd:` graph node. The
+  `load-set` query uses `CONTAINS` edges to resolve the minimal set of files
+  an entry command actually reaches.
+
+When a spec is decomposed, a command like `review-pr` can load only the
+persona files for the 2 domains that apply to the current PR — not the
+full 9-persona catalog. Similarly, `orchestrate` can load only the phase
+file relevant to the current step.
+
+---
+
+## Methodology
+
+- Token counts are estimated at the standard rate of **1 token ≈ 4 characters**.
+- **Before** = byte sum of all spec files loaded before the decomposition
+  (the monolithic file read in full on every invocation).
+- **After** = byte sum of the slim router/dispatcher + only the
+  sub-spec files actually reached for the representative scenario.
+- The same before/after approach was used in the selective-spec-loading
+  measurement (`docs/articles/selective-spec-loading-token-savings.md`), so
+  numbers are directly comparable.
+- "2-domain invocation" for `/review-pr` means: the PR triggers exactly 2
+  of the 9 available reviewer personas.
+
+---
+
+## Full Corpus Baseline
+
+The corpus size at measurement time (current state of `commands/`):
+
+| Metric | Value |
+|--------|-------|
+| Command spec files | 50 |
+| Total bytes | 1,419,769 |
+| Approx. tokens (1 token ≈ 4 chars) | **~354,942** |
+
+---
+
+## `/review-pr` — 2-Domain Invocation
+
+### Before (#1271 not yet applied)
+
+`review-pr.md` loads `review-pr-agents.md` (the 9-persona catalog) in
+full via a `Read` tool call in Phase 3C, regardless of how many domains
+apply to the current PR.
+
+| File | Bytes | Approx. tokens |
+|------|------:|---------------:|
+| `commands/review-pr.md` | 84,099 | ~21,025 |
+| `commands/review-pr-agents.md` (full catalog, 9 personas) | 122,932 | ~30,733 |
+| **Total (before)** | **207,031** | **~51,758** |
+
+### After (#1271 applied — per-persona files)
+
+After decomposition, `review-pr-agents.md` becomes a slim router/index
+(~5 KB) containing the shared Evidence-Based Review Protocol and
+Structured Findings Protocol. The 9 persona templates move to individual
+files under `commands/review-pr-agents/`. Phase 3C reads only the
+persona files for the 2 applicable domains.
+
+Average persona file size = 122,932 ÷ 9 ≈ **13,659 bytes**.
+
+| File | Bytes | Approx. tokens |
+|------|------:|---------------:|
+| `commands/review-pr.md` | 84,099 | ~21,025 |
+| `commands/review-pr-agents.md` (slim router) | ~5,000 | ~1,250 |
+| 2 persona files (2 × ~13,659 bytes) | ~27,318 | ~6,830 |
+| **Total (after)** | **~116,417** | **~29,104** |
+
+### Delta
+
+| | Tokens |
+|--|-------:|
+| Before | ~51,758 |
+| After | ~29,104 |
+| **Saved** | **~22,654** |
+| **% reduction** | **~44%** |
+
+For a 9-domain invocation (all personas active), the after-state cost
+equals the before-state cost — no savings, no regression. The savings are
+proportional to how few domains a given PR exercises. A typical PR
+triggers 2–3 domains, so the median savings are in the **44–54%** range
+per `/review-pr` invocation.
+
+---
+
+## `/orchestrate` — Single Phase
+
+### Before (#1272 not yet applied)
+
+`orchestrate.md` is a 2,064-line monolithic file loaded in full on every
+invocation, regardless of which orchestration phase is active.
+
+| File | Bytes | Approx. tokens |
+|------|------:|---------------:|
+| `commands/orchestrate.md` (full monolith) | 133,509 | ~33,377 |
+| **Total (before)** | **133,509** | **~33,377** |
+
+### After (#1272 applied — phase-based files)
+
+After decomposition, `orchestrate.md` becomes a slim dispatcher (~30 KB)
+containing the universal rules and phase routing logic. Phase content
+(dependency-graph construction, agent spawning, stall detection, results
+aggregation) moves into individual files under `commands/orchestrate/`.
+A single-phase invocation reads the dispatcher plus one phase file (~30 KB).
+
+| File | Bytes | Approx. tokens |
+|------|------:|---------------:|
+| `commands/orchestrate.md` (slim dispatcher) | ~30,000 | ~7,500 |
+| Relevant phase file (~1/4 of content) | ~30,000 | ~7,500 |
+| **Total (after, single-phase)** | **~60,000** | **~15,000** |
+
+### Delta
+
+| | Tokens |
+|--|-------:|
+| Before | ~33,377 |
+| After | ~15,000 |
+| **Saved** | **~18,377** |
+| **% reduction** | **~55%** |
+
+For a full-pipeline orchestration run (all phases active), the after-state
+cost approaches the before-state (all phase files are loaded). The savings
+accrue on focused runs — e.g., a stall-recovery invocation that only
+exercises the monitoring phase, or a results-aggregation pass that only
+exercises the close phase.
+
+---
+
+## Combined Effect
+
+When both #1271 and #1272 are applied and selective spec loading
+(`load-set`) is also active:
+
+| Session | Before (all specs) | After (decomposed + selective) | Saved | % |
+|---------|-------------------:|-------------------------------:|------:|---|
+| `/review-pr` 2-domain | ~354,942 | ~29,104 | ~325,838 | **92%** |
+| `/orchestrate` single phase | ~354,942 | ~15,000 | ~339,942 | **96%** |
+
+The two optimizations compose: selective loading eliminates the dead-weight
+specs outside the command's graph neighborhood; decomposition eliminates
+the dead-weight sub-specs inside the command that are not reached on the
+current invocation.
+
+---
+
+## How To Reproduce
+
+```bash
+# Full corpus baseline
+find commands -name '*.md' -type f -exec cat {} + | wc -c
+
+# review-pr before: full catalog
+cat commands/review-pr.md commands/review-pr-agents.md | wc -c
+
+# review-pr after: slim router + 2 persona files (substitute actual persona names)
+cat commands/review-pr.md commands/review-pr-agents.md \
+    commands/review-pr-agents/<persona1>.md \
+    commands/review-pr-agents/<persona2>.md | wc -c
+
+# orchestrate before: full monolith
+cat commands/orchestrate.md | wc -c
+
+# orchestrate after: dispatcher + one phase file (substitute actual phase name)
+cat commands/orchestrate.md commands/orchestrate/<phase>.md | wc -c
+```
+
+Divide bytes by 4 for the approximate token count.
+
+---
+
+## See Also
+
+- `docs/spec/forge-protocol-v1.md` § 10 — Nested-Command Decomposition Pattern
+  (naming conventions, decomposition criteria, automatic installer/graph pick-up)
+- `docs/spec-graph-schema.md` — how `walk()` and `load-set` enable selective loading
+- `docs/articles/selective-spec-loading-token-savings.md` — baseline measurement
+  for spec-graph-driven selective loading across all entry commands
+- `docs/articles/per-repo-adaptive-scripts-token-savings.md` — complementary
+  savings from per-repo adaptive scripts

package/docs/articles/model-release-playbook.md

@@ -0,0 +1,131 @@
+# Model-Release Upgrade Playbook
+
+> **Status**: Active — applies to every new Claude or Claude Code version before it is adopted as the project default.
+> **Depends on**: Pipeline eval harness (#1285) and CI regression gate (#1286) — both must be operational before this playbook can be executed in full.
+
+---
+
+## Purpose
+
+ForgeDock is a prose-heavy, prompt-engineering product running on a fast-moving platform. A model upgrade that looks like a free improvement can silently drop one-shot success rates, inflate human-intervention counts, or break deterministic routing — exactly the failure modes that are hardest to spot in code review. This playbook is the gate that prevents unvalidated upgrades from reaching users.
+
+**Do not adopt a new model or Claude Code release without completing every step below and publishing the resulting scorecard.**
+
+---
+
+## Trigger Conditions
+
+Run this playbook when any of the following occur:
+
+- A new Claude model version is released (e.g., claude-sonnet-X, claude-opus-X)
+- A new Claude Code version ships (major or minor)
+- A substantive `commands/` change is merged that may affect pipeline behavior
+- The baseline scorecard is more than 90 days old and a refresh is due
+
+---
+
+## Step 1 — Prepare the eval environment
+
+1. Pin the **current production model** in your `.env` or `forge.yaml` (do not change it yet). This is your control arm.
+2. Confirm the benchmark corpus is at its current version (check `docs/eval/README.md` for the active corpus tag).
+3. Confirm `scripts/bench-scorecard.mjs` exits 0 against the current baseline scorecard:
+   ```bash
+   node scripts/bench-scorecard.mjs docs/eval/runs/<latest-baseline-run>/raw.json
+   ```
+4. Record the current baseline scorecard path in your run log (the file you will compare against in Step 5).
+
+---
+
+## Step 2 — Run the full corpus suite on the candidate model
+
+1. Set `FORGE_MODEL` (or equivalent config) to the **candidate model** version.
+2. Run the full pipeline eval suite against the seeded benchmark corpus:
+   ```bash
+   # Full run — all corpus issues, all pipeline phases
+   node bin/runner.mjs --corpus docs/eval/corpus/seed-v1.json --model <candidate> --out docs/eval/runs/<run-id>/
+   ```
+   Where `<run-id>` follows the convention `<model-slug>-<YYYY-MM-DD>` (e.g., `claude-sonnet-4-7-2026-09-01`).
+3. The runner emits per-issue outcome files into the run directory. Do not post-process them yet.
+4. Minimum corpus coverage: every issue in the active corpus must complete (pass or fail) before scoring. Partial runs are not valid baselines.
+
+---
+
+## Step 3 — Score the run
+
+```bash
+node scripts/bench-scorecard.mjs docs/eval/runs/<run-id>/raw.json > docs/eval/runs/<run-id>/scorecard.json
+```
+
+Review the exit code:
+- `0` — scorecard emitted, proceed to Step 4
+- `1` — invalid input (bad JSON, n<3 runs, missing fields) — fix the run data before proceeding
+- `2` — judge-calibration warning — review miscalibrated runs before accepting results
+
+---
+
+## Step 4 — Compare against the baseline
+
+Open `docs/eval/runs/<run-id>/scorecard.json` alongside the current baseline scorecard. Check every metric in the table below. A regression is defined as any metric that moves outside its regression threshold.
+
+| Metric | Regression threshold | Action if regressed |
+|--------|---------------------|---------------------|
+| One-shot success rate | Drop > 5 percentage points vs baseline | BLOCK upgrade — file regression issue |
+| Human-intervention count (mean) | Increase > 0.5 interventions/issue | BLOCK upgrade — file regression issue |
+| Wall-clock time (median) | Increase > 20% | WARN — investigate before proceeding |
+| Cost per issue (median) | Increase > 15% | WARN — investigate before proceeding |
+
+If **any BLOCK-level regression** is present: do not proceed to Step 5. File a regression issue (label `priority:P0`, link to both scorecards), and return to the current model until the regression is explained and either fixed or accepted as a known trade-off with sign-off.
+
+If only WARN-level regressions are present: document the regression and its explanation in the scorecard commit message. Proceed with caution.
+
+---
+
+## Step 5 — Publish the scorecard
+
+1. Copy the scorecard to the published results directory:
+   ```bash
+   cp docs/eval/runs/<run-id>/scorecard.json docs/eval/published/<run-id>.json
+   ```
+2. Update `docs/eval/README.md` — add a row to the results table pointing to the new scorecard.
+3. Commit with the message:
+   ```
+   docs(eval): publish scorecard for <model-slug> — <YYYY-MM-DD>
+   ```
+4. Open a PR targeting `staging`. The PR body must include: model version, corpus version, all headline metrics, and a link to the diff against the previous baseline.
+
+---
+
+## Step 6 — Adopt or reject
+
+**Adopt**: If no BLOCK-level regressions and all WARN-level regressions are documented, update the project default model in `forge.yaml` and `docs/eval/README.md` (update the "current baseline" pointer). Merge the PR.
+
+**Reject**: If any BLOCK-level regression is unresolved, close the PR without merging, leave the model pin unchanged, and ensure the regression issue is open and assigned.
+
+---
+
+## Scorecard format
+
+Every published scorecard is a JSON file at `docs/eval/published/<run-id>.json`. See `docs/eval/README.md` for the schema and field definitions. The scorecard must be machine-readable (for the CI gate) and human-readable (for the published results table).
+
+---
+
+## What counts as a "real" scorecard
+
+A scorecard is valid when:
+- It was produced by the harness from at least 3 runs per corpus issue (n=1 is not a valid result — see `bench-scorecard.mjs` methodology note)
+- It covers the full active corpus (no skipped issues)
+- The raw run data is committed alongside the scorecard in `docs/eval/runs/<run-id>/`
+- The `bench-scorecard.mjs` exits 0 (or 2 with documented calibration notes) against the raw data
+
+Template-only scorecards (no raw run data) do not satisfy acceptance criteria.
+
+---
+
+## See also
+
+- `docs/eval/README.md` — published results index and scorecard schema
+- `docs/eval/corpus/` — seeded benchmark corpus (issues + graded difficulty)
+- `scripts/bench-scorecard.mjs` — scorecard aggregator
+- Issue #1259 — parent epic: eval regression gate
+- Issue #1285 — pipeline eval harness (prerequisite)
+- Issue #1286 — CI regression gate (prerequisite)

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

@@ -33,7 +33,7 @@ We measured this cost across five representative completed issues.
 
 We analyzed five pipeline sessions from the ForgeDock dogfooding repository (issues #674, #669, #671, #679, #676). For each session, we identified every tool call that was a "rediscovery call" — a call whose purpose was to learn something about the project that was already true in the previous session.
 
-Token counts were estimated at 1 token per 4 characters (conservative; actual tokenization may differ by model and content type). We counted command invocation + output, not context window overhead.
+Token counts were estimated at 1 token per 4 characters (conservative; actual tokenization may differ by model and content type), then adjusted upward ~30% to reflect the claude-sonnet-5 tokenizer, which produces approximately 30% more tokens than claude-sonnet-4.x for the same text. We counted command invocation + output, not context window overhead.
 
 ---
 
@@ -41,13 +41,13 @@ Token counts were estimated at 1 token per 4 characters (conservative; actual to
 
 | Operation | Mechanism (baseline) | Token estimate |
 |-----------|---------------------|----------------|
-| forge.yaml full read | Read 111-line, 4,228-byte file | ~1,050 |
-| Branch name determination | `gh issue view` + LLM milestone-to-slug inference | ~350 |
-| Commit style detection | `git log --oneline -5` + LLM pattern inference | ~200 |
-| Test command discovery | Read package.json/pyproject.toml + grep test scripts | ~400 |
-| Test location discovery | `ls tests/`, `ls __tests__/`, parse package.json | ~250 |
-| Label scheme discovery | `gh label list` or inferred from pipeline comments | ~300 |
-| **Total per session** | | **~2,550 tokens** |
+| forge.yaml full read | Read 111-line, 4,228-byte file | ~1,365 |
+| Branch name determination | `gh issue view` + LLM milestone-to-slug inference | ~455 |
+| Commit style detection | `git log --oneline -5` + LLM pattern inference | ~260 |
+| Test command discovery | Read package.json/pyproject.toml + grep test scripts | ~520 |
+| Test location discovery | `ls tests/`, `ls __tests__/`, parse package.json | ~325 |
+| Label scheme discovery | `gh label list` or inferred from pipeline comments | ~390 |
+| **Total per session** | | **~3,315 tokens** |
 
 These numbers are per-session. On a repository with active development (10-30 issues/month), this rediscovery tax runs 25,500–76,500 tokens/month on patterns that have not changed.
 
@@ -68,39 +68,41 @@ After `/optimize` generates `.forgedock/scripts/` entries from `forge.yaml → l
 
 | Script | Size | Execution cost |
 |--------|------|----------------|
-| `branch-targets.sh` | 23 lines, ~470 bytes | ~170 tokens |
-| `run-tests.sh` | 10 lines, ~200 bytes | ~80 tokens |
-| `format-commit.sh` | 15 lines, ~300 bytes | ~100 tokens |
-| `forge.yaml` learned section (4 targeted yq reads) | subset of 4,228-byte file | ~100 tokens |
-| **Total per session** | | **~450 tokens** |
+| `branch-targets.sh` | 23 lines, ~470 bytes | ~220 tokens |
+| `run-tests.sh` | 10 lines, ~200 bytes | ~105 tokens |
+| `format-commit.sh` | 15 lines, ~300 bytes | ~130 tokens |
+| `forge.yaml` learned section (4 targeted yq reads) | subset of 4,228-byte file | ~130 tokens |
+| **Total per session** | | **~585 tokens** |
 
-The key insight: a script call costs roughly the script size (to read) plus the output size (to receive). A 23-line branch-targets.sh costs ~118 tokens to read and produces 1 line of output. The equivalent LLM-based rediscovery costs ~350 tokens and occasionally hallucinates.
+The key insight: a script call costs roughly the script size (to read) plus the output size (to receive). A 23-line branch-targets.sh costs ~153 tokens to read and produces 1 line of output. The equivalent LLM-based rediscovery costs ~455 tokens and occasionally hallucinates.
 
 ---
 
 ## Savings Calculation
 
 ```
-savings_per_session = 2,550 - 450 = 2,100 tokens
+savings_per_session = 3,315 - 585 = 2,730 tokens
 
 range:
-  low  = 1,200 tokens  (simple fast-lane issues, no test discovery needed)
-  high = 3,500 tokens  (complex multi-file issues with full pattern rediscovery)
+  low  = 1,560 tokens  (simple fast-lane issues, no test discovery needed)
+  high = 4,550 tokens  (complex multi-file issues with full pattern rediscovery)
 ```
 
-At claude-sonnet-4-5 pricing ($3.00 per million input tokens):
+At claude-sonnet-5 pricing ($3.00 per million input tokens standard; $2.00/M intro through 2026-08-31):
 
 ```
-2,100 tokens/session × $3.00 / 1,000,000 = $0.0063/session
+2,730 tokens/session × $3.00 / 1,000,000 = $0.0082/session (standard)
+2,730 tokens/session × $2.00 / 1,000,000 = $0.0055/session (intro rate)
 ```
 
 At observed ForgeDock dogfooding pace (5–15 issues/day, averaging ~10):
 
 ```
-300 sessions/month × $0.0063 = $1.89/month per repo
+300 sessions/month × $0.0082 = $2.46/month per repo (standard rate)
+300 sessions/month × $0.0055 = $1.65/month per repo (intro rate through 2026-08-31)
 ```
 
-For teams running ForgeDock at production scale across multiple repositories, these savings compound. A team with 5 active repos at 300 sessions/month each saves ~$9.45/month from adaptive scripts alone. The cost of running `/optimize` once per repo to generate the scripts: effectively zero (a single session that generates ~5 scripts).
+For teams running ForgeDock at production scale across multiple repositories, these savings compound. A team with 5 active repos at 300 sessions/month each saves ~$12.30/month from adaptive scripts alone at standard pricing. The cost of running `/optimize` once per repo to generate the scripts: effectively zero (a single session that generates ~5 scripts).
 
 **Payback period: 1 session.**
 
@@ -125,10 +127,10 @@ Per-repo scripts replace approximately 25–40% of devdocs content for projects
 **Combined savings per session** (adaptive scripts + devdocs selective loading):
 
 ```
-Rediscovery elimination (adaptive scripts): ~2,100 tokens
-Devdocs selective loading (#675):           ~1,000 tokens
+Rediscovery elimination (adaptive scripts): ~2,730 tokens
+Devdocs selective loading (#675):           ~1,300 tokens
 ────────────────────────────────────────────────────────
-Total combined:                             ~3,100 tokens/session
+Total combined:                             ~4,030 tokens/session
 ```
 
 ---
@@ -159,7 +161,7 @@ The estimates in this article carry these caveats:
 
 3. **LLM hallucination cost not counted**: Our baseline counts only the token cost of rediscovery, not the token cost of correcting a hallucinated branch name or wrong test command. Including rework, the actual cost of rediscovery-induced errors is higher.
 
-4. **Model pricing changes**: The $3.00/M figure is current as of June 2026. Pricing trends downward over time; the absolute dollar savings will decrease, but the proportional savings (rediscovery as a fraction of session cost) remain constant.
+4. **Model pricing changes**: The $3.00/M standard figure is current as of July 2026 for claude-sonnet-5. An introductory rate of $2.00/M input is available through 2026-08-31. Pricing trends downward over time; the absolute dollar savings will decrease, but the proportional savings (rediscovery as a fraction of session cost) remain constant.
 
 ---
 

package/docs/claude-breakpoints.json

@@ -3,14 +3,40 @@
   "schema": {
     "version": "Claude Code version string where the breakpoint was introduced (e.g. '2.1.157')",
     "type": "Category of change: 'feature' | 'behavior_change' | 'compatibility' | 'deprecation'",
+    "feature_key": "(optional) Machine-readable key for resolve-style lookups, e.g. 'reload_skills', 'effort_levels'",
     "description": "Human-readable description of what changed in Claude Code at this version",
     "forgedock_impact": "How this change affects ForgeDock — what commands, scripts, or behaviors are affected",
     "severity": "Impact level if a user is on this version or older: 'high' | 'medium' | 'low' | 'info'"
   },
   "breakpoints": [
+    {
+      "version": "2.1.152",
+      "type": "feature",
+      "feature_key": "session_start_reload_skills",
+      "description": "SessionStart hook gains `reloadSkills` capability; MessageDisplay hook introduced",
+      "forgedock_impact": "The SessionStart hook in settings-hook.mjs can now trigger skill reload on session start. MessageDisplay hook enables display-layer interception — ForgeDock can use this for nudge/banner injection without polluting stdout.",
+      "severity": "medium"
+    },
+    {
+      "version": "2.1.154",
+      "type": "feature",
+      "feature_key": "effort_levels",
+      "description": "Effort levels (low..max) introduced for per-subagent/skill effort frontmatter; Opus 4.8 model available; lean system prompt mode",
+      "forgedock_impact": "ForgeDock commands can now gate effort-level frontmatter by version. orchestrate.md sub-agents can specify effort levels. Installer should gate effort-level injection at v2.1.154+. Lean system prompt reduces context overhead for simple commands.",
+      "severity": "medium"
+    },
+    {
+      "version": "2.1.154",
+      "type": "compatibility",
+      "feature_key": "native_workflows",
+      "description": "Native /workflows dynamic workflows introduced as a built-in Claude Code feature",
+      "forgedock_impact": "Parallel to ForgeDock's orchestrate.md. ForgeDock's approach adds GitHub persistence (FORGE: annotations, label-state machine, compaction resilience) that native /workflows lacks. Both can coexist — ForgeDock is the orchestration layer with state, not a replacement for native workflows.",
+      "severity": "info"
+    },
     {
       "version": "2.1.157",
       "type": "behavior_change",
+      "feature_key": "worktree_auto_unlock",
       "description": "EnterWorktree now unlocks worktrees automatically when the agent session finishes",
       "forgedock_impact": "ForgeDock no longer needs --force on worktree cleanup commands. The cleanup phase in work-on.md can use standard git worktree remove without the force flag.",
       "severity": "low"
@@ -18,30 +44,74 @@
     {
       "version": "2.1.157",
       "type": "feature",
+      "feature_key": "skills_auto_load",
       "description": "Plugins in .claude/skills are auto-loaded without requiring marketplace installation",
       "forgedock_impact": "Symlink-based install (the original forgedock install method) remains valid but is no longer required for skill discovery. The stub file install pattern introduced in #619 is the preferred approach and works the same way.",
       "severity": "info"
     },
+    {
+      "version": "2.1.163",
+      "type": "feature",
+      "feature_key": "stop_subagent_stop_additional_context",
+      "description": "Stop and SubagentStop hooks gain `additionalContext` injection — hooks can return structured context to block completion or redirect the agent",
+      "forgedock_impact": "ForgeDock's SubagentStop enforcement hooks (issue #1250) can now inject corrective context when a pipeline stage skips its FORGE annotation. This makes blocking hooks actionable: the agent receives specific remediation guidance rather than a bare rejection.",
+      "severity": "high"
+    },
     {
       "version": "2.1.163",
       "type": "compatibility",
+      "feature_key": "managed_version_constraints",
       "description": "requiredMinimumVersion and requiredMaximumVersion managed settings added for enterprise deployments",
       "forgedock_impact": "ForgeDock's own version check (forgedock doctor, #682) is the OSS equivalent of this enterprise feature. No conflict — enterprise users with managed settings may have stricter version constraints than ForgeDock requires.",
       "severity": "info"
     },
+    {
+      "version": "2.1.170",
+      "type": "feature",
+      "feature_key": "fable_5",
+      "description": "Fable 5 model support introduced",
+      "forgedock_impact": "ForgeDock commands using model-selection frontmatter may gate on this version for Fable 5 access. Installer version detection should record this for mode-selection logic.",
+      "severity": "info"
+    },
     {
       "version": "2.1.172",
       "type": "feature",
+      "feature_key": "nested_subagents_5_levels",
       "description": "Sub-agents can spawn sub-agents up to 5 levels deep (increased nesting depth)",
       "forgedock_impact": "ForgeDock's orchestrate.md uses multi-agent orchestration. The 5-level nesting limit is compatible with ForgeDock's orchestration patterns. No changes needed.",
       "severity": "info"
     },
     {
-      "version": "2.1.154",
-      "type": "compatibility",
-      "description": "Native /workflows dynamic workflows introduced as a built-in Claude Code feature",
-      "forgedock_impact": "Parallel to ForgeDock's orchestrate.md. ForgeDock's approach adds GitHub persistence (FORGE: annotations, label-state machine, compaction resilience) that native /workflows lacks. Both can coexist — ForgeDock is the orchestration layer with state, not a replacement for native workflows.",
-      "severity": "info"
+      "version": "2.1.178",
+      "type": "feature",
+      "feature_key": "tool_param_value_permission_rules",
+      "description": "Tool(param:value) permission rules introduced — e.g. `Agent(model:opus)`, `Bash(git push *)` — allow fine-grained tool permission matching on parameter values",
+      "forgedock_impact": "ForgeDock installer can now ship opt-in permission-rule suggestions (e.g. deny `Bash(git push origin main*)`) via `npx forgedock install`. These rules require v2.1.178+. Gate their injection in the installer by detected version. Enforces branch-protection policies deterministically rather than by prose.",
+      "severity": "high"
+    },
+    {
+      "version": "2.1.186",
+      "type": "feature",
+      "feature_key": "background_subagent_permission_surfacing",
+      "description": "Background sub-agent permission requests are surfaced to the user; completion notifications for background sub-agents added (v2.1.186–2.1.191 rollout)",
+      "forgedock_impact": "ForgeDock's orchestrate.md sub-agents dispatched in background mode will now surface permission prompts to the user when they encounter ungranted tools. Completion notifications reduce the need for polling. No ForgeDock spec changes required — behavior improves automatically.",
+      "severity": "medium"
+    },
+    {
+      "version": "2.1.196",
+      "type": "feature",
+      "feature_key": "skills_commands_merge",
+      "description": "Skills and commands merge into a unified namespace; `CLAUDE_CODE_SUBAGENT_MODEL=inherit` env var introduced for sub-agent model inheritance",
+      "forgedock_impact": "ForgeDock install method (symlinks into ~/.claude/commands/) is unaffected. `CLAUDE_CODE_SUBAGENT_MODEL=inherit` allows orchestrate.md sub-agents to inherit the parent model without explicit frontmatter — reduces per-subagent config overhead. Gate this env injection at v2.1.196+.",
+      "severity": "medium"
+    },
+    {
+      "version": "2.1.197",
+      "type": "feature",
+      "feature_key": "sonnet_5_default_1m_context",
+      "description": "Sonnet 5 becomes the default model; native 1M context window supported",
+      "forgedock_impact": "ForgeDock commands benefit from the 1M context window — compaction is less likely to trigger during long pipeline runs. Context budget calculations in orchestrate.md and work-on.md can be relaxed. compat-audit.md should surface this as the new minimum-recommended version for optimal context handling.",
+      "severity": "medium"
     }
   ]
 }

package/docs/design/abc-benchmark.md

@@ -8,7 +8,7 @@
 > Companion to [design-spec-schema](design-spec-schema.md) (#881), [reference-corpus](reference-corpus.md) (#880),
 > and the [`/design-bench`](../../commands/design-bench.md) command spec.
 > Results are carried as a `FORGE:BENCH_SCORECARD` annotation — registered in
-> [`../FORGE-PROTOCOL.md`](../FORGE-PROTOCOL.md).
+> [`../spec/forge-protocol-v1.md`](../spec/forge-protocol-v1.md).
 
 ## Why this exists first
 

package/docs/design/design-spec-schema.md

@@ -9,7 +9,7 @@
 > `motion.video_placeholder` fields + `motion` rubric dimension (#1043); `product_mock` field + `product_mock`
 > rubric dimension (#1045); `scroll_narrative` object + `scroll_narrative` rubric dimension (#1046).
 >
-> Registered as a FORGE annotation type in [`../FORGE-PROTOCOL.md`](../FORGE-PROTOCOL.md).
+> Registered as a FORGE annotation type in [`../spec/forge-protocol-v1.md`](../spec/forge-protocol-v1.md).
 
 ## Purpose
 

package/docs/design/divergent-generation.md

@@ -76,7 +76,7 @@ directions are retained in the `FORGE:DESIGN_CANDIDATES` annotation (below) so t
 
 ## The `FORGE:DESIGN_CANDIDATES` annotation
 
-Registered in [FORGE-PROTOCOL](../FORGE-PROTOCOL.md). Posted at the divergent-generation step, between the rationale
+Registered in [FORGE Annotation Protocol](../spec/forge-protocol-v1.md). Posted at the divergent-generation step, between the rationale
 and the spec. It records the committed archetype, the N directions, and the judge's selection + scores — so the
 variance decision is a first-class, machine-queryable artifact, not a hidden roll.