forgedock 1.27.0 → 1.28.0

package/docs/OUTCOME-CODES.md

@@ -46,6 +46,9 @@ An absent or unknown code is recorded as `unclassified`, with the raw reason kep
 | `infra.cli_spawn_transient` | CLI spawn failed transiently before the child ran (ETIMEDOUT, EAGAIN, ENOMEM, EMFILE); retried with backoff on a separate bounded counter that does not consume a phase attempt | engine | `err.code` `CLI_SPAWN_TRANSIENT` |
 | `cli.timeout` | CLI child ran and was killed at the wall-clock limit; a normal attempt (consumes one of `maxAttempts`), usage recorded when the CLI emitted any | engine | `err.code` `CLI_TIMEOUT` |
 | `cli.spawn_failed` | The CLI could not be started for a reason that repeats on every rerun (`E2BIG` argv too large, `ENOENT`/`EACCES`/`ENOEXEC` binary missing or not executable, `ENAMETOOLONG`). Core work-on ends `needs-human` with this code instead of `engine-error`, so `forgedock orchestrate` does not spend its relaunch on it | lean, engine | `err.code` `CLI_SPAWN_FAILED` (E2BIG) or `err.spawnDeterministic` (other errnos keep their `err.code`); `err.spawnErrno` holds the errno |
+| `env.setup_failed` | forge.yaml `env.setup` (run once per fresh lane worktree, before the builder) exited non-zero, timed out or could not start. An environment error, not a build failure: the builder never ran. Core work-on ends `needs-human` with this code instead of `engine-error`, so `forgedock orchestrate` does not relaunch it; fix the setup command or the environment and rerun | lean | `io.runSetup` exit code / spawn error |
+| `sandbox.start_failed` | A `forgedock orchestrate` lane sandbox (forge.yaml `execution`, provider `container` or `remote`) could not start: bad image, missing endpoint or credential, refused launch. The lane never ran. Final `needs-human` row: not relaunched and not counted by the engine-error circuit breaker | orchestrate | `bin/lean/execution.mjs` `providerLanes`: `provider.start` threw without `retryable` |
+| `sandbox.capacity` | The sandbox provider had no capacity for the lane (HTTP 429/503 from the remote transport). `deferred` with backoff (`Retry-After` when sent), bounded by `orchestration.max_deferrals` | orchestrate | `provider.start` threw with `err.retryable: true` |
 | `lease.held` | Another live agent holds the issue lease | engine | Foreign live lease on acquire |
 | `dependency.open` | A dependency is still open: a trusted `**Depends on**: #N` line refused the run before any state write, or the core builder reported `block.kind: "dependency"` naming an issue that is open. Carries `dependencies`; never `needs-human`. `forgedock orchestrate` adds the edge and requeues the issue behind it, without skipping dependents | engine, lean | Trusted `**Depends on**` line, or `result.json` `block.issues`, + the dependency issue's live open state |
 | `dependency.unreadable` | The issue body or a declared dependency could not be read, so the run was refused (fail closed) | engine, lean | Failed or unparsable `gh api` / `gh issue view` read |
@@ -72,9 +75,14 @@ An absent or unknown code is recorded as `unclassified`, with the raw reason kep
 | `conformance.unjustified_deferral` | Core work-on: the reviewer judged a deferred or post-deploy requirement unjustified (it belongs in this change), after one builder resume; nothing is filed or merged | lean | Review requirement row `deferral_ok: false` |
 | `conformance.preserve_violated` | Core work-on: a preserve constraint is violated or unverified, after one builder resume | lean | Review `preserve` row not `intact` |
 | `conformance.regression` | Core work-on: the reviewer named a concrete regression, after one builder resume | lean | Review `regressions` row |
+| `docs.stale` | Core work-on: the target repo's own `scripts/check-devdocs-freshness.sh` (docs must move with `bin/lean/` / `scripts/` behaviour) still fails after one builder resume; caught before the PR instead of by its required check | lean | the repo's `scripts/check-devdocs-freshness.sh <base>` exit 1 |
 | `structure.undeclared_edge` | Core work-on: the change adds a package.json dependency between workspace packages that the frozen contract does not name, still present after one builder resume | lean | `unnamedEdges` over `scripts/structure-delta.sh` `package_edges_added` |
+| `maintenance.hotspot_growth` | Core work-on: the change grows a file already over `maintenance.hotspot.file_lines` by more than `growth_lines` without a `hotspot-exempt: <reason>` in the contract, still present after one builder resume; blocks in shadow and enforce | lean | `hotspotGrowth` precheck over `scripts/hotspots.sh --base` `growth` |
 | `followup.unavailable` | Core work-on: filing or verifying the tracking issue for a deferral failed; the run is deferred with nothing merged, never needs-human | lean | `file-deferred-followups.sh` exit 3/4 or an unreadable tracking issue |
 | `merge.head_mismatch` | Core work-on: CI passed for a head other than the reviewed head; merge refused | lean | Gate head differs from the reviewed head |
+| `split.unsupported` | Core work-on `refactor:split` lane (forge#4211): no codemod or index tool for the target's language (Python and TypeScript have movers), or libcst / ts-morph is not available; refused before any edit | lean | target extension, `scripts/symbol-index.py`/`symbol-index.mjs` `unsupported`, `scripts/symbol-move.py` exit 3 naming libcst, `scripts/symbol-move.mjs` exit 3 `no codemod tool for ts` (forge#4212), `scripts/refactor-verify.sh` exit 2 |
+| `split.plan_invalid` | Core work-on `refactor:split` lane: no target or test command in the issue, an unparseable grouping reply, a failed baseline, or a plan `scripts/symbol-move.py` / `scripts/symbol-move.mjs` refuses; nothing written | lean | `bin/lean/refactor.mjs` parsers, `scripts/symbol-move.py` / `scripts/symbol-move.mjs` exit 3 |
+| `split.verify_failed` | Core work-on `refactor:split` lane: the move did not prove location-only (logic diff, missing symbol, changed pass/skip counts or a new import cycle); the branch is reset and nothing is pushed | lean | `scripts/refactor-verify.sh verify` exit 1 `failures[].kind` |
 | `completed` | Non-failure terminal (merged, phase-complete, investigation) | engine | Terminal reason |
 | `awaiting_merge` | Clean result held for a merge decision | remediate | Terminal reason `awaiting-merge` |
 | `unclassified` | Fallback for an absent or unknown code | engine | The raw reason is kept alongside |

package/docs/TELEMETRY.md

@@ -40,7 +40,7 @@ is dropped. Payload keys are `[A-Za-z0-9_]+` and cannot shadow the shared keys;
 | `ci_local` | `scripts/ci-local.sh run` (validate V4.8), one per run | `result` = `PASS` \| `FAIL` \| `DEGRADED`, `jobs_run`, `jobs_deferred`, `jobs_failed`, `duration_ms` (execution), `wait_ms` (time queued for a machine slot), `fix_iterations` (0 first run, 1 and 2 after fixes), `checks`, `cache_hits`, `narrowed` (checks run on a subset or skipped for no impact), `widened` (checks widened to the full command), `selected` / `total` (summed scope) |
 | `ci_local_check` | `scripts/ci-local.sh run`, one per scoped, widened or executed check (at most 20 per run) | `job`, `selector`, `selected`, `total`, `cache` = `hit` \| `miss` \| `dedup` \| `na`, `duration_ms`, `wait_ms` (job slot wait), `widen` (reason or `none`). A remote-CI failure at merge on a check recorded here as narrowed is a selector bug |
 | `liveness` | `scripts/remediate-liveness.sh` | `decision` = `PROCEED` \| `DEFER` \| `EXHAUSTED`, `why` |
-| `phase_attempt` | the engine (`bin/engine/telemetry-seam.mjs`, one per phase attempt; `phase` = the phase id) | `attempt`, `model`, `turns`, `duration_ms`, `cost_usd`, `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_creation_tokens` (any value the runner did not report is omitted) |
+| `phase_attempt` | the engine (`bin/engine/telemetry-seam.mjs`, one per phase attempt; `phase` = the phase id) | `attempt`, `model`, `backend` (`cli`/`api`), `turns`, `duration_ms`, `cost_usd`, `input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_creation_tokens` (any value the runner did not report is omitted) |
 | `run_terminal` | the engine (`terminate()`, one per run segment) | `reason` (terminal reason), `code` (see `docs/OUTCOME-CODES.md`), `wall_ms` (this engine process, start to terminal) |
 
 The engine records carry `run` = `r_<issue>_<start epoch seconds>` (one per `forgedock run-issue` process) so `forgedock stats`

package/docs/site/command-reference.md

@@ -553,6 +553,28 @@ Onboards an existing repo into the ForgeDock pipeline — scans open issues, cla
 
 ---
 
+### `/bootstrap`
+
+**Idea-to-backlog setup for a new project.**
+
+Guided setup for a brand-new project — interviews you about the idea, proposes defaults, surfaces doubts, writes a technical spike doc, and files a validated, orchestrate-ready issue backlog. The plan is validated before any GitHub write.
+
+```bash
+/bootstrap "a habit tracker for teams"   # Start from a free-text idea
+/bootstrap docs/idea.md                  # Start from existing docs
+/bootstrap "<idea>" --dry-run            # Preview the backlog without GitHub writes
+```
+
+Headless, from a terminal or CI:
+
+```bash
+npx forgedock bootstrap "<idea>" [--dry-run]       # Run /bootstrap without an interactive session
+npx forgedock bootstrap --plan plan.json --dry-run # Preview milestones, titles, DAG and estimated agent cost; no GitHub access
+npx forgedock bootstrap --plan plan.json           # Validate and create; re-run the same command to resume from GitHub
+```
+
+---
+
 #### `/sync-ecosystem`
 
 **Cross-repo sync.**

package/docs/site/getting-started.md

@@ -10,6 +10,8 @@ ForgeDock turns GitHub issues into shipped code — automatically. You open an i
 
 This tutorial gets you from zero to your first autonomous pipeline run in under 5 minutes.
 
+No repo or issues yet? [Start a New Project with ForgeDock](./start-a-new-project.md) turns an idea into a ready-to-build backlog with `/bootstrap`.
+
 ---
 
 ## Prerequisites

package/docs/site/start-a-new-project.md

@@ -0,0 +1,327 @@
+---
+title: "Start a New Project with ForgeDock"
+description: "Go from a one-line idea to a validated, orchestrate-ready GitHub backlog with /bootstrap: interview, spike doc, dry-run preview with estimated cost, creation and the /orchestrate hand-off. Includes a worked example."
+keywords: ["forgedock bootstrap", "new project backlog", "claude code new project", "ai project setup", "orchestrate"]
+---
+
+# Start a New Project with ForgeDock
+
+[Getting Started](./getting-started.md) assumes a repo that already has issues. This guide covers a brand-new project. You start with an idea, `/bootstrap` turns it into a backlog of GitHub issues in build order, and `/orchestrate` builds that backlog one milestone at a time.
+
+```text
+idea ──▶ /bootstrap ──▶ spike doc + plan ──▶ dry-run preview ──▶ backlog on GitHub ──▶ /orchestrate per milestone
+```
+
+All the GitHub writes happen in one deterministic script (`scripts/bootstrap-create.mjs`). The agent does the judgment work: the interview, the defaults and the plan. The script validates the plan and creates it. Flags are listed in the [command reference](./command-reference.md#bootstrap).
+
+---
+
+## Prerequisites
+
+- A GitHub repo for the new project (it can be empty). Set it in `forge.yaml` (`project.owner` / `project.repo`, from `npx forgedock init`) or pass `--repo OWNER/NAME`.
+- GitHub CLI (`gh`) authenticated (`gh auth login`).
+- Node.js 18 or higher.
+- Claude Code with ForgeDock installed for `/bootstrap`, or just `npx forgedock` for the headless path.
+
+## 1. From idea to `/bootstrap`
+
+Start from a free-text idea, or from docs you already have:
+
+```bash
+/bootstrap "a shared grocery list for households"   # in a Claude Code session
+/bootstrap docs/idea.md                             # start from existing docs
+/bootstrap "<idea>" --dry-run                       # preview only, no GitHub writes
+```
+
+Without an interactive session:
+
+```bash
+npx forgedock bootstrap "a shared grocery list for households" --dry-run
+```
+
+Headless mode can't ask you questions. It takes the recommended option for each one and lists it under "Here's what I assumed", so check that list before you create anything.
+
+## 2. What `/bootstrap` does
+
+1. **Interview.** It covers the aspects in `templates/bootstrap/interview.md` (users, core jobs, scope, platforms, stack, auth, data and tenancy, integrations, payments, compliance, deployment, budget and more) and skips anything your idea already answers.
+2. **Fills the blanks.** Every unanswered aspect gets a sensible default with a one-line rationale. All of them appear in one editable "Here's what I assumed" list.
+3. **Asks only genuine doubts.** These are choices that change architecture or cost, such as native vs PWA, data residency or self-hosted vs managed DB, plus the product name and repo owner, which are always asked. It asks at most 4 multiple-choice questions per batch, each with a recommended option.
+4. **Writes the spike doc** to `docs/engineering/technical-spike.md` (or the path in `--spike <path>`). It must have the sections Stack, Repo layout, Runtime topology, Data model, Security and privacy, Design system and quality gates, Route/API map, Credentials and Milestone plan. Each section needs a `**Rationale**:` line.
+5. **Writes a plan JSON** with milestones in build order (foundation first), a `SPIKE` parent issue, and sub-issues in the pipeline issue template. Each sub-issue lists planned files and acceptance criteria with `[type:*]` tags.
+   - Every credential, account or external input gets its own **needs-human** issue. Code issues may mention it, but they never depend on it. A mock keeps dev and CI green until the real thing exists.
+6. **Validates** the plan with `scripts/bootstrap-validate.mjs` and fixes it until it passes. Nothing is ever created from an invalid plan.
+
+## 3. Preview the backlog (dry run)
+
+If you already have a plan file, you can preview it without an LLM call or any GitHub access:
+
+```bash
+npx forgedock bootstrap --plan plan.json --dry-run
+```
+
+The preview lists each milestone with its `milestone/<slug>` branch, the issues in build order and their dependencies, a DAG summary, and an **estimated agent cost**. The estimate is a flat rate per build issue: `$3` by default, or `costPerIssueUsd` in the plan, or `--cost-per-issue <usd>`. The spike and needs-human issues are excluded. It's a planning estimate, not a measured figure.
+
+The spike doc has to exist on disk even for a dry run. If it's missing a section or a rationale, the script prints the error and writes nothing.
+
+## 4. Create the backlog
+
+```bash
+npx forgedock bootstrap --plan plan.json
+```
+
+This creates:
+
+- the spike parent issue
+- the milestones, plus a `milestone/<slug>` branch for each
+- every sub-issue, with a `**Parent**` link to the spike, the plan's guardrails and domain rules added to its Context, and <code v-pre>#{{KEY}}</code> placeholders resolved to real issue numbers
+- a board item for each issue (Status=Todo, Priority, Component)
+- `FORGE:BOOTSTRAP_PLAN` and `FORGE:DECOMPOSED` comments on the spike, which is then labelled `workflow:decomposed`
+
+Exit codes: `0` created (or previewed), `1` invalid plan or spike doc (nothing written), `2` usage error, `3` GitHub error.
+
+**Resume by re-running.** GitHub is the state. Issues are reused by exact title plus their `**Parent**` link, milestones by title, branches if they already exist, and comments if their marker is already there. After a network or rate-limit failure (exit `3`), run the same command again.
+
+## 5. The hand-off
+
+Creation ends with a hand-off in three parts:
+
+- **Created**: links to the build issues.
+- **Needs a human**: links to the credential and account issues. Do these when you can. They block nothing, because the code issues use mocks until then.
+- **Next commands**: one `/orchestrate milestone "<title>"` per milestone, in build order.
+
+Run the orchestrate commands in that order. Each one builds its milestone's issues through the normal `/work-on` pipeline.
+
+---
+
+## Worked example: Shelf, a shared grocery list
+
+The idea: *"Shelf, a shared grocery list for households. Members invite each other by email and see items checked off live."*
+
+### Assumptions and doubts
+
+Headless, `/bootstrap` takes the recommended options and lists them:
+
+```text
+Here's what I assumed
+- Platform: responsive web app (PWA later): a household list is used on phones, and a PWA avoids app-store review.
+- Stack: Next.js + TypeScript + Postgres (Prisma): the closest preset for a small web app.
+- Auth: email magic link: members already arrive through an email invite.
+- Email: Resend, behind a mock mailer in dev and CI.
+- Hosting: one web service plus managed Postgres.
+```
+
+### The spike doc
+
+`docs/engineering/technical-spike.md` has every required section, each with a rationale:
+
+```markdown
+# Shelf — technical spike
+
+## Stack
+Next.js (App Router) + TypeScript, Postgres via Prisma, pnpm.
+**Rationale**: one language end to end; the closest stack preset for a small web app.
+
+## Repo layout
+Single app: `app/`, `lib/`, `prisma/`.
+**Rationale**: one deployable; no monorepo until a second app exists.
+
+## Runtime topology
+One web service plus managed Postgres.
+**Rationale**: the cheapest setup that still gives live updates for a few households.
+
+## Data model
+`Household`, `Member`, `List`, `Item`; every row carries `householdId`.
+**Rationale**: the household is the sharing and access boundary.
+
+## Security and privacy
+Members only ever read their own household's rows; invites expire after 7 days.
+**Rationale**: grocery lists are personal data.
+
+## Design system and quality gates
+shadcn/ui; `pnpm build`, lint and unit tests in CI.
+**Rationale**: accessible defaults and fast feedback.
+
+## Route/API map
+`/api/lists`, `/api/invites`.
+**Rationale**: one route per milestone feature.
+
+## Credentials
+Resend API key (needs-human); the mock mailer is used until it exists.
+**Rationale**: agents cannot create third-party accounts.
+
+## Milestone plan
+1. Foundation: scaffold, schema. 2. Sharing: list API, invites.
+**Rationale**: sharing needs the schema first.
+```
+
+### The plan
+
+Two milestones, a spike, four build issues and one needs-human issue. `INVITES` mentions <code v-pre>#{{RESEND_KEY}}</code> but doesn't depend on it, so it can be built and tested against the mock mailer.
+
+```json
+{
+  "labels": [
+    "frontend",
+    "backend",
+    "infra",
+    "needs-human"
+  ],
+  "milestones": [
+    {
+      "key": "foundation",
+      "title": "Foundation"
+    },
+    {
+      "key": "sharing",
+      "title": "Sharing"
+    }
+  ],
+  "spikeDoc": "docs/engineering/technical-spike.md",
+  "guardrails": [
+    "no email is sent without an explicit invite"
+  ],
+  "domainRules": [
+    "one household per list"
+  ],
+  "issues": [
+    {
+      "key": "SPIKE",
+      "title": "spike: Shelf stack, layout and milestone plan",
+      "milestone": "foundation",
+      "labels": [
+        "infra"
+      ],
+      "deps": [],
+      "body": "## Problem\n\nDecide Shelf's stack, repo layout and milestone plan.\n\n## Root Cause (if known)\n\nGreenfield: not built yet.\n\n## Affected Files\n\n1. `docs/engineering/technical-spike.md` — new\n\n## Acceptance Criteria\n\n- [ ] Spike doc covers every section with a rationale [type:manual]\n\n## Context\n\n**Parent**: none (spike)\n\n## Dependencies\n\nNone.\n"
+    },
+    {
+      "key": "SCAFFOLD",
+      "title": "scaffold: Next.js app with pnpm and CI",
+      "milestone": "foundation",
+      "labels": [
+        "frontend",
+        "infra"
+      ],
+      "deps": [
+        "SPIKE"
+      ],
+      "priority": "p0",
+      "body": "## Problem\n\nScaffold the Next.js app with pnpm and a CI workflow.\n\n## Root Cause (if known)\n\nGreenfield: not built yet.\n\n## Affected Files\n\n1. `package.json` — new\n2. `app/layout.tsx` — new\n3. `.github/workflows/ci.yml` — new\n\n## Acceptance Criteria\n\n- [ ] `pnpm build` succeeds [type:unit]\n\n## Context\n\n**Parent**: #{{SPIKE}}\n\n## Dependencies\n\nDepends on #{{SPIKE}} — needs the stack decision\n"
+    },
+    {
+      "key": "DB",
+      "title": "db: Postgres schema for households, lists and items",
+      "milestone": "foundation",
+      "labels": [
+        "backend"
+      ],
+      "deps": [
+        "SCAFFOLD"
+      ],
+      "priority": "p0",
+      "body": "## Problem\n\nPostgres schema for households, lists and items via Prisma.\n\n## Root Cause (if known)\n\nGreenfield: not built yet.\n\n## Affected Files\n\n1. `prisma/schema.prisma` — new\n\n## Acceptance Criteria\n\n- [ ] A member reads only their own household's lists [type:unit]\n\n## Context\n\n**Parent**: #{{SPIKE}}\n\n## Dependencies\n\nDepends on #{{SCAFFOLD}} — needs the app and package setup\n"
+    },
+    {
+      "key": "LISTS_API",
+      "title": "lists: Shared list API with live updates",
+      "milestone": "sharing",
+      "labels": [
+        "backend"
+      ],
+      "deps": [
+        "DB"
+      ],
+      "priority": "p1",
+      "body": "## Problem\n\nAPI to add, check off and remove items, with live updates for everyone in the household.\n\n## Root Cause (if known)\n\nGreenfield: not built yet.\n\n## Affected Files\n\n1. `app/api/lists/route.ts` — new\n\n## Acceptance Criteria\n\n- [ ] Checking an item off shows up for a second member [type:api]\n\n## Context\n\n**Parent**: #{{SPIKE}}\n\n## Dependencies\n\nDepends on #{{DB}} — needs the schema\n"
+    },
+    {
+      "key": "INVITES",
+      "title": "invites: Email invites to join a household",
+      "milestone": "sharing",
+      "labels": [
+        "backend"
+      ],
+      "deps": [
+        "LISTS_API"
+      ],
+      "priority": "p1",
+      "body": "## Problem\n\nInvite a member by email. Sending uses Resend; the key comes from #{{RESEND_KEY}}, and until it exists dev and CI use the mock mailer.\n\n## Root Cause (if known)\n\nGreenfield: not built yet.\n\n## Affected Files\n\n1. `app/api/invites/route.ts` — new\n2. `lib/mailer.ts` — new\n\n## Acceptance Criteria\n\n- [ ] An invite link adds the member to the household [type:api]\n\n## Context\n\n**Parent**: #{{SPIKE}}\n\n## Dependencies\n\nDepends on #{{LISTS_API}} — needs households and lists\n"
+    },
+    {
+      "key": "RESEND_KEY",
+      "title": "resend: Create the Resend API key and store it",
+      "milestone": "sharing",
+      "labels": [
+        "needs-human"
+      ],
+      "deps": [],
+      "needsHuman": true,
+      "body": "## Problem\n\nCreate the Resend API key that #{{INVITES}} uses to send email.\n\n### Setup steps\n\n1. Create an API key at https://resend.com/api-keys with sending access only.\n2. Store it as the `RESEND_API_KEY` deploy secret.\n\n### Environment variables\n\n- `RESEND_API_KEY` — Resend sending key\n\n### Secret handling\n\nNever commit the key or paste it into issues. Until it exists, dev and CI use the mock mailer.\n\n## Root Cause (if known)\n\nGreenfield: not built yet.\n\n## Affected Files\n\n1. `docs/setup/resend.md` — new\n\n## Acceptance Criteria\n\n- [ ] Key stored as a deploy secret [type:manual]\n- [ ] The real mailer replaces the mock in staging [type:manual]\n\n## Context\n\n**Parent**: #{{SPIKE}}\n\n## Dependencies\n\nNone.\n"
+    }
+  ]
+}
+```
+
+`node scripts/bootstrap-validate.mjs plan.json` prints `bootstrap-validate: OK (6 issues, 2 milestones)`.
+
+### The dry-run preview
+
+`npx forgedock bootstrap --plan plan.json --dry-run --repo acme/shelf` prints:
+
+```text
+## Bootstrap plan preview (dry run: nothing written to GitHub)
+
+Spike: spike: Shelf stack, layout and milestone plan — doc `docs/engineering/technical-spike.md`
+
+### 1. Foundation (`milestone/foundation`, 2 issues)
+- scaffold: Next.js app with pnpm and CI
+- db: Postgres schema for households, lists and items — depends on SCAFFOLD
+
+### 2. Sharing (`milestone/sharing`, 3 issues)
+- lists: Shared list API with live updates — depends on DB
+- invites: Email invites to join a household — depends on LISTS_API
+- resend: Create the Resend API key and store it [needs-human]
+
+DAG: 5 sub-issues (4 build, 1 needs-human), 3 dependency edges, 2 milestones.
+Estimated agent cost: ~$12.00 (4 build issues × $3/issue; needs-human and spike excluded).
+```
+
+### Create and hand off
+
+`npx forgedock bootstrap --plan plan.json --repo acme/shelf` creates the backlog and prints the hand-off. The issue numbers below are illustrative:
+
+```text
+## Bootstrap hand-off
+
+Spike: #1 spike: Shelf stack, layout and milestone plan — https://github.com/acme/shelf/issues/1
+
+### Created
+- #2 scaffold: Next.js app with pnpm and CI — https://github.com/acme/shelf/issues/2
+- #3 db: Postgres schema for households, lists and items — https://github.com/acme/shelf/issues/3
+- #4 lists: Shared list API with live updates — https://github.com/acme/shelf/issues/4
+- #5 invites: Email invites to join a household — https://github.com/acme/shelf/issues/5
+
+### Needs a human
+- #6 resend: Create the Resend API key and store it — https://github.com/acme/shelf/issues/6
+
+### Next commands (in build order)
+1. /orchestrate milestone "Foundation"
+2. /orchestrate milestone "Sharing"
+```
+
+Then:
+
+```bash
+/orchestrate milestone "Foundation"   # scaffold, then the schema
+/orchestrate milestone "Sharing"      # list API, then invites (against the mock mailer until #6 is done)
+```
+
+If creation fails halfway, for example at issue #4, re-run `npx forgedock bootstrap --plan plan.json --repo acme/shelf`. Issues #1–#3 are reused and creation carries on from #4.
+
+---
+
+## Next
+
+- [Command Reference: `/bootstrap`](./command-reference.md#bootstrap)
+- [How It Works](./how-it-works.md): what `/orchestrate` and `/work-on` do with each issue
+- [Troubleshooting & Recovery](./troubleshooting.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forgedock",
-  "version": "1.27.0",
+  "version": "1.28.0",
   "description": "Autonomous development pipeline for coding agents. GitHub as institutional memory, with native Claude Code and OpenCode entrypoints.",
   "bin": {
     "forgedock": "bin/forgedock.mjs"

package/scripts/affected-files-check.sh

@@ -0,0 +1,91 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+#
+# affected-files-check.sh — /issue Phase 3E rule 2: are the draft's Affected Files real? (forge#4172)
+#
+# Usage:
+#   affected-files-check.sh <body-file> [--ref <git-ref>]... [--spike <spike-doc>]
+#
+#   <body-file>   issue body (markdown); paths are the backticked tokens containing '/' or '.'
+#                 inside its `## Affected Files` section (up to the next `## ` heading).
+#   --ref         git ref to check existence against (repeatable). Default: origin/staging then
+#                 origin/main; refs that do not resolve are skipped. Run from the target repo.
+#   --spike       greenfield mode: a path that exists at no ref still passes as PLANNED when it
+#                 equals an entry of the spike doc's repo-layout section, or starts with an entry
+#                 ending in '/'. The section is the first heading matching /repo layout/i; its
+#                 entries are backticked paths plus the lines of fenced blocks (tree glyphs and
+#                 `#` comments stripped). Entries are full repo-relative paths: indentation-based
+#                 nesting is not reconstructed.
+#
+# Output: one `OK <path>` | `PLANNED <path>` | `MISSING <path>` line per path.
+# Exit:   0 no MISSING | 1 any MISSING, or no paths found | 2 usage error (no body file,
+#         --spike file absent, spike doc without a repo-layout section or entries).
+# Deterministic, no LLM. bash 3.2 portable.
+
+set -u
+BODY_FILE=""
+SPIKE=""
+REFS=""
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --ref) [ -n "${2:-}" ] || { echo "affected-files-check: --ref requires a value" >&2; exit 2; }
+           REFS="$REFS
+$2"; shift 2 ;;
+    --spike) [ -n "${2:-}" ] || { echo "affected-files-check: --spike requires a value" >&2; exit 2; }
+             SPIKE="$2"; shift 2 ;;
+    --*) echo "affected-files-check: unknown argument: $1" >&2; exit 2 ;;
+    *) [ -z "$BODY_FILE" ] || { echo "affected-files-check: more than one body file" >&2; exit 2; }
+       BODY_FILE="$1"; shift ;;
+  esac
+done
+[ -n "$BODY_FILE" ] && [ -r "$BODY_FILE" ] || { echo "usage: affected-files-check.sh <body-file> [--ref <git-ref>]... [--spike <spike-doc>]" >&2; exit 2; }
+[ -n "$REFS" ] || REFS="
+origin/staging
+origin/main"
+
+# Backticked path-like tokens from the `## Affected Files` section.
+PATHS=$(awk '/^## /{ins=($0 ~ /^## Affected Files[[:space:]]*$/); next} ins' "$BODY_FILE" \
+  | grep -oE '`[^` ]+`' | tr -d '`' | grep -E '[/.]' | sed 's|^\./||; s|:[0-9][0-9,-]*$||' | awk '!seen[$0]++' || true)
+
+LAYOUT=""
+if [ -n "$SPIKE" ]; then
+  [ -r "$SPIKE" ] || { echo "affected-files-check: spike doc not found: $SPIKE" >&2; exit 2; }
+  grep -qiE '^#+[[:space:]].*repo layout' "$SPIKE" || { echo "affected-files-check: spike doc has no 'Repo layout' section: $SPIKE" >&2; exit 2; }
+  LAYOUT=$(awk '
+      /^[[:space:]]*```/ { fence=!fence; next }
+      !fence && /^#+[[:space:]]/ { if (ins) exit; if (tolower($0) ~ /repo layout/) ins=1; next }
+      !ins { next }
+      fence { sub(/#.*/, ""); gsub(/├──|└──|│|─/, ""); gsub(/^[[:space:]]+|[[:space:]]+$/, ""); if ($0 != "") print; next }
+      { while (match($0, /`[^` ]+`/)) { print substr($0, RSTART+1, RLENGTH-2); $0 = substr($0, RSTART+RLENGTH) } }
+    ' "$SPIKE" | sed 's|^\./||' | grep -E '[/.]' | awk '!seen[$0]++' || true)
+  [ -n "$LAYOUT" ] || { echo "affected-files-check: spike doc 'Repo layout' section declares no paths: $SPIKE" >&2; exit 2; }
+fi
+
+[ -n "$PATHS" ] || { echo "MISSING (no backticked paths in ## Affected Files)"; exit 1; }
+
+exists_at_ref() { # path -> 0 when it exists at any resolvable ref
+  printf '%s\n' "$REFS" | while IFS= read -r r; do
+    [ -n "$r" ] || continue
+    git cat-file -e "$r:$1" 2>/dev/null && { echo y; break; }
+  done | grep -q y
+}
+in_layout() { # path -> 0 when it equals a declared entry or sits under a declared directory
+  printf '%s\n' "$LAYOUT" | while IFS= read -r e; do
+    [ -n "$e" ] || continue
+    if [ "$1" = "$e" ]; then echo y; break; fi
+    case "$e" in */) case "$1" in "$e"*) echo y; break ;; esac ;; esac
+  done | grep -q y
+}
+
+FAIL=0
+while IFS= read -r p; do
+  [ -n "$p" ] || continue
+  if exists_at_ref "$p"; then echo "OK $p"
+  elif [ -n "$LAYOUT" ] && in_layout "$p"; then echo "PLANNED $p"
+  else echo "MISSING $p"; FAIL=1
+  fi
+done <<EOF
+$PATHS
+EOF
+exit $FAIL

package/scripts/affected-files-check.test.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# affected-files-check.test.sh — tests for scripts/affected-files-check.sh (forge#4172)
+#
+# Builds a throwaway git repo under $TMPDIR; no network or GitHub access.
+# Usage: bash scripts/affected-files-check.test.sh
+# Exit code: 0 if all assertions pass, 1 if any fail.
+#
+# SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios
+# SPDX-License-Identifier: AGPL-3.0-or-later
+
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+CHECK="$SCRIPT_DIR/affected-files-check.sh"
+T=$(mktemp -d "${TMPDIR:-/tmp}/afc-test.XXXXXX")
+trap 'rm -rf "$T"' EXIT
+
+PASS=0; FAIL=0
+expect() { # label expected actual
+  if [ "$2" = "$3" ]; then PASS=$((PASS+1)); else FAIL=$((FAIL+1)); printf 'FAIL %s\n  expected: %s\n  actual:   %s\n' "$1" "$2" "$3"; fi
+}
+run() { # args... -> "<exit>|<stdout lines joined by ;>"
+  local out rc
+  out=$(cd "$T/repo" && bash "$CHECK" "$@" 2>/dev/null); rc=$?
+  printf '%s|%s' "$rc" "$(printf '%s' "$out" | tr '\n' ';')"
+}
+body() { # name lines... -> body file path
+  local f="$T/$1.md"; shift
+  { printf '## Problem\n\nx `not/listed.ts`\n\n## Affected Files\n\n'; printf '%s\n' "$@"; printf '\n## Acceptance Criteria\n\n- [ ] y\n'; } > "$f"
+  printf '%s' "$f"
+}
+
+mkdir -p "$T/repo/src"
+git -C "$T/repo" init -q -b main
+printf 'x\n' > "$T/repo/src/existing.ts"
+git -C "$T/repo" add -A && git -C "$T/repo" -c user.name=t -c user.email=t@t commit -qm init
+
+cat > "$T/spike.md" <<'EOF'
+# Technical spike
+
+## Repo layout
+
+Apps live in `apps/web/` and the shared schema is `packages/db/schema.sql`.
+
+```
+apps/api/            # backend
+├── apps/api/src/main.ts
+└── docs/README.md
+```
+
+## Data model
+
+`packages/billing/` is mentioned outside the layout section.
+EOF
+printf '# Spike\n\n## Stack\n\n`apps/web/`\n' > "$T/nolayout.md"
+
+R="--ref main"
+
+# Brownfield (no --spike): unchanged semantics — existing OK, missing MISSING.
+expect "brownfield existing path" "0|OK src/existing.ts" "$(run "$(body b1 '1. `src/existing.ts`: the file')" $R)"
+expect "brownfield missing path" "1|MISSING apps/web/page.tsx" "$(run "$(body b2 '1. `apps/web/page.tsx`: planned')" $R)"
+expect "brownfield ignores paths outside the section" "0|OK src/existing.ts" "$(run "$(body b3 '- `src/existing.ts`')" $R)"
+expect "brownfield unresolvable default refs -> MISSING" "1|MISSING src/existing.ts" "$(run "$(body b4 '- `src/existing.ts`')")"
+
+# Greenfield (--spike): planned paths validated against the declared layout.
+expect "greenfield path under declared dir" "0|PLANNED apps/web/app/page.tsx" "$(run "$(body g1 '- `apps/web/app/page.tsx`')" $R --spike "$T/spike.md")"
+expect "greenfield path equal to declared file" "0|PLANNED packages/db/schema.sql" "$(run "$(body g2 '- `packages/db/schema.sql`')" $R --spike "$T/spike.md")"
+expect "greenfield path from fenced tree" "0|PLANNED apps/api/src/main.ts;PLANNED apps/api/routes.ts" "$(run "$(body g3 '- `apps/api/src/main.ts`' '- `apps/api/routes.ts`')" $R --spike "$T/spike.md")"
+expect "greenfield path outside layout" "1|PLANNED apps/web/x.ts;MISSING packages/billing/x.ts" "$(run "$(body g4 '- `apps/web/x.ts`' '- `packages/billing/x.ts`')" $R --spike "$T/spike.md")"
+expect "greenfield existing path still OK" "0|OK src/existing.ts" "$(run "$(body g5 '- `src/existing.ts`')" $R --spike "$T/spike.md")"
+expect "greenfield file prefix is not a directory" "1|MISSING packages/db/schema.sql.bak" "$(run "$(body g6 '- `packages/db/schema.sql.bak`')" $R --spike "$T/spike.md")"
+
+# Usage errors.
+expect "spike doc missing" "2|" "$(run "$(body u1 '- `apps/web/x.ts`')" $R --spike "$T/absent.md")"
+expect "spike doc without repo layout" "2|" "$(run "$(body u2 '- `apps/web/x.ts`')" $R --spike "$T/nolayout.md")"
+expect "no body file" "2|" "$(run)"
+expect "body without Affected Files paths" "1|MISSING (no backticked paths in ## Affected Files)" "$(run "$(body e1 'Files to be identified during investigation.')" $R)"
+
+echo "affected-files-check.test.sh: $PASS passed, $FAIL failed"
+[ "$FAIL" -eq 0 ]