forgedock 1.1.1 → 1.1.2

package/README.md

@@ -150,7 +150,7 @@ Issue → Investigate → Context → Architect → Build → Quality Gate → R
 | **Review** | PR diff, contract, gate results | `FORGE:REVIEW_STARTED` on the issue; per-agent findings as structured `FINDING` blocks on the PR |
 | **Close** | All of the above | `FORGE:TRAJECTORY` — the full audit trail of the run |
 
-**GitHub as the database.** Every annotation is wrapped in an HTML comment (`<!-- FORGE:INVESTIGATOR -->`) that makes it machine-parseable. When an agent starts — even in a brand-new conversation after compaction — it queries the issue via `gh` and reconstructs full context from these tags. Workflow labels (`workflow:investigating`, `workflow:in-review`, `workflow:merged`…) track state, and the pipeline resumes from whatever state GitHub reports. The annotation format is an open standard — see the [FORGE Annotation Protocol](docs/FORGE-PROTOCOL.md).
+**GitHub as the database.** Every annotation is wrapped in an HTML comment (`<!-- FORGE:INVESTIGATOR -->`) that makes it machine-parseable. When an agent starts — even in a brand-new conversation after compaction — it queries the issue via `gh` and reconstructs full context from these tags. Workflow labels (`workflow:investigating`, `workflow:in-review`, `workflow:merged`…) track state, and the pipeline resumes from whatever state GitHub reports. The annotation format is an open standard — see the [FORGE Annotation Protocol](docs/spec/forge-protocol-v1.md).
 
 **Durable by design.** Headless runs are backed by a real execution engine, not prompt-hope: every phase transition is appended to an event-sourced, crash-safe run log, mirrored to the issue as a compact `FORGE:STATE` index, and guarded by leases so two agents can never own the same issue. Kill the process mid-run and restart it — the engine reconciles local state against GitHub (GitHub wins), adopts branches and PRs that already exist instead of re-running the LLM, and escalates to `needs-human` after bounded retries instead of looping. Phase selection is a pure rule-based state machine: **the engine, not the model, decides what happens next.** The headless core shipped in [PR #1326](https://github.com/RapierCraftStudios/ForgeDock/pull/1326); wiring the interactive path onto the same engine is in progress ([#1323](https://github.com/RapierCraftStudios/ForgeDock/issues/1323)–[#1325](https://github.com/RapierCraftStudios/ForgeDock/issues/1325)).
 
@@ -221,9 +221,12 @@ More ship today (web-property analytics, browser QA sweeps, self-benchmarking)
 **Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code) · [GitHub CLI](https://cli.github.com/) (authenticated) · Node.js ≥ 18.
 
 ```bash
-npx forgedock          # checks your environment, installs the commands, detects your repo, and hands you a reviewed forge.yaml
+npx forgedock          # project-scoped install: checks your environment, installs commands for this repo, detects your repo, and hands you a reviewed forge.yaml
+npx forgedock --global # global install: installs into ~/.claude/commands/ — available in every Claude Code session on this machine
 ```
 
+**Project-scoped is the default.** `npx forgedock` installs commands scoped to the current project directory. Use `--global` only when you want the commands available across all your projects on this machine.
+
 One command does everything: it checks your environment, installs the slash commands into Claude Code, detects your repo (owner, branches, paths), and hands you a single annotated `forge.yaml` to review — press Enter to accept. Run `npx forgedock init` any time afterward to re-generate the config only.
 
 Installing also registers a SessionStart hook, so every Claude Code session
@@ -248,6 +251,15 @@ Commands then appear as `/forgedock:work-on`, etc. You still run `npx forgedock
 
 **Headless / CI:** the pipeline also runs outside Claude Code. `npx forgedock run work-on <issue> --dry-run` previews the assembled prompt and tool plan; with an `ANTHROPIC_API_KEY`, `npx forgedock run` drives the same command specs through a hardened tool-use loop, and `npx forgedock run-issue <issue>` executes them on the durable engine (event-sourced run log, leases, crash-safe resume).
 
+**Install modes:**
+
+```bash
+npx forgedock install           # project-scoped: <cwd>/.claude/commands/ (default)
+npx forgedock install --global  # global: ~/.claude/commands/ (opt-in)
+```
+
+`uninstall`, `update`, and `doctor` auto-detect which mode is installed — no need to re-specify `--global` after a global install. To explicitly target global: `npx forgedock doctor --global`.
+
 **Maintenance:**
 
 ```bash
@@ -255,8 +267,9 @@ npx forgedock update      # relink commands + refresh the SessionStart hook
 npx forgedock enable      # turn ForgeDock on for this directory
 npx forgedock disable     # turn ForgeDock off for this directory
 npx forgedock status      # show ForgeDock's state for this directory
-npx forgedock doctor      # installation health check with fix hints
-npx forgedock uninstall   # remove commands, the hook, and tracked copies
+npx forgedock doctor      # installation health check with fix hints (auto-detects mode)
+npx forgedock report      # 30-day pipeline impact receipts (--md for Markdown, --json for scripting)
+npx forgedock uninstall   # remove commands, the hook, and tracked copies (auto-detects mode)
 npx forgedock help        # show everything
 ```
 
@@ -264,6 +277,35 @@ npx forgedock help        # show everything
 
 </details>
 
+<details>
+<summary><strong>Migrating from a global install</strong></summary>
+
+If you installed ForgeDock before project-scoped became the default, your commands live in `~/.claude/commands/`. You have two paths forward:
+
+**Keep the global install** — add `--global` going forward and nothing changes:
+
+```bash
+npx forgedock --global   # install / update globally as before
+```
+
+**Switch to project-scoped** (recommended for multi-repo setups):
+
+```bash
+# 1. Check your current install mode
+npx forgedock status
+
+# 2. Remove the global install
+npx forgedock uninstall --global
+
+# 3. Install project-scoped in each repo you use ForgeDock in
+cd /path/to/your/project
+npx forgedock
+```
+
+Run `npx forgedock doctor` after switching to confirm everything is healthy.
+
+</details>
+
 ---
 
 ## For companies
@@ -272,8 +314,8 @@ The core is AGPL-3.0 and stays that way: engineers run the full pipeline on thei
 
 Two things are for sale:
 
-- **A [commercial license](COMMERCIAL-LICENSE.md)** — for organizations that need ForgeDock inside proprietary workflows or products without AGPL copyleft obligations. Contact [licensing@rapiercraft.studio](mailto:licensing@rapiercraft.studio).
-- **The fleet layer** *(in development)* — org-wide observability over every pipeline run: the receipts on this page, live, across all your repos, plus policy controls and audit-grade provenance for autonomous merges. We're onboarding a small group of design partners — [open a Discussion](https://github.com/RapierCraftStudios/ForgeDock/discussions) or email the address above to get in early.
+- **A [commercial license](COMMERCIAL-LICENSE.md)** — for organizations that need ForgeDock inside proprietary workflows or products without AGPL copyleft obligations. Contact [support@rapiercraftstudios.com](mailto:support@rapiercraftstudios.com).
+- **The fleet layer** *(in development)* — org-wide observability over every pipeline run: the receipts on this page, live, across all your repos, plus policy controls and audit-grade provenance for autonomous merges. We're onboarding a small group of design partners — see [ForgeDock for Companies](docs/site/for-companies.md) for details and intake.
 
 ---
 
@@ -282,7 +324,7 @@ Two things are for sale:
 Month one built the execution layer. The open roadmap — tracked in the [five-foundations epic (#1320)](https://github.com/RapierCraftStudios/ForgeDock/issues/1320) — is about earning trust while unattended:
 
 1. **Durability** — engine-owned state instead of prose-owned state. Headless core shipped ([PR #1326](https://github.com/RapierCraftStudios/ForgeDock/pull/1326)); interactive wiring in progress.
-2. **Verification** — an outcome-based acceptance gate and a graded eval corpus, so "done" is machine-checkable before anything claims success.
+2. **Verification** — an outcome-based acceptance gate and a graded eval corpus, so "done" is machine-checkable before anything claims success. Per-release pipeline scorecards are published in [`docs/eval/`](docs/eval/README.md); model upgrades follow the [model-release playbook](docs/articles/model-release-playbook.md).
 3. **Learning** — per-codebase memory that compounds across runs.
 4. **Economics** — per-run cost accounting and risk×cost dispatch decisions.
 5. **Provenance** — signed, replayable records of every autonomous change.
@@ -320,15 +362,18 @@ Using ForgeDock in your pipeline? Add the badge — each one is a backlink and a
 
 ## Docs & community
 
+- [GitHub Is Already Your Agents' Memory](docs/site/github-is-the-memory.md) — the canonical argument: why GitHub is the right place for agent memory, how FORGE annotations make it machine-readable, and how to adopt the protocol without ForgeDock
 - [Getting Started in 5 Minutes](docs/site/getting-started.md)
 - [How the Knowledge Graph Works](docs/site/how-it-works.md)
 - [What Are Those FORGE Comments?](docs/site/annotations-explained.md) — 2-minute explainer for annotations you meet in the wild
-- [FORGE Annotation Protocol](docs/FORGE-PROTOCOL.md) — the open standard for AI context passing ([formal v1.0 spec](docs/spec/forge-protocol-v1.md))
+- [FORGE Annotation Protocol](docs/spec/forge-protocol-v1.md) — the open standard for AI context passing (CC-BY-4.0)
 - [ForgeDock vs. Manual Claude Code Workflows](docs/site/vs-manual-workflows.md)
 - [ForgeDock vs. DeepWiki, AGENTS.md, and Cursor Memories](docs/comparison.md)
 - [Command Learning Path](docs/site/command-learning-path.md) — which commands to learn first
 - [Complete Command Reference](docs/site/command-reference.md)
 - [Troubleshooting & Recovery](docs/site/troubleshooting.md)
+- [Pipeline Eval Scorecards](docs/eval/README.md) — per-release published results for every model/Claude Code upgrade
+- [Model-Release Upgrade Playbook](docs/articles/model-release-playbook.md) — how to validate a new model before adopting it
 
 **Contributing:** PRs welcome — every change goes through a PR, tested against 3+ scenarios, using conventional commits (`fix(command):`, `feat(command):`). **License:** [AGPL-3.0](LICENSE) — free to use, modify, and distribute; network use of modifications must be open-sourced under the same license. Commercial licenses are available for proprietary use — see [COMMERCIAL-LICENSE.md](COMMERCIAL-LICENSE.md).
 

package/bin/batch-runner.mjs

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+/**
+ * bin/batch-runner.mjs — Batch driver for the ForgeDock pipeline eval harness (#1285)
+ *
+ * Iterates a corpus of GitHub issue numbers, invokes runCommand() (from
+ * bin/runner.mjs) for each issue against the /work-on spec, and writes a
+ * structured per-run results file consumable by scripts/eval-gate-scorecard.mjs.
+ *
+ * This is the batch/corpus increment of the standalone runtime — the natural
+ * next step after bin/runner.mjs's single-command foundational increment (#1151).
+ *
+ * Exports (all pure, no SDK, no network):
+ *   loadCorpus(path)                           → {corpus_version, issues}
+ *   makeRunResult(issue, status, opts)         → RunResult object
+ *   classifyRunnerResult(result)               → "success" | "failure" | "incomplete"
+ *   writeResults(outputPath, results, meta)    → void
+ *   runCorpus(opts)                            → Promise<RunResult[]>
+ *
+ * CLI usage:
+ *   node bin/batch-runner.mjs <corpus.json> [output.json]
+ *   node bin/batch-runner.mjs <corpus.json> [output.json] --dry-run
+ *
+ *   ANTHROPIC_API_KEY must be set for live runs.
+ *   FORGEDOCK_MODEL overrides the model (default: runner.mjs default).
+ *
+ * Corpus file format (docs/spec/eval-run-result.md):
+ *   { "corpus_version": "v1", "issues": [1001, 1002, 1003] }
+ *
+ * Output file format:
+ *   { "corpus_version": "v1", "runs": [ ...RunResult ] }
+ *
+ * See docs/spec/eval-run-result.md for the full JSON schema.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+
+// ---------------------------------------------------------------------------
+// Corpus loading
+// ---------------------------------------------------------------------------
+
+/**
+ * Load and validate a corpus JSON file.
+ *
+ * Throws a descriptive Error if the file is missing, invalid JSON, or does not
+ * contain a non-empty integer array at the "issues" key.
+ *
+ * @param {string} corpusPath - Absolute or relative path to the corpus JSON.
+ * @returns {{ corpus_version: string|null, issues: number[] }}
+ */
+export function loadCorpus(corpusPath) {
+  let raw;
+  try {
+    raw = readFileSync(corpusPath, "utf-8");
+  } catch (e) {
+    throw new Error(`Cannot read corpus file "${corpusPath}": ${e.message}`);
+  }
+
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch (e) {
+    throw new Error(`Corpus file "${corpusPath}" contains invalid JSON: ${e.message}`);
+  }
+
+  if (!data || typeof data !== "object") {
+    throw new Error(`Corpus file must be a JSON object; got ${typeof data}`);
+  }
+  if (!Array.isArray(data.issues) || data.issues.length === 0) {
+    throw new Error(`Corpus file must contain a non-empty "issues" array`);
+  }
+  for (let i = 0; i < data.issues.length; i++) {
+    const n = data.issues[i];
+    if (typeof n !== "number" || !Number.isInteger(n) || n <= 0) {
+      throw new Error(
+        `issues[${i}]: must be a positive integer (got ${JSON.stringify(n)})`,
+      );
+    }
+  }
+
+  return {
+    corpus_version: data.corpus_version ?? null,
+    issues: data.issues,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Run-result construction helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Map a runCommand() result status + stop reason to a scorecard status.
+ *
+ * runCommand() returns:
+ *   status: "complete" | "incomplete" | "dry-run" | "max-iterations"
+ *
+ * We map these to the eval-result schema's status:
+ *   "success"    — run completed cleanly (status "complete")
+ *   "incomplete" — run was cut short (status "incomplete" or "max-iterations" or "dry-run")
+ *
+ * The caller is responsible for "failure" — that requires inspecting GitHub
+ * state (whether the issue reached workflow:merged). For the purposes of the
+ * batch driver, a clean runner completion is classified as "success"; the
+ * scorecard consumer or a post-run hook can downgrade to "failure" by
+ * inspecting the issue label state.
+ *
+ * @param {{ status: string, stopReason?: string }} result
+ * @returns {"success" | "incomplete"}
+ */
+export function classifyRunnerResult(result) {
+  if (result.status === "complete") return "success";
+  return "incomplete";
+}
+
+/**
+ * Construct a per-run result object conforming to docs/spec/eval-run-result.md.
+ *
+ * @param {number} issue - GitHub issue number.
+ * @param {"success"|"failure"|"incomplete"|"error"} status
+ * @param {object} [opts]
+ * @param {number} [opts.wallClockMs]        - Wall-clock duration (ms).
+ * @param {number} [opts.interventionCount]  - Human intervention count.
+ * @param {number|null} [opts.cost]          - Token cost (null until #1255).
+ * @param {number} [opts.iterations]         - Tool-loop iteration count.
+ * @param {string} [opts.stopReason]         - Anthropic stop_reason or "max_iterations".
+ * @param {string|null} [opts.error]         - Error message when status === "error".
+ * @param {string} [opts.specVersion]        - Package version at run time.
+ * @param {string} [opts.model]              - Model used.
+ * @param {string} [opts.runAt]              - ISO-8601 timestamp.
+ * @returns {object}
+ */
+export function makeRunResult(issue, status, opts = {}) {
+  return {
+    issue,
+    status,
+    wallClockMs: opts.wallClockMs ?? 0,
+    interventionCount: opts.interventionCount ?? 0,
+    cost: opts.cost !== undefined ? opts.cost : null,
+    iterations: opts.iterations ?? null,
+    stopReason: opts.stopReason ?? null,
+    error: opts.error ?? null,
+    specVersion: opts.specVersion ?? null,
+    model: opts.model ?? null,
+    runAt: opts.runAt ?? new Date().toISOString(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Output writing
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialize run results to a JSON file.
+ * Creates parent directories as needed.
+ *
+ * @param {string} outputPath   - Absolute or relative path to write.
+ * @param {object[]} results    - Array of per-run result objects.
+ * @param {object} [meta]       - Top-level metadata (corpus_version, spec_version, model, corpus_size).
+ * @returns {void}
+ */
+export function writeResults(outputPath, results, meta = {}) {
+  const resolved = resolve(outputPath);
+  mkdirSync(dirname(resolved), { recursive: true });
+  const payload = {
+    corpus_version: meta.corpus_version ?? null,
+    corpus_size: meta.corpus_size ?? null,
+    spec_version: meta.spec_version ?? null,
+    model: meta.model ?? null,
+    generated_at: new Date().toISOString(),
+    runs: results,
+  };
+  writeFileSync(resolved, JSON.stringify(payload, null, 2) + "\n", "utf-8");
+}
+
+// ---------------------------------------------------------------------------
+// Batch orchestrator
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the full corpus headlessly.
+ *
+ * For each issue number in `corpus.issues`, invokes runCommand() against the
+ * /work-on spec in a shared working directory, records a per-run result, and
+ * returns the full array of results.
+ *
+ * Does NOT write output itself — callers should call writeResults() on the
+ * returned array. The CLI entry point below does this automatically.
+ *
+ * @param {object} opts
+ * @param {string} opts.commandsDir           - Absolute path to commands/.
+ * @param {{ corpus_version: string|null, issues: number[] }} opts.corpus
+ * @param {string} [opts.cwd]                 - Working directory for runner (default process.cwd()).
+ * @param {string} [opts.apiKey]              - Anthropic API key.
+ * @param {string} [opts.model]               - Model id.
+ * @param {number} [opts.maxIterations]       - Per-issue tool-loop bound.
+ * @param {boolean} [opts.dryRun]             - If true, no API calls are made.
+ * @param {{log: Function, error?: Function}} [opts.logger]
+ * @returns {Promise<object[]>}               - Array of per-run result objects.
+ */
+export async function runCorpus(opts = {}) {
+  const {
+    commandsDir,
+    corpus,
+    cwd = process.cwd(),
+    apiKey = process.env.ANTHROPIC_API_KEY,
+    model,
+    maxIterations,
+    dryRun = false,
+    logger = console,
+  } = opts;
+
+  // Lazy import of runCommand so this module stays import-safe without the SDK.
+  const { runCommand } = await import("./runner.mjs");
+
+  const results = [];
+
+  for (const issue of corpus.issues) {
+    logger.log(`[batch-runner] Starting issue #${issue}…`);
+    const startMs = Date.now();
+    let result;
+    try {
+      result = await runCommand({
+        commandsDir,
+        commandName: "work-on",
+        args: [String(issue)],
+        cwd,
+        apiKey,
+        ...(model ? { model } : {}),
+        ...(maxIterations !== undefined ? { maxIterations } : {}),
+        dryRun,
+        logger,
+      });
+      const wallClockMs = Date.now() - startMs;
+      const status = classifyRunnerResult(result);
+      results.push(
+        makeRunResult(issue, status, {
+          wallClockMs,
+          interventionCount: 0,
+          cost: null, // wired in once #1255 lands
+          iterations: result.iterations ?? null,
+          stopReason: result.stopReason ?? null,
+          model: model ?? result.model ?? null,
+          runAt: new Date().toISOString(),
+        }),
+      );
+      logger.log(`[batch-runner] Issue #${issue} → ${status} (${wallClockMs}ms)`);
+    } catch (e) {
+      const wallClockMs = Date.now() - startMs;
+      results.push(
+        makeRunResult(issue, "error", {
+          wallClockMs,
+          interventionCount: 0,
+          cost: null,
+          error: e.message,
+          model: model ?? null,
+          runAt: new Date().toISOString(),
+        }),
+      );
+      logger.error
+        ? logger.error(`[batch-runner] Issue #${issue} → error: ${e.message}`)
+        : logger.log(`[batch-runner] Issue #${issue} → error: ${e.message}`);
+    }
+  }
+
+  return results;
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry point
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const [, , corpusArg, outputArg, ...flags] = process.argv;
+  const dryRun = flags.includes("--dry-run");
+
+  if (!corpusArg) {
+    process.stderr.write(
+      "Usage: node bin/batch-runner.mjs <corpus.json> [output.json] [--dry-run]\n",
+    );
+    process.exit(1);
+  }
+
+  // Resolve paths relative to cwd of the calling shell, not __dirname.
+  const corpusPath = resolve(corpusArg);
+  const outputPath = outputArg ? resolve(outputArg) : resolve("eval-results.json");
+
+  let corpus;
+  try {
+    corpus = loadCorpus(corpusPath);
+  } catch (e) {
+    process.stderr.write(`ERROR: ${e.message}\n`);
+    process.exit(1);
+  }
+
+  // commandsDir: sibling of bin/ at the repo root.
+  const { fileURLToPath } = await import("node:url");
+  const { join } = await import("node:path");
+  const binDir = dirname(fileURLToPath(import.meta.url));
+  const commandsDir = join(binDir, "..", "commands");
+
+  // Read package version for specVersion field.
+  let specVersion = null;
+  try {
+    const pkgPath = join(binDir, "..", "package.json");
+    specVersion = JSON.parse(readFileSync(pkgPath, "utf-8")).version ?? null;
+  } catch {
+    // non-fatal — specVersion stays null
+  }
+
+  console.log(
+    `[batch-runner] Running ${corpus.issues.length} issue(s) from corpus "${corpus.corpus_version ?? "(no version)"}"${dryRun ? " (dry-run)" : ""}`,
+  );
+
+  const results = await runCorpus({
+    commandsDir,
+    corpus,
+    dryRun,
+    logger: console,
+  });
+
+  const meta = {
+    corpus_version: corpus.corpus_version,
+    corpus_size: corpus.issues.length,
+    spec_version: specVersion,
+    model: results.find((r) => r.model)?.model ?? null,
+  };
+
+  writeResults(outputPath, results, meta);
+  console.log(`[batch-runner] Results written to ${outputPath}`);
+
+  const nSuccess = results.filter((r) => r.status === "success").length;
+  const nTotal = results.length;
+  console.log(`[batch-runner] ${nSuccess}/${nTotal} runs succeeded`);
+}
+
+import { fileURLToPath } from "node:url";
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  main();
+}

package/bin/demo.mjs

@@ -61,6 +61,9 @@ export const DEFAULT_DEMO_DIRNAME = "forgedock-demo";
  *   --repo <slug> | --repo=<slug> Override the demo repo (owner/name).
  *   --open                        Launch Claude Code in the demo dir when found.
  *   --no-open                     Explicitly disable launching (the default).
+ *   --run                         Run the seeded issue through /work-on automatically
+ *                                 (requires ANTHROPIC_API_KEY; falls back to print-only
+ *                                 instructions when the key is absent).
  *   --help | -h                   Show usage.
  *
  * The first non-flag argument is treated as the target directory (positional
@@ -68,8 +71,8 @@ export const DEFAULT_DEMO_DIRNAME = "forgedock-demo";
  *
  * @param {string[]} args
  * @returns {{positional: string|undefined, dir: string|undefined,
- *            repo: string|undefined, open: boolean, help: boolean,
- *            error: string|null}}
+ *            repo: string|undefined, open: boolean, run: boolean,
+ *            help: boolean, error: string|null}}
  */
 export function parseDemoArgs(args = []) {
   const out = {
@@ -77,6 +80,7 @@ export function parseDemoArgs(args = []) {
     dir: undefined,
     repo: undefined,
     open: false,
+    run: false,
     help: false,
     error: null,
   };
@@ -88,6 +92,8 @@ export function parseDemoArgs(args = []) {
       out.open = true;
     } else if (a === "--no-open") {
       out.open = false;
+    } else if (a === "--run") {
+      out.run = true;
     } else if (a === "--dir") {
       out.dir = args[++i];
       if (out.dir === undefined) out.error = "--dir requires a path argument";
@@ -145,7 +151,7 @@ function isEmptyDir(dir, fsx) {
 
 export function demoUsage() {
   return [
-    "Usage: forgedock demo [dir] [--dir <path>] [--repo <owner/name>] [--open]",
+    "Usage: forgedock demo [dir] [--dir <path>] [--repo <owner/name>] [--open] [--run]",
     "",
     "Stand up a runnable ForgeDock demo at a predictable location (default",
     "~/forgedock-demo) and print the exact next steps. No configuration needed.",
@@ -155,6 +161,9 @@ export function demoUsage() {
     "  --repo <slug>    Demo repo to clone (default: RapierCraftStudios/forgedock-demo).",
     "  --open           Launch Claude Code in the demo directory if available.",
     "  --no-open        Do not launch Claude Code (default).",
+    "  --run            Automatically run the seeded issue through /work-on to a",
+    "                   merged PR (requires ANTHROPIC_API_KEY; falls back to",
+    "                   print-only instructions when the key is absent).",
     "  -h, --help       Show this help.",
   ].join("\n");
 }
@@ -186,10 +195,10 @@ export function demoForgeYaml(repoSlug) {
 
 /**
  * Render the success / next-steps card.
- * @param {{target: string, source: string, claudeAvailable: boolean}} ctx
+ * @param {{target: string, source: string, claudeAvailable: boolean, apiKeyAvailable?: boolean}} ctx
  * @returns {string}
  */
-export function renderNextSteps({ target, source, claudeAvailable }) {
+export function renderNextSteps({ target, source, claudeAvailable, apiKeyAvailable = false }) {
   const sourceNote = {
     cloned: "Cloned the live demo repo.",
     pulled: "Demo already present — pulled the latest.",
@@ -214,6 +223,15 @@ export function renderNextSteps({ target, source, claudeAvailable }) {
       ? "  claude            # open Claude Code here (or re-run with --open)"
       : "  # then open Claude Code in this directory",
   ];
+
+  if (!apiKeyAvailable) {
+    lines.push(
+      "",
+      "Tip: set ANTHROPIC_API_KEY and re-run with --run to execute the pipeline",
+      "automatically and watch a PR merge without opening Claude Code.",
+    );
+  }
+
   return lines.join("\n");
 }
 
@@ -261,11 +279,12 @@ const defaultLogger = {
  * Stand up the demo.
  *
  * @param {object} opts
- * @param {string}  opts.forgeHome            - Package root (for bundled scaffold).
+ * @param {string}  opts.forgeHome            - Package root (for bundled scaffold and commands/).
  * @param {string[]} [opts.args]              - CLI args after `demo`.
  * @param {string}  [opts.home]               - Home dir (default os.homedir()).
  * @param {string}  [opts.cwd]                - Working dir (default process.cwd()).
  * @param {string}  [opts.demoRepo]           - Override demo repo slug.
+ * @param {string}  [opts.apiKey]             - Anthropic API key (default ANTHROPIC_API_KEY env).
  * @param {Function} [opts.exec]              - (cmd, args, {cwd}) => {status,...}.
  * @param {object}  [opts.fsx]                - Filesystem facade.
  * @param {Function} [opts.commandExists]     - (bin) => boolean.
@@ -279,6 +298,7 @@ export async function runDemo(opts = {}) {
     args = [],
     home = homedir(),
     cwd = process.cwd(),
+    apiKey = process.env.ANTHROPIC_API_KEY,
     exec = defaultExec,
     fsx = defaultFsx,
     commandExists = defaultCommandExists,
@@ -371,7 +391,72 @@ export async function runDemo(opts = {}) {
   }
 
   const claudeAvailable = commandExists("claude");
-  logger.log(renderNextSteps({ target, source, claudeAvailable }));
+  const apiKeyAvailable = Boolean(apiKey);
+
+  // --run: drive the seeded issue through /work-on automatically.
+  // Requires ANTHROPIC_API_KEY; falls back to print-only instructions gracefully.
+  if (parsed.run) {
+    if (!apiKeyAvailable) {
+      logger.log(
+        "\nANTHROPIC_API_KEY is not set — cannot run the pipeline automatically.\n" +
+        "Export your key and re-run with --run, or open Claude Code manually:\n",
+      );
+      logger.log(renderNextSteps({ target, source, claudeAvailable, apiKeyAvailable: false }));
+      return { status: "ok", target, source };
+    }
+
+    const commandsDir = forgeHome ? join(forgeHome, "commands") : null;
+    if (!commandsDir || !fsx.existsSync(commandsDir)) {
+      logger.error(
+        "Could not locate the ForgeDock commands/ directory. " +
+        "Falling back to manual instructions.",
+      );
+      logger.log(renderNextSteps({ target, source, claudeAvailable, apiKeyAvailable }));
+      return { status: "ok", target, source };
+    }
+
+    logger.log(
+      "\nRunning /work-on 1 in the demo repo — watch the full pipeline execute…\n",
+    );
+
+    let runCommand;
+    try {
+      ({ runCommand } = await import("./runner.mjs"));
+    } catch {
+      logger.error(
+        "Could not load bin/runner.mjs. Falling back to manual instructions.",
+      );
+      logger.log(renderNextSteps({ target, source, claudeAvailable, apiKeyAvailable }));
+      return { status: "ok", target, source };
+    }
+
+    try {
+      const result = await runCommand({
+        commandsDir,
+        commandName: "work-on",
+        args: ["1"],
+        cwd: target,
+        apiKey,
+        logger: { log: logger.log, error: logger.error },
+      });
+      logger.log(`\nDemo pipeline finished with status: ${result.status}`);
+      return { status: result.status === "ok" ? "ok" : result.status, target, source };
+    } catch (err) {
+      if (err.code === "NO_SDK") {
+        logger.error(
+          "\n@anthropic-ai/sdk is not installed. Install it with:\n" +
+          "  npm install @anthropic-ai/sdk\n" +
+          "Then re-run with --run, or open Claude Code manually:\n",
+        );
+      } else {
+        logger.error(`\nPipeline error: ${err.message}\nFalling back to manual instructions.\n`);
+      }
+      logger.log(renderNextSteps({ target, source, claudeAvailable, apiKeyAvailable }));
+      return { status: "ok", target, source };
+    }
+  }
+
+  logger.log(renderNextSteps({ target, source, claudeAvailable, apiKeyAvailable }));
 
   if (parsed.open) {
     if (claudeAvailable) {